pmx-canvas 0.5.0 → 0.5.1

package/dist/types/client/canvas/canvas-area.d.ts

@@ -23,3 +23,17 @@ export declare function canvasAreaCenter(): {
     x: number;
     y: number;
 };
+export interface CanvasFitInsets {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+}
+/**
+ * Screen-space insets Fit must reserve for the floating chrome that overlays
+ * the canvas region: the bottom command bar (whose pinned-chip row grows it)
+ * and the bottom-right minimap. Measured from the live elements — fit's old
+ * world-space padding shrank with the fit zoom and parked nodes underneath
+ * both (0.5.0 Amp report, finding A; architecture rule 9's trap).
+ */
+export declare function canvasFitInsets(): CanvasFitInsets;

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

@@ -3,6 +3,8 @@ import { AppBridge } from '@modelcontextprotocol/ext-apps/app-bridge';
 import type { CanvasNodeState } from '../types';
 type ExtAppBridgeNotifications = Pick<AppBridge, 'sendToolInput' | 'sendToolResult'>;
 type DisplayMode = 'inline' | 'fullscreen' | 'pip';
+/** Paint probe outcome: only a content-carrying tick counts as painted. */
+export type PaintProbeVerdict = 'content-verified' | 'tick-no-content' | 'timeout';
 interface ExtAppHostDimensionsTarget {
     clientWidth?: number;
     clientHeight?: number;

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

@@ -178,6 +178,16 @@ export declare function setCanvasContextPins(nodeIds: string[], mode?: CanvasPin
     nodeIds: string[];
 };
 export declare function listCanvasSnapshots(options?: Parameters<typeof canvasState.listSnapshots>[0]): CanvasSnapshot[];
+/**
+ * Snapshot save with unchanged-board reuse — the ONE path every surface must
+ * take (op registry, SDK). The SDK once called saveCanvasSnapshot directly and
+ * stacked identical snapshots the HTTP/MCP path deduplicated (0.5.0 Codex
+ * finding V).
+ */
+export declare function saveCanvasSnapshotWithReuse(name: string): {
+    snapshot: CanvasSnapshot | null;
+    reused: boolean;
+};
 export declare function saveCanvasSnapshot(name: string): CanvasSnapshot | null;
 export declare function restoreCanvasSnapshot(idOrName: string): Promise<{
     ok: boolean;

package/docs/RELEASE.md

@@ -250,3 +250,17 @@ with `ok: true`, the published tarball is intact end-to-end.
 - **Node 24 deprecation timeline**: GitHub Actions is migrating
   `actions/checkout`, `setup-node`, `upload-artifact` to Node 24 by
   June 2, 2026. The publish workflow already pins `@v5` of all three.
+- **npm token failures wear two disguises** (both hit the 0.5.0 publish,
+  after build/tests/provenance all succeeded):
+  - `404 Not Found - PUT …/pmx-canvas` on a package that exists = the
+    token was rejected (npm masks permission refusals as 404). Rotate the
+    `NPM_TOKEN` repo secret.
+  - `EOTP: This operation requires a one-time password` = the account
+    enforces 2FA on writes and the token doesn't have **Bypass 2FA**
+    ticked — CI cannot answer an OTP. A granular token needs that box
+    checked to publish from Actions.
+  - Both are fixed without re-tagging: update the secret, then
+    `gh run rerun <publish-run-id> --failed` re-publishes the same tag.
+  - npm restricts bypass-2FA tokens for direct publishing by **Jan 2027**
+    — migrate to Trusted Publishing (OIDC; `publish.yml` already has
+    `id-token: write`) and delete the token before then.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pmx-canvas",
-  "version": "0.5.0",
-  "description": "Spatial canvas workbench for coding agents — infinite 2D canvas with agent-native CLI, MCP integration, nodes, edges, file watching, and snapshots",
+  "version": "0.5.1",
+  "description": "Spatial canvas workbench for coding agents \u2014 infinite 2D canvas with agent-native CLI, MCP integration, nodes, edges, file watching, and snapshots",
   "type": "module",
   "main": "./src/server/index.ts",
   "module": "./src/server/index.ts",
@@ -43,9 +43,9 @@
     "typecheck": "tsc --noEmit && tsc -p tsconfig.tests.json",
     "lint": "biome check .",
     "lint:fix": "biome check --write .",
-    "test": "if [ -d tests/unit ]; then PMX_MCP_APP_HOST_STATE_FILE=/tmp/pmx-canvas-test-app-host-state.json PMX_CANVAS_DISABLE_BROWSER_OPEN=1 bun test tests/unit; else echo 'tests/ is not shipped in the npm package — clone the repo to run the suite'; fi",
+    "test": "if [ -d tests/unit ]; then PMX_MCP_APP_HOST_STATE_FILE=/tmp/pmx-canvas-test-app-host-state.json PMX_CANVAS_DISABLE_BROWSER_OPEN=1 bun test tests/unit; else echo 'tests/ is not shipped in the npm package \u2014 clone the repo to run the suite'; fi",
     "test:unit": "PMX_MCP_APP_HOST_STATE_FILE=/tmp/pmx-canvas-test-app-host-state.json PMX_CANVAS_DISABLE_BROWSER_OPEN=1 bun test tests/unit",
-    "test:client": "if [ -d tests/client ]; then bun test --preload ./tests/client/setup.ts tests/client; else echo 'tests/ is not shipped in the npm package — clone the repo to run the suite'; fi",
+    "test:client": "if [ -d tests/client ]; then bun test --preload ./tests/client/setup.ts tests/client; else echo 'tests/ is not shipped in the npm package \u2014 clone the repo to run the suite'; fi",
     "test:coverage": "PMX_MCP_APP_HOST_STATE_FILE=/tmp/pmx-canvas-test-app-host-state.json PMX_CANVAS_DISABLE_BROWSER_OPEN=1 bun test tests/unit --coverage --coverage-reporter=text --coverage-reporter=lcov --coverage-dir coverage && bun scripts/check-coverage.ts",
     "test:web-canvas": "PMX_CANVAS_DISABLE_BROWSER_OPEN=1 bun run build && PMX_CANVAS_DISABLE_BROWSER_OPEN=1 bash scripts/run-playwright.sh",
     "test:e2e": "bun run test:web-canvas",

package/skills/pmx-canvas/SKILL.md

@@ -147,7 +147,7 @@ this table is kept in sync with the server's composite registry; `tools/list` on
 | `canvas_query` | `search`, `layout`, `validate` |
 | `canvas_webview` | `status`, `start`, `stop`, `resize`, `evaluate` |
 | `canvas_app` | `open-mcp-app`, `diagram`, `build-artifact` |
-| `canvas_ax_state` | `get`, `set-focus`, `set-policy`, `report-capability` |
+| `canvas_ax_state` | `get`, `set-focus`, `set-policy`, `report-capability`, `presence`, `set-presence` |
 | `canvas_ax_work` | `add`, `update`, `annotate` |
 | `canvas_ax_gate` | `request`, `resolve`, `await` with `approval`, `elicitation`, or `mode` |
 | `canvas_ax_timeline` | `read`, `record-event`, `add-evidence`, `send-steering` |
@@ -262,6 +262,14 @@ The board has three modes, all gated on one fact — whether a session is attach
   extension) attach for you; the human can also start a session from the board's *Start agent
   session* button — your writes (transport or `PMX_CANVAS_AGENT_SOURCE` label alike) are
   attributed to it and it takes your name.
+- **No adapter? Use the pump.** Any CLI agent becomes steer-reactive with one command in a
+  terminal: `pmx-canvas pump --consumer <your-key> --exec '<command>'`. It long-polls your
+  delivery queue, runs the command once per steer (message on stdin plus the
+  `PMX_STEER_MESSAGE`/`ID`/`SOURCE`/`TARGET`/`CREATED_AT` env envelope), and marks
+  per-consumer only after the command exits 0 — a failed hand-off stays pending and the pump
+  exits non-zero. `{message}` in the template expands to a quoted env reference (never spliced;
+  refused on Windows — read stdin there). `--parent <key>` rolls you up under an orchestrator's
+  chip; `--once` for scripts. See `pmx-canvas pump --help`.
 
 What the session asks of you:
 

package/src/cli/commands/pump.ts

@@ -16,7 +16,15 @@
  * takes the message from stdin instead. See `renderExecTemplate`.
  */
 import { spawn } from 'node:child_process';
-import { cmd, getBaseUrl, getStringFlag, invokeOperation, parseFlags, requireFlag } from '../shared.js';
+import {
+  cmd,
+  getBaseUrl,
+  getStringFlag,
+  invokeOperation,
+  parseFlags,
+  requireFlag,
+  showCommandHelp,
+} from '../shared.js';
 
 interface PendingSteer {
   id: string;
@@ -137,7 +145,10 @@ cmd(
     `pmx-canvas pump --consumer testbot --exec 'cat' --once`,
   ],
   async (args) => {
-    const { flags } = parseFlags(args, { boolFlags: ['once'] });
+    const { flags } = parseFlags(args, { boolFlags: ['once', 'help', 'h'] });
+    // Help before required-flag validation — `pump --help` died on
+    // "Missing required flag: --consumer" (0.5.0 Codex finding W).
+    if (flags.help || flags.h) return showCommandHelp('pump');
     const consumer = requireFlag(
       flags,
       'consumer',

package/src/cli/index.ts

@@ -314,6 +314,7 @@ Agent CLI (works against running server):
   code-graph                          File dependencies
   spatial                             Spatial analysis
   watch                               Semantic watch stream
+  pump                                Reactive steering loop for CLI agents (Amp, Codex CLI)
   smoke                               Check that a running canvas works here
   skills sync                         Sync installed copies of the bundled skills
   copilot install-extension           Install the GitHub Copilot app extension

package/src/client/canvas/canvas-area.ts

@@ -39,3 +39,36 @@ export function canvasAreaCenter(): { x: number; y: number } {
   const rect = canvasArea();
   return { x: rect.left + rect.width / 2, y: rect.top + rect.height / 2 };
 }
+
+export interface CanvasFitInsets {
+  top: number;
+  right: number;
+  bottom: number;
+  left: number;
+}
+
+/**
+ * Screen-space insets Fit must reserve for the floating chrome that overlays
+ * the canvas region: the bottom command bar (whose pinned-chip row grows it)
+ * and the bottom-right minimap. Measured from the live elements — fit's old
+ * world-space padding shrank with the fit zoom and parked nodes underneath
+ * both (0.5.0 Amp report, finding A; architecture rule 9's trap).
+ */
+export function canvasFitInsets(): CanvasFitInsets {
+  let bottom = 16;
+  try {
+    const area = canvasArea();
+    const areaBottom = area.top + area.height;
+    for (const selector of ['.command-bar', '.minimap']) {
+      const el = document.querySelector(selector);
+      if (!(el instanceof HTMLElement) || !el.isConnected) continue;
+      const rect = el.getBoundingClientRect();
+      if (rect.height <= 0) continue;
+      const overlap = areaBottom - rect.top;
+      if (overlap > 0) bottom = Math.max(bottom, overlap + 12);
+    }
+  } catch {
+    // Chromeless embeds and unit DOMs: the defaults below are the contract.
+  }
+  return { top: 16, right: 16, bottom, left: 16 };
+}

package/src/client/nodes/ExtAppFrame.tsx

@@ -30,6 +30,8 @@ type McpUiTheme = 'light' | 'dark';
 type ExtAppBridgeNotifications = Pick<AppBridge, 'sendToolInput' | 'sendToolResult'>;
 type DisplayMode = 'inline' | 'fullscreen' | 'pip';
 type ExtAppFrameStatus = 'loading' | 'ready' | 'done';
+/** Paint probe outcome: only a content-carrying tick counts as painted. */
+export type PaintProbeVerdict = 'content-verified' | 'tick-no-content' | 'timeout';
 
 interface ExtAppHostDimensionsTarget {
   clientWidth?: number;
@@ -285,10 +287,28 @@ export function buildExtAppBootBeaconScript(frameToken: string, nodeId: string):
   // rendering pipeline is actually running — a frame whose layer WebKit never
   // composites stays silent, and that silence drives the parent's recovery
   // ladder. One unsolicited tick at boot, then on-demand answers to probes.
+  // Content oracle (Finding N, 0.5.0 reopen): a double rAF fires even while
+  // WKWebKit composites nothing — the tick alone was a false green. The tick
+  // now carries a verdict: does this document actually CONTAIN rendered
+  // content (a laid-out canvas/svg, or real text)? The parent only accepts
+  // paint-ok when it does.
+  function contentReady() {
+    try {
+      var els = document.querySelectorAll('canvas, svg');
+      for (var i = 0; i < els.length; i++) {
+        var r = els[i].getBoundingClientRect();
+        if (r.width > 8 && r.height > 8) return true;
+      }
+      var body = document.body;
+      return !!(body && body.innerText && body.innerText.trim().length > 0);
+    } catch (e) {
+      return false;
+    }
+  }
   function sendPaintTick() {
     requestAnimationFrame(function () {
       requestAnimationFrame(function () {
-        window.parent.postMessage({ source: '${EXT_APP_BOOT_BEACON_SOURCE}', token: TOKEN, nodeId: NODE_ID, kind: 'paint-tick' }, '*');
+        window.parent.postMessage({ source: '${EXT_APP_BOOT_BEACON_SOURCE}', token: TOKEN, nodeId: NODE_ID, kind: 'paint-tick', content: contentReady() }, '*');
       });
     });
   }
@@ -367,8 +387,9 @@ export function ExtAppFrame({ node, expanded = false }: { node: CanvasNodeState;
   const bridgeReadyRef = useRef(false);
   const themeUnsubRef = useRef<(() => void) | null>(null);
   const webkitRemountAttemptsRef = useRef(0);
-  // Paint oracle (Finding N): resolvers waiting for the frame's next paint-tick.
-  const paintTickWaitersRef = useRef<Array<() => void>>([]);
+  // Paint oracle (Finding N): resolvers waiting for the frame's next paint-tick,
+  // each handed the tick's content verdict.
+  const paintTickWaitersRef = useRef<Array<(content: boolean) => void>>([]);
   // Genuine boot signal: set ONLY when the app completes the ui/initialize
   // handshake (bridge.oninitialized) — NOT by the 1200ms bootstrap fallback,
   // which flips status via notifications that resolve even into a dead iframe.
@@ -450,7 +471,8 @@ export function ExtAppFrame({ node, expanded = false }: { node: CanvasNodeState;
         return;
       appScriptsRanRef.current = true;
       if (data.kind === 'paint-tick') {
-        for (const waiter of paintTickWaitersRef.current.splice(0)) waiter();
+        const content = (data as { content?: unknown }).content === true;
+        for (const waiter of paintTickWaitersRef.current.splice(0)) waiter(content);
       }
     }
     window.addEventListener('message', onBootBeacon);
@@ -503,7 +525,7 @@ export function ExtAppFrame({ node, expanded = false }: { node: CanvasNodeState;
     enqueueWebkitRemount({
       remount: () => {
         remountQueuedRef.current = false;
-        if (unmountedRef.current || expandedNodeId.value === nodeId) {
+        if (unmountedRef.current || (!expanded && expandedNodeId.value === nodeId)) {
           extAppRecoveryLog(nodeId, 'remount-skipped');
           // The ladder left paintPending set on the promise that this remount
           // would re-enter it via the new frame's settle path. A skip means
@@ -555,28 +577,42 @@ export function ExtAppFrame({ node, expanded = false }: { node: CanvasNodeState;
   // again → serialized remount (bounded by the shared attempt cap) → explicit
   // Retry affordance. Never silent eternal black. WebKit inline frames only.
   const PAINT_TICK_TIMEOUT_MS = 1500;
-  const probePaint = (): Promise<boolean> =>
+  const probePaint = (): Promise<PaintProbeVerdict> =>
     new Promise((resolve) => {
       const contentWindow = iframeRef.current?.contentWindow;
       if (!contentWindow || unmountedRef.current) {
-        resolve(false);
+        resolve('timeout');
         return;
       }
       let settled = false;
       const timer = window.setTimeout(() => {
         if (settled) return;
         settled = true;
-        resolve(false);
+        resolve('timeout');
       }, PAINT_TICK_TIMEOUT_MS);
-      paintTickWaitersRef.current.push(() => {
+      paintTickWaitersRef.current.push((content) => {
         if (settled) return;
         settled = true;
         window.clearTimeout(timer);
-        resolve(true);
+        // A tick without content is NOT paint-ok: the rAF pipeline runs while
+        // the document is empty cream / never composited (Finding N reopen).
+        resolve(content ? 'content-verified' : 'tick-no-content');
       });
       contentWindow.postMessage({ source: EXT_APP_PAINT_PROBE_SOURCE, token: axToken }, '*');
     });
 
+  // Bounded wait for the frame's content oracle to turn green — the mount
+  // queue's release gate (guidance: never green-light the NEXT app while the
+  // previous document is still contentless; D-then-E was the repro).
+  const awaitContentVerified = async (maxMs: number): Promise<boolean> => {
+    const deadline = Date.now() + maxMs;
+    while (Date.now() < deadline && !unmountedRef.current) {
+      if ((await probePaint()) === 'content-verified') return true;
+      await new Promise((resolve) => window.setTimeout(resolve, 400));
+    }
+    return false;
+  };
+
   // Force a real layer reallocation: grow the iframe's box meaningfully for two
   // frames, then restore. Invisible under the paint-pending overlay.
   const runSoftExpandCycle = (): Promise<void> =>
@@ -638,29 +674,44 @@ export function ExtAppFrame({ node, expanded = false }: { node: CanvasNodeState;
   // 0.4.7). Say so in the trail instead of recording an unqualified success.
   const paintOkLabel = (suffix = ''): string =>
     typeof document !== 'undefined' && document.visibilityState === 'hidden'
-      ? `paint-ok${suffix} (unverified: host hidden)`
-      : `paint-ok${suffix}`;
+      ? `paint-ok (content-verified)${suffix} (host hidden)`
+      : `paint-ok (content-verified)${suffix}`;
 
   const runPaintLadder = async (): Promise<void> => {
-    if (expanded) return;
+    // Runs for the EXPANDED instance too (Finding N reopen: expanded C was a
+    // black frame with no recovery — the ladder used to early-return here).
     if (typeof navigator === 'undefined' || typeof window === 'undefined') return;
     if (!isWebKitOnlyHost(navigator.userAgent)) return;
     setPaintPending(true);
-    if (await probePaint()) {
+    let verdict = await probePaint();
+    if (verdict === 'content-verified') {
       extAppRecoveryLog(nodeId, paintOkLabel());
       setPaintPending(false);
       maybeAssumeVisibleRearm();
       return;
     }
-    extAppRecoveryLog(nodeId, 'paint-fail');
+    extAppRecoveryLog(
+      nodeId,
+      verdict === 'tick-no-content' ? 'paint-fail (tick without content)' : 'paint-fail (no tick)',
+    );
     await runSoftExpandCycle();
-    if (await probePaint()) {
+    verdict = await probePaint();
+    if (verdict === 'content-verified') {
       extAppRecoveryLog(nodeId, paintOkLabel(' (after soft-expand)'));
       setPaintPending(false);
       maybeAssumeVisibleRearm();
       return;
     }
     if (unmountedRef.current) return;
+    // A contentless-but-alive app may still be DRAWING its scene: give the
+    // oracle a bounded settle before burning a remount attempt on it.
+    if (verdict === 'tick-no-content' && (await awaitContentVerified(3_000))) {
+      extAppRecoveryLog(nodeId, paintOkLabel(' (after content wait)'));
+      setPaintPending(false);
+      maybeAssumeVisibleRearm();
+      return;
+    }
+    if (unmountedRef.current) return;
     // The remounted frame re-enters this ladder from its own settle path.
     if (!scheduleWebkitRemount('paint-fail')) {
       extAppRecoveryLog(nodeId, 'recovery-exhausted');
@@ -709,7 +760,8 @@ export function ExtAppFrame({ node, expanded = false }: { node: CanvasNodeState;
   // serialized queue (bounded by the shared attempt cap).
   const WEBKIT_BOOT_WATCHDOG_MS = 6000;
   useEffect(() => {
-    if (expanded) return;
+    // Covers the expanded instance too — its fresh iframe was black with no
+    // recovery at all (Finding N reopen, expanded C).
     if (typeof navigator === 'undefined' || typeof window === 'undefined') return;
     if (!isWebKitOnlyHost(navigator.userAgent)) return;
     if (!iframeDocument.ready || !mountGranted) return;
@@ -725,7 +777,7 @@ export function ExtAppFrame({ node, expanded = false }: { node: CanvasNodeState;
     () => () => {
       unmountedRef.current = true;
       for (const waiter of bootWaitersRef.current.splice(0)) waiter();
-      for (const waiter of paintTickWaitersRef.current.splice(0)) waiter();
+      for (const waiter of paintTickWaitersRef.current.splice(0)) waiter(false);
     },
     [],
   );
@@ -1035,8 +1087,22 @@ export function ExtAppFrame({ node, expanded = false }: { node: CanvasNodeState;
             // its own settle pause covering the draw) only from this genuine path;
             // the bootstrap fallback never releases it (a dead iframe must run the
             // queue's bounded timeout instead of green-lighting the next remount).
-            extAppRecoveryLog(nodeId, 'settled');
-            for (const waiter of bootWaitersRef.current.splice(0)) waiter();
+            // Release the mount queue only once this document's CONTENT
+            // oracle is green (bounded): a settled-but-empty app must not
+            // green-light the next mount slot (D-then-E repro, Finding N
+            // reopen). WebKit only — elsewhere the oracle race doesn't exist.
+            const releaseQueue = () => {
+              for (const waiter of bootWaitersRef.current.splice(0)) waiter();
+            };
+            if (typeof navigator !== 'undefined' && isWebKitOnlyHost(navigator.userAgent)) {
+              void awaitContentVerified(4_000).then((verified) => {
+                extAppRecoveryLog(nodeId, verified ? 'settled (content-verified)' : 'settled (content-timeout)');
+                releaseQueue();
+              });
+            } else {
+              extAppRecoveryLog(nodeId, 'settled');
+              releaseQueue();
+            }
             nudgeHostContextAfterLayout();
             schedulePaintLadder();
           })

package/src/client/state/canvas-store.ts

@@ -9,7 +9,7 @@ import {
   type ViewportState,
 } from '../types';
 import { computeAutoArrange } from '../../shared/auto-arrange';
-import { canvasAreaCenter } from '../canvas/canvas-area';
+import { canvasAreaCenter, canvasFitInsets } from '../canvas/canvas-area';
 import { pushCanvasUpdate, requestBestEffort, requestOk, updateViewportFromClient } from './intent-bridge';
 
 function logCanvasStoreError(action: string, error: unknown): void {
@@ -808,16 +808,22 @@ export function fitAll(containerW: number, containerH: number): void {
     maxY = Math.max(maxY, n.position.y + n.size.height);
   }
 
-  const PAD = 60;
-  const worldW = maxX - minX + PAD * 2;
-  const worldH = maxY - minY + PAD * 2;
-  const scale = Math.min(1, Math.min(containerW / worldW, containerH / worldH));
+  // Screen-space fit (architecture rule 9): the margins that must clear the
+  // floating chrome are SCREEN constants. The old world-space PAD shrank with
+  // the fit zoom, parking fitted nodes under the command bar and minimap
+  // (0.5.0 Amp report, finding A).
+  const insets = canvasFitInsets();
+  const usableW = Math.max(80, containerW - insets.left - insets.right);
+  const usableH = Math.max(80, containerH - insets.top - insets.bottom);
+  const worldW = Math.max(1, maxX - minX);
+  const worldH = Math.max(1, maxY - minY);
+  const scale = Math.min(1, Math.min(usableW / worldW, usableH / worldH));
   const cx = (minX + maxX) / 2;
   const cy = (minY + maxY) / 2;
 
   animateViewport({
-    x: containerW / 2 - cx * scale,
-    y: containerH / 2 - cy * scale,
+    x: insets.left + usableW / 2 - cx * scale,
+    y: insets.top + usableH / 2 - cy * scale,
     scale,
   });
 }

package/src/client/theme/global.css

@@ -1632,7 +1632,9 @@ body,
   flex-wrap: nowrap;
   gap: 1px;
   margin: 2px -12px 8px;
-  padding: 0 10px;
+  /* Compact panels (Amp portal, 0.5.0 report B): six chips overflowed the
+     row by 11px — tighter inset + chip padding buys ~16px back. */
+  padding: 0 8px;
   overflow-x: auto;
   scrollbar-width: none;
 }
@@ -1651,7 +1653,7 @@ body,
 }
 .session-timeline-filters .activity-filter {
   flex-shrink: 0;
-  padding: 2px 5px;
+  padding: 2px 4px;
 }
 
 .session-timeline-row {

package/src/server/canvas-operations.ts

@@ -1,6 +1,8 @@
 import { existsSync, readFileSync, statSync } from 'node:fs';
 import { basename, resolve } from 'node:path';
+import { agentPresence } from './agent-presence.js';
 import { recomputeCodeGraph } from './code-graph.js';
+import { diffLayouts } from './mutation-history.js';
 import {
   canvasState,
   type CanvasEdge,
@@ -1396,6 +1398,30 @@ export function listCanvasSnapshots(options?: Parameters<typeof canvasState.list
   return canvasState.listSnapshots(options);
 }
 
+/**
+ * Snapshot save with unchanged-board reuse — the ONE path every surface must
+ * take (op registry, SDK). The SDK once called saveCanvasSnapshot directly and
+ * stacked identical snapshots the HTTP/MCP path deduplicated (0.5.0 Codex
+ * finding V).
+ */
+export function saveCanvasSnapshotWithReuse(name: string): { snapshot: CanvasSnapshot | null; reused: boolean } {
+  const newest = canvasState.listSnapshots({ limit: 1 })[0];
+  if (newest) {
+    const newestData = canvasState.getSnapshotData(newest.id);
+    if (newestData) {
+      const diff = diffLayouts(newestData.name, newestData, canvasState.getLayout());
+      const identical =
+        diff.addedNodes.length === 0 &&
+        diff.removedNodes.length === 0 &&
+        diff.modifiedNodes.length === 0 &&
+        diff.addedEdges.length === 0 &&
+        diff.removedEdges.length === 0;
+      if (identical) return { snapshot: newest, reused: true };
+    }
+  }
+  return { snapshot: saveCanvasSnapshot(name), reused: false };
+}
+
 export function saveCanvasSnapshot(name: string): CanvasSnapshot | null {
   return canvasState.saveSnapshot(name);
 }
@@ -1748,7 +1774,7 @@ export function getClientViewportSize(): { width: number; height: number } | nul
 export function fitCanvasView(options: CanvasFitViewOptions = {}): CanvasFitViewResult {
   const width = positiveNumber(options.width, lastClientViewportSize?.width ?? 1440);
   const height = positiveNumber(options.height, lastClientViewportSize?.height ?? 900);
-  const padding = positiveNumber(options.padding, 60);
+  const padding = positiveNumber(options.padding, 24); // screen px now, not world units
   const maxScale = positiveNumber(options.maxScale, 1);
   const nodeIdFilter = options.nodeIds && options.nodeIds.length > 0 ? new Set(options.nodeIds) : null;
   const targetNodes = canvasState.getLayout().nodes.filter((node) => !nodeIdFilter || nodeIdFilter.has(node.id));
@@ -1770,14 +1796,23 @@ export function fitCanvasView(options: CanvasFitViewOptions = {}): CanvasFitView
   }
 
   const bounds = { x: minX, y: minY, width: maxX - minX, height: maxY - minY };
-  const worldWidth = Math.max(1, bounds.width + padding * 2);
-  const worldHeight = Math.max(1, bounds.height + padding * 2);
-  const scale = Math.min(maxScale, width / worldWidth, height / worldHeight);
+  // Screen-space fit (architecture rule 9): `padding` and the chrome reserve
+  // are SCREEN pixels — world-space padding shrank with the fit zoom and
+  // parked nodes under the command bar and minimap (0.5.0 Amp report,
+  // finding A). The server cannot measure the client's chrome, so it reserves
+  // nominal bottom space: the minimap is always there; the command bar only
+  // while a session is attached.
+  const bottomReserve = agentPresence.snapshot().sessionActive ? 128 : 96;
+  const usableWidth = Math.max(80, width - padding * 2);
+  const usableHeight = Math.max(80, height - padding - bottomReserve);
+  const worldWidth = Math.max(1, bounds.width);
+  const worldHeight = Math.max(1, bounds.height);
+  const scale = Math.min(maxScale, usableWidth / worldWidth, usableHeight / worldHeight);
   const centerX = minX + bounds.width / 2;
   const centerY = minY + bounds.height / 2;
   const viewport = {
-    x: width / 2 - centerX * scale,
-    y: height / 2 - centerY * scale,
+    x: padding + usableWidth / 2 - centerX * scale,
+    y: padding + usableHeight / 2 - centerY * scale,
     scale,
   };
 

package/src/server/index.ts

@@ -59,7 +59,7 @@ import {
   removeCanvasEdge,
   resolveHtmlContent,
   restoreCanvasSnapshot,
-  saveCanvasSnapshot,
+  saveCanvasSnapshotWithReuse,
   scheduleCodeGraphRecompute,
   syncCanvasRuntimeBackends,
   setCanvasContextPins,
@@ -1072,7 +1072,9 @@ export class PmxCanvas extends EventEmitter {
   }
 
   saveSnapshot(name: string) {
-    return saveCanvasSnapshot(name);
+    // Same reuse path as HTTP/MCP: an unchanged board returns the existing
+    // newest snapshot instead of stacking an identical copy (Codex finding V).
+    return saveCanvasSnapshotWithReuse(name).snapshot;
   }
 
   async restoreSnapshot(id: string): Promise<{ ok: boolean }> {

package/src/server/operations/ops/nodes.ts

@@ -422,6 +422,13 @@ export function createBasicCanvasNode(
         : '"path" is only an image-node compatibility alias — use `content`.',
     );
   }
+  // Docking was removed in 0.5.0 — a create that still sends it silently
+  // succeeded and read as "docking works" (0.5.0 Copilot report, PASS-ish).
+  if (body.dockPosition !== undefined) {
+    throw new OperationError(
+      'Unknown field "dockPosition" — docking was removed in 0.5.0; use `position` and `pinned`.',
+    );
+  }
   const content =
     type === 'image' && typeof body.path === 'string' && typeof body.content !== 'string' ? body.path : body.content;
   // For html nodes, accept top-level `html` AND `axCapabilities` and merge into data
@@ -496,6 +503,11 @@ export function buildNodePatch(
   if (body.src !== undefined) {
     throw new OperationError('Unknown field "src" — update the image source via `content`.');
   }
+  if (body.dockPosition !== undefined) {
+    throw new OperationError(
+      'Unknown field "dockPosition" — docking was removed in 0.5.0; use `position` and `pinned`.',
+    );
+  }
   if (body.path !== undefined && existing.type !== 'image') {
     if (existing.type === 'file') {
       // Repoint: `path` on a file-node patch moves the node to another file

package/src/server/operations/ops/snapshots.ts

@@ -29,9 +29,9 @@ import {
   gcCanvasSnapshots,
   listCanvasSnapshots,
   restoreCanvasSnapshot,
-  saveCanvasSnapshot,
+  saveCanvasSnapshotWithReuse,
 } from '../../canvas-operations.js';
-import { diffLayouts, formatDiff } from '../../mutation-history.js';
+import { formatDiff, diffLayouts } from '../../mutation-history.js';
 import { defineOperation, OperationError, type Operation } from '../types.js';
 import { isRecord } from './nodes.js';
 
@@ -129,24 +129,11 @@ const snapshotSaveOperation = defineOperation<z.infer<typeof snapshotSaveSchema>
     const name = typeof input.name === 'string' ? input.name.trim() : '';
     if (!name) throw new OperationError('Missing snapshot name');
     // A save of an unchanged board reuses the newest snapshot instead of
-    // stacking an identical copy in the History drawer.
-    const newest = canvasState.listSnapshots({ limit: 1 })[0];
-    if (newest) {
-      const newestData = canvasState.getSnapshotData(newest.id);
-      if (newestData) {
-        const diff = diffLayouts(newestData.name, newestData, canvasState.getLayout());
-        const identical =
-          diff.addedNodes.length === 0 &&
-          diff.removedNodes.length === 0 &&
-          diff.modifiedNodes.length === 0 &&
-          diff.addedEdges.length === 0 &&
-          diff.removedEdges.length === 0;
-        if (identical) return { ok: true, id: newest.id, snapshot: newest, reused: true };
-      }
-    }
-    const snapshot = saveCanvasSnapshot(name);
+    // stacking an identical copy — via the ONE shared path the SDK uses too
+    // (0.5.0 Codex finding V).
+    const { snapshot, reused } = saveCanvasSnapshotWithReuse(name);
     if (!snapshot) throw new OperationError('Failed to save snapshot');
-    return { ok: true, id: snapshot.id, snapshot };
+    return { ok: true, id: snapshot.id, snapshot, ...(reused ? { reused: true } : {}) };
   },
 });