pmx-canvas 0.1.25 → 0.1.26

package/CHANGELOG.md

@@ -3,6 +3,47 @@
 All notable changes to `pmx-canvas` are documented here. This project follows
 [Semantic Versioning](https://semver.org/).
 
+## [0.1.26] - 2026-06-03
+
+Small follow-up to 0.1.25. `canvas_add_node` can now create populated
+groups directly, the snapshot diff is available over HTTP, and the
+packaged skill documents host-aware browser-panel etiquette.
+
+### Added
+
+- **`canvas_add_node({ type: 'group' })` creates a populated group.**
+  The generic add path (MCP and SDK) now routes `type: 'group'` to
+  `createGroup`, accepting `children` / `childIds` (node IDs to
+  enclose), an optional `childLayout` (`grid` / `column` / `flow`),
+  and a frame `color`. `canvas_create_group` remains the dedicated
+  entry point; this just removes the dead-end where `canvas_add_node`
+  produced an empty group node. Child-ID validation is inherited from
+  `createGroup` (missing / self / nested-group children rejected).
+- **`GET /api/canvas/snapshots/diff` over HTTP.** The snapshot-vs-
+  current-layout diff that was previously MCP-only (`canvas_diff`) is
+  now reachable over HTTP at
+  `/api/canvas/snapshots/diff?name=<name|id>`, returning both the
+  structured `diff` and a `text` rendering. Missing name → 400,
+  unknown snapshot → 404.
+
+### Changed
+
+- **Packaged skill documents host-aware browser-panel etiquette.**
+  `skills/pmx-canvas/SKILL.md` now tells agents to reuse an existing
+  native canvas panel (e.g. the GitHub Copilot `pmx-canvas` extension
+  or Codex's in-app Browser on `/workbench`) instead of opening a
+  second browser panel to the same workbench, and to open the browser
+  workbench only when no native adapter is present. It also restates
+  that only same-origin `/api/canvas/frame-documents/<id>` URLs are
+  auto-trusted — external `mcp-app` URLs show the unverified-domain
+  interstitial by design.
+
+### Internal
+
+- Regression coverage for: `canvas_add_node` group creation via both
+  `children` and `childIds` (MCP), and the HTTP snapshot-diff endpoint
+  returning the snapshot name in the structured diff.
+
 ## [0.1.25] - 2026-06-03
 
 Adapter-regression cleanup on top of 0.1.24. Fixes several issues the
@@ -1235,6 +1276,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.26]: https://github.com/pskoett/pmx-canvas/releases/tag/v0.1.26
 [0.1.25]: https://github.com/pskoett/pmx-canvas/releases/tag/v0.1.25
 [0.1.24]: https://github.com/pskoett/pmx-canvas/releases/tag/v0.1.24
 [0.1.23]: https://github.com/pskoett/pmx-canvas/releases/tag/v0.1.23

package/dist/types/server/index.d.ts

@@ -25,6 +25,10 @@ export declare class PmxCanvas extends EventEmitter {
         type: CanvasNodeState['type'];
         title?: string;
         content?: string;
+        children?: string[];
+        childIds?: string[];
+        childLayout?: 'grid' | 'column' | 'flow';
+        color?: string;
         toolName?: string;
         category?: string;
         status?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmx-canvas",
-  "version": "0.1.25",
+  "version": "0.1.26",
   "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

@@ -75,6 +75,19 @@ reference before using adapter-native features:
 - `references/codex-app-adapter.md` — Codex app native Browser + MCP adapter, AX context reading,
   focus labeling, and live-test checklist.
 
+Host-aware visibility rule:
+- If a native PMX Canvas adapter/panel is available and already represents the workbench (for example
+  the GitHub Copilot app `pmx-canvas` canvas extension, or Codex's in-app Browser opened to
+  `/workbench`), use that panel. Do **not** also open a separate browser panel to the same workbench;
+  it wastes space and confuses which surface is authoritative.
+- If no native adapter/panel is available (generic MCP client, shell-only agent, raw CLI harness,
+  or another agent harness without canvas support), open the normal PMX Canvas browser workbench first
+  so the human can see mutations as they happen. Use the server URL's `/workbench` route.
+- External URLs in `mcp-app` nodes show the "Unverified domain" interstitial by design. Only
+  same-origin `/api/canvas/frame-documents/<id>` URLs are auto-trusted. For external tools, use a
+  bundled `web-artifact`, same-origin frame document, or set `data.trustedDomain: true` only when the
+  user accepts the risk.
+
 The canvas auto-starts on first MCP tool call when running in MCP mode (`pmx-canvas --mcp`).
 For manual start:
 

package/src/mcp/server.ts

@@ -363,6 +363,10 @@ export async function startMcpServer(): Promise<void> {
       width: z.number().optional().describe('Width in pixels (default: 720)'),
       height: z.number().optional().describe('Height in pixels (default: 600)'),
       strictSize: z.boolean().optional().describe('Keep explicit width/height fixed and scroll overflowing content instead of browser auto-fitting'),
+      children: z.array(z.string()).optional().describe('Group-only alias for childIds. Node IDs to include in a generic group node.'),
+      childIds: z.array(z.string()).optional().describe('Group-only field. Node IDs to include in a generic group node. Prefer canvas_create_group for groups.'),
+      childLayout: z.enum(['grid', 'column', 'flow']).optional().describe('Group-only optional layout for grouped children.'),
+      color: z.string().optional().describe('Group-only frame accent color.'),
       toolName: z.string().optional().describe('Trace node tool or operation label'),
       category: z.string().optional().describe('Trace node category: mcp, file, subagent, or other'),
       status: z.string().optional().describe('Trace node status: running, success, or failed'),

package/src/server/index.ts

@@ -167,6 +167,10 @@ export class PmxCanvas extends EventEmitter {
     type: CanvasNodeState['type'];
     title?: string;
     content?: string;
+    children?: string[];
+    childIds?: string[];
+    childLayout?: 'grid' | 'column' | 'flow';
+    color?: string;
     toolName?: string;
     category?: string;
     status?: string;
@@ -182,6 +186,18 @@ export class PmxCanvas extends EventEmitter {
     if (input.type === 'webpage') {
       throw new Error('Use addWebpageNode for webpage nodes so page content is fetched and cached on the server.');
     }
+    if (input.type === 'group') {
+      return this.createGroup({
+        ...(typeof input.title === 'string' ? { title: input.title } : {}),
+        childIds: input.childIds ?? input.children ?? [],
+        ...(typeof input.x === 'number' ? { x: input.x } : {}),
+        ...(typeof input.y === 'number' ? { y: input.y } : {}),
+        ...(typeof input.width === 'number' ? { width: input.width } : {}),
+        ...(typeof input.height === 'number' ? { height: input.height } : {}),
+        ...(typeof input.color === 'string' ? { color: input.color } : {}),
+        ...(input.childLayout ? { childLayout: input.childLayout } : {}),
+      });
+    }
     const { id, needsCodeGraphRecompute } = addCanvasNode({
       ...input,
       defaultWidth: input.type === 'markdown'

package/src/server/server.ts

@@ -4584,6 +4584,15 @@ export function startCanvasServer(options: CanvasServerOptions = {}): string | n
             return handleSnapshotGc(req);
           }
 
+          if (url.pathname === '/api/canvas/snapshots/diff' && req.method === 'GET') {
+            const name = url.searchParams.get('name') ?? url.searchParams.get('id') ?? '';
+            if (!name.trim()) return responseJson({ ok: false, error: 'Missing snapshot name or id.' }, 400);
+            const snapshot = canvasState.getSnapshotData(name);
+            if (!snapshot) return responseJson({ ok: false, error: `Snapshot "${name}" not found.` }, 404);
+            const diff = diffLayouts(snapshot.name, snapshot, canvasState.getLayout());
+            return responseJson({ ok: true, text: formatDiff(diff), diff });
+          }
+
           if (url.pathname.startsWith('/api/canvas/snapshots/') && url.pathname.endsWith('/diff') && req.method === 'GET') {
             const id = decodeURIComponent(url.pathname.slice('/api/canvas/snapshots/'.length, -'/diff'.length));
             const snapshot = canvasState.getSnapshotData(id);