pmx-canvas 0.1.16 → 0.1.18

package/CHANGELOG.md

@@ -3,6 +3,114 @@
 All notable changes to `pmx-canvas` are documented here. This project follows
 [Semantic Versioning](https://semver.org/).
 
+## [0.1.18] - 2026-05-05
+
+Token-budget polish on top of 0.1.17. Full-mode MCP responses for
+hosted external-MCP-app nodes now elide the rendered shell HTML in
+favor of a compact `{ omitted, resourceUri, bytes, sha256 }` summary,
+so an agent that asks for `full: true` no longer re-receives the same
+ext-app shell HTML on every read. Adds a dedicated
+`excalidraw-diagram-authoring.md` skill reference and folds the
+freehand annotation feature into the README's main feature list.
+
+### Added
+
+- **`serializeCanvasNodeForAgent` / `serializeCanvasLayoutForAgent`.**
+  New agent-facing serializers wrap the existing
+  `serializeCanvasNode` / `serializeCanvasLayout` helpers and replace
+  hosted ext-app shell HTML (`mcp-app` nodes in `ext-app` mode that
+  carry a `resourceUri`) with a `{ omitted: 'external-mcp-app-html',
+  resourceUri, bytes, sha256 }` descriptor. The MCP server uses
+  these wrappers for `canvas_get_node` (full), `canvas_get_layout`
+  (full), and the full-payload branch of every add-style response.
+  Non-external-app HTML — `html` nodes, bundled web-artifact
+  output — is preserved exactly as before.
+- **`skills/pmx-canvas/references/excalidraw-diagram-authoring.md`.**
+  A 145-line authoring guide for `canvas_add_diagram` covering shape-
+  level `label` format, sizing and camera rules, the pastel palette,
+  and common pitfalls. The SKILL points to it from the diagram
+  guidance section.
+
+### Changed
+
+- **README adds an `03 / Annotate` section.** The annotation feature
+  shipped in 0.1.17 is now part of the main README feature list
+  alongside Curate / Mix / Control / Save / Any agent. Subsequent
+  sections were renumbered (Control your context → 04, Save → 05,
+  Any agent → 06).
+
+### Internal
+
+- Regression coverage for: agent-mode node serialization eliding
+  hosted ext-app shell HTML, agent-mode layout serialization not
+  repeating the ext-app shell across multiple nodes, non-external-
+  app HTML payloads being preserved unchanged, and `canvas_get_node`
+  / `canvas_get_layout` full-mode elision through the MCP server.
+
+## [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
@@ -663,6 +771,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.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
 [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

package/Readme.md

@@ -1,8 +1,8 @@
 # pmx-canvas
 
 **A moldable canvas for agent-assisted thinking.** An infinite 2D surface
-where files, plans, status, charts, fetched web pages, and hand-drawn
-diagrams live side by side. Every node carries its own renderer; agents
+where files, plans, status, charts, fetched web pages, annotations, and
+hand-drawn diagrams live side by side. Every node carries its own renderer; agents
 (and you) build new views in the middle of a session, not as a separate
 tooling project. Pin what matters and the agent reads your spatial
 curation as structured context.
@@ -41,14 +41,21 @@ surface. The reach of the canvas is the union of its
 already has access to** — MCP servers, CLIs, file reads, web fetch, anything
 on its toolbelt.
 
-### 03 / Control your context
+### 03 / Annotate
+
+Draw freehand marks directly on the canvas to circle, underline, connect, or
+call out what matters without turning the markup into another node. Annotations
+persist with state and snapshots, can be erased in the browser, and appear to
+agents as compact spatial context: target, bounds, and nearby canvas content.
+
+### 04 / Control your context
 
 Pinning is an explicit, low-noise control over what the agent sees next. No
 prompt engineering, no copy-paste — pin a node in the browser and the MCP
 server fires a `notifications/resources/updated` event the agent's harness
 picks up immediately.
 
-### 04 / Save
+### 05 / Save
 
 Spatial state auto-saves to `.pmx-canvas/state.json` (debounced ~500 ms) —
 git-committable, shareable across machines, and survives both browser
@@ -56,9 +63,9 @@ refresh and server restart. Named [snapshots](docs/mcp.md#tools), full
 undo/redo, and an auto-detected code graph (JS/TS, Python, Go, Rust) make
 the canvas durable rather than throwaway.
 
-### 05 / Any agent
+### 06 / 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 +143,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;