pmx-canvas 0.1.18 → 0.1.20

package/CHANGELOG.md

@@ -3,6 +3,132 @@
 All notable changes to `pmx-canvas` are documented here. This project follows
 [Semantic Versioning](https://semver.org/).
 
+## [0.1.20] - 2026-05-06
+
+A bigger feature release. Adds 18 reusable HTML communication
+primitives (choice grids, plans, review sheets, system maps, design
+sheets, decks, explainers, status reports, throwaway editors…) so
+agents can stop reaching for long markdown for structured artifacts,
+introduces text annotations alongside the existing pen/eraser, makes
+expanded mcp-app/webpage/json-render/graph viewers stretch to fill
+the overlay, fixes grid arrange to respect grouped children, and
+extracts the project-tour demo to a declarative JSON seed.
+
+### Added
+
+- **`canvas_add_html_primitive` and 18 communication primitives.**
+  A new MCP tool plus CLI `html primitive add` / `html primitive
+  schema` and HTTP `POST /api/canvas/node` with `{type:
+  "html-primitive", kind, data}` (or the alternative `{type:
+  "html", primitive: kind, data}`) generate sandboxed `html` nodes
+  from named primitives: `choice-grid`, `plan-timeline`,
+  `review-sheet`, `pr-writeup`, `system-map`, `code-walkthrough`,
+  `design-sheet`, `component-gallery`, `interaction-prototype`,
+  `flowchart`, `deck`, `illustration-set`, `explainer`,
+  `status-report`, `incident-report`, `triage-board`,
+  `config-editor`, `prompt-tuner`. The MCP canvas now exposes 42
+  tools (was 41). `canvas_describe_schema` adds an `htmlPrimitives`
+  array describing each primitive's data shape.
+- **Text annotations.** The annotation toolbar gains a third tool
+  alongside pen and eraser. Text annotations render as SVG `<text>`
+  using the `--c-annotation` token, persist alongside freehand
+  strokes (`type: 'text'` on `CanvasAnnotation`), and route through
+  the same HTTP create/delete + canvas-state undo/redo paths as the
+  freehand layer.
+- **Declarative demo seed (`src/server/demo-state.json`).** The
+  project-tour demo is now a 28KB JSON snapshot loaded by a small
+  `demo.ts` shim, replacing the 800-line imperative seed. Editing
+  the tour is now a JSON edit, and the unit tests exercise the
+  loader and verify a stable grouped layout.
+- **Install section in the README.** Documents `bunx pmx-canvas`,
+  `bun add -g pmx-canvas`, `bun add pmx-canvas` (for the SDK), and
+  `npm install -g pmx-canvas`, plus the Bun-on-PATH caveat (the
+  CLI uses a `#!/usr/bin/env bun` shebang). (Released as commits
+  `f9449e5`, `fe0843c`.)
+
+### Changed
+
+- **Expanded mcp-app / webpage / json-render / graph viewers
+  stretch to fill the overlay.** `ExpandedNodeOverlay` now wraps
+  embedded viewers in a flex container, json-render and graph
+  viewers receive `?display=expanded` in the URL plus a
+  `window.__PMX_CANVAS_JSON_RENDER_DISPLAY__` global, and a new
+  `useChartFrameHeight()` hook computes available content height
+  dynamically. Expanded charts no longer leave a white band at the
+  bottom of the overlay.
+- **Grid arrange preserves grouped child offsets.** The arrange
+  algorithm in the new shared `auto-arrange.ts` excludes grouped
+  children from translation. Previously the parent group was moved
+  *and* the child was moved relative to it, double-translating the
+  child off-screen. Undo restores the original positions exactly.
+- **CommandPalette gains a "New note" markdown shortcut.** Quick-
+  add a `markdown` node from the palette with the standard
+  520×360 default size.
+
+### Internal
+
+- Regression coverage for: HTML primitive CLI/MCP creation
+  producing searchable html nodes with primitive metadata, text
+  annotation persistence and HTTP create/delete, grid arrange
+  preserving grouped child offsets through the operation and its
+  undo, declarative demo seed loading into a stable grouped layout,
+  graph chart-height absent unless explicitly provided, and
+  expanded graph nodes stretching content to the overlay frame
+  (e2e), plus pen and text annotations starting over nodes (e2e).
+
+## [0.1.19] - 2026-05-05
+
+Snapshot ergonomics and reference-doc distribution. Adds `before` /
+`after` ISO timestamp filters on snapshot listing across CLI, HTTP,
+and MCP, ships the `docs/` reference tree inside the npm tarball so
+consumers see the same surface docs as the repo, and surfaces the
+existing trace-field flags in `node update --help`. Also lands the
+deflake of the MCP-app fullscreen reopen e2e (originally
+`LRN-20260505-001`) — 9/20 → 50+/50 stability via a retry-on-stuck-
+iframe helper.
+
+### Added
+
+- **`pmx-canvas snapshot list --before / --after`.** Both flags
+  accept ISO 8601 timestamps and filter against `snapshot.createdAt`.
+  Same surface lands on `GET /api/canvas/snapshots?before=&after=`,
+  `RemoteCanvasAccess.listSnapshots()`, and the `canvas_list_snapshots`
+  MCP tool schema. The CLI help (`pmx-canvas snapshot list --help`)
+  now lists the new flags alongside `--limit`, `--query`, and
+  `--all`.
+- **`docs/` shipped in the npm tarball.** The package `files`
+  allowlist now includes `docs/`, so consumers installing
+  `pmx-canvas` see the same `docs/cli.md`, `docs/http-api.md`,
+  `docs/mcp.md`, `docs/node-types.md`, and `docs/sdk.md` reference
+  files that ship in the repo.
+- **`node update --help` advertises trace flags.** The CLI help now
+  documents `--tool-name` / `--toolName`, `--category`, `--status`,
+  `--duration`, `--result-summary` / `--resultSummary`, and `--error`
+  so agents discover trace-field updates without reading the source
+  or schema.
+
+### Fixed
+
+- **MCP-app fullscreen reopen e2e is no longer flaky.** The
+  visibility check for the fixture editor used to race the ext-app
+  bridge handshake — if the iframe started parsing before the
+  parent registered its postMessage listener, the iframe's
+  `ui/initialize` request was lost and `app.connect()` hung. The
+  test now wraps the assertion in a retry-on-stuck-iframe helper
+  that closes and reopens the fullscreen overlay (each remount is
+  independent of the prior failed handshake), with three 5s
+  attempts to match the original 15s budget. Pass rate moved from
+  9/20 to 50+/50 consecutive runs.
+
+### Internal
+
+- Regression coverage for: snapshot list before/after filtering at
+  the canvas-state layer and through the CLI, snapshot list help
+  advertising the new flags, `node update --help` advertising
+  trace flags, the `docs/` allowlist entry surviving in
+  `package.json` for npm consumers, and the existing arrange
+  operation recording as a single undoable history entry.
+
 ## [0.1.18] - 2026-05-05
 
 Token-budget polish on top of 0.1.17. Full-mode MCP responses for
@@ -771,6 +897,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.1.20]: https://github.com/pskoett/pmx-canvas/releases/tag/v0.1.20
+[0.1.19]: https://github.com/pskoett/pmx-canvas/releases/tag/v0.1.19
 [0.1.18]: https://github.com/pskoett/pmx-canvas/releases/tag/v0.1.18
 [0.1.17]: https://github.com/pskoett/pmx-canvas/releases/tag/v0.1.17
 [0.1.16]: https://github.com/pskoett/pmx-canvas/releases/tag/v0.1.16

package/Readme.md

@@ -65,7 +65,7 @@ the canvas durable rather than throwaway.
 
 ### 06 / Any agent
 
-Harness-agnostic. Drive the canvas from [MCP](docs/mcp.md) (41 tools,
+Harness-agnostic. Drive the canvas from [MCP](docs/mcp.md) (42 tools,
 8 resources, change notifications), the [CLI](docs/cli.md), the
 [HTTP API](docs/http-api.md), or the [Bun SDK](docs/sdk.md). Works with
 Claude Code, GitHub Copilot CLI, Codex, Cursor, Windsurf, or any agent
@@ -78,22 +78,35 @@ that can spawn an MCP stdio server, call a CLI, or hit an HTTP endpoint.
 The published SDK entrypoint is Bun-first. Node.js consumers should use the
 CLI, MCP server, or HTTP API.
 
+## Install
+
+```bash
+bunx pmx-canvas              # Run without installing (recommended for one-off use)
+bun add -g pmx-canvas        # Install globally — exposes the `pmx-canvas` command
+bun add pmx-canvas           # Install into a project (needed for the Bun SDK)
+npm install -g pmx-canvas    # npm works too — still requires Bun on PATH to run
+```
+
+`pmx-canvas` is Bun-first: the CLI is a TypeScript file with a `#!/usr/bin/env bun`
+shebang, so Bun must be installed even when you fetch the package via npm or pnpm.
+
+To work on the canvas itself, clone the repo — see [Development](#development).
+
 ## Quick start
 
 ### Run the canvas
 
 ```bash
 bunx pmx-canvas              # Start canvas, open browser
-bunx pmx-canvas --demo       # Start with the project-tour demo board
+bunx pmx-canvas --demo       # Start with the saved dashboard demo board
 bunx pmx-canvas --no-open    # Headless (good for daemons / CI)
 bunx pmx-canvas --mcp        # Run as MCP server (stdio)
 bunx pmx-canvas --help       # All commands
 ```
 
 The canvas opens at `http://localhost:4313`. Try `--demo` first — it seeds a
-project tour with grouped markdown, status, file, image, webpage,
-json-render, graph, html, Excalidraw diagram, and MCP App nodes connected by
-labeled edges.
+saved dashboard with grouped OKR notes, graph panels, context pins, and labeled
+edges.
 
 ### Connect your agent (MCP)
 
@@ -143,7 +156,7 @@ the agent can read `canvas://skills` and pull in companion skills
   the three-tier visual matrix (json-render → html → web-artifact)
 - **[CLI reference](docs/cli.md)** — full command surface, daemon mode,
   watch streams, WebView automation
-- **[MCP reference](docs/mcp.md)** — 41 tools, 8 resources, change
+- **[MCP reference](docs/mcp.md)** — 42 tools, 8 resources, change
   notifications, node-type routing
 - **[HTTP API](docs/http-api.md)** — REST endpoints, SSE, batch operations
 - **[Bun SDK](docs/sdk.md)** — `createCanvas()` for TypeScript on Bun

package/dist/canvas/global.css

@@ -392,6 +392,19 @@ body,
   margin: 0.4em 0;
   color: var(--c-muted);
 }
+
+.canvas-node .node-body ul,
+.canvas-node .node-body ol {
+  margin: 0.4em 0;
+  padding-left: 0.25em;
+  list-style-position: inside;
+}
+
+.canvas-node .node-body li {
+  margin: 0.2em 0;
+  padding-left: 0.15em;
+}
+
 .canvas-node .node-body a {
   color: var(--c-accent);
   text-decoration: none;
@@ -1481,14 +1494,14 @@ body,
   height: 1px;
   overflow: visible;
   pointer-events: none;
-  z-index: 45;
+  z-index: 9000;
 }
 
 .annotation-capture-layer {
   position: absolute;
   inset: 0;
   z-index: 9996;
-  pointer-events: none;
+  pointer-events: auto;
   background: color-mix(in srgb, var(--c-accent) 5%, transparent);
 }
 
@@ -1496,6 +1509,26 @@ body,
   background: color-mix(in srgb, var(--c-danger) 6%, transparent);
 }
 
+.annotation-capture-layer.text {
+  background: color-mix(in srgb, var(--c-annotation) 4%, transparent);
+}
+
+.annotation-text-input {
+  position: absolute;
+  z-index: 9997;
+  min-width: 120px;
+  max-width: min(560px, calc(100% - 24px));
+  padding: 2px 4px;
+  border: 1px solid var(--c-annotation);
+  border-radius: 4px;
+  background: color-mix(in srgb, var(--c-bg) 72%, transparent);
+  color: var(--c-annotation);
+  font-family: var(--font);
+  font-weight: 700;
+  line-height: 1.15;
+  outline: none;
+}
+
 /* ── Drop Zone (file drag-and-drop) ─────────────────────────── */
 .drop-zone-overlay {
   position: absolute;