pmx-canvas 0.1.17 → 0.1.18

package/CHANGELOG.md

@@ -3,6 +3,50 @@
 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
@@ -727,6 +771,7 @@ 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

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,7 +63,7 @@ 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) (41 tools,
 8 resources, change notifications), the [CLI](docs/cli.md), the

package/dist/types/server/canvas-serialization.d.ts

@@ -33,8 +33,10 @@ export declare function getCanvasNodeKind(node: CanvasNodeState, data: Record<st
 export declare function getCanvasNodeTitle(node: CanvasNodeState): string | null;
 export declare function getCanvasNodeContent(node: CanvasNodeState): string | null;
 export declare function serializeCanvasNode(node: CanvasNodeState): SerializedCanvasNode;
+export declare function serializeCanvasNodeForAgent(node: CanvasNodeState): SerializedCanvasNode;
 export declare function serializeCanvasNodeWithBlobSummaries(node: CanvasNodeState): SerializedCanvasNode;
 export declare function serializeCanvasLayout(layout: CanvasLayout): SerializedCanvasLayout;
+export declare function serializeCanvasLayoutForAgent(layout: CanvasLayout): SerializedCanvasLayout;
 export declare function serializeCanvasLayoutWithBlobSummaries(layout: CanvasLayout): SerializedCanvasLayout;
 export declare function summarizeCanvasAnnotation(annotation: CanvasAnnotation): CanvasAnnotationSummary;
 export declare function summarizeCanvasAnnotationForContext(annotation: CanvasAnnotation, nodes: CanvasNodeState[]): CanvasAnnotationContextSummary;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmx-canvas",
-  "version": "0.1.17",
+  "version": "0.1.18",
   "description": "Spatial canvas workbench for coding agents — infinite 2D canvas with agent-native CLI, MCP integration, nodes, edges, file watching, and snapshots",
   "type": "module",
   "main": "./src/server/index.ts",

package/skills/pmx-canvas/SKILL.md

@@ -622,6 +622,8 @@ canvas_webview_stop();
 - Do not use separate `text` elements with `containerId`/`boundElements` to place centered text
   inside shapes. The hosted SVG preview does not auto-position those; PMX normalizes imported
   canonical bound text back into shape labels for hosted app calls.
+- For detailed sizing, camera, and label-fit rules, read `references/excalidraw-diagram-authoring.md`
+  before creating dense diagrams.
 - Prefer the pastel fill palette in the Excalidraw `read_me` (light blue/green/orange/...) for
   a consistent look across diagrams
 

package/skills/pmx-canvas/references/excalidraw-diagram-authoring.md

@@ -0,0 +1,145 @@
+# Excalidraw Diagram Authoring
+
+Use this guide when creating diagrams through PMX Canvas with `canvas_add_diagram` or
+`pmx-canvas external-app add --kind excalidraw`.
+
+## Why Text Can Still Drift
+
+PMX normalizes canonical Excalidraw bound text (`containerId` / `boundElements`) into the hosted
+app's supported shape-level `label` format before calling Excalidraw. That fixes the payload
+format mismatch, but it does not fix poor diagram geometry.
+
+Text can still appear clipped or misplaced when:
+
+- A label is too long for its shape.
+- A diamond or ellipse is too small for the label's usable center area.
+- The `cameraUpdate` viewport is too tight or not 4:3.
+- Title, footer, or notes are placed near the camera edge.
+- The caller bypasses PMX and sends raw elements directly to Excalidraw MCP.
+
+## Text Format Rules
+
+For text inside a rectangle, ellipse, or diamond, use shape-level `label`:
+
+```json
+{
+  "type": "rectangle",
+  "id": "step-a",
+  "x": 100,
+  "y": 100,
+  "width": 260,
+  "height": 90,
+  "label": { "text": "Step A", "fontSize": 18 }
+}
+```
+
+Do not create separate centered text elements for shape labels:
+
+```json
+{
+  "type": "text",
+  "containerId": "step-a",
+  "text": "Step A"
+}
+```
+
+Standalone text is fine for titles, notes, captions, and free-floating annotations. For standalone
+text, `x` is the left edge; `textAlign` does not center it on a point.
+
+## Label Length Rules
+
+- Use 1-4 words inside shapes.
+- Put detailed explanations in nearby standalone text annotations.
+- Prefer `Bound Text` over `Pattern B: containerId+boundElements only`.
+- If a label needs more than 4 words, either widen the shape or split the idea into a label plus an annotation.
+
+## Shape Sizing Rules
+
+- Minimum labeled rectangle or ellipse: `180x80`.
+- For 3-5 word labels: `240x90` or larger.
+- For long labels: `320+` width or use an external annotation.
+- Diamonds need more room than rectangles because the usable center area is smaller.
+- Leave at least `30px` gap between shapes and labels/arrows.
+
+## Camera Rules
+
+Always start with a `cameraUpdate` as the first element.
+
+Use 4:3 camera sizes only:
+
+- `400x300`
+- `600x450`
+- `800x600`
+- `1200x900`
+- `1600x1200`
+
+Camera bounds must include the full diagram plus padding. Leave at least `80px` padding around all
+visible content.
+
+Example:
+
+```json
+{ "type": "cameraUpdate", "x": 20, "y": 0, "width": 1200, "height": 900 }
+```
+
+If a title, footer, or rightmost label is clipped, the camera is wrong even if the elements are valid.
+
+## Good Pattern
+
+```json
+[
+  { "type": "cameraUpdate", "x": 20, "y": 0, "width": 1200, "height": 900 },
+  {
+    "type": "rectangle",
+    "id": "a",
+    "x": 120,
+    "y": 160,
+    "width": 260,
+    "height": 90,
+    "backgroundColor": "#a5d8ff",
+    "fillStyle": "solid",
+    "label": { "text": "Short Label", "fontSize": 18 }
+  },
+  {
+    "type": "rectangle",
+    "id": "b",
+    "x": 520,
+    "y": 160,
+    "width": 280,
+    "height": 90,
+    "backgroundColor": "#b2f2bb",
+    "fillStyle": "solid",
+    "label": { "text": "Next Step", "fontSize": 18 }
+  },
+  {
+    "type": "arrow",
+    "id": "a-to-b",
+    "x": 390,
+    "y": 205,
+    "width": 110,
+    "height": 0,
+    "points": [[0, 0], [110, 0]],
+    "endArrowhead": "arrow",
+    "label": { "text": "then", "fontSize": 14 }
+  },
+  {
+    "type": "text",
+    "id": "note",
+    "x": 120,
+    "y": 290,
+    "text": "Longer explanation goes here, outside the shape.",
+    "fontSize": 16
+  }
+]
+```
+
+## Preflight Checklist
+
+- Shape text uses `label`, not separate `text` elements.
+- Shape labels are short enough to fit.
+- Long explanations are outside shapes.
+- The first element is a 4:3 `cameraUpdate`.
+- Camera has at least `80px` padding around all visible content.
+- Titles and footers are not near the camera edge.
+- Arrows have explicit `points` and enough space for labels.
+- Calls go through PMX (`canvas_add_diagram` or `external-app add --kind excalidraw`) unless you manually apply these rules to raw Excalidraw MCP input.

package/src/mcp/server.ts

@@ -29,7 +29,13 @@ import { createCanvasAccess, refreshCanvasAccess, type CanvasAccess } from './ca
 import { serializeNodeForAgentContext } from '../server/agent-context.js';
 import { wrapCanvasAutomationScript } from '../server/server.js';
 import { buildSpatialContext, findNeighborhoods } from '../server/spatial-analysis.js';
-import { getCanvasNodeTitle, serializeCanvasLayout, serializeCanvasNode, summarizeCanvasAnnotationForContext } from '../server/canvas-serialization.js';
+import {
+  getCanvasNodeTitle,
+  serializeCanvasLayoutForAgent,
+  serializeCanvasNode,
+  serializeCanvasNodeForAgent,
+  summarizeCanvasAnnotationForContext,
+} from '../server/canvas-serialization.js';
 import { listBundledSkills, readBundledSkill } from '../server/bundled-skills.js';
 
 let canvas: CanvasAccess | null = null;
@@ -207,7 +213,7 @@ function compactLayoutPayload(layout: Awaited<ReturnType<CanvasAccess['getLayout
 
 function agentSafeFullLayoutPayload(layout: Awaited<ReturnType<CanvasAccess['getLayout']>>): Record<string, unknown> {
   return {
-    ...serializeCanvasLayout(layout),
+    ...serializeCanvasLayoutForAgent(layout),
     annotations: (layout.annotations ?? []).map((annotation) => summarizeCanvasAnnotationForContext(annotation, layout.nodes)),
   };
 }
@@ -240,7 +246,7 @@ async function createdNodePayload(c: CanvasAccess, id: string, options: { full?:
   if (!wantsFullPayload(options)) {
     return { ok: true, node: compactNodePayload(node), id };
   }
-  const serialized = serializeCanvasNode(node);
+  const serialized = serializeCanvasNodeForAgent(node);
   return { ok: true, node: serialized, ...serialized };
 }
 
@@ -324,7 +330,7 @@ export async function startMcpServer(): Promise<void> {
           isError: true,
         };
       }
-      const payload = wantsFullPayload(input) ? serializeCanvasNode(node) : compactNodePayload(node);
+      const payload = wantsFullPayload(input) ? serializeCanvasNodeForAgent(node) : compactNodePayload(node);
       return {
         content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
       };

package/src/server/canvas-serialization.ts

@@ -1,3 +1,4 @@
+import { createHash } from 'node:crypto';
 import { canvasState } from './canvas-state.js';
 import type { CanvasAnnotation, CanvasLayout, CanvasNodeState, ViewportState } from './canvas-state.js';
 import {
@@ -47,6 +48,13 @@ interface BlobSummary {
   sha256: string;
 }
 
+interface ExternalMcpAppHtmlSummary {
+  omitted: 'external-mcp-app-html';
+  resourceUri: string;
+  bytes: number;
+  sha256: string;
+}
+
 function pickString(value: unknown): string | null {
   return typeof value === 'string' && value.length > 0 ? value : null;
 }
@@ -90,6 +98,39 @@ export function serializeCanvasNode(node: CanvasNodeState): SerializedCanvasNode
   };
 }
 
+function summarizeExternalMcpAppHtml(node: SerializedCanvasNode): Record<string, unknown> {
+  const html = node.data.html;
+  const resourceUri = node.data.resourceUri;
+  if (
+    node.type !== 'mcp-app' ||
+    node.data.mode !== 'ext-app' ||
+    typeof html !== 'string' ||
+    html.length === 0 ||
+    typeof resourceUri !== 'string' ||
+    resourceUri.length === 0
+  ) {
+    return node.data;
+  }
+
+  return {
+    ...node.data,
+    html: {
+      omitted: 'external-mcp-app-html',
+      resourceUri,
+      bytes: Buffer.byteLength(html, 'utf-8'),
+      sha256: createHash('sha256').update(html).digest('hex'),
+    } satisfies ExternalMcpAppHtmlSummary,
+  };
+}
+
+export function serializeCanvasNodeForAgent(node: CanvasNodeState): SerializedCanvasNode {
+  const serialized = serializeCanvasNode(node);
+  return {
+    ...serialized,
+    data: summarizeExternalMcpAppHtml(serialized),
+  };
+}
+
 function summarizeBlobValue(value: unknown): unknown {
   if (!canvasState.isBlobReference(value)) return value;
   return {
@@ -117,6 +158,13 @@ export function serializeCanvasLayout(layout: CanvasLayout): SerializedCanvasLay
   };
 }
 
+export function serializeCanvasLayoutForAgent(layout: CanvasLayout): SerializedCanvasLayout {
+  return {
+    ...layout,
+    nodes: layout.nodes.map(serializeCanvasNodeForAgent),
+  };
+}
+
 export function serializeCanvasLayoutWithBlobSummaries(layout: CanvasLayout): SerializedCanvasLayout {
   return {
     ...layout,