pmx-canvas 0.1.2 → 0.1.4

package/CHANGELOG.md

@@ -3,6 +3,150 @@
 All notable changes to `pmx-canvas` are documented here. This project follows
 [Semantic Versioning](https://semver.org/).
 
+## [0.1.4] - 2026-04-26
+
+Graph/CLI ergonomics + canvas-node taxonomy hardening. Three threads:
+(1) full graph payload surface (`zKey`, `axisKey`, `metrics`, `series`,
+`barKey`/`lineKey`, `barColor`/`lineColor`) reaches CLI/MCP/HTTP/batch with
+both kebab-case and camelCase flag aliases, (2) `mcp-app` nodes serialize a
+`kind` discriminator so agents can target `web-artifact` / `external-app` /
+`mcp-app` subtypes without inspecting `data`, (3) the long-standing
+`ext-app-ext-app-…` double-prefix bug on node IDs is fixed with explicit
+`nodeId` propagation through SSE.
+
+### Added
+
+- Serialized `kind` discriminator on every canvas node. `mcp-app` nodes now
+  surface as `web-artifact`, `external-app`, or `mcp-app` so agents can
+  filter via `node list --type web-artifact` or
+  `--type external-app` directly.
+- Full graph payload surface on MCP, HTTP `validate-spec`, and `batch`:
+  `zKey`, `axisKey`, `metrics`, `series`, `barKey`, `lineKey`, `barColor`,
+  `lineColor`. Radar (`metrics`), stacked-bar (`series`), and composed
+  (`barKey`/`lineKey`) configs are now uniformly addressable.
+- CLI camelCase aliases for graph flags: `--graphType`, `--xKey`, `--yKey`,
+  `--zKey`, `--axisKey`, `--barKey`, `--lineKey`, `--barColor`,
+  `--lineColor`, alongside existing kebab-case forms. Same fields land in
+  `canvas_validate_spec` and `canvas_batch`.
+- `id` field on `external-app add` / `canvas_open_mcp_app` /
+  `canvas_add_diagram` responses (alias for the canvas node ID, matches
+  HTTP).
+- `viewerType: 'web-artifact'` persisted on web-artifact mcp-app nodes for
+  authoritative `kind` classification.
+
+### Changed
+
+- `SerializedCanvasNode` now includes `kind: string` (additive; consumers
+  grouping by `type === 'mcp-app'` should switch to `kind`).
+- `canvas://summary` `typeCounts` keys are derived from `kind`, not `type` —
+  `mcp-app` totals split into `web-artifact` / `external-app` / `mcp-app`.
+- Charts wrap with type-specific CSS modifier classes
+  (`pmx-chart--line/--bar/--pie/--area/--scatter/--radar/--stacked-bar/--composed`)
+  and per-type minimum widths, so axes don't clip in narrow nodes.
+- `canvas-schema.ts` cleanup based on the v0.1.4 review:
+  - `nodeHeight` no longer aliases `height` (collision with the chart-content
+    `height` field). Use `--node-height` going forward; `--height` always
+    means chart content height.
+  - `stdin` removed from the `data` and `appTsx` aliases — `--stdin` is an
+    input-mode (read from pipe), not a flag synonym. Behavior unchanged;
+    schema is now accurate.
+
+### Fixed
+
+- Excalidraw / external-app node IDs no longer double-prefix to
+  `ext-app-ext-app-…`. The canvas node ID retains the `ext-app-` prefix; the
+  `toolCallId` is the random suffix only.
+- SSE `ext-app-open` / `ext-app-update` / `ext-app-result` events now carry
+  an explicit `nodeId` so the client and server agree on node identity even
+  after the ID-format change.
+- `getCanvasNodeKind` precedence reordered so a future URL-only web-artifact
+  (no `data.path`) still classifies correctly via `viewerType`. The legacy
+  `hostMode + path` heuristic is now an explicitly-documented backwards-compat
+  fallback for canvas state.json files persisted before v0.1.4.
+
+### Internal
+
+- `findCanvasExtAppNodeId` extracted into `src/server/ext-app-lookup.ts` and
+  shared between `src/server/index.ts` and `src/server/server.ts` (was
+  duplicated; drift risk eliminated).
+- `shouldReplayAppToolResult` documented with explicit intent: only `isError`
+  or `structuredContent` results overwrite the bootstrap-replay
+  `toolResult`, so a plain-text `read_checkpoint`-style return doesn't
+  clobber widget state on reload.
+- E2E coverage now exercises camelCase graph flags and asserts the
+  single-prefix node-ID fix.
+- New unit coverage:
+  - `kind` discriminator across fresh, URL-only, legacy, ext-app, and
+    plain-mcp-app paths (6 tests).
+  - Camel-case graph flags in CLI.
+  - Full-surface graph validation in MCP `canvas_validate_spec`.
+  - Single-prefix node-ID round-trip in `external-app add`.
+  - Post-restart text-tool replay semantics.
+
+[0.1.4]: https://github.com/pskoett/pmx-canvas/releases/tag/v0.1.4
+
+## [0.1.3] - 2026-04-25
+
+CLI hardening release with full MCP parity for the new affordances. Closes
+gaps surfaced by the v0.1.2 fresh-install E2E (silent web-artifact failures,
+generic `mcp-app` confusion, viewport-hijacking focus), persists Excalidraw
+edits across iframe remounts, and ships a new `test:e2e-cli` coverage eval.
+
+### Added
+
+- `pmx-canvas external-app add --kind excalidraw` for tool-backed Excalidraw
+  nodes, with optional `--elements-json` / `--elements-file` / position +
+  size flags.
+- `pmx-canvas web-artifact build --deps <csv|json>` and matching HTTP
+  `deps?: string[]` for adding npm dependencies before bundling. Validated
+  against npm-name format; flags and shell metacharacters are rejected. The
+  web-artifact scaffold now bundles `recharts` by default.
+  **MCP:** `canvas_build_web_artifact` accepts `deps` for parity.
+- `pmx-canvas focus <id> --no-pan` (and HTTP `noPan: true`) selects/raises
+  a node without moving the viewport. The HTTP response gains
+  `panned: boolean`; the SSE `canvas-focus-node` event payload gains
+  `noPan`. **MCP:** `canvas_focus_node` accepts `noPan` for parity. **SDK:**
+  `c.focusNode(id, { noPan? })` returns `{ focused, panned } | null`.
+- `pmx-canvas node add --type graph --data <json>` as an alias for
+  `--data-json`.
+- `bun run test:e2e-cli` (`scripts/e2e-cli-coverage.sh` +
+  `docs/evals/e2e-cli-coverage.md`) — fresh-workspace CLI coverage eval.
+- `skills/pmx-canvas/references/installing-pmx-canvas.md` install reference
+  for first-run agents.
+
+### Changed
+
+- `pmx-canvas node add --type mcp-app …` is now rejected with guidance
+  pointing at `web-artifact build` or `external-app add` instead of creating
+  an empty node.
+- `pmx-canvas web-artifact build` exits non-zero with `ok: false` JSON on
+  bundle failure and does not create a canvas node.
+- `pmx-canvas status` buckets hosted artifact `mcp-app` nodes under
+  `web-artifact`.
+- Grid arrange spaces columns by the widest movable node so wide artifacts
+  do not overlap; `POST /api/canvas/arrange` returns `validation` +
+  `collisions` when the resulting layout has overlaps.
+
+### Fixed
+
+- Excalidraw edits made in fullscreen are now persisted into a replayable
+  `toolResult` and survive iframe remounts
+  (`POST /api/ext-app/model-context`).
+- Web-artifact builds fail loudly instead of emitting a zero-byte HTML when
+  Parcel/html-inline produce empty output (`bundle-artifact.sh` exits early
+  on missing/empty Parcel output).
+
+### Internal
+
+- Web-artifact dep installer now uses `bash -c` instead of `bash -lc`, so
+  the user's login profile (`~/.bashrc`/`~/.zshrc`) cannot perturb installs.
+- Removed the redundant post-copy bundle-size check (the script-side check
+  already guarantees a non-empty source; CLAUDE.md TypeScript Guardrail #3).
+- New unit coverage in `cli-node`, `server-api`, `web-artifacts`, and
+  `canvas-operations` test suites.
+
+[0.1.3]: https://github.com/pskoett/pmx-canvas/releases/tag/v0.1.3
+
 ## [0.1.2] - 2026-04-24
 
 Follow-up to 0.1.1 driven by fresh-install review feedback. Two validation /

package/Readme.md

@@ -28,6 +28,7 @@ The published SDK entrypoint is Bun-first: `import { createCanvas } from 'pmx-ca
 
 ```bash
 bunx pmx-canvas              # Start canvas, open browser
+bunx pmx-canvas serve --daemon --no-open --wait-ms=20000
 bunx pmx-canvas --demo       # Start with sample nodes
 bunx pmx-canvas --mcp        # Run as MCP server
 ```
@@ -143,9 +144,9 @@ The canvas auto-starts on first tool call. Works with Claude Code, Cursor, Winds
 | `file` | Live file viewer with auto-update on disk changes |
 | `image` | Image viewer (file paths, data URIs, URLs) |
 | `webpage` | Persisted webpage snapshot with stored URL, extracted text, and refresh support |
-| `mcp-app` | Hosted MCP app iframes (Excalidraw, Chart.js, etc.) -- see [MCP app nodes](#mcp-app-nodes) |
+| `mcp-app` | Tool-backed hosted MCP app iframes (Excalidraw, web artifacts, etc.) -- see [MCP app nodes](#mcp-app-nodes) |
 | `json-render` | Structured UI from JSON specs |
-| `graph` | Line, bar, and pie charts |
+| `graph` | Line, bar, pie, area, scatter, radar, stacked-bar, and composed charts |
 | `group` | Spatial container/frame that contains other nodes |
 
 Thread node types `prompt` and `response` are used internally for agent conversation
@@ -185,6 +186,10 @@ canvas_refresh_webpage_node({ id: 'node-abc123' })
 sandboxed iframes. Any server that implements the [MCP Apps extension](https://modelcontextprotocol.io/docs/extensions/apps)
 can be opened as a node with `canvas_open_mcp_app`.
 
+Generic `pmx-canvas node add --type mcp-app` is intentionally rejected because these nodes need
+tool/session metadata. Use `pmx-canvas web-artifact build` for bundled React artifacts or
+`pmx-canvas external-app add --kind excalidraw` for the Excalidraw preset.
+
 #### Recommended: Excalidraw (hand-drawn diagrams)
 
 [Excalidraw](https://github.com/excalidraw/excalidraw-mcp) ships a hosted MCP server at
@@ -196,6 +201,10 @@ supports fullscreen editing when you want to expand it into a larger workspace.
 PMX Canvas ships a preset so an agent can open an Excalidraw diagram in one call, without wiring
 the transport by hand:
 
+```bash
+pmx-canvas external-app add --kind excalidraw --title "Agent to Canvas"
+```
+
 ```typescript
 canvas_add_diagram({
   elements: [
@@ -229,7 +238,8 @@ canvas_open_mcp_app({
 
 The canvas runs the tool against the remote MCP server, renders the returned `ui://` resource in
 a sandboxed iframe node, and keeps the resource's CSP + permission hints intact. Resize, drag,
-and pin the node like any other canvas node.
+and pin the node like any other canvas node. Edits made in expanded/fullscreen mode are persisted
+back into the node model context and replayed when the iframe remounts.
 
 ### Json-render nodes
 
@@ -266,9 +276,13 @@ self-contained HTML to `.pmx-canvas/artifacts/<slug>.html`, and (by default) ope
 
 ```bash
 pmx-canvas node add --type web-artifact --title "Dashboard" --app-file ./App.tsx
-pmx-canvas web-artifact build --title "Dashboard" --app-file ./App.tsx --include-logs
+pmx-canvas web-artifact build --title "Dashboard" --app-file ./App.tsx --deps recharts --include-logs
 ```
 
+The scaffold includes `recharts` for chart-heavy artifacts. Pass `--deps name,name2` for any
+additional package dependencies before bundling. Failed or empty CLI bundles print `ok: false`,
+exit non-zero, and do not create a canvas node.
+
 The matching agent skill is at [skills/web-artifacts-builder/SKILL.md](skills/web-artifacts-builder/SKILL.md).
 
 ### Groups
@@ -494,7 +508,7 @@ layout validation, graph/json-render nodes, group control, snapshots, and search
 | `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) |
+| `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 |
@@ -504,7 +518,7 @@ layout validation, graph/json-render nodes, group control, snapshots, and search
 | `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 |
+| `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 |
@@ -706,6 +720,9 @@ await canvas.stopAutomationWebView();
 
 The CLI is the equally recommended shell-native way to run and control PMX Canvas.
 
+The CLI targets `http://localhost:4313` by default. Override with `PMX_CANVAS_URL` or
+`PMX_CANVAS_PORT` when the server runs elsewhere.
+
 ```bash
 pmx-canvas                        # Start canvas, open browser
 pmx-canvas --demo                 # Start with sample nodes
@@ -721,13 +738,16 @@ pmx-canvas open                   # Open the current workbench in a browser
 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 --help --type webpage --json
+pmx-canvas external-app add --kind excalidraw --title "Diagram"
 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 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 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 --include-logs
+pmx-canvas web-artifact build --title "Dashboard" --app-file ./App.tsx --deps recharts --include-logs
 pmx-canvas webview status         # Show WebView automation status
 pmx-canvas webview start --backend chrome --width 1440 --height 900
 pmx-canvas webview evaluate --expression "document.title"
@@ -808,9 +828,15 @@ bun run dev:portless:demo     # Same, with demo nodes
 bun run test                  # Unit tests
 bun run test:coverage         # Unit tests with text summary + coverage/lcov.info
 bun run test:e2e              # Playwright end-to-end tests
-bun run test:all              # All tests
+bun run test:e2e-cli          # Fresh-workspace CLI coverage eval
+bun run test:all              # Unit tests + browser smoke
 ```
 
+`bun run test:e2e-cli` starts a local server in a fresh temp workspace and verifies the CLI flows
+from the durable eval in [docs/evals/e2e-cli-coverage.md](docs/evals/e2e-cli-coverage.md):
+parseable JSON, node creation, graph `--data`, web-artifact failure handling, Excalidraw external
+apps, `focus --no-pan`, arrange/validate, and status subtype reporting.
+
 ## Release
 
 Use this sequence before publishing a new version:
@@ -818,6 +844,7 @@ Use this sequence before publishing a new version:
 ```bash
 bun install --frozen-lockfile
 bun run release:check
+bun run test:e2e-cli
 bun run release:smoke
 bun run pack:dry-run
 ```