pmx-canvas 0.1.17 → 0.1.19

package/docs/sdk.md

@@ -0,0 +1,92 @@
+# JavaScript/TypeScript SDK (Bun runtime)
+
+The published SDK entrypoint is Bun-first. Node.js consumers should use the
+[CLI](cli.md), [MCP server](mcp.md), or [HTTP API](http-api.md) instead.
+
+```bash
+bun add pmx-canvas
+```
+
+## Quick example
+
+```ts
+import { createCanvas } from 'pmx-canvas';
+
+const canvas = createCanvas({ port: 4313 });
+await canvas.start({ open: true });
+
+// Add nodes
+const n1 = canvas.addNode({ type: 'markdown', title: 'Plan', content: '# Step 1\nDo the thing.' });
+const n2 = canvas.addNode({ type: 'status', title: 'Build', content: 'passing' });
+const n3 = canvas.addNode({ type: 'file', content: 'src/index.ts' });
+
+// Connect them
+canvas.addEdge({ from: n1, to: n2, type: 'flow' });
+
+// Group related nodes
+canvas.createGroup({ title: 'Build Pipeline', childIds: [n1, n2] });
+
+// Self-contained HTML in a sandboxed iframe
+canvas.addHtmlNode({
+  title: 'Cost projection',
+  html: '<canvas id="c"></canvas><script src="https://cdn.jsdelivr.net/npm/chart.js"></script><script>/* ... */</script>',
+});
+
+// Hand-drawn diagram via the Excalidraw MCP-app preset
+await canvas.addDiagram({
+  elements: [
+    { type: 'rectangle', id: 'r1', x: 80, y: 80, width: 160, height: 60,
+      roundness: { type: 3 }, backgroundColor: '#a5d8ff', fillStyle: 'solid',
+      label: { text: 'Agent' } },
+  ],
+  title: 'Quick sketch',
+});
+
+// Batch-build a graph and group around it
+await canvas.runBatch([
+  {
+    op: 'graph.add',
+    assign: 'graph',
+    args: {
+      title: 'Major wins',
+      graphType: 'bar',
+      data: [
+        { label: 'Docs', value: 5 },
+        { label: 'Tests', value: 8 },
+      ],
+      xKey: 'label',
+      yKey: 'value',
+    },
+  },
+  {
+    op: 'group.create',
+    args: {
+      title: 'Quarterly graphs',
+      childIds: ['$graph.id'],
+    },
+  },
+]);
+
+// Arrange and inspect
+canvas.arrange('grid');
+console.log(canvas.validate());
+console.log(canvas.getLayout());
+```
+
+## WebView automation
+
+```ts
+const webview = await canvas.startAutomationWebView({ backend: 'chrome', width: 1280, height: 800 });
+console.log(webview.active);
+console.log(await canvas.evaluateAutomationWebView('document.title'));
+await canvas.resizeAutomationWebView(1440, 900);
+const screenshot = await canvas.screenshotAutomationWebView({ format: 'png' });
+console.log(screenshot.byteLength);
+await canvas.stopAutomationWebView();
+```
+
+## See also
+
+- [Node types](node-types.md) — what each node type is for
+- [HTTP API](http-api.md) — the same operations from any language
+- [MCP reference](mcp.md) — the agent-facing surface

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmx-canvas",
-  "version": "0.1.17",
+  "version": "0.1.19",
   "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",
@@ -18,6 +18,7 @@
   "files": [
     "src/",
     "skills/",
+    "docs/",
     "dist/canvas/",
     "dist/json-render/",
     "dist/types/",

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/cli/agent.ts

@@ -1698,6 +1698,7 @@ cmd('snapshot save', 'Save a named snapshot of the current canvas', [
 cmd('snapshot list', 'List saved snapshots', [
   'pmx-canvas snapshot list',
   'pmx-canvas snapshot list --limit 50 --query baseline',
+  'pmx-canvas snapshot list --after 2026-05-01T00:00:00Z --before 2026-05-05T00:00:00Z',
   'pmx-canvas snapshot list --all',
 ], async (args) => {
   const { flags } = parseFlags(args);
@@ -1706,8 +1707,12 @@ cmd('snapshot list', 'List saved snapshots', [
   const params = new URLSearchParams();
   const limit = optionalNumberFlag(flags, 'limit', 'Use a positive integer, e.g. --limit 50');
   const query = getStringFlag(flags, 'query', 'q');
+  const before = getStringFlag(flags, 'before');
+  const after = getStringFlag(flags, 'after');
   if (limit !== undefined) params.set('limit', String(limit));
   if (query) params.set('q', query);
+  if (before) params.set('before', before);
+  if (after) params.set('after', after);
   if (flags.all) params.set('all', 'true');
   const result = await api('GET', `/api/canvas/snapshots${params.size > 0 ? `?${params.toString()}` : ''}`);
   output(result);
@@ -2328,8 +2333,20 @@ function showCommandHelp(name: string): void {
     console.log('\nOptions:');
     console.log('  --limit <number>          Maximum snapshots to return (default 20)');
     console.log('  --query <text>            Case-insensitive ID/name filter');
+    console.log('  --before <timestamp>      Only return snapshots created at or before this ISO timestamp');
+    console.log('  --after <timestamp>       Only return snapshots created at or after this ISO timestamp');
     console.log('  --all                     Return all snapshots');
   }
+  if (name === 'node update') {
+    console.log('\nTrace fields:');
+    console.log('  --tool-name, --toolName   Trace tool or operation label');
+    console.log('  --category <name>         Trace category, e.g. mcp, file, subagent, other');
+    console.log('  --status <status>         Trace status, e.g. running, success, failed');
+    console.log('  --duration <text>         Trace duration badge text');
+    console.log('  --result-summary, --resultSummary <text>');
+    console.log('                            Trace result summary');
+    console.log('  --error <text>            Trace error message');
+  }
   if (name === 'snapshot gc') {
     console.log('\nOptions:');
     console.log('  --keep <number>           Number of newest snapshots to keep (default 20)');

package/src/mcp/canvas-access.ts

@@ -559,6 +559,8 @@ class RemoteCanvasAccess implements CanvasAccess {
     const params = new URLSearchParams();
     if (typeof options?.limit === 'number') params.set('limit', String(options.limit));
     if (options?.query) params.set('q', options.query);
+    if (options?.before) params.set('before', options.before);
+    if (options?.after) params.set('after', options.after);
     if (options?.all) params.set('all', 'true');
     const query = params.size > 0 ? `?${params.toString()}` : '';
     return await this.requestJson<SnapshotList>('GET', `/api/canvas/snapshots${query}`);

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) }],
       };
@@ -1753,6 +1759,8 @@ export async function startMcpServer(): Promise<void> {
     {
       limit: z.number().optional().describe('Maximum snapshots to return (default: 20)'),
       query: z.string().optional().describe('Optional case-insensitive ID/name filter'),
+      before: z.string().optional().describe('Only return snapshots created at or before this ISO timestamp'),
+      after: z.string().optional().describe('Only return snapshots created at or after this ISO timestamp'),
       all: z.boolean().optional().describe('Return all snapshots instead of the default limit'),
     },
     async (input) => {

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,

package/src/server/canvas-state.ts

@@ -32,6 +32,12 @@ function normalizePositiveInteger(value: number | undefined): number | undefined
   return Math.floor(value);
 }
 
+function normalizeSnapshotTimestamp(value: string | undefined): string | undefined {
+  if (!value) return undefined;
+  const parsed = Date.parse(value);
+  return Number.isFinite(parsed) ? new Date(parsed).toISOString() : undefined;
+}
+
 export const PMX_CANVAS_DIR = '.pmx-canvas';
 const STATE_FILENAME = 'state.json';
 const SNAPSHOTS_SUBDIR = 'snapshots';
@@ -89,6 +95,8 @@ export interface CanvasSnapshot {
 export interface CanvasSnapshotListOptions {
   limit?: number;
   query?: string;
+  before?: string;
+  after?: string;
   all?: boolean;
 }
 
@@ -856,11 +864,16 @@ class CanvasStateManager {
         }
       }
       const query = options.query?.trim().toLowerCase();
-      const filtered = query
-        ? snapshots.filter((snapshot) =>
-          snapshot.id.toLowerCase().includes(query) || snapshot.name.toLowerCase().includes(query),
-        )
-        : snapshots;
+      const before = normalizeSnapshotTimestamp(options.before);
+      const after = normalizeSnapshotTimestamp(options.after);
+      const filtered = snapshots.filter((snapshot) => {
+        if (query && !snapshot.id.toLowerCase().includes(query) && !snapshot.name.toLowerCase().includes(query)) {
+          return false;
+        }
+        if (before && snapshot.createdAt > before) return false;
+        if (after && snapshot.createdAt < after) return false;
+        return true;
+      });
       const sorted = filtered.sort((a, b) => b.createdAt.localeCompare(a.createdAt));
       const limit = options.all ? undefined : (normalizePositiveInteger(options.limit) ?? 20);
       return limit === undefined ? sorted : sorted.slice(0, limit);

package/src/server/server.ts

@@ -4145,6 +4145,8 @@ export function startCanvasServer(options: CanvasServerOptions = {}): string | n
             return responseJson(listCanvasSnapshots({
               limit: parsePositiveIntegerParam(url.searchParams.get('limit')),
               query: url.searchParams.get('q') ?? url.searchParams.get('query') ?? undefined,
+              before: url.searchParams.get('before') ?? undefined,
+              after: url.searchParams.get('after') ?? undefined,
               all: url.searchParams.get('all') === 'true',
             }));
           }