pmx-canvas 0.1.18 → 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.18",
+  "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/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

@@ -1759,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-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',
             }));
           }