pmx-canvas 0.4.6 → 0.4.8

package/docs/http-api.md

@@ -64,6 +64,23 @@ A node creation request must resolve a `type` — pass it in the body (`{ "type"
 ... }`) or as a `?type=` query param. An empty / type-less body returns `400`
 rather than silently creating a markdown node.
 
+### File node content and bytes
+
+A `file` node reads its file server-side. Text is stored on the node as
+`data.fileContent` (with `data.lineCount`); `data.byteSize` is always set.
+Non-text files are never decoded into mojibake — they carry `data.binary: true`
+with no `fileContent`, plus `data.mimeType` when the type is known
+(`application/pdf` for PDFs). A text file larger than 2 MB is stored truncated
+with `data.truncated: true`.
+
+```bash
+# Raw bytes for a binary file node (PDF viewer, downloads)
+curl http://localhost:4313/api/canvas/file-bytes?nodeId=node-abc123
+```
+
+The byte route is workspace-scoped: a file node whose path resolves outside the
+workspace root returns `403`, and an unknown node id returns `404`.
+
 ## Edges
 
 ```bash

package/docs/mcp.md

@@ -227,6 +227,18 @@ interaction against the node's effective capabilities.
 - **Commands:** `canvas_invoke_command` runs a registry command (`pmx.plan`,
   `pmx.execute`, `pmx.promote-context`, `pmx.summarize`, `pmx.review`); unknown
   names are rejected and a successful call records a `command` agent-event.
+  Commands *record* a signal for the agent — they do not execute anything
+  server-side.
+- **`ax.flow.materialize`:** the one interaction that creates canvas nodes, and
+  it is deliberately narrow. The caller supplies text only — up to 12 steps with
+  a title (<= 120 chars) and optional detail — and the SERVER owns the resulting
+  shape: one `markdown` node per step, `flow` edges between them, a dashed
+  `references` loop edge when looping, and one work item per step linked to its
+  node (so the existing status-chip mirroring shows progress). The surface never
+  names a node type, geometry, or node data. Re-materializing replaces the
+  previous flow: the source node keeps a manifest of the ids it created, and
+  only nodes on that manifest that still carry the matching flow id are removed,
+  so a surface can never delete anything it did not create.
 
 ## Change notifications
 

package/docs/node-types.md

@@ -14,7 +14,7 @@ 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) |
@@ -50,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
@@ -221,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,6 +1,6 @@
 {
   "name": "pmx-canvas",
-  "version": "0.4.6",
+  "version": "0.4.8",
   "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",
@@ -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",

package/skills/pmx-canvas/SKILL.md

@@ -105,6 +105,7 @@ exit 1 on failure.
 | 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` |
@@ -113,6 +114,9 @@ exit 1 on failure.
 | 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 (interactive/human drawing) | `canvas_app { action: "diagram" }` — prefer `mermaid` for agent-authored diagrams |
@@ -190,10 +194,23 @@ distant nodes, an auto-placed node lands off-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. Since 0.4.6 the server clamps explicit creation sizes UP to per-type
+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
@@ -258,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:
@@ -296,8 +356,12 @@ Prefer `canvas_query { action: "search" }` over parsing the full layout.
   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
+  `mount-slot`, `paint-ok`, `paint-fail`, `soft-expand-cycle`, `recovery-exhausted`, and
+  `assume-visible-rearm` — when diagnosing, trust `paint-ok`/`paint-fail`, and never assert
+  health from `settled` alone. Exception: in a host that reports the document hidden (the
+  GitHub Copilot panel does so continuously), `paint-ok` is recorded as
+  `paint-ok (unverified: host hidden)` — the app answered the paint probe, but nothing is
+  proven composited, so do not treat it as a verified paint. 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
@@ -308,8 +372,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.
@@ -327,10 +391,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

@@ -30,6 +30,16 @@ bun run test:web-canvas     # Browser smoke against a real running app
 bun run test:all            # Bun suite + browser smoke
 ```
 
+**Direct `bun test` is side-effect-guarded by `tests/preload.ts`** (wired via `bunfig.toml`
+`[test].preload`): it defaults `PMX_CANVAS_DISABLE_BROWSER_OPEN=1` so the suite's open-as-site
+tests cannot launch the developer's real browser, whichever way the tests are invoked. The
+preload covers `bun test` only — when you boot a server yourself (`bun run src/cli/index.ts`),
+pass `--no-open` and set `PMX_CANVAS_DISABLE_BROWSER_OPEN=1` explicitly.
+
+**Never pipe a gating command through `tail`, `head`, or `grep`.** The pipeline reports the exit
+code of the LAST command, so `bun run test | tail -5` exits 0 on a red suite. Redirect to a file
+and check `$?`, then read the file.
+
 ## Which Command To Run
 
 - Server/state/API-only changes: run `bun run test`
@@ -79,6 +89,30 @@ Prefer extending the existing suites before inventing a one-off script.
   `pmx-canvas skills sync --yes` to refresh them (whole trees, whatever agent layout owns them) before
   trusting skill-guided results
 
+## Tests That Cannot Fail
+
+A test that passes against the broken code is worse than no test — it certifies the bug. Every
+regression test must be shown to discriminate: run it against the unfixed code (or hard-code the
+broken value) and watch it go red BEFORE you trust the green.
+
+Four ways a test silently stops discriminating in this repo:
+
+- **Polled assertions pass on the first sample.** `expect.poll(fn).toBeGreaterThanOrEqual(180)`
+  succeeds the instant one sample qualifies, so it never observes the failure window. Wait for the
+  settle condition, then assert once.
+- **Committed fixtures embed generated output.** `src/server/demo-state.json` carries each
+  primitive's generated markup; count and coverage assertions are satisfied by stale markup just
+  as well as fresh. Guard generated fixtures by rebuilding from the generator's INPUT and
+  byte-comparing against the current renderer.
+- **Absolute assertions about globally-wired side effects are order-dependent.** Anything flowing
+  through a single-slot listener (architecture rule 8 in `CLAUDE.md`) is wired or not depending on
+  whether an earlier test file booted a server — so the test passes alone and fails in the suite,
+  or vice versa. Assert DIFFERENTIALLY: run the action disarmed and armed, require the deltas to
+  match. Always run the full suite before trusting a new test; a single-file run hides this.
+- **A new node type passes every test and renders nothing.** Server, API, and client-unit
+  assertions all pass while `isCanvasNodeType` drops the type during layout apply. Only a DOM
+  census on a live board catches it.
+
 ## Layout And Embedded Content Checks
 
 - For seeded or generated boards, add API-level geometry assertions: expected node/edge counts,
@@ -95,6 +129,12 @@ 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.
+- **A node's stored content is not render evidence.** An html/primitive node's stored HTML holds
+  every conditional branch — hidden banners, error states, empty states — so a content-level read
+  (search hit, pinned context, `node get`, any text summary) quotes strings the user never saw.
+  The 0.4.7 report filed an "AX bridge unavailable" banner as a live product gap on exactly this
+  basis; the served surface had the bridge injected ahead of the check and the banner was `hidden`
+  in the document. Before filing a rendering bug, fetch the served surface or inspect the DOM.
 - 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.

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');

package/src/cli/commands/view.ts

@@ -44,7 +44,7 @@ cmd(
   'Get the full canvas layout (nodes, edges, viewport)',
   ['pmx-canvas layout', 'pmx-canvas layout --summary'],
   async (args) => {
-    const { flags } = parseFlags(args);
+    const { flags } = parseFlags(args, { boolFlags: ['summary'] });
     if (flags.help || flags.h) return showCommandHelp('layout');
 
     if (flags.summary || flags.compact) {

package/src/cli/index.ts

@@ -298,19 +298,25 @@ Agent CLI (works against running server):
   validate spec                       Validate json-render/graph payloads without creating nodes
   watch [--json] [--events ...]       Watch low-token semantic canvas changes
   focus <node-id>                     Pan to node
+  fit [node-id ...]                   Fit the viewport to all nodes or a subset
   ax status|context|focus             Inspect AX state and focus
   external-app add                    Add hosted external apps like Excalidraw
   diagram add                         Add an Excalidraw diagram node
+  html primitive add|schema           Add or inspect HTML communication primitives
   pin <ids...> | --list | --clear     Manage context pins
   undo / redo / history               Time travel
   snapshot save|list|restore|diff|delete
                                       Manage snapshots
+  diff <snapshot-id>                  Compare the canvas against a snapshot
   group create|add|remove             Manage groups
   web-artifact build                  Build bundled web artifacts
   clear --yes                         Clear canvas
   code-graph                          File dependencies
   spatial                             Spatial analysis
   watch                               Semantic watch stream
+  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
 
 Run any command with --help for details and examples:
   pmx-canvas node add --help

package/src/cli/shared.ts

@@ -47,6 +47,13 @@ export function extractGlobalTargetFlags(args: string[]): string[] {
     const arg = args[i];
     let name: 'port' | 'server-url' | null = null;
     let value: string | undefined;
+    if (arg === '--') {
+      // End of flags: everything after a bare `--` is an operand, so a literal
+      // `--port`-looking value is never mistaken for the global target flag.
+      // The separator itself is kept so parseFlags stops there too.
+      rest.push(...args.slice(i));
+      break;
+    }
     if (arg === '--port' || arg === '--server-url') {
       name = arg.slice(2) as 'port' | 'server-url';
       value = args[i + 1];
@@ -125,11 +132,25 @@ async function invokeOperation(name: string, input: Record<string, unknown>): Pr
 
 // ── Flag parsing ─────────────────────────────────────────────
 
-function parseFlags(args: string[]): { positional: string[]; flags: Record<string, string | true> } {
+/**
+ * `options.boolFlags` marks flags that are boolean FOR THIS COMMAND. Value
+ * flags consume the next token verbatim (so a unified diff beginning with
+ * `--- a/file` survives), which makes a flag that is boolean here and
+ * value-taking elsewhere ambiguous — `--summary` is boolean in `history` /
+ * `layout` / `node get` / `validate spec` but carries text in `node add`.
+ * Without this per-command override, `history --summary --limit 5` would
+ * swallow `--limit` as the summary's value. The global set below holds flags
+ * that are boolean everywhere.
+ */
+function parseFlags(
+  args: string[],
+  options: { boolFlags?: readonly string[] } = {},
+): { positional: string[]; flags: Record<string, string | true> } {
   const positional: string[] = [];
   const flags: Record<string, string | true> = {};
   // Boolean-only flags (never take a value argument)
-  const BOOL_FLAGS = new Set([
+  const BOOL_FLAGS = new Set<string>([
+    ...(options.boolFlags ?? []),
     'help',
     'h',
     'ids',
@@ -168,14 +189,22 @@ function parseFlags(args: string[]): { positional: string[]; flags: Record<strin
   ]);
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
+    // Conventional end-of-flags separator: the rest is positional, never flags.
+    if (arg === '--') {
+      positional.push(...args.slice(i + 1));
+      break;
+    }
     if (arg.startsWith('--')) {
       const eq = arg.indexOf('=');
       if (eq !== -1) {
         flags[arg.slice(2, eq)] = arg.slice(eq + 1);
       } else {
         const key = arg.slice(2);
-        // If not a boolean flag and next arg exists and isn't a flag, consume it as value
-        if (!BOOL_FLAGS.has(key) && i + 1 < args.length && !args[i + 1].startsWith('-')) {
+        // A value flag consumes the very next token VERBATIM — including one
+        // that starts with `-`/`--`. Unified diffs legitimately begin with
+        // `--- a/file`, and the old "next token must not look like a flag"
+        // heuristic silently dropped that content.
+        if (!BOOL_FLAGS.has(key) && i + 1 < args.length) {
           flags[key] = args[++i];
         } else {
           flags[key] = true;
@@ -183,7 +212,7 @@ function parseFlags(args: string[]): { positional: string[]; flags: Record<strin
       }
     } else if (arg.startsWith('-') && arg.length === 2) {
       const key = arg.slice(1);
-      if (!BOOL_FLAGS.has(key) && i + 1 < args.length && !args[i + 1].startsWith('-')) {
+      if (!BOOL_FLAGS.has(key) && i + 1 < args.length) {
         flags[key] = args[++i];
       } else {
         flags[key] = true;