pmx-canvas 0.1.15 → 0.1.17

package/CHANGELOG.md

@@ -3,6 +3,128 @@
 All notable changes to `pmx-canvas` are documented here. This project follows
 [Semantic Versioning](https://semver.org/).
 
+## [0.1.17] - 2026-05-04
+
+Adds a freehand annotation layer so humans can draw directly on the
+canvas and agents read compact spatial annotation context (bounds,
+target nodes, optional label) without seeing the raw ink. Excalidraw
+bound-text → label hoisting now covers the full set of canonical and
+shorthand shapes the hosted app emits, and the `html` node type gets
+its first-class entry in `canvas_describe_schema` plus a CLI
+`--content` alias that maps to `data.html`.
+
+### Added
+
+- **Freehand canvas annotations.** A new top-level annotation layer
+  lets humans draw freehand strokes on the canvas with pen and
+  eraser tools wired into the toolbar. Annotations live alongside
+  nodes and edges in `canvasState` (their own `addAnnotation` /
+  `removeAnnotation` history operations), persist into snapshots,
+  and are rendered as SVG paths whose default `currentColor` stroke
+  follows the active theme via a new `--c-annotation` token.
+  Surfaces:
+  - HTTP: `POST /api/canvas/annotation`, `DELETE
+    /api/canvas/annotation/:id`.
+  - MCP: `canvas_remove_annotation` (the canvas now exposes 41 MCP
+    tools, was 40).
+  - Client: pen / eraser toolbar buttons with theme-aware iconography
+    and an `AnnotationLayer` that renders the strokes.
+- **Spatial annotation context for agents.** Each pinned-context /
+  spatial-context read now includes a compact
+  `SpatialAnnotationContext` per annotation: `id`, `label`,
+  `bounds`, `targetNodeIds`, `targetNodeTitles`, and `target`
+  summary. Agents see what the annotation *circles* (which nodes it
+  overlaps), not the freehand path itself, keeping the read budget
+  small while still letting the agent act on the human's intent.
+- **HTML node schema entry in `canvas_describe_schema`.** The `html`
+  node type added in 0.1.15 now appears in the schema tour with a
+  documented `html` field, `--content` / `--stdin` aliases, the
+  sandboxed-iframe note, and an example payload.
+- **CLI `--content` alias for HTML nodes.** `pmx-canvas node add
+  --type html --content '<main>Hello</main>'` is accepted as a
+  shorthand for setting `data.html` (also supported via `--stdin`).
+
+### Changed
+
+- **Excalidraw bound-text → container label hoisting now covers
+  every canonical shape.** The diagram preset
+  (`normalizeExcalidrawElementsForToolInput`) hoists text into a
+  `rectangle` / `ellipse` / `diamond` container's `label` for all
+  four patterns the hosted app emits: the canonical
+  `containerId`-pointing text, the centered-container variant,
+  pre-existing shorthand labels (preserved as-is), and the
+  `boundElements`-only path where the text lacks a back-reference.
+  Text alignment and vertical-alignment hints are forwarded into
+  the label when present.
+
+### Internal
+
+- Regression coverage for: annotation persistence and removal in
+  `canvasState`, annotation undo/redo history operations,
+  annotation create/delete over HTTP, html-content CLI alias
+  mapping, all four Excalidraw bound-text patterns, html node
+  rendering from server state in the browser (e2e), annotation
+  theme contrast plus eraser flow (e2e), and annotation toolbar
+  actions preserving the active light theme (e2e).
+
+## [0.1.16] - 2026-05-04
+
+Live-context-dock and undo-history hygiene pass on top of 0.1.15. The
+context dock now renders the actual pinned nodes instead of falling back
+to stale context-card data, auto-focus from ext-app opens stops
+polluting undo history, and a couple of HTTP endpoints reject malformed
+payloads instead of creating blank or empty nodes.
+
+### Added
+
+- **`ContextNode` renders the active pinned nodes.** A new exported
+  `normalizePinnedContextDisplay()` produces a stable `{id, title,
+  summary, kind, path}` shape per pinned node, and the component now
+  takes a `pinnedNodes` prop. The dock falls back to the previous
+  context-card data only when no nodes are pinned, so what the agent
+  reads via `canvas://pinned-context` and what the human sees in the
+  dock are now the same view.
+- **`StatusNode` exposes `getStatusDisplayPhase()` with a documented
+  fallback chain.** The display phase falls back `phase → content
+  → status → 'idle'` and is shared by the inline node, the summary,
+  and any consumer that needs the phase shown to the user.
+
+### Changed
+
+- **`ContextPinBar` is mutually exclusive with the Updates panel.**
+  Like the docked context node, the floating pin bar now hides while
+  the right-edge attention history panel is open so the two surfaces
+  no longer collide on the same anchor.
+- **Browser-driven viewport updates support `recordHistory: false`.**
+  Client `focusNode(id, options)` and the matching
+  `commitViewportWithOptions()` thread an optional
+  `{ recordHistory: false }` flag through to `POST
+  /api/canvas/viewport`, which now wraps the mutation in
+  `withSuppressedRecording` when the flag is set. Auto-focus
+  triggered by ext-app opens uses this path so opening an external
+  app no longer fills undo history with viewport churn.
+
+### Fixed
+
+- **HTML nodes reject non-string `html` payloads.** `POST
+  /api/canvas/node` and the matching MCP path now return a 400
+  with a clear error when an html node is created with `html` (or
+  `data.html`) set to a non-string value, instead of accepting the
+  payload and producing a blank node.
+- **Group creation rejects missing child IDs.** `POST
+  /api/canvas/group` (and `canvas_create_group`) no longer silently
+  creates an empty group when one or more of the requested children
+  do not exist; it returns a 400 listing the missing IDs.
+
+### Internal
+
+- Regression coverage for: client status-node display-phase fallback,
+  ext-app auto-focus history suppression on the client side, the
+  context dock rendering pinned nodes (e2e), HTML-node payload type
+  validation over HTTP, group-create child-presence validation over
+  HTTP, and the `recordHistory: false` flag on the viewport
+  endpoint.
+
 ## [0.1.15] - 2026-05-03
 
 A bigger release focused on right-sizing what flows through MCP and the
@@ -605,6 +727,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.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
 [0.1.15]: https://github.com/pskoett/pmx-canvas/releases/tag/v0.1.15
 [0.1.14]: https://github.com/pskoett/pmx-canvas/releases/tag/v0.1.14
 [0.1.13]: https://github.com/pskoett/pmx-canvas/releases/tag/v0.1.13

package/Readme.md

@@ -58,7 +58,7 @@ the canvas durable rather than throwaway.
 
 ### 05 / Any agent
 
-Harness-agnostic. Drive the canvas from [MCP](docs/mcp.md) (40 tools,
+Harness-agnostic. Drive the canvas from [MCP](docs/mcp.md) (41 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
@@ -136,7 +136,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)** — 40 tools, 8 resources, change
+- **[MCP reference](docs/mcp.md)** — 41 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

@@ -50,6 +50,7 @@
   --c-accent-hover: #6ECAFF;
   --c-warn-hover: #f5d06b;
   --c-canvas-wash: linear-gradient(180deg, rgba(255, 255, 255, 0.02), rgba(0, 0, 0, 0));
+  --c-annotation: #F4EFE6;
   /* ── Non-color tokens ────────────────────────────────────── */
   --font: "IBM Plex Sans", "SF Pro Text", "Avenir Next", system-ui, sans-serif;
   --mono: "IBM Plex Mono", "SF Mono", "Fira Code", monospace;
@@ -109,6 +110,7 @@
   --c-accent-hover: #1588CE;
   --c-warn-hover: #dab040;
   --c-canvas-wash: linear-gradient(180deg, rgba(255, 255, 255, 0.12), rgba(8, 21, 36, 0.02));
+  --c-annotation: #081524;
 }
 
 :root[data-theme="high-contrast"] {
@@ -162,6 +164,7 @@
   --c-accent-hover: #33ffff;
   --c-warn-hover: #ffff33;
   --c-canvas-wash: linear-gradient(180deg, rgba(255, 255, 255, 0.03), rgba(255, 255, 255, 0));
+  --c-annotation: #ffff00;
 }
 
 * {
@@ -1471,6 +1474,28 @@ body,
   z-index: 9998;
 }
 
+.annotation-layer {
+  position: absolute;
+  inset: 0;
+  width: 1px;
+  height: 1px;
+  overflow: visible;
+  pointer-events: none;
+  z-index: 45;
+}
+
+.annotation-capture-layer {
+  position: absolute;
+  inset: 0;
+  z-index: 9996;
+  pointer-events: none;
+  background: color-mix(in srgb, var(--c-accent) 5%, transparent);
+}
+
+.annotation-capture-layer.erasing {
+  background: color-mix(in srgb, var(--c-danger) 6%, transparent);
+}
+
 /* ── Drop Zone (file drag-and-drop) ─────────────────────────── */
 .drop-zone-overlay {
   position: absolute;