pmx-canvas 0.1.1 → 0.1.3

package/CHANGELOG.md

@@ -3,6 +3,137 @@
 All notable changes to `pmx-canvas` are documented here. This project follows
 [Semantic Versioning](https://semver.org/).
 
+## [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 /
+UX bugs, one long-tail stability fix in the MCP App host, plus new agent
+ergonomics (version flag, skill discovery).
+
+### Added
+
+- **`pmx-canvas --version` / `-v`.** Prints the installed package version and
+  exits. Version is read from the sibling `package.json` so it stays accurate
+  whether the CLI is invoked via `bunx`, a global npm install, or a repo-local
+  `bun run` — no hard-coded string, no build step required.
+- **`canvas://skills` MCP resource.** Agent skills bundled with the npm install
+  (`skills/<name>/SKILL.md`) are now discoverable through MCP. The `canvas://skills`
+  resource returns a JSON index (name, description, per-skill URI), and each
+  skill is addressable individually at `canvas://skills/<name>`. The
+  `canvas_build_web_artifact` tool description now explicitly points agents at
+  `canvas://skills/web-artifacts-builder` for the full workflow, stack choices,
+  and anti-slop design guidelines.
+
+### Fixed
+
+- **`image` node no longer accepts non-image file paths.** Creating an image
+  node with a path like `report.pptx` previously stored the path silently
+  with no `mimeType`; the server now rejects the request with a 400 and a
+  helpful message listing the accepted extensions (png, jpg, jpeg, gif, svg,
+  webp, bmp, avif, ico). `data:` URIs are validated against `image/*` media
+  types. Use `type="file"` or `type="webpage"` for non-image sources.
+- **`web-artifact` init is more resilient on machines with tight process
+  limits.** `init-artifact.sh` and `bundle-artifact.sh` now spawn in their
+  own POSIX process group so timeouts and failures kill every descendant
+  (pnpm, bun, parcel, swc, lmdb) instead of leaving orphans that accumulate
+  FDs and eventually produce `fork: Resource temporarily unavailable`. pnpm's
+  internal child concurrency is capped to 2 via
+  `pnpm_config_child_concurrency` so the ~30-package shadcn install doesn't
+  blow past macOS's default `ulimit -u`. Failure responses now include the
+  last 20 lines of stderr (falling back to stdout) so the cause of an exit
+  code is visible directly in the API response rather than requiring a manual
+  re-run of the shell script.
+- **MCP App (`mcp-app` / Excalidraw) state sync.** Edits saved by an MCP App
+  widget now propagate via SSE to other clients hosting the same app node
+  (fixes Excalidraw losing multi-client sync). The host also suppresses
+  echo-back re-renders when a layout update mints a new `toolResult`
+  reference with unchanged content — so a widget's own `callServerTool` call
+  no longer causes its UI to re-render mid-interaction.
+- **MCP App inline-mode click safety.** The ext-app iframe in inline mode is
+  now covered by a transparent `ext-app-preview-catcher` overlay that opens
+  the fullscreen view on click, rather than letting stray canvas clicks
+  reach the widget. Agents / users interact with widgets in the expanded
+  overlay (via MCP tools or direct click); inline mode stays a safe
+  preview.
+
+### Internal
+
+- New unit tests: `image` node validation (accepted extensions, URL + data
+  URI paths, rejected non-image extensions, rejected non-image data URIs)
+  and `canvas://skills` discovery (loader resolves the packaged skills
+  directory, index is stable-sorted, individual skill contents resolve,
+  unknown names return null).
+- Shared `extAppToolResultsMatch` helper in `src/shared/ext-app-tool-result.ts`
+  for structural equality between `CallToolResult` values, used by the host
+  ExtAppFrame to dedupe SSE-delivered tool results.
+- E2E: Counter-fixture test updated for the new expand-to-interact
+  interaction model (opens the `.ext-app-preview-catcher` overlay, finds
+  the iframe in `.expanded-overlay-panel`, force-clicks the in-widget button
+  to tolerate the widget's auto-resize settling).
+
+[0.1.2]: https://github.com/pskoett/pmx-canvas/releases/tag/v0.1.2
+
 ## [0.1.1] - 2026-04-24
 
 ### Changed

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
 ```