pmx-canvas 0.4.5 → 0.4.7

package/CHANGELOG.md

@@ -3,6 +3,122 @@
 All notable changes to `pmx-canvas` are documented here. This project follows
 [Semantic Versioning](https://semver.org/).
 
+## [0.4.7] - 2026-08-09
+
+### Added
+
+- The flow works without the panel too: materialized step nodes get native
+  Start / Done / Blocked controls, and the first step adds Run loop / Stop and
+  a steer box. That loop runs server-side, so it survives a browser reload and
+  keeps advancing while the tab is closed.
+- Two live AX control surfaces you can put on the board: **`ax-board`** (give
+  the agent tasks, watch their status change as it works, steer it, and run a
+  bounded task loop) and **`ax-flow`** (the same controls drawn as a task flow
+  with a loop-back rail, plus a **Materialize to board** button that lays the
+  flow out as real nodes joined by edges, each tracking its own status).
+- The demo board is a proper showcase now: every node type, every chart type,
+  every HTML primitive, a grouped cluster, labelled edges and context pins —
+  laid out in labelled bands instead of the old three-group OKR dashboard.
+- `GET /api/canvas/file-bytes?nodeId=…` serves a file node's bytes from the
+  workspace (used by the inline PDF viewer); paths outside the workspace, or
+  reached through a symlink out of it, are refused.
+- File nodes now handle more than source code: `.csv` and `.tsv` files render
+  as real tables, PDFs render in an embedded viewer, and other binary files
+  show a name-and-size placeholder instead of decoded gibberish. Text files
+  larger than 2 MB render truncated with a notice rather than being read into
+  memory whole.
+
+### Changed
+
+- The mouse wheel now zooms the canvas (trackpad two-finger scrolling still
+  pans, and the toolbar +/- buttons and their keyboard shortcuts both zoom
+  around the viewport centre).
+- The browser honors the server's readability floor, so content-fit never
+  shrinks a node back below it.
+- `validate` now reports edges whose endpoint node is docked (and therefore
+  cannot be drawn) as an advisory `hiddenEdgeEndpoints` list. Like
+  `sizeWarnings` it does not fail `ok`, so boards that passed before still
+  pass.
+
+### Fixed
+
+- `strictSize` is no longer dropped on file, image and webpage nodes — it used
+  to be honored when sizing the node but never stored, so the browser resized
+  the node anyway.
+- Node chrome no longer crowds out short nodes when you zoom out: the title bar
+  used to grow until it took most of a small node and clipped its text away.
+- Context nodes no longer dock themselves invisibly: a node you create lands on
+  the canvas where you put it, and docking to the HUD column is something you
+  ask for. Previously an agent-created context node existed in the API and
+  passed validation but never rendered, so edges to it trailed off into empty
+  space.
+- `fit` now sizes the board to the connected browser window instead of assuming
+  1440x900, so fitting no longer leaves nodes clipped on both sides.
+- Edges stay legible when you zoom out: strokes, dashes, arrowheads, and labels
+  now hold their on-screen size instead of shrinking to invisible hairlines,
+  and `references` edges use a higher-contrast colour.
+- CLI flag values that begin with a dash now work, so a unified diff starting
+  with `--- a/file` can be passed straight to `--content` (and a bare `--` ends
+  flag parsing).
+- Web-artifact builds now fail fast with a clear message naming the Node.js
+  version they need, instead of an opaque package-manager error.
+
+## [0.4.6] - 2026-08-08
+
+### Added
+
+- A `pmx-canvas smoke` command: one-command check that a running canvas works
+  in the current environment — server health + workspace, CLI/server version
+  skew, MCP initialize handshake, a temporary node create/search/remove
+  round-trip, and board validation. JSON report, exit 1 on failure.
+- The `/health` endpoint now reports the server's package `version`, so tools
+  can detect version skew between a CLI and the daemon it targets.
+- The CLI now accepts `--agent-id` on `ax work add/update` and `ax event add`,
+  and `--agent-id` / `--target` on `ax steer`; the SDK's work, event, and
+  steering methods accept the same identity fields.
+- The skill now teaches in-view placement and content sizing: focus or fit
+  newly created user-facing nodes, use per-type default sizes, and keep AX
+  state reads lean.
+- A new `diff` node type: unified diffs render with per-file headers, hunk
+  rows, and colored added/removed lines instead of a plain code fence.
+- A new `mermaid` node type: flowcharts, sequence and state diagrams render
+  client-side from mermaid text — no hosted app needed; Excalidraw remains
+  for interactive drawing.
+- A live work-item board: `canvas_render { action: "workboard" }` (HTTP
+  `POST /api/canvas/workboard`) materializes one board node showing all AX
+  work items by status, and it refreshes automatically whenever work items
+  change.
+
+
+### Changed
+
+- **Nodes created with unreadably small explicit sizes are now clamped up to a
+  per-type minimum.** A request for e.g. 200x100 now yields a readable
+  default-ish size instead; pass `strictSize: true` to keep a genuinely small
+  fixed frame. `validate` reports any undersized nodes as advisory size
+  warnings. Agents doing their own layout arithmetic should read back the
+  created size (or set `strictSize`).
+- The README's MCP and Amp orb setup guides now cover portable configs: pin
+  the package version in orb setup scripts and avoid hard-coding an absolute
+  `PMX_CANVAS_WORKSPACE_ROOT` in committed MCP configs.
+- Focus margins are now screen-space and zoom-aware, so a focused node clears
+  the floating toolbar at any scale.
+
+### Fixed
+
+- A browser panel left open across a `pmx-canvas` upgrade now reloads itself
+  once on reconnect instead of silently running the old client bundle (which
+  hid new client behavior such as the auto-ghost minimum dwell).
+- A batch that pins nodes now updates the browser's pin state immediately —
+  the context menu no longer shows a stale "Pin as context" until reload.
+- The MCP stdio server now exits when its client closes the connection instead
+  of remaining as an orphaned process.
+- Black app tiles in WebKit host panels (e.g. the GitHub Copilot app): hosted
+  app frames now boot one at a time, confirm they actually painted via a paint
+  probe, and recover automatically when they did not — soft resize, then
+  remount, then an explicit Retry button instead of a silent black tile. The
+  loading overlay stays up until the paint is confirmed.
+
 ## [0.4.5] - 2026-08-07
 
 ### Added
@@ -2989,6 +3105,8 @@ otherwise have to discover by trial and error.
 - Regression coverage for snapshot flat-`id` aliases on both MCP and
   HTTP surfaces, plus async / top-level-`await` WebView script bodies.
 
+[0.4.7]: https://github.com/pskoett/pmx-canvas/releases/tag/v0.4.7
+[0.4.6]: https://github.com/pskoett/pmx-canvas/releases/tag/v0.4.6
 [0.4.5]: https://github.com/pskoett/pmx-canvas/releases/tag/v0.4.5
 [0.4.4]: https://github.com/pskoett/pmx-canvas/releases/tag/v0.4.4
 [0.4.3]: https://github.com/pskoett/pmx-canvas/releases/tag/v0.4.3

package/Readme.md

@@ -1,8 +1,8 @@
 # pmx-canvas
 
 **A moldable canvas for agent-assisted thinking.** An infinite 2D surface
-where files, plans, status, charts, fetched web pages, annotations, and
-hand-drawn diagrams live side by side. Every node carries its own renderer; agents
+where files, plans, status, charts, fetched web pages, annotations, code
+diffs, and diagrams live side by side. Every node carries its own renderer; agents
 (and you) build new views in the middle of a session — even streaming a
 structured panel into place as they generate it — not as a separate tooling
 project. Pin what matters and the agent reads your spatial curation as
@@ -35,14 +35,21 @@ neighborhoods) and uses your layout to ground its next action.
 
 ### 02 / Mix any data source
 
-Files, web pages, screenshots, structured panels, charts, hand-drawn
-diagrams, embedded MCP Apps, and bundled web artifacts all live on the same
-surface. Any rich surface — an HTML node or a web artifact — can be **opened as
-a site**, full-page in its own browser tab with one click; the canvas and the
-tab render the same document. The reach of the canvas is the union of its
-[built-in node types](docs/node-types.md) and **whatever your agent's harness
-already has access to** — MCP servers, CLIs, file reads, web fetch, anything
-on its toolbelt.
+Files, web pages, screenshots, structured panels, charts, diagrams, embedded
+MCP Apps, and bundled web artifacts all live on the same surface. A file node
+follows the file on disk as the agent edits it — source with line numbers, a
+CSV or TSV as a real table, a PDF inline. Anything else binary shows its name
+and size rather than decoded gibberish, and a very large text file renders
+truncated with a note saying so. Code review has its own node: a unified
+diff with per-file headers and colored added and removed lines. Diagrams can
+be drawn by hand in Excalidraw or written as plain mermaid text and rendered
+on the spot. Context cards, execution ledgers, and agent trace pills round out
+the set. Any rich surface — HTML, mermaid, json-render, graph, webpage, or a
+web artifact — can be **opened as a site**, full-page in its own browser tab
+with one click; the canvas and the tab render the same document. The reach of
+the canvas is the union of its [built-in node types](docs/node-types.md) and
+**whatever your agent's harness already has access to** — MCP servers, CLIs,
+file reads, web fetch, anything on its toolbelt.
 
 ### 03 / Annotate
 
@@ -61,13 +68,17 @@ immediately — an explicit, low-noise control over what the agent sees next.
 On top of pins, a host-agnostic **AX (agent-experience) layer** turns the
 canvas into a shared workspace between you and the agent:
 
-- **Agent-native nodes** — create markdown, status, HTML, json-render, graph,
-  web-artifact, or MCP app nodes that can act as interactive controls for the
-  agent. A node can focus context, create or update work, add evidence, request
-  input or approval, or send steering without leaving the board.
+- **Agent-native nodes** — most node types can act as interactive controls for
+  the agent out of the box: a node can focus context, create or update work,
+  add evidence, request input or approval, or send steering without leaving the
+  board. The sandboxed surfaces — HTML nodes and MCP apps — stay off until a
+  node opts in, since their content is author-supplied.
 - **Focus** — promote nodes into the agent's active context without moving the viewport.
 - **Work items & approval gates** — track visible tasks tied to nodes, and gate
-  high-impact actions behind a human `pending → approved/rejected` decision.
+  high-impact actions behind a human `pending → approved/rejected` decision. A
+  linked node shows its work item's status on the title bar, and a live work
+  board lays the whole queue out by status and keeps itself current — useful
+  when several agents are working at once.
 - **Steering messages & agent-event timeline** — send instructions to the
   active session, and read a normalized, bounded timeline of prompts, tool
   runs, evidence (logs/diffs/screenshots/test-output), and failures.
@@ -109,8 +120,9 @@ Harness-agnostic. Drive the canvas from [MCP](docs/mcp.md) (22 tools,
 14 resources, change notifications), the [CLI](docs/cli.md), the
 [HTTP API](docs/http-api.md), or the [Bun SDK](docs/sdk.md) — all
 [environment variables documented here](docs/environment.md). Works with
-Claude Code, GitHub Copilot CLI, Codex, Cursor, Windsurf, or any agent
-that can spawn an MCP stdio server, call a CLI, or hit an HTTP endpoint.
+Claude Code, the GitHub Copilot app and CLI, Codex, Amp, Cursor, Windsurf, or
+any agent that can spawn an MCP stdio server, call a CLI, or hit an HTTP
+endpoint.
 
 ### 07 / Native app adapters
 
@@ -203,15 +215,20 @@ To work on the canvas itself, clone the repo — see [Development](#development)
 
 ```bash
 bunx pmx-canvas              # Start canvas, open browser
-bunx pmx-canvas --demo       # Start with the saved dashboard demo board
+bunx pmx-canvas --demo       # Start with the showcase demo board
 bunx pmx-canvas --no-open    # Headless (good for daemons / CI)
+bunx pmx-canvas --theme=volt # Pick a theme (nine ship; PMX_CANVAS_THEME works too)
 bunx pmx-canvas --mcp        # Run as MCP server (stdio)
 bunx pmx-canvas --help       # All commands
 ```
 
+Themes are a toolbar picker away too, and any one panel can override the
+shared theme for itself with `?theme=<name|auto>`.
+
 The canvas opens at `http://localhost:4313`. Try `--demo` first — it seeds a
-saved dashboard with grouped OKR notes, graph panels, context pins, and labeled
-edges.
+showcase board with every node type on it: notes and status, files, a diff, a
+CSV table, charts of every kind, mermaid diagrams, the HTML primitives,
+structured panels, a grouped cluster, labeled edges, and context pins.
 
 ### Connect your agent (MCP)
 
@@ -228,7 +245,21 @@ Add to your agent's MCP config:
 }
 ```
 
-The canvas auto-starts on first tool call.
+The canvas auto-starts on first tool call. Keep the config portable: commit it
+to the repo and let the workspace default to the launch directory — hard-coding
+an absolute `PMX_CANVAS_WORKSPACE_ROOT` breaks other checkouts and machines.
+Set that env var only when your host spawns the MCP server from an incidental
+directory (e.g. `~/.copilot`) instead of the project root.
+
+Verify any environment in one command against a running server:
+
+```bash
+bunx pmx-canvas smoke
+```
+
+It checks server health + workspace, CLI/server version skew, the MCP stdio
+initialize handshake, a temp-node create/search/remove round-trip, and board
+validation — JSON report, exit 1 on failure.
 
 ### Use inside the GitHub Copilot app
 
@@ -274,8 +305,9 @@ services:
 ```
 
 ```bash
-# .agents/setup — install the CLI (pin the version for reproducible starts)
-npm install -g pmx-canvas@latest
+# .agents/setup — install the CLI (pin the exact version: a fresh orb running
+# @latest can silently pick up a newer release than the one you validated)
+npm install -g pmx-canvas@0.4.7
 ```
 
 The server binds the portal-assigned `$PORT` automatically (gated on the
@@ -286,12 +318,15 @@ caveat: WebView automation (`pmx-canvas screenshot`) needs Bun >= 1.3.12 in
 the orb image; the canvas itself runs fine without it and says so in the
 error. The canvas detects the orb and the portal's nested-iframe
 embed on its own: live updates arrive over the proxy-safe polling transport,
-and iframe-backed nodes (HTML, graph, json-render, web artifacts) render
-inline via `srcdoc` with their theme styling included. Cross-origin hosted
-apps (e.g. the hosted Excalidraw MCP app) cannot be inlined and may stay
-blocked by the portal embed — everything served from the canvas itself works.
+and iframe-backed nodes (HTML, mermaid, graph, json-render, web artifacts)
+render inline via `srcdoc` with their theme styling included. Two things can't
+be inlined and stay blocked by the portal embed: cross-origin hosted apps (e.g.
+the hosted Excalidraw MCP app), and PDF file nodes — a PDF node offers an
+"Open PDF" link there instead of a preview.
 Debug overrides: `/workbench?transport=poll|sse` and
-`?iframe-mode=srcdoc|src`.
+`?iframe-mode=srcdoc|src`. Once the service is up, `pmx-canvas smoke` verifies
+the whole stack (health, versions, MCP handshake, node lifecycle, validation)
+in one command.
 
 ### Install the agent skill (recommended)
 
@@ -315,7 +350,8 @@ Common harness skill directories: `.claude/skills/` (Claude Code),
 `.github/skills/` or `.copilot/skills/` (Copilot CLI),
 `.agents/skills/` (cross-harness convention). Once the canvas is running,
 the agent can read `canvas://skills` and pull in companion skills
-(`control-session-orchestrator`, `web-artifacts-builder`, `json-render-*`,
+(`pmx-canvas-orchestration` for running several agents on one board,
+`control-session-orchestrator`, `web-artifacts-builder`, `json-render-*`,
 `pmx-canvas-testing`, `playwright-cli`, etc.) as the work demands.
 
 ## Documentation
@@ -341,16 +377,20 @@ the agent can read `canvas://skills` and pull in companion skills
   `.pmx-canvas/canvas.db`.
 - **What leaves your machine.** The core canvas runs entirely on
   `localhost`. Network egress only happens for explicit, opt-in flows:
-  `webpage` nodes fetch the URL you give them; `mcp-app` /
-  `canvas_app { action: "diagram" }` calls go to whatever MCP server URL you
-  configure (the Excalidraw preset uses `https://mcp.excalidraw.com/mcp`);
-  `bunx` itself reads the npm registry on first install. Nothing else phones
-  home.
+  `webpage` nodes and remote-URL `image` nodes fetch the address you give
+  them; `mcp-app` / `canvas_app { action: "diagram" }` calls go to whatever
+  MCP server URL you configure (the Excalidraw preset uses
+  `https://mcp.excalidraw.com/mcp`); building a web artifact runs a package
+  manager, which fetches a React/Tailwind toolchain plus that artifact's declared dependencies (and, if neither pnpm nor bun is present, installs pnpm globally) from the npm
+  registry; and `bunx` itself reads the registry on first install. Nothing
+  else phones home.
 
 ## Tech stack
 
 - **Runtime:** [Bun](https://bun.sh)
-- **UI:** [Preact](https://preactjs.com) + [@preact/signals](https://github.com/preactjs/signals)
+- **UI:** [Preact](https://preactjs.com) + [@preact/signals](https://github.com/preactjs/signals);
+  the json-render/graph viewer bundle is React + [recharts](https://recharts.org),
+  and mermaid nodes render with [mermaid](https://mermaid.js.org)
 - **Styling:** CSS custom properties + Tailwind (json-render bundle only)
 - **Server:** Bun.serve (HTTP + SSE)
 - **MCP:** [@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/typescript-sdk) (stdio)
@@ -363,7 +403,7 @@ cd pmx-canvas
 bun install
 bun run build
 bun run dev            # Start + open browser
-bun run dev:demo       # Start with the demo board
+bun run dev:demo       # Start with the showcase demo board
 bun run test           # Unit tests
 bun run test:e2e       # Playwright end-to-end tests
 bun run test:all       # Unit tests + browser smoke

package/dist/canvas/global.css

@@ -643,6 +643,10 @@ body,
   overflow: hidden;
   text-overflow: ellipsis;
   flex: 1;
+  /* The name is the one thing that must survive a cramped title bar. Everything
+     else in the bar is flex-shrink: 0, so without a floor the title absorbed all
+     the pressure and collapsed to an ellipsis on narrow nodes. */
+  min-width: 9ch;
   min-width: 0;
 }
 
@@ -670,6 +674,13 @@ body,
 }
 
 .canvas-node .node-ax-status {
+  /* A long status ("in-progress") must not push the node's NAME out of the bar;
+     the pill is a glance-level cue, the name is the identity. */
+  max-width: 11ch;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  flex-shrink: 1;
   font-size: calc(9px * var(--node-chrome-scale, 1));
   padding: calc(1px * var(--node-chrome-scale, 1)) calc(6px * var(--node-chrome-scale, 1));
   border-radius: calc(4px * var(--node-chrome-scale, 1));
@@ -1846,10 +1857,11 @@ html.is-node-resizing .ext-app-preview-catcher {
   border-radius: 999px;
 }
 
-/* Edge labels */
+/* Edge labels — --edge-chrome-scale is set on the edge <svg> so labels keep a
+   constant screen size while zoomed out (see edgeChromeScale in EdgeLayer). */
 .edge-label {
   font-family: var(--font);
-  font-size: 11px;
+  font-size: calc(11px * var(--edge-chrome-scale, 1));
   pointer-events: none;
   user-select: none;
 }
@@ -1857,7 +1869,7 @@ html.is-node-resizing .ext-app-preview-catcher {
 .edge-label-bg {
   fill: var(--c-panel-glass);
   stroke: var(--c-line);
-  stroke-width: 0.5;
+  stroke-width: calc(0.5 * var(--edge-chrome-scale, 1));
 }
 
 /* Trace nodes — compact pills for agent tool/subagent visualization */
@@ -1895,6 +1907,160 @@ html.is-node-resizing .ext-app-preview-catcher {
   }
 }
 
+/* Diff nodes — unified diff viewer with per-file sections */
+.diff-node {
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+  height: 100%;
+  overflow: auto;
+  font-family: var(--mono);
+  font-size: 12px;
+  color: var(--c-text);
+}
+
+.diff-node.diff-node-empty {
+  align-items: center;
+  justify-content: center;
+  color: var(--c-muted);
+}
+
+.diff-node .diff-file {
+  border: 1px solid var(--c-line);
+  border-radius: 6px;
+  overflow: hidden;
+  flex-shrink: 0;
+}
+
+.diff-node .diff-file-header {
+  padding: 4px 8px;
+  background: var(--c-panel-overlay);
+  border-bottom: 1px solid var(--c-line);
+  color: var(--c-text-soft);
+  font-weight: 600;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.diff-node .diff-lines {
+  margin: 0;
+  padding: 4px 0;
+  overflow-x: auto;
+  font-family: inherit;
+  font-size: inherit;
+  line-height: 1.5;
+}
+
+.diff-node .diff-lines > div {
+  padding: 0 8px;
+  white-space: pre;
+}
+
+.diff-node .diff-hunk {
+  color: var(--c-muted);
+}
+
+.diff-node .diff-line-add {
+  color: var(--c-ok);
+  background: var(--c-ok-10);
+}
+
+.diff-node .diff-line-remove {
+  color: var(--c-danger);
+  background: var(--c-danger-12);
+}
+
+.diff-node .diff-line-context {
+  color: var(--c-text-soft);
+}
+
+/* File nodes — delimited-data tables and non-text placeholders */
+.file-table-shell {
+  display: flex;
+  flex-direction: column;
+  height: 100%;
+  min-height: 0;
+}
+
+.file-node-notice {
+  flex-shrink: 0;
+  padding: 4px 10px;
+  color: var(--c-muted);
+  font-size: 10px;
+}
+
+/* Own scroll port so a wide CSV scrolls inside the node instead of blowing out
+   the layout — and so the sticky header row has something to stick to. */
+.file-table-wrap {
+  flex: 1;
+  min-height: 0;
+  overflow: auto;
+}
+
+/* The shell/wrap prefix is load-bearing: these rules must out-specify the markdown
+   table styles (`.canvas-node .node-body table` / `th` / `td`), whose 0.5em
+   margin and translucent header background break the sticky header. Borders are
+   separate, not collapsed — collapsed borders belong to the table element, so
+   the header leaks the rows scrolling beneath it. */
+.file-table-shell .file-table-wrap .file-table {
+  margin: 0;
+  border-collapse: separate;
+  border-spacing: 0;
+  width: max-content;
+  min-width: 100%;
+  font-family: var(--mono);
+  color: var(--c-text);
+}
+
+.file-table-shell .file-table-wrap .file-table th,
+.file-table-shell .file-table-wrap .file-table td {
+  max-width: 320px;
+  padding: 3px 8px;
+  border: none;
+  border-right: 1px solid var(--c-line);
+  border-bottom: 1px solid var(--c-line);
+  text-align: left;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.file-table-shell .file-table-wrap .file-table th {
+  position: sticky;
+  top: 0;
+  z-index: 1;
+  /* Opaque in every theme — rows must not bleed through while scrolling. */
+  background: var(--c-panel);
+  color: var(--c-text-soft);
+  font-weight: 600;
+}
+
+.file-table-shell .file-table-wrap .file-table tbody tr:nth-child(even) {
+  background: var(--c-surface-subtle);
+}
+
+.file-node-placeholder {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: 4px;
+  height: 100%;
+  padding: 16px;
+  color: var(--c-muted);
+  text-align: center;
+}
+
+.file-node-placeholder-name {
+  color: var(--c-text-soft);
+  word-break: break-all;
+}
+
+.file-node-link {
+  color: var(--c-accent);
+}
+
 /* Docked node — compact toolbar-flanking panel */
 .docked-node {
   min-width: 200px;