pmx-canvas 0.1.8 → 0.1.9

package/CHANGELOG.md

@@ -3,6 +3,70 @@
 All notable changes to `pmx-canvas` are documented here. This project follows
 [Semantic Versioning](https://semver.org/).
 
+## [0.1.9] - 2026-05-01
+
+Workflow ergonomics pass for agent-authored boards. This release tightens
+geometry contracts, adds in-place structured-node updates, and gives agents a
+first-class viewport fit operation for screenshot/review flows.
+
+### Added
+
+- **`pmx-canvas fit`, `POST /api/canvas/fit`, and `canvas_fit_view`.** Agents
+  can fit the server viewport to the whole canvas or selected node IDs using
+  consistent width/height/padding/max-scale options before screenshots or
+  whole-board review.
+- **In-place json-render and graph updates.** `node update --spec-file`, HTTP
+  `PATCH /api/canvas/node/<id>`, and MCP `canvas_update_node` can update
+  json-render specs and graph datasets/configuration without replacing the
+  node, preserving IDs, edges, pins, and placement.
+- **Nested `node` payloads on node create/update responses.** Node responses now
+  include `node: { ...serializedNode }` while retaining the existing flat
+  `id`, `position`, `size`, and data fields for compatibility.
+- **README adds reference sections for image nodes and `pmx-canvas watch`.**
+  The README now lists all four control surfaces (CLI, MCP, HTTP, Bun SDK)
+  side-by-side, documents the image node payload with provenance and
+  validation metadata, documents `pmx-canvas watch` semantic deltas, and
+  notes that bundled skills are readable as MCP resources at
+  `canvas://skills/<name>`.
+
+### Changed
+
+- **HTTP node geometry accepts flat and nested shapes.** Create/update paths now
+  accept both `{ x, y, width, height }` and `{ position, size }`, with invalid
+  sizes still rejected instead of silently ignored.
+- **Graph/json-render explicit heights are preserved in the canvas renderer.**
+  The client no longer auto-shrinks large explicit structured-node frames to the
+  generic 600px auto-fit cap.
+- **MCP schema metadata advertises update and fit tools.** `canvas_describe_schema`
+  and `canvas://schema` include `canvas_update_node` and `canvas_fit_view` in
+  the tool list.
+- **Agent-facing `skills/pmx-canvas/SKILL.md` documents the new operations.**
+  The skill now covers `canvas_fit_view`, the `node update --spec-file` flag for
+  in-place json-render updates, the per-graph-field flags for in-place graph
+  rebuilds, the `chartHeight` vs `height`/`nodeHeight` distinction, and a
+  caveat that `canvas_evaluate` scripts should not call PMX HTTP APIs via
+  `fetch()` (use the matching MCP tools instead).
+
+### Fixed
+
+- **Embedded Excalidraw previews receive unscaled host dimensions.** The ext-app
+  host now reports layout dimensions instead of canvas-zoomed bounding boxes, so
+  text inside diagram boxes remains visible in inline previews instead of only
+  appearing after expansion.
+
+### Internal
+
+- Regression coverage for HTTP/CLI/MCP fit-view parity, nested geometry inputs,
+  json-render and graph in-place updates, richer node response payloads, and the
+  structured-node auto-fit height guard. Ext-app host sizing now also covers the
+  zoomed-canvas case that affected embedded Excalidraw previews.
+- Published-consumer e2e harness swaps the Bun stdin parser for `python3` for
+  portability across hosts.
+- Web-artifact reusable build project no longer commits its Parcel cache.
+  `.parcel-cache` is now gitignored and the previously committed copy was
+  removed; CI no longer inherits a stale cache that prevented Parcel from
+  producing `dist/index.html` for the SDLC Control Room showcase build.
+
 ## [0.1.8] - 2026-04-25
 
 Retest-driven follow-up to 0.1.7. This next release restores compatibility
@@ -100,6 +164,7 @@ 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.1.9]: https://github.com/pskoett/pmx-canvas/releases/tag/v0.1.9
 [0.1.8]: https://github.com/pskoett/pmx-canvas/releases/tag/v0.1.8
 [0.1.7]: https://github.com/pskoett/pmx-canvas/releases/tag/v0.1.7
 

package/Readme.md

@@ -27,7 +27,7 @@ pmx-canvas drives any work that benefits from making **context, relations, and p
 
 **The canvas is agnostic about what you do with it.** The reach of the workspace is the union of pmx-canvas's own node types and **whatever your agent's harness already has access to** — MCP servers, MCP apps, shell commands and CLIs, files in the working directory, web-fetch tools, anything else its toolbelt exposes. The canvas itself doesn't care where the data came from; it just needs the agent (or you) to drop it on the surface as the right node type. To make that concrete:
 
-- A **Jira MCP** turns the canvas into a triage board — tickets land as `markdown` nodes you can group by status and pin the in-flight ones.
+- An **Atlassian MCP** or **GitHub MCP/CLI** turns the canvas into a triage board — tickets or issues land as `markdown` nodes you can group by status and pin the in-flight ones.
 - A **database MCP** turns it into an exploratory query workbench — each query result becomes a `json-render` table or `graph` node next to the `markdown` node holding the SQL.
 - An **Excalidraw MCP app** turns it into a sketch surface — diagrams open as `mcp-app` nodes you can resize and annotate.
 - A **shell-driven agent** with `gh` + `kubectl` in its harness turns it into an ops board — open issues become markdown, pod statuses become `status` nodes, the relationships you care about become edges.
@@ -200,15 +200,16 @@ For one-off local runs without linking, `bun run src/cli/index.ts ...` works too
 
 ### Recommended ways to drive the canvas
 
-Once the canvas is up, two control surfaces are first-class:
+Once the canvas is up, pick the control surface that fits your agent or script:
 
 - **CLI** for local use, scripting, automation, and terminal-native agents.
 - **MCP** for agents that already speak the Model Context Protocol — 38 tools +
-  8 resources, including the bundled-skill index at `canvas://skills`.
+  8 core resources, including the bundled-skill index at `canvas://skills`.
+- **HTTP API** for REST/SSE clients in any language.
+- **Bun SDK** for TypeScript code running on Bun.
 
-Both paths cover core canvas work. A few advanced capabilities (live resource
-subscriptions, `canvas_diff`) remain MCP-only. The HTTP API and the
-[Bun SDK](#javascripttypescript-sdk-bun-runtime) are also available for programmatic use.
+The CLI and MCP cover normal canvas work; the reference sections below show
+the exact commands, tools, and payloads.
 
 #### Connect your agent (MCP)
 
@@ -379,6 +380,24 @@ File nodes display project files with line numbers and language detection. When
 canvas_add_node({ type: 'file', content: 'src/server/index.ts' })
 ```
 
+### Image nodes
+
+Image nodes display local paths, remote URLs, and data URIs. File-backed and
+HTTP(S)-backed images preserve provenance so agents can tell where evidence
+came from, and nodes can carry validation status or warnings when an agent is
+using screenshots as proof.
+
+```typescript
+canvas_add_node({
+  type: 'image',
+  content: 'artifacts/dashboard.png',
+  data: {
+    validationStatus: 'passed',
+    validationMessage: 'Screenshot matches the requested dashboard state.',
+  },
+})
+```
+
 ### Webpage nodes
 
 Webpage nodes store the source URL on the node, fetch the page server-side, and cache extracted text for search, pins, and agent context. Saved canvases keep enough information for an agent to come back later and refresh the node from the original URL.
@@ -645,6 +664,19 @@ File nodes automatically detect import dependencies between each other. Add file
 - Auto-reconnect with exponential backoff
 - MCP resource change notifications close the human-to-agent loop
 
+### Semantic watch
+
+`pmx-canvas watch` consumes the SSE stream and emits compact semantic deltas
+for agents that need low-token updates instead of full layout snapshots. It
+filters noise from harmless moves and reports meaningful events such as pins,
+node additions/removals, group changes, edge connections, and moves that
+change spatial clustering.
+
+```bash
+pmx-canvas watch --events context-pin,move-end
+pmx-canvas watch --json --events context-pin --max-events 1
+```
+
 ### WebView automation
 
 Agents can drive a headless Bun.WebView (Chromium or WebKit) pointed at their own workbench,
@@ -709,21 +741,19 @@ tool.
 
 ## Integration
 
-### CLI and MCP (recommended)
-
-Use either of the two primary control surfaces depending on how your agent runs:
+### CLI and MCP alignment
 
-- **CLI** if your workflow is shell-native, scriptable, or driven by terminal commands
-- **MCP** if your agent already uses tool/resource calls over stdio
-
-Both paths are first-class for core canvas work. A few advanced capabilities, such as `canvas_diff` and MCP resource subscriptions, remain MCP-only.
-
-CLI and MCP are intentionally kept aligned for the main canvas operations, including batch builds,
-layout validation, graph/json-render nodes, group control, snapshots, and search-based edge creation.
+CLI and MCP are kept aligned for the main canvas operations: node and edge
+creation, graph/json-render nodes, web artifacts, external apps, groups,
+batch builds, layout validation, snapshots, search, focus, pins, undo/redo,
+semantic watch streams, WebView automation, and daemon/server control where
+it applies. A few agent-native capabilities, such as resource subscriptions
+and `canvas_diff`, remain MCP-only.
 
 ### MCP server
 
-38 tools + 8 resources. Zero config for any MCP-capable agent.
+38 tools + 8 core resources, plus per-skill resources under `canvas://skills/<name>`.
+Zero config for any MCP-capable agent.
 
 <details>
 <summary>MCP tools</summary>
@@ -774,6 +804,9 @@ layout validation, graph/json-render nodes, group control, snapshots, and search
 <details>
 <summary>MCP resources</summary>
 
+The table lists the core resources. Individual bundled skills are also readable
+at `canvas://skills/<name>`.
+
 | Resource | Description |
 |----------|-------------|
 | `canvas://pinned-context` | Content of pinned nodes + nearby unpinned neighbors |
@@ -976,6 +1009,7 @@ pmx-canvas node schema --type json-render --component Table --summary
 pmx-canvas edge add --from-search "DVT O3 — GitOps" --to-search "deep work trend" --type relation
 pmx-canvas batch --file ./canvas-ops.json
 pmx-canvas validate
+pmx-canvas watch --events context-pin,move-end
 pmx-canvas focus <node-id> --no-pan
 pmx-canvas validate spec --type json-render --spec-file ./dashboard.json --summary
 pmx-canvas web-artifact build --title "Dashboard" --app-file ./App.tsx --deps recharts --include-logs
@@ -1018,48 +1052,12 @@ make HTTP requests, or invoke a CLI can drive the canvas.
 | HTTP-only environment | REST + SSE | `fetch()` / `curl` at `http://localhost:4313/api/canvas/...` |
 | Bun runtime | TypeScript SDK | `import { createCanvas } from 'pmx-canvas'` |
 
-## Known limitations
-
-These are real things you'll hit and they aren't your fault — work around
-them rather than chase them as bugs.
-
-- **Single-machine, no built-in multi-user auth.** See
-  [Scope](#scope) above. Sharing a canvas
-  across machines today means committing `.pmx-canvas/state.json`.
-- **Excalidraw / external `mcp-app` flakes:** grouped Excalidraw element IDs
-  can change after edits, so an agent that builds a diagram in two passes
-  should capture every element ID immediately after `canvas_add_diagram`
-  returns. Editing while another tool call is in flight occasionally drops
-  the in-progress edit.
-- **External MCP apps are transport-based over MCP.** `canvas_open_mcp_app`
-  requires `toolName` plus a `transport` object for the external MCP server.
-  For the built-in Excalidraw preset, use `canvas_add_diagram`; the CLI's
-  `external-app add --kind excalidraw` is a higher-level convenience wrapper.
-- **Web-artifact build timeouts on cold installs.** The first
-  `canvas_build_web_artifact` call in a fresh workspace runs `pnpm install`
-  for ~30 dependencies. On constrained machines or slow networks, the
-  default timeout can fire before the install completes — bump
-  `--timeout-ms` (CLI) or `timeoutMs` (MCP/SDK) on first use, or
-  pre-warm with `bunx pmx-canvas web-artifact build --title warmup
-  --app-tsx 'export default () => null'`.
-- **Webpage-fetch failure modes.** Sites that require auth, render purely
-  client-side without server HTML, or block headless fetches will store
-  with empty extracted text. The node still works as a URL bookmark; the
-  agent's view of the content will be the URL only.
-- **Image cloud-on-demand stalls (macOS).** Images stored in iCloud Drive
-  / OneDrive that aren't downloaded locally are detected up-front and
-  rejected with a clear error rather than freezing the server. Download
-  the file locally first.
-- **`prompt` and `response` node types are internal.** They surface in
-  `canvas://layout` for thread rendering but aren't created via the public
-  `canvas_add_node` API.
-
 ## Architecture
 
 ```
 Agent harness (any MCP-capable client, CLI consumer, or HTTP caller)
   |
-  |-- MCP Server ---- 38 tools + 8 resources + change notifications
+  |-- MCP Server ---- 38 tools + 8 core resources + per-skill resources + change notifications
   |-- Bun SDK ------- createCanvas()
   |-- HTTP API ------ REST + SSE at localhost:4313
   |