pmx-canvas 0.1.17 → 0.1.19

package/docs/cli.md

@@ -0,0 +1,140 @@
+# CLI reference
+
+The CLI is the shell-native way to run and control PMX Canvas. It targets
+`http://localhost:4313` by default — override with `PMX_CANVAS_URL` or
+`PMX_CANVAS_PORT` when the server runs elsewhere.
+
+## Server lifecycle
+
+```bash
+pmx-canvas                            # Start canvas, open browser
+pmx-canvas --demo                     # Start with the project-tour demo board
+pmx-canvas --port=8080                # Custom port
+pmx-canvas --no-open                  # Headless (for agents/CI)
+pmx-canvas --theme=light              # dark | light | high-contrast
+pmx-canvas --mcp                      # Run as MCP server (stdio)
+pmx-canvas --webview-automation       # Start headless Bun.WebView session
+pmx-canvas open                       # Open the current workbench in a browser
+```
+
+### Daemon mode
+
+Run detached with pid/log tracking instead of holding a terminal:
+
+```bash
+pmx-canvas serve --daemon --no-open --wait-ms=20000   # Start detached, wait for health
+pmx-canvas serve status                               # Inspect daemon health + pid
+pmx-canvas serve stop                                 # Stop the daemon for this port
+```
+
+## Nodes and edges
+
+```bash
+pmx-canvas node add --type webpage --url https://example.com/docs
+pmx-canvas node add --type web-artifact --title "Dashboard" --app-file ./App.tsx
+pmx-canvas node add --type graph --graph-type bar --data-file ./metrics.json --x-key label --y-key value
+pmx-canvas node add --type graph --graph-type bar --data '[{"x":"a","y":1}]' --x-key x --y-key y
+pmx-canvas graph add --graph-type bar --data '[{"x":"a","y":1}]' --x-key x --y-key y   # Alias
+pmx-canvas node add --help --type webpage --json                                        # Schema for one type
+
+pmx-canvas external-app add --kind excalidraw --title "Diagram"
+
+pmx-canvas edge add --from-search "DVT O3 — GitOps" --to-search "deep work trend" --type relation
+```
+
+`--from-search` / `--to-search` must each resolve to exactly one node — broad
+queries fail rather than guess. Use the full visible title.
+
+CLI create commands return the created node shape with normalized title,
+content, and geometry, which makes scripting stacked layouts and batch
+follow-ups easier.
+
+### Graph height flags
+
+Graph height flags split by target:
+
+- `--node-height` / `--nodeHeight` — the canvas node frame
+- `--chart-height` — the chart content inside the node
+- `--height` — accepted as a frame-height compatibility alias
+
+For MCP/HTTP payloads, use `nodeHeight` for the frame and `height` for chart
+content.
+
+## Discovery and validation
+
+```bash
+pmx-canvas node schema --type json-render --component Table --summary
+pmx-canvas validate                                                      # Layout validation
+pmx-canvas validate spec --type json-render --spec-file ./dashboard.json --summary
+```
+
+The schema commands surface the running server's data, which is strictly
+better than guessing flags or payloads.
+
+## Batch and arrange
+
+```bash
+pmx-canvas batch --file ./canvas-ops.json
+```
+
+See [HTTP API → batch](http-api.md#batch-operations) for the operation
+schema; the same JSON works for the CLI batch file.
+
+## Web artifacts
+
+```bash
+pmx-canvas web-artifact build --title "Dashboard" --app-file ./App.tsx --deps recharts --include-logs
+```
+
+Failed or empty CLI bundles print `ok: false`, exit non-zero, and do not
+create a canvas node.
+
+## Watch (semantic deltas)
+
+`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
+```
+
+## Focus
+
+```bash
+pmx-canvas focus <node-id>            # Pan viewport to a node
+pmx-canvas focus <node-id> --no-pan   # Select/raise without panning
+```
+
+## WebView automation
+
+Drive a headless Bun.WebView (Chromium or WebKit) pointed at the workbench:
+
+```bash
+pmx-canvas webview status
+pmx-canvas webview start --backend chrome --width 1440 --height 900
+pmx-canvas webview evaluate --expression "document.title"
+pmx-canvas webview resize --width 1280 --height 800
+pmx-canvas webview screenshot --output ./canvas.png
+pmx-canvas webview stop
+```
+
+Use WebView for visual annotation inspection. Agent-readable canvas context only
+reports annotation targets and bounds; it does not describe whether the human
+drew an arrow, line, circle, or other shape. Inspect `.annotation-layer path` or
+take a screenshot when the drawn form matters.
+
+Humans draw with the pen toolbar button and remove marks with the eraser button.
+If an agent already knows the annotation ID from context, it can remove it through
+MCP with `canvas_remove_annotation`.
+
+## When to reach for the CLI
+
+- Direct terminal control without MCP wiring
+- Shell scripts and CI-friendly automation
+- Schema-driven discovery from the running server
+- Local debugging of canvas, webview, and screenshot flows
+- A control surface that covers normal canvas work without MCP wiring

package/docs/evals/e2e-cli-coverage.md

@@ -0,0 +1,61 @@
+---
+id: eval-20260424-001
+pattern-key: pmx-canvas.cli-e2e-fresh-workspace
+source: pmx-canvas-0.1.2-e2e-cli-coverage-report
+promoted-rule: "Fresh-workspace CLI coverage must verify node creation, parseable JSON, web-artifact failure behavior, external apps, arrange/validate, and focus no-pan before release."
+promoted-to: package.json test:e2e-cli
+created: 2026-04-24
+last-run: 2026-04-25
+last-result: pass
+---
+
+# PMX Canvas CLI E2E Coverage Eval
+
+## What This Tests
+
+Prevents regressions in the published-agent CLI flows that caused the 0.1.2 E2E report failures.
+
+## Precondition
+
+- Bun is installed.
+- The repo has been built with `bun run build` when client/browser assets changed.
+- Network is available for the hosted Excalidraw MCP preset and web-artifact dependency install.
+- Port `4567` is free, or `PMX_CANVAS_E2E_PORT` is set to a free port.
+
+## Verification Method
+
+Command check:
+
+```bash
+bun run test:e2e-cli
+```
+
+The command runs `scripts/e2e-cli-coverage.sh`, which creates a fresh temp workspace, starts the local PMX Canvas CLI server, and verifies:
+
+- `layout` and `node list` emit JSON parseable by Python's `json` module.
+- Core node types can be created through the CLI, including two webpage input paths.
+- Graph nodes accept `--data` as an alias for `--data-json`.
+- All graph variants create successfully: line, bar, pie, area, scatter, radar, stacked-bar, composed.
+- Simple and dashboard-shaped json-render specs create successfully.
+- Generic `node add --type mcp-app` is rejected with guidance.
+- `external-app add --kind excalidraw` creates a tool-backed app node.
+- Broken web-artifact builds return `ok: false`, exit non-zero, and do not create a node.
+- One successful web-artifact build emits a substantial bundled React/Recharts app, opens a node, and browser-verifies the real app content renders in the iframe.
+- `focus --no-pan` selects without viewport panning.
+- `arrange --layout grid` and `validate` agree on a valid layout.
+- Search can find artifact nodes and `status` reports expected graph/json-render/web-artifact counts.
+
+## Expected Result
+
+**Pass:** `PMX Canvas CLI E2E coverage passed` and exit code 0.
+
+**Fail:** Any command exits non-zero, JSON parsing fails, an assertion fails, or the server does not become healthy.
+
+## Recovery Action
+
+If this eval fails:
+
+1. Re-run with `PMX_CANVAS_E2E_KEEP_WORKDIR=1 bun run test:e2e-cli` to preserve the temp workspace.
+2. Inspect the preserved `.pmx-canvas/` state and `pmx-canvas.log` printed by the script.
+3. Fix the failing CLI/server path and add or update the narrower unit regression.
+4. Re-run `bun run test:e2e-cli`, then `bun run test:all` before release.

package/docs/http-api.md

@@ -0,0 +1,191 @@
+# HTTP API reference
+
+REST endpoints for all canvas operations + an SSE event stream. Works from
+any language. Default base URL: `http://localhost:4313`.
+
+## Canvas state
+
+```bash
+# Get canvas state
+curl http://localhost:4313/api/canvas/state
+
+# Search nodes
+curl "http://localhost:4313/api/canvas/search?q=auth"
+
+# Validate the current layout
+curl http://localhost:4313/api/canvas/validate
+
+# Inspect running-server schemas
+curl http://localhost:4313/api/canvas/schema
+
+# Validate a json-render spec without creating a node
+curl -X POST http://localhost:4313/api/canvas/schema/validate \
+  -H "Content-Type: application/json" \
+  -d '{"type":"json-render","spec":{"root":"card","elements":{"card":{"type":"Card","props":{"title":"Preview"},"children":[]}}}}'
+```
+
+## Nodes
+
+```bash
+# Add a node
+curl -X POST http://localhost:4313/api/canvas/node \
+  -H "Content-Type: application/json" \
+  -d '{"type":"markdown","title":"Hello","content":"# World"}'
+
+# Add an html node (sandboxed iframe)
+curl -X POST http://localhost:4313/api/canvas/node \
+  -H "Content-Type: application/json" \
+  -d '{"type":"html","title":"Chart","html":"<canvas id=\"c\"></canvas><script src=\"https://cdn.jsdelivr.net/npm/chart.js\"></script><script>/* ... */</script>"}'
+```
+
+## Edges
+
+```bash
+# Add an edge
+curl -X POST http://localhost:4313/api/canvas/edge \
+  -H "Content-Type: application/json" \
+  -d '{"from":"node-1","to":"node-2","type":"flow","label":"next"}'
+
+# Add an edge by unique search match instead of explicit IDs
+curl -X POST http://localhost:4313/api/canvas/edge \
+  -H "Content-Type: application/json" \
+  -d '{"fromSearch":"DVT O3 — GitOps","toSearch":"deep work trend","type":"relation"}'
+```
+
+Search-based edge creation is intentionally strict: `fromSearch` and
+`toSearch` must each resolve to exactly one node. Broad queries that match
+multiple nodes fail; use the full visible title.
+
+## Annotations
+
+```bash
+# Add a freehand annotation. The default/currentColor stroke follows the active theme.
+curl -X POST http://localhost:4313/api/canvas/annotation \
+  -H "Content-Type: application/json" \
+  -d '{"points":[{"x":100,"y":120},{"x":220,"y":120}],"color":"currentColor","width":4}'
+
+# Remove an annotation
+curl -X DELETE http://localhost:4313/api/canvas/annotation/ann-123
+```
+
+Agent-readable context reports annotation IDs, targets, and bounds. Use WebView
+inspection or screenshots when the drawn shape matters.
+
+## Pins
+
+```bash
+# Pin nodes for agent context
+curl -X POST http://localhost:4313/api/canvas/context-pins \
+  -H "Content-Type: application/json" \
+  -d '{"nodeIds":["node-1","node-2"]}'
+
+# Get pinned context
+curl http://localhost:4313/api/canvas/pinned-context
+```
+
+## Diagrams (Excalidraw preset)
+
+```bash
+curl -X POST http://localhost:4313/api/canvas/diagram \
+  -H "Content-Type: application/json" \
+  -d '{"elements":[{"type":"rectangle","id":"r1","x":60,"y":60,"width":180,"height":80,"roundness":{"type":3},"backgroundColor":"#a5d8ff","fillStyle":"solid","label":{"text":"Hello","fontSize":18}}],"title":"Diagram"}'
+```
+
+## SSE event stream
+
+```bash
+curl -N http://localhost:4313/api/workbench/events
+```
+
+The browser, the CLI `watch` command, and the MCP resource notifications
+all consume this stream. Auto-reconnect with exponential backoff.
+
+## Time travel
+
+```bash
+curl -X POST http://localhost:4313/api/canvas/undo
+curl -X POST http://localhost:4313/api/canvas/redo
+curl http://localhost:4313/api/canvas/history
+```
+
+## WebView automation
+
+```bash
+# Start WebView automation
+curl -X POST http://localhost:4313/api/workbench/webview/start \
+  -H "Content-Type: application/json" \
+  -d '{"backend":"chrome","width":1280,"height":800}'
+
+# Evaluate JS in the active WebView session
+curl -X POST http://localhost:4313/api/workbench/webview/evaluate \
+  -H "Content-Type: application/json" \
+  -d '{"expression":"document.title"}'
+
+# Resize the active WebView session
+curl -X POST http://localhost:4313/api/workbench/webview/resize \
+  -H "Content-Type: application/json" \
+  -d '{"width":1440,"height":900}'
+
+# Capture a screenshot
+curl -X POST http://localhost:4313/api/workbench/webview/screenshot \
+  -H "Content-Type: application/json" \
+  -d '{"format":"png"}' \
+  --output canvas.png
+```
+
+## Batch operations
+
+Build a canvas in one shot. Earlier results can be referenced from later
+operations via `$assigned-name.field`.
+
+```bash
+curl -X POST http://localhost:4313/api/canvas/batch \
+  -H "Content-Type: application/json" \
+  -d '{"operations":[{"op":"node.add","assign":"a","args":{"type":"markdown","title":"A"}},{"op":"group.create","args":{"title":"Frame","childIds":["$a.id"]}}]}'
+```
+
+Supported operations:
+
+- `node.add`, `node.update`
+- `graph.add`
+- `edge.add`
+- `group.create`, `group.add`, `group.remove`
+- `pin.set`, `pin.add`, `pin.remove`
+- `snapshot.save`
+- `arrange`
+
+`node.add` supports `type: "webpage"` inside batch. The batch itself still
+succeeds when the webpage node is created but the fetch fails; the
+per-operation result includes `fetch: { ok, error? }` plus a top-level
+`error` field for the fetch problem.
+
+Example with assignments:
+
+```json
+{
+  "operations": [
+    {
+      "op": "graph.add",
+      "assign": "wins",
+      "args": {
+        "title": "Major wins",
+        "graphType": "bar",
+        "data": [
+          { "label": "Docs", "value": 5 },
+          { "label": "Tests", "value": 8 }
+        ],
+        "xKey": "label",
+        "yKey": "value"
+      }
+    },
+    {
+      "op": "group.create",
+      "assign": "frame",
+      "args": {
+        "title": "Quarterly graphs",
+        "childIds": ["$wins.id"]
+      }
+    }
+  ]
+}
+```

package/docs/mcp.md

@@ -0,0 +1,135 @@
+# MCP reference
+
+PMX Canvas ships an MCP stdio server with **41 tools** + **8 core resources**,
+plus per-skill resources at `canvas://skills/<name>`. The server emits
+`notifications/resources/updated` when canvas state changes — humans pin
+nodes in the browser, agents are notified immediately.
+
+## Connect
+
+Add to your agent's MCP config:
+
+```json
+{
+  "mcpServers": {
+    "canvas": {
+      "command": "bunx",
+      "args": ["pmx-canvas", "--mcp"]
+    }
+  }
+}
+```
+
+The canvas auto-starts on first tool call.
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `canvas_add_node` | Add a node (markdown, status, context, file, webpage, html, etc.) |
+| `canvas_add_html_node` | Create an `html` node from a self-contained HTML/JS document (sandboxed iframe) |
+| `canvas_add_diagram` | Hand-drawn diagram via the hosted Excalidraw MCP App (preset alias for `canvas_open_mcp_app`) |
+| `canvas_open_mcp_app` | Open any [MCP Apps](https://modelcontextprotocol.io/docs/extensions/apps) server's `ui://` resource as an iframe node |
+| `canvas_describe_schema` | Describe the running server's create schemas, examples, and json-render catalog |
+| `canvas_validate_spec` | Validate a json-render spec or graph payload without creating a node |
+| `canvas_refresh_webpage_node` | Re-fetch and update a webpage node from its stored URL |
+| `canvas_add_json_render_node` | Create a native json-render node from a validated spec |
+| `canvas_add_graph_node` | Create a native graph node (line, bar, pie, area, scatter, radar, stacked-bar, composed) |
+| `canvas_build_web_artifact` | Build a bundled HTML artifact and open it on the canvas |
+| `canvas_update_node` | Update content, position, size, collapsed state |
+| `canvas_remove_node` | Remove a node and its edges |
+| `canvas_get_layout` | Get full canvas state |
+| `canvas_get_node` | Get a single node by ID |
+| `canvas_remove_annotation` | Remove a human-drawn annotation by ID |
+| `canvas_add_edge` | Connect two nodes |
+| `canvas_remove_edge` | Remove a connection |
+| `canvas_arrange` | Auto-arrange (grid/column/flow) |
+| `canvas_validate` | Validate collisions, containment, and missing edge endpoints |
+| `canvas_focus_node` | Pan viewport to a node; use CLI `focus --no-pan` when you only need to select/raise |
+| `canvas_pin_nodes` | Pin nodes to include in agent context |
+| `canvas_clear` | Clear all nodes and edges |
+| `canvas_snapshot` | Save current canvas as a named snapshot |
+| `canvas_list_snapshots` | List saved snapshots, bounded to the newest 20 by default |
+| `canvas_gc_snapshots` | Delete old snapshots while keeping the newest N |
+| `canvas_restore` | Restore canvas from a saved snapshot |
+| `canvas_delete_snapshot` | Delete a saved snapshot |
+| `canvas_search` | Find nodes by title/content keywords |
+| `canvas_undo` | Undo the last canvas mutation |
+| `canvas_redo` | Redo the last undone mutation |
+| `canvas_diff` | Compare current canvas vs a saved snapshot |
+| `canvas_create_group` | Create a group containing specified nodes |
+| `canvas_group_nodes` | Add nodes to an existing group |
+| `canvas_ungroup` | Release all children from a group |
+| `canvas_batch` | Run a batch of canvas operations with `$ref` support |
+| `canvas_webview_status` | Get Bun.WebView automation status for the workbench |
+| `canvas_webview_start` | Start or replace the Bun.WebView automation session |
+| `canvas_webview_stop` | Stop the active Bun.WebView automation session |
+| `canvas_evaluate` | Evaluate JavaScript in the active workbench automation session |
+| `canvas_resize` | Resize the active workbench automation viewport |
+| `canvas_screenshot` | Capture a screenshot from the active workbench automation session |
+
+## Resources
+
+Individual bundled skills are also readable at `canvas://skills/<name>`.
+
+| Resource | Description |
+|----------|-------------|
+| `canvas://pinned-context` | Content of pinned nodes + nearby unpinned neighbors |
+| `canvas://schema` | Running-server create schemas and json-render catalog metadata |
+| `canvas://layout` | Full canvas state (all nodes, edges, viewport) |
+| `canvas://summary` | Compact overview: counts, pinned titles, viewport |
+| `canvas://spatial-context` | Proximity clusters, reading order, pinned neighborhoods |
+| `canvas://history` | Mutation history timeline with undo/redo position |
+| `canvas://code-graph` | Auto-detected file dependency graph (JS/TS, Python, Go, Rust) |
+| `canvas://skills` | Index of bundled agent skills + per-skill content at `canvas://skills/<name>` |
+
+## Change notifications
+
+The MCP server emits `notifications/resources/updated` whenever canvas state
+changes:
+
+- Pin changes notify `canvas://pinned-context`
+- All mutations notify `canvas://layout`, `canvas://summary`,
+  `canvas://spatial-context`, `canvas://history`, and `canvas://code-graph`
+
+This closes the human-to-agent loop: spatial curation in the browser becomes
+an immediate signal in the agent's context.
+
+## Annotation Visibility
+
+Human-drawn canvas annotations are rendered as browser SVG ink. MCP resources
+keep annotation context compact: agents see annotation counts, bounds, and target
+summaries such as the node or empty canvas region that was marked, but not the
+raw stroke geometry or visual shape.
+
+Annotations are a browser-visible markup layer. Use the pen toolbar button to
+draw and the eraser toolbar button to remove an annotation again; agents can also
+remove a known annotation ID with `canvas_remove_annotation`.
+
+Use WebView automation when an agent needs to actually see annotations as drawn.
+For example, inspect `.annotation-layer path` with `canvas_evaluate` or capture a
+`canvas_screenshot` to distinguish an arrow from a line, circle, or highlight.
+
+## Node-type routing
+
+MCP node creation uses dedicated tools for structured node families. Read
+`mcp.nodeTypeRouting` from `canvas_describe_schema` / `canvas://schema` when
+in doubt:
+
+- `json-render` → `canvas_add_json_render_node`
+- `graph` → `canvas_add_graph_node`
+- `html` → `canvas_add_html_node`
+- `web-artifact` → `canvas_build_web_artifact`
+- `mcp-app` → `canvas_open_mcp_app`
+- `group` → `canvas_create_group`
+- Basic nodes (`markdown`, `status`, `file`, `image`, `webpage`) →
+  `canvas_add_node`
+
+## CLI/MCP alignment
+
+CLI and MCP are kept aligned for the main canvas operations: node and edge
+creation, graph/json-render/html 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 — resource subscriptions and
+`canvas_diff` — remain MCP-only.