pmx-canvas 0.4.5 → 0.4.7

package/docs/node-types.md

@@ -14,7 +14,9 @@ see [MCP tools](mcp.md), [HTTP API](http-api.md), and [SDK](sdk.md).
 | `context` | Context cards, token usage, workspace grounding |
 | `ledger` | Execution ledger summary |
 | `trace` | Agent trace pills (tool calls, subagent activity) |
-| `file` | Live file viewer with auto-update on disk changes |
+| `file` | Live file viewer with auto-update on disk changes — also renders CSV/TSV as tables and PDFs inline |
+| `diff` | Unified diff viewer: per-file headers, hunk rows, +/− colored lines |
+| `mermaid` | Mermaid diagram rendered client-side from text (flowchart, sequence, state, …) |
 | `image` | Image viewer (file paths, data URIs, URLs) |
 | `webpage` | Persisted webpage snapshot with stored URL, extracted text, refresh |
 | `mcp-app` | Tool-backed hosted MCP App iframes (Excalidraw, etc.) |
@@ -48,6 +50,20 @@ automatically via `fs.watch()`.
 canvas_node({ action: 'add', type: 'file', content: 'src/server/index.ts' })
 ```
 
+The same node type handles non-source files, so you never have to pick a
+different type by extension:
+
+- **`.csv` / `.tsv`** render as a real table (quoted fields, embedded newlines,
+  and escaped quotes are parsed properly) instead of raw delimited text. Very
+  long files render a bounded number of rows and say how many were omitted.
+- **`.pdf`** renders in an embedded viewer, served from
+  `GET /api/canvas/file-bytes?nodeId=…`. In hosts that block src-URL iframes
+  (Amp orb portals) the node offers an "Open PDF" link instead of a blank frame.
+- **Other binary files** show a placeholder with the name and size rather than
+  decoding bytes into mojibake.
+- **Text files over 2 MB** render truncated with a banner saying so, so a huge
+  log can never exhaust memory.
+
 ## Image nodes
 
 Image nodes display local paths, remote URLs, and data URIs. File-backed and
@@ -219,6 +235,36 @@ component gallery, interaction prototype, flowchart, SVG illustration set,
 presentation, explainer, status report, incident report, triage board, config
 editor, or prompt tuner.
 
+Two kinds are **live AX control surfaces** rather than static documents, and are
+the only primitives created with AX enabled:
+
+- **`ax-board`** — give the agent tasks, watch their status change as it works,
+  send steering, and run a bounded task loop. Task rows read from live AX state,
+  so a status the agent sets anywhere shows up here.
+- **`ax-flow`** — the same controls drawn as a task flow with an explicit
+  loop-back rail, plus **Materialize to board**: the flow is laid out as real
+  canvas nodes joined by `flow` edges (and a dashed `references` loop edge),
+  each linked to a work item so the node's status chip tracks progress.
+  Re-materializing replaces the previous flow instead of duplicating it.
+
+A steer emitted from either surface is *queued* on the timeline — it reaches the
+agent on its next turn rather than waking it. Both stop their loop if the panel
+reloads; the work items are the durable record.
+
+### The flow on ordinary nodes
+
+You do not need the panel to drive a flow. A materialized step node carries
+`data.axStep`, and the canvas renders native controls on it — **Start / Done /
+Blocked** on every step, plus **Run loop / Stop** and a steer box on the first
+one. These are canvas chrome, not sandboxed content, so they work on any node
+type carrying the stamp.
+
+The native loop runs **server-side**, which is the one real difference from the
+panel: it advances when a step's work item is completed, survives a browser
+reload, and keeps going while the tab is closed. Same bounds either way — it only
+advances while running, stops at its run cap (hard limit 20), and Stop is
+persisted immediately. `blocked` or `cancelled` halts it without disarming.
+
 ```ts
 canvas_node({
   action: 'add',

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pmx-canvas",
-  "version": "0.4.5",
-  "description": "Spatial canvas workbench for coding agents \u2014 infinite 2D canvas with agent-native CLI, MCP integration, nodes, edges, file watching, and snapshots",
+  "version": "0.4.7",
+  "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",
   "module": "./src/server/index.ts",
@@ -32,7 +32,7 @@
     "dev:demo": "bun run src/cli/index.ts --demo",
     "dev:portless": "portless run --name pmx --app-port 4313 bun run src/cli/index.ts --no-open --port=4313",
     "dev:portless:demo": "portless run --name pmx --app-port 4313 bun run src/cli/index.ts --no-open --port=4313 --demo",
-    "build:client": "bun build src/client/index.tsx --outdir dist/canvas --minify && cp src/client/theme/global.css dist/canvas/global.css && cp src/client/theme/surface-theme.css dist/canvas/surface-theme.css",
+    "build:client": "bun build src/client/index.tsx --outdir dist/canvas --minify && bun build src/client/mermaid-entry.ts --outdir dist/canvas --minify && cp src/client/theme/global.css dist/canvas/global.css && cp src/client/theme/surface-theme.css dist/canvas/surface-theme.css",
     "build:json-render": "bash scripts/build-json-render.sh",
     "build:types": "tsc -p tsconfig.types.json",
     "build": "bun run build:client && bun run build:json-render && bun run build:types",
@@ -46,7 +46,7 @@
     "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: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:coverage": "PMX_MCP_APP_HOST_STATE_FILE=/tmp/pmx-canvas-test-app-host-state.json bun test tests/unit --coverage --coverage-reporter=text --coverage-reporter=lcov --coverage-dir coverage && bun scripts/check-coverage.ts",
+    "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",
     "test:e2e-cli": "bash scripts/e2e-cli-coverage.sh",
@@ -68,6 +68,7 @@
     "@modelcontextprotocol/sdk": "^1.0.0",
     "@preact/signals": "^2.0.0",
     "marked": "^15.0.0",
+    "mermaid": "^11.16.1",
     "preact": "^10.25.0",
     "react": "^19.2.3",
     "react-dom": "^19.2.3",

package/skills/pmx-canvas/SKILL.md

@@ -52,6 +52,10 @@ Humans curate agent context by pinning nodes; agents read that curation through
 6. **Mutate through current composites.** Prefer the 16 composite MCP tools below.
 7. **Arrange and validate.** After batch changes, use `canvas_view { action: "arrange" }` when
    appropriate and always finish with `canvas_query { action: "validate" }`.
+7b. **Show the human.** After creating user-facing output, bring the camera to it: a single node
+   gets `canvas_view { action: "focus", id }` (pans by default), a small cluster gets
+   `canvas_view { action: "fit", nodeIds: [...] }` with exactly the new ids. See
+   **In-View Placement & Sizing** below — auto-placement is board-relative, not camera-relative.
 8. **Verify context pins.** Pin with `canvas_pin_nodes` or the browser's **Pin as context**, then
    read `canvas://pinned-context`.
 9. **Clean up temporary nodes.** Remove retry/test fixtures and restore the baseline snapshot when
@@ -67,6 +71,10 @@ pmx-canvas serve status
 ```
 
 Both surfaces report `workspace`. It must match the intended workspace root.
+For a full environment check in one command (health + workspace, CLI/server
+version skew, MCP initialize handshake, temp-node create/search/remove
+round-trip, board validation), run `pmx-canvas smoke` (0.4.6+) — JSON report,
+exit 1 on failure.
 
 - If `responsive: true` but `pidRunning: false`, treat the listener as potentially stale.
 - On mismatch, do not mutate. Start the intended workspace on an explicit free port:
@@ -97,14 +105,21 @@ Both surfaces report `workspace`. It must match the intended workspace root.
 | Persistent context cards | `context` via `canvas_node` |
 | Event/check stream | `ledger` or `trace` via `canvas_node` |
 | Local source with live updates | `file` via `canvas_node` |
+| Tabular data (`.csv`/`.tsv`), a PDF, or any other file on disk (0.4.6+) | `file` via `canvas_node` — CSV/TSV render as tables, PDFs render inline, other binaries show a size placeholder. Never paste a CSV into a markdown fence. |
+| Code review / unified diff (0.4.6+) | `diff` via `canvas_node` (content = diff text; link to its file node with a `references` edge) |
+| Flowchart / sequence / state diagram (0.4.6+) | `mermaid` via `canvas_node` (content = mermaid source; renders client-side, no hosted app) |
 | Image | `image` via `canvas_node` |
 | Cached URL content | `webpage` via `canvas_node` |
 | Structured UI | `json-render` via `canvas_render` |
 | Chart | `graph` via `canvas_render` |
+| Live work-item board (0.4.6+) | `canvas_render { action: "workboard" }` — one board node, auto-refreshes on work-item changes |
 | Generated communication surface | HTML primitive via `canvas_node` |
+| Give the agent tasks + watch progress + loop (0.4.7+) | `ax-board` HTML primitive — a live AX control surface, created AX-enabled |
+| The same, drawn as a task flow, and materializable to real nodes+edges (0.4.7+) | `ax-flow` HTML primitive — **Materialize to board** lays the steps out as nodes joined by `flow` edges with a loop-back edge, each linked to a work item |
+| Drive a flow WITHOUT the panel (0.4.7+) | Materialized step nodes carry native Start/Done/Blocked controls, and the anchor adds Run loop/Stop + steer. The native loop runs server-side, so it survives a browser reload and keeps advancing while the tab is closed. |
 | Self-contained HTML/JS | `html` via `canvas_node` |
 | Hosted interactive MCP app | `canvas_app { action: "open-mcp-app" }` |
-| Excalidraw diagram | `canvas_app { action: "diagram" }` |
+| Excalidraw diagram (interactive/human drawing) | `canvas_app { action: "diagram" }` — prefer `mermaid` for agent-authored diagrams |
 | Bundled React artifact | `canvas_app { action: "build-artifact" }` |
 
 Use the lightest tier that communicates the result. Do not build a web artifact when markdown,
@@ -164,6 +179,48 @@ v0.4.0 after their deprecated 0.3.x window.
 - Edge types: `flow`, `depends-on`, `relation`, `references`.
 - After manual or batch layout changes, run `canvas_query { action: "validate" }`.
 
+## In-View Placement & Sizing (required for user-facing nodes)
+
+Auto-placement (omitting `x`/`y`) is **board-relative, not camera-relative**: it places right of
+the last node or scans rows from the origin, ignoring where the human is looking. On a board with
+distant nodes, an auto-placed node lands off-camera.
+
+1. Omit `x`/`y` only on an empty or locally dense board. Otherwise place near the human's
+   attention: the pinned/focused neighborhood, or explicit coordinates beside the last
+   user-facing output (gap ≥ 24–48 px).
+2. After creating nodes the human should see, pan the camera (operating-sequence step 7b):
+   `focus` for one node, `fit` with exactly the new `nodeIds` for a cluster. Use `noPan`
+   (`focus --no-pan`) only when you must not steal the camera.
+3. Never fit the whole board to "show" new work — on a board with outliers that miniaturizes
+   everything. Always pass explicit `nodeIds` to `fit`.
+4. Never leave user-facing output at far coordinates without a focus/fit.
+5. **Do not hand-compute a whole board's coordinates.** Create the nodes (omitting x/y), then
+   `canvas_view { action: "arrange", layout: "grid" | "column" | "flow" }` and finish with a
+   `fit` over the new ids. Manual pixel math is what produces long-line, unbalanced boards.
+6. `fit` sizes itself to the connected browser window (0.4.6+) — you do not need to guess
+   `width`/`height`. Pass them only to fit for a window other than the human's.
+7. **Docking is explicit (0.4.6+).** Nodes render on the canvas where you put them; a node is
+   only a HUD pill if you set `dockPosition`. An edge whose endpoint is docked cannot be drawn —
+   `validate` reports it as `hiddenEdgeEndpoints` and fails `ok`, because the edge visually
+   trails off into empty canvas.
+
+**Size for content.** Omitting `width`/`height` gives readable per-type defaults — prefer them:
+markdown 640×420, status 360×200, file 520×360, diff 640×420, mermaid 640×460, html 720×640,
+graph 760×520, mcp-app 960×600, web-artifact 960×720. A *hosted* app opened with
+`canvas_app { action: "open-mcp-app" | "diagram" }` — including the Excalidraw diagram preset — is
+the exception: it opens at 720×500, not 960×600 (960×600 is the default for an `mcp-app` node you
+create directly). Pass `width`/`height` to that action when you want a bigger diagram tile.
+Since 0.4.6 the server clamps explicit creation sizes UP to per-type
+readability floors (e.g. markdown 360×180, graph/json-render/html 420×280, mcp-app 480×320) —
+a tiny probe size silently becomes the floor. `strictSize: true` is the only opt-out (a fixed
+scrolling frame you genuinely want small). `canvas_query { action: "validate" }` additionally
+reports any node below its floor as an advisory `sizeWarnings` entry — treat a non-empty list
+as layout work left to do.
+
+**Token hygiene.** For routine state checks use `canvas_ax_state { action: "get" }` WITHOUT
+`includeContext` — the full AX context payload is ~10× larger; request it only when you are
+actually consuming context.
+
 ## Context Pins
 
 Context pins are the primary human-to-agent bridge:
@@ -218,6 +275,49 @@ or host actions.
 Read [AX HTML control surfaces](references/ax-html-control-surface.md) before building an
 interactive AX-enabled HTML node.
 
+### Ready-made control surfaces (0.4.7+) — prefer these over hand-rolling
+
+Two HTML primitives ship AX-enabled, so you do not need to author a control surface or pass
+`axCapabilities` yourself. They are the ONLY primitives created with AX on; every other kind is
+still a static document.
+
+- **`ax-board`** — task list: create tasks, watch status change live, steer, bounded loop.
+- **`ax-flow`** — the same controls drawn as a task flow with a loop-back rail, plus
+  **Materialize to board**.
+
+**`ax.flow.materialize`** is the one interaction that creates canvas nodes, and it is deliberately
+narrow: you supply TEXT ONLY (<= 12 steps, title <= 120 chars) and the server owns the result —
+one `markdown` node per step, `flow` edges between them, a dashed `references` loop edge, and one
+work item per step linked to its node. Re-materializing REPLACES the previous flow (the source
+node keeps a manifest of what it created), so it is safe to call repeatedly.
+
+**The flow also works without the panel.** Materialized step nodes carry `data.axStep`, and the
+canvas renders native Start / Done / Blocked controls on them, with Run loop / Stop and a steer box
+on the anchor (first) step. Those controls also follow the node into focus mode. The native loop
+runs **server-side**: it advances when a step's work item completes, survives a browser reload, and
+keeps going while the tab is closed — unlike the panel's loop, which dies with the iframe. Bounds
+are the same either way: advances only while running, hard cap 20 runs, Stop persists immediately,
+and `blocked`/`cancelled` halts it.
+
+When you want the agent to work through a checklist the human can watch and steer, reach for
+`ax-flow` + materialize rather than a markdown to-do list — the status chips and the loop come free.
+
+### Working a flow: keep the board honest as you go
+
+A materialized flow is only useful if it tracks reality. While you work one:
+
+1. **Move the step to `in-progress` BEFORE you start it, and to `done` when it is actually done** —
+   not in a batch at the end. The human is watching the chips to know where you are; a board that
+   only updates on completion tells them nothing while it matters.
+2. **Pin the in-progress step as context** (`canvas_pin_nodes` with just that node, or
+   `POST /api/canvas/context-pins` mode `set`). This makes the active step the one thing in
+   `canvas://pinned-context`, so the board's "what am I working on" and your own context are the
+   same answer instead of drifting apart. Re-pin as you advance.
+3. **Mark `blocked` rather than going quiet** when you are stuck — a stalled `in-progress` chip is
+   indistinguishable from a crashed agent.
+4. Read steering back with `canvas_ax_delivery` as you go; a human watching a live flow steers
+   mid-run, and a steer you never claim is a correction you ignored.
+
 ## Resources
 
 Read the smallest resource that answers the question:
@@ -245,24 +345,21 @@ Prefer `canvas_query { action: "search" }` over parsing the full layout.
   renders the same content and theme, but `window.PMX_AX` is not injected without the canvas
   iframe's per-mount nonce, so AX buttons only work inside the in-canvas node (0.4.4 Codex note).
   Do not tell a user a standalone tab's controls will steer the agent.
-- A hosted ext-app (Excalidraw) node that is already on the board when a **WebKit** host panel
-  loads (e.g. the GitHub Copilot app's embedded WKWebView) can render as a black tile — a host
-  compositor paint race on the nested iframe, **not** a broken node (the session is healthy and
-  `sessionStatus` is `ready`; it renders fine in Chrome, the Codex browser, and for nodes created
-  live after the panel hydrates). Under WebKit the canvas ATTEMPTS auto-recovery: after boot,
-  each present-at-load ext-app is remounted through a serialized, boot-aware queue (one app at a
-  time), with a watchdog retry for iframes that never boot and a re-arm when a panel that loaded
-  hidden becomes visible. Treat the auto-recovery as best-effort, NOT guaranteed — the 0.3.2
-  Copilot-host report shows tiles can still come up black in real WKWebView panels (compositing
-  success is not observable from page JS, so retries are bounded). Since 0.4.1 the canvas also
-  fires a post-boot **repaint nudge** under WebKit (a 1px layout bounce that forces the
-  compositor to re-rasterize the frame — the cheap half of the proven enlarge-close unstick;
-  shows as `repaint-nudge` in the recovery trail). Keep the cautionary behavior anyway:
-  recovery is deterministic via **expand-then-close** of the black tile (forces a fresh mount in
-  the fullscreen overlay, which always paints), or open the workbench in a normal browser
-  (Chrome). Do not diagnose a healthy app session as a broken node. When reporting a black tile,
-  fetch `GET /api/canvas/debug/ext-app-recovery` from the daemon and attach the trace — it shows
-  what the recovery queue actually did in that panel.
+- A hosted ext-app (Excalidraw) node in a **WebKit** host panel (e.g. the GitHub Copilot app's
+  embedded WKWebView) historically could render as a black tile — a host compositor paint race
+  on the nested iframe, **not** a broken node (the session is healthy, `sessionStatus` is
+  `ready`, and it renders fine in Chrome/Codex). Since 0.4.6 the canvas runs a **paint oracle +
+  recovery ladder** under WebKit: present-at-load ext-apps mount strictly one at a time (the
+  cold burst was the trigger), each frame answers a double-rAF **paint probe** after settle, and
+  on silence the ladder escalates — soft-expand cycle (the automatic analogue of the proven
+  enlarge+close) → serialized remount → an explicit "App surface failed to paint / Retry"
+  affordance. The connecting overlay stays up until paint is confirmed, so a black layer is
+  never presented as ready. The recovery trail
+  (`GET /api/canvas/debug/ext-app-recovery` / `window.__PMX_EXTAPP_LOG`) now records
+  `mount-slot`, `paint-ok`, `paint-fail`, `soft-expand-cycle`, and `recovery-exhausted` — when
+  diagnosing, trust `paint-ok`/`paint-fail`, and never assert health from `settled` alone. If a
+  tile still shows the Retry affordance, click Retry (fresh recovery budget) or expand-then-close;
+  attach the recovery trail when reporting.
 - Ext-app frame documents live in server memory. Through 0.4.0, killing/restarting the daemon
   while a panel stays open leaves ext-app tiles on dead frame URLs (`Frame document not found`,
   0.4.0 report Finding S) until a full workbench reload. Since 0.4.1 the browser revalidates its
@@ -271,8 +368,8 @@ Prefer `canvas_query { action: "search" }` over parsing the full layout.
 - A hosted ext-app (Excalidraw) resized NARROW/TALL (e.g. 360x529) can show its diagram in the
   upper region with the app's own dark fill below it — in every engine (0.3.4 report Finding Q).
   This letterboxing lives inside the hosted app bundle's root container, not in PMX (a body-level
-  background override ships but cannot reach the app's inner root). Keep ext-app tiles near the
-  app's aspect (the 960x738 default, or the same ratio), or expand the node — the fullscreen
+  background override ships but cannot reach the app's inner root). Keep ext-app tiles landscape —
+  at or above the 720x500 they open at, or the same ratio — or expand the node: the fullscreen
   overlay renders full-bleed. The durable fix is upstream in the excalidraw-mcp app.
 - Behind proxies that buffer streaming responses (e.g. portal hosts), the workbench auto-falls
   back from SSE to a polling transport within ~3s, so the board still boots and stays live.
@@ -290,10 +387,11 @@ Prefer `canvas_query { action: "search" }` over parsing the full layout.
   URLs cannot be inlined (cross-origin) and may stay blocked in such hosts. Force a mode with
   `/workbench?iframe-mode=srcdoc` (or `iframe-mode=src`) when diagnosing.
 - Graph and json-render standalone surfaces use `display=site` and fill the browser viewport, and
-  reflow on a live window resize in a normal browser. Some single-tab host browsers historically
-  didn't deliver live-resize events (current Codex builds do — the 0.4.0 retest saw a standalone
-  graph reflow on a native viewport resize), so if a resized standalone chart looks stale,
-  reload it or use a system browser for separate full-page viewing.
+  reflow on a live window resize. Some single-tab host browsers historically didn't deliver
+  live-resize events; current Codex builds do — the 0.4.6 pass watched a standalone graph reflow
+  live (SVG 1550×783 → 850×483 on a 1600×900 → 900×600 window resize) with no reload. Do not
+  present a system browser as a workaround for stale resizing; it is only a preference for viewing
+  a full page beside the canvas.
 - Some hosts cannot automate inside sandboxed workbench iframes. Verify those interactions in a
   system browser or through server-side AX state.
 - `pmx-canvas screenshot` requires an active WebView. Start it with

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

@@ -417,7 +417,7 @@
       "id": 17,
       "name": "standalone-surface-open-as-site",
       "prompt": "Open the bar-chart graph node as a standalone full-page site for a screenshot, and also try to open the Excalidraw diagram node the same way. Tell me the correct surface URL for each.",
-      "expected_output": "For the graph/json-render node, uses the stable surface URL /api/canvas/surface/<id> which redirects to the full-viewport display=site viewer (reads surfaceUrl from the node, does not fabricate a path). Recognizes the hosted Excalidraw/ext-app node is NOT an open-as-site target (its surface route returns a clean 404 \u2014 it renders only with the in-canvas host bridge) and does not claim a standalone tab will work. Notes that some host browsers (e.g. the Codex in-app single-tab browser) don't deliver live-resize events, so a system browser is recommended for separate full-page viewing.",
+      "expected_output": "For the graph/json-render node, uses the stable surface URL /api/canvas/surface/<id> which redirects to the full-viewport display=site viewer (reads surfaceUrl from the node, does not fabricate a path). Recognizes the hosted Excalidraw/ext-app node is NOT an open-as-site target (its surface route returns a clean 404 \u2014 it renders only with the in-canvas host bridge, and open-external refuses it with the same message) and does not claim a standalone tab will work. Describes the standalone surface as reflowing live on a window resize; does not claim host browsers leave a resized chart stale until reload, and does not prescribe a system browser as a workaround.",
       "assertions": [
         {
           "name": "graph-site-surface-url",
@@ -430,8 +430,59 @@
           "type": "output_check"
         },
         {
-          "name": "host-browser-caveat",
-          "description": "Recommends a system browser for separate full-page viewing and/or notes single-tab host browsers may not reflow on live resize",
+          "name": "no-stale-resize-claim",
+          "description": "Does not assert that host browsers fail to deliver live resize (current Codex builds do — the 0.4.6 pass saw a standalone graph reflow live with no reload); a system browser may be offered as a viewing preference, never as a resize workaround",
+          "type": "output_check"
+        }
+      ]
+    },
+    {
+      "id": 18,
+      "name": "in-view-placement-after-create",
+      "prompt": "The board already has a cluster of nodes from this morning, way off to the far right. Add a markdown summary of the incident and a status node for the follow-up, and make sure I can actually see them.",
+      "expected_output": "Places the new nodes near the human's attention (pinned/focused neighborhood or beside the last user-facing output) instead of trusting board-relative auto-placement on a spread-out board, then pans the camera: canvas_view {action:focus} for a single node, or canvas_view {action:fit, nodeIds:[...]} with exactly the new ids for the pair. Does not hand-compute the whole board's coordinates and does not fit the whole board to 'show' the new work — an outlier cluster would miniaturize everything.",
+      "assertions": [
+        {
+          "name": "ends-with-focus-or-fit",
+          "description": "Finishes with canvas_view {action:focus} (single node) or {action:fit} after creating the nodes, rather than leaving them off-camera",
+          "type": "output_check"
+        },
+        {
+          "name": "fit-targets-new-ids-only",
+          "description": "Passes exactly the new node ids to fit instead of fitting the whole board (a distant cluster would shrink everything)",
+          "type": "output_check"
+        },
+        {
+          "name": "no-whole-board-coordinate-math",
+          "description": "Places relative to the human's attention or uses create-then-arrange; does not hand-compute a full board layout in pixels",
+          "type": "output_check"
+        }
+      ]
+    },
+    {
+      "id": 19,
+      "name": "node-size-discipline",
+      "prompt": "Add a markdown write-up of the outage and a bar chart of the error counts. Keep them tight — I don't want huge tiles.",
+      "expected_output": "Omits width/height and takes the per-type defaults (markdown 640×420, graph 760×520) rather than passing small probe sizes for human-readable content. Uses strictSize:true only for a deliberately fixed small frame, not to dodge the floor. Reads the size back from the create result or the layout before any layout math, because the server clamps an undersized explicit frame UP to the per-type floor (markdown 360×180, graph 420×280) — the returned size can differ from what was requested.",
+      "assertions": [
+        {
+          "name": "uses-type-defaults",
+          "description": "Omits width/height (or passes a readable size) instead of guessing a frame for readable content",
+          "type": "output_check"
+        },
+        {
+          "name": "no-tiny-probe-sizes",
+          "description": "Does not create human-readable nodes at tiny probe sizes that the floor would silently raise",
+          "type": "output_check"
+        },
+        {
+          "name": "strict-size-only-when-deliberate",
+          "description": "Reaches for strictSize:true only for an intentionally fixed small frame, not as a way around the readability floor",
+          "type": "output_check"
+        },
+        {
+          "name": "reads-back-created-size",
+          "description": "Reads the actual created size from the create result / canvas_query layout before positioning or sizing anything else, rather than assuming the requested size was kept",
           "type": "output_check"
         }
       ]

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

@@ -952,12 +952,15 @@ the host's embedded browser (e.g. Codex) opens `_blank` tabs in-place.
   renders with the in-canvas host bridge — a bare tab has no peer, so the surface route
   returns `404` ("This MCP app renders in the canvas and cannot be opened as a standalone
   site"); view/edit them in the canvas, or open them externally through their own app
-  (report #61). Only bundled `web-artifact` apps (redirect to `/artifact`) and URL-backed
-  `mcp-app` / `webpage` viewers redirect to their external site.
+  (report #61). `POST /api/canvas/open-external` refuses those nodes with the same message
+  instead of launching a browser at a URL that 404s. Only bundled `web-artifact` apps
+  (redirect to `/artifact`) and URL-backed `mcp-app` / `webpage` viewers redirect to their
+  external site.
 - `graph` / `json-render` nodes redirect to the full-viewport `display=site` viewer; the chart
-  fills the window and reflows on a live resize in a normal browser. Single-tab host browsers
-  that don't deliver live-resize events (e.g. the Codex in-app browser) can leave a resized chart
-  stale until reload — recommend a system browser for separate full-page viewing (report #67).
+  fills the window and reflows on a live resize. Current Codex builds deliver live-resize events —
+  the 0.4.6 pass watched a standalone graph reflow live (SVG 1550×783 → 850×483 on a
+  1600×900 → 900×600 window resize) with no reload — so do not present a system browser as a
+  workaround for stale resizing (report #67).
 - This is additive — opening a site never evicts or replaces canvas nodes.
 
 ### Choosing the Right Visual Tier
@@ -1112,7 +1115,7 @@ AX interactions are gated per node type. The lists below are each type's **ceili
 
 | Node type | Allowed AX interaction types |
 |-----------|------------------------------|
-| `markdown` | `ax.steer`, `ax.work.create`, `ax.evidence.add`, `ax.command.invoke`, `ax.event.record` |
+| `markdown` | `ax.steer`, `ax.work.create`, `ax.work.update`, `ax.evidence.add`, `ax.command.invoke`, `ax.event.record` |
 | `context` | `ax.focus.set`, `ax.steer`, `ax.evidence.add`, `ax.command.invoke`, `ax.event.record` |
 | `status` | `ax.work.create`, `ax.work.update`, `ax.approval.request`, `ax.mode.request`, `ax.event.record` |
 | `file` | `ax.evidence.add`, `ax.review.add`, `ax.focus.set`, `ax.event.record` |
@@ -1121,6 +1124,8 @@ AX interactions are gated per node type. The lists below are each type's **ceili
 | `ledger` | `ax.evidence.add`, `ax.event.record` |
 | `trace` | `ax.evidence.add`, `ax.event.record` |
 | `image` | `ax.evidence.add`, `ax.review.add` |
+| `diff` | `ax.evidence.add`, `ax.review.add`, `ax.focus.set`, `ax.event.record` |
+| `mermaid` | `ax.steer`, `ax.work.create`, `ax.evidence.add`, `ax.command.invoke`, `ax.event.record` |
 | `webpage` | `ax.evidence.add`, `ax.review.add`, `ax.focus.set`, `ax.event.record` |
 | `group` | `ax.focus.set`, `ax.work.create`, `ax.command.invoke`, `ax.event.record` |
 

package/skills/pmx-canvas-testing/SKILL.md

@@ -95,6 +95,9 @@ Prefer extending the existing suites before inventing a one-off script.
 - When checking embedded frame fit manually, start from a clean seeded state, rebuild stale bundles,
   and inspect the actual iframe document in a browser. Server dimensions can look correct while the
   embedded content is still clipped.
+- User-facing creation flows must end with the new nodes visible: after the create (plus the
+  skill-mandated focus/fit), a screenshot must show them without any manual pan. A `panned: true`
+  API result alone is not proof — verify the frame is on-screen and unobscured.
 
 ## Failure Handling
 

package/src/cli/agent.ts

@@ -32,6 +32,7 @@ import './commands/webview.js';
 import './commands/apps.js';
 import './commands/copilot.js';
 import './commands/skills.js';
+import './commands/smoke.js';
 
 // Re-exported for existing importers (tests import it from this module).
 export { extractGlobalTargetFlags };
@@ -75,6 +76,7 @@ Canvas commands:
   pmx-canvas arrange [--layout MODE]  Auto-arrange (grid|column|flow)
   pmx-canvas batch [--file FILE]      Run many canvas operations at once
   pmx-canvas validate                 Check collisions and containment issues
+  pmx-canvas smoke                    One-command environment check of a running canvas
   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

package/src/cli/commands/ax.ts

@@ -53,6 +53,7 @@ cmd(
   [
     'pmx-canvas ax event add --kind tool-start --summary "ran tests"',
     'pmx-canvas ax event add --kind failure --summary "build broke" --detail "..." node1 node2',
+    'pmx-canvas ax event add --kind tool-start --summary "ran tests" --agent-id builder-1',
   ],
   async (args) => {
     const { positional, flags } = parseFlags(args);
@@ -61,12 +62,14 @@ cmd(
     const kind = requireFlag(flags, 'kind', 'pmx-canvas ax event add --kind <kind> --summary <text>');
     const summary = requireFlag(flags, 'summary', 'pmx-canvas ax event add --kind <kind> --summary <text>');
     const detail = getStringFlag(flags, 'detail');
+    const agentId = getStringFlag(flags, 'agent-id');
 
     output(
       await invokeOperation('ax.event.record', {
         kind,
         summary,
         ...(detail ? { detail } : {}),
+        ...(agentId ? { agentId } : {}),
         ...(positional.length > 0 ? { nodeIds: positional } : {}),
         source: resolveAxSource(flags),
       }),
@@ -77,7 +80,11 @@ cmd(
 cmd(
   'ax steer',
   'Send a steering message to the active agent session',
-  ['pmx-canvas ax steer "focus on the failing test first"', 'pmx-canvas ax steer --message "stop and re-plan"'],
+  [
+    'pmx-canvas ax steer "focus on the failing test first"',
+    'pmx-canvas ax steer --message "stop and re-plan"',
+    'pmx-canvas ax steer "wave 2 is unblocked" --agent-id orchestrator --target builder-1',
+  ],
   async (args) => {
     const { positional, flags } = parseFlags(args);
     if (flags.help || flags.h) return showCommandHelp('ax steer');
@@ -86,8 +93,17 @@ cmd(
     if (!message) {
       die('Missing steering message', 'pmx-canvas ax steer <message>');
     }
+    const agentId = getStringFlag(flags, 'agent-id');
+    const target = getStringFlag(flags, 'target');
 
-    output(await invokeOperation('ax.steer', { message, source: resolveAxSource(flags) }));
+    output(
+      await invokeOperation('ax.steer', {
+        message,
+        ...(agentId ? { agentId } : {}),
+        ...(target ? { target } : {}),
+        source: resolveAxSource(flags),
+      }),
+    );
   },
 );
 
@@ -374,6 +390,7 @@ cmd(
   [
     'pmx-canvas ax work add --title "Wire up auth" --status in-progress',
     'pmx-canvas ax work add --title "Review API" node1 node2',
+    'pmx-canvas ax work add --title "Wire up auth" --agent-id builder-1',
   ],
   async (args) => {
     const { positional, flags } = parseFlags(args);
@@ -382,12 +399,14 @@ cmd(
     const title = requireFlag(flags, 'title', 'pmx-canvas ax work add --title <text>');
     const status = getStringFlag(flags, 'status');
     const detail = getStringFlag(flags, 'detail');
+    const agentId = getStringFlag(flags, 'agent-id');
 
     output(
       await invokeOperation('ax.work.create', {
         title,
         ...(status ? { status } : {}),
         ...(detail ? { detail } : {}),
+        ...(agentId ? { agentId } : {}),
         ...(positional.length > 0 ? { nodeIds: positional } : {}),
         source: resolveAxSource(flags),
       }),
@@ -398,7 +417,11 @@ cmd(
 cmd(
   'ax work update',
   'Update a canvas-bound AX work item by ID',
-  ['pmx-canvas ax work update <id> --status done', 'pmx-canvas ax work update <id> --title "New title" --detail "..."'],
+  [
+    'pmx-canvas ax work update <id> --status done',
+    'pmx-canvas ax work update <id> --title "New title" --detail "..."',
+    'pmx-canvas ax work update <id> --agent-id builder-2',
+  ],
   async (args) => {
     const { positional, flags } = parseFlags(args);
     if (flags.help || flags.h) return showCommandHelp('ax work update');
@@ -408,6 +431,7 @@ cmd(
     const title = getStringFlag(flags, 'title');
     const status = getStringFlag(flags, 'status');
     const detail = getStringFlag(flags, 'detail');
+    const agentId = getStringFlag(flags, 'agent-id');
 
     output(
       await invokeOperation('ax.work.update', {
@@ -415,6 +439,7 @@ cmd(
         ...(title ? { title } : {}),
         ...(status ? { status } : {}),
         ...(detail ? { detail } : {}),
+        ...(agentId ? { agentId } : {}),
         ...(positional.length > 1 ? { nodeIds: positional.slice(1) } : {}),
         source: resolveAxSource(flags),
       }),

package/src/cli/commands/history.ts

@@ -81,7 +81,7 @@ cmd(
   'Show canvas mutation history',
   ['pmx-canvas history', 'pmx-canvas history --summary', 'pmx-canvas history --compact'],
   async (args) => {
-    const { flags } = parseFlags(args);
+    const { flags } = parseFlags(args, { boolFlags: ['summary'] });
     if (flags.help || flags.h) return showCommandHelp('history');
 
     const result = (await invokeOperation('history.get', {})) as Record<string, unknown>;

package/src/cli/commands/nodes.ts

@@ -691,7 +691,7 @@ cmd(
     'pmx-canvas node schema --summary',
   ],
   async (args) => {
-    const { flags } = parseFlags(args);
+    const { flags } = parseFlags(args, { boolFlags: ['summary'] });
     if (flags.help || flags.h) return showCommandHelp('node schema');
 
     const result = await loadCanvasSchema();
@@ -783,7 +783,7 @@ cmd(
     'pmx-canvas node get node-abc123 --field title --field graphConfig',
   ],
   async (args) => {
-    const { positional, flags } = parseFlags(args);
+    const { positional, flags } = parseFlags(args, { boolFlags: ['summary'] });
     if (flags.help || flags.h) return showCommandHelp('node get');
 
     const id = positional[0];

package/src/cli/commands/query.ts

@@ -65,7 +65,7 @@ cmd(
     'pmx-canvas validate spec --type json-render --spec-file ./dashboard.json --summary',
   ],
   async (args) => {
-    const { flags } = parseFlags(args);
+    const { flags } = parseFlags(args, { boolFlags: ['summary'] });
     if (flags.help || flags.h) return showCommandHelp('validate spec');
 
     const type = getStringFlag(flags, 'type');