pmx-canvas 0.1.24 → 0.1.25

package/dist/types/client/nodes/McpAppNode.d.ts

@@ -1,4 +1,5 @@
 import type { CanvasNodeState } from '../types';
+export declare function isSameOriginFrameDocumentUrl(url: string, origin?: string): boolean;
 export declare function McpAppNode({ node, expanded }: {
     node: CanvasNodeState;
     expanded?: boolean;

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

@@ -60,6 +60,10 @@ export declare const MARKDOWN_NODE_DEFAULT_SIZE: {
     width: number;
     height: number;
 };
+export declare const MCP_APP_NODE_DEFAULT_SIZE: {
+    width: number;
+    height: number;
+};
 interface CanvasCreateGroupInput {
     title?: string;
     childIds?: string[];

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

@@ -163,6 +163,7 @@ declare class CanvasStateManager {
     private applyResolvedGroupBounds;
     private getGroupSnapshot;
     private normalizeNode;
+    private nodeForRead;
     private reflowAllGroups;
     private translateGroupChildren;
     private recomputeParentGroupBounds;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmx-canvas",
-  "version": "0.1.24",
+  "version": "0.1.25",
   "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/references/codex-app-adapter.md

@@ -62,8 +62,10 @@ in the Codex in-app Browser, usually `http://127.0.0.1:4313/workbench` or
 
 ## Codex-Native Workflow
 
-1. Start or connect to the PMX MCP server.
-2. Open `/workbench` in the Codex in-app Browser.
+1. Open `/workbench` in the Codex in-app Browser as the first visible action. If PMX is not running
+   yet, start/connect the MCP server first only long enough to get the workbench URL, then open the
+   browser before mutating the board.
+2. Start or keep using the PMX MCP server for agent operations.
 3. Use the browser canvas for human spatial curation: pin nodes, move nodes, group nodes, and
    inspect rendered artifacts.
 4. Use MCP tools for agent operations: create/update nodes, pin nodes, read layout, and read AX
@@ -90,9 +92,10 @@ Codex agents should treat PMX AX context as host-native working context:
 
 ## Live-Test Checklist
 
-1. Confirm the PMX MCP server is configured for the workspace.
-2. Call `canvas_get_ax` and confirm it returns `ok: true`.
-3. Open `http://127.0.0.1:4313/workbench` in the Codex in-app Browser.
+1. Open `http://127.0.0.1:4313/workbench` in the Codex in-app Browser first so the user can see
+   all later canvas mutations.
+2. Confirm the PMX MCP server is configured for the workspace.
+3. Call `canvas_get_ax` and confirm it returns `ok: true`.
 4. Add or reuse a node, then pin it from the browser or with `canvas_pin_nodes`.
 5. Read `canvas://ax-context` and confirm the pinned node appears.
 6. Call `canvas_set_ax_focus` with `source: "codex"` and a real node ID.

package/skills/pmx-canvas/references/github-copilot-app-adapter.md

@@ -11,6 +11,20 @@ maps Copilot SDK features onto PMX AX primitives.
 - Canvas ID: `pmx-canvas`
 - Display name: `PMX Canvas`
 
+## Quick Start
+
+1. Install the project adapter by copying the packaged extension into the repository:
+   `mkdir -p .github/extensions/pmx-canvas && cp node_modules/pmx-canvas/.github/extensions/pmx-canvas/extension.mjs .github/extensions/pmx-canvas/extension.mjs`
+2. Reload Copilot app extensions with `extensions_reload` so `project:pmx-canvas` is registered.
+3. Start or confirm a PMX Canvas daemon for the workspace: `pmx-canvas serve --daemon`
+   and `pmx-canvas serve status`. The adapter can auto-start in many local sessions, but a running
+   daemon is the most reliable setup for fresh agents.
+4. Open the canvas with `extensionId: "project:pmx-canvas"`, `canvasId: "pmx-canvas"`, and a stable
+   `instanceId`.
+5. If the first `invoke_canvas_action` immediately after `open_canvas` returns
+   `Canvas instance not open`, retry the same action once. This is a known Copilot app timing race
+   during panel initialization, not a PMX server failure.
+
 Open it with:
 
 ```json

package/src/client/nodes/McpAppNode.tsx

@@ -14,6 +14,18 @@ function withViewerParams(url: string, expanded: boolean): string {
   }
 }
 
+export function isSameOriginFrameDocumentUrl(url: string, origin = window.location.origin): boolean {
+  if (!url) return false;
+  try {
+    const baseOrigin = new URL(origin).origin;
+    const resolved = new URL(url, baseOrigin);
+    return resolved.origin === baseOrigin &&
+      resolved.pathname.startsWith('/api/canvas/frame-documents/');
+  } catch {
+    return false;
+  }
+}
+
 export function McpAppNode({ node, expanded = false }: { node: CanvasNodeState; expanded?: boolean }) {
   if (node.data.mode === 'ext-app') {
     return <ExtAppFrame node={node} expanded={expanded} />;
@@ -23,7 +35,7 @@ export function McpAppNode({ node, expanded = false }: { node: CanvasNodeState;
   const sourceServer = (node.data.sourceServer as string) || '';
   const hostMode = (node.data.hostMode as string) || 'hosted';
   const fallbackReason = node.data.fallbackReason as string | undefined;
-  const trustedDomain = node.data.trustedDomain as boolean | undefined;
+  const trustedDomain = node.data.trustedDomain === true || isSameOriginFrameDocumentUrl(url);
 
   if (hostMode === 'fallback') {
     return (

package/src/client/state/sse-bridge.ts

@@ -75,7 +75,7 @@ const DEFAULT_POSITIONS: Record<
   status: { x: 40, y: 80, w: 300, h: 120 },
   markdown: { x: 380, y: 80, w: 720, h: 600 },
   context: { x: 1130, y: 80, w: 320, h: 400 },
-  'mcp-app': { x: 380, y: 720, w: 720, h: 500 },
+  'mcp-app': { x: 380, y: 720, w: 960, h: 600 },
   webpage: { x: 380, y: 80, w: 520, h: 420 },
   'json-render': { x: 380, y: 720, w: 840, h: 620 },
   graph: { x: 380, y: 720, w: 760, h: 520 },

package/src/server/canvas-operations.ts

@@ -103,7 +103,8 @@ interface CanvasAddNodeInput {
   strictSize?: boolean;
 }
 
-export const MARKDOWN_NODE_DEFAULT_SIZE = { width: 520, height: 360 };
+export const MARKDOWN_NODE_DEFAULT_SIZE = { width: 640, height: 420 };
+export const MCP_APP_NODE_DEFAULT_SIZE = { width: 960, height: 600 };
 
 interface CanvasCreateGroupInput {
   title?: string;
@@ -1176,7 +1177,7 @@ function shiftGridUpdatesBelowObstacles(
 }
 
 export function arrangeCanvasNodes(layout: CanvasArrangeMode): { arranged: number; layout: CanvasArrangeMode } {
-  const nodes = canvasState.getLayout().nodes;
+  const nodes = canvasState.getLayoutForPersistence().nodes;
   const excludedIds = layout === 'grid'
     ? collectGridArrangeExcludedNodeIds(nodes)
     : collectArrangeExcludedNodeIds(nodes);
@@ -1657,8 +1658,20 @@ export async function executeCanvasBatch(
               ...(typeof args.width === 'number' ? { width: args.width } : {}),
               ...(typeof args.height === 'number' ? { height: args.height } : {}),
               ...(args.strictSize === true ? { strictSize: true } : {}),
-              defaultWidth: type === 'html' ? 720 : type === 'markdown' ? MARKDOWN_NODE_DEFAULT_SIZE.width : 360,
-              defaultHeight: type === 'html' ? 640 : type === 'markdown' ? MARKDOWN_NODE_DEFAULT_SIZE.height : 200,
+              defaultWidth: type === 'html'
+                ? 720
+                : type === 'markdown'
+                  ? MARKDOWN_NODE_DEFAULT_SIZE.width
+                  : type === 'mcp-app'
+                    ? MCP_APP_NODE_DEFAULT_SIZE.width
+                    : 360,
+              defaultHeight: type === 'html'
+                ? 640
+                : type === 'markdown'
+                  ? MARKDOWN_NODE_DEFAULT_SIZE.height
+                  : type === 'mcp-app'
+                    ? MCP_APP_NODE_DEFAULT_SIZE.height
+                    : 200,
               fileMode: 'auto',
             });
             result = { ok: true, ...serializeCreatedNode(created.node) };

package/src/server/canvas-state.ts

@@ -400,6 +400,14 @@ class CanvasStateManager {
     return normalized;
   }
 
+  private nodeForRead(node: CanvasNodeState): CanvasNodeState {
+    const resolved = this.resolveNodeDataBlobs(node);
+    return {
+      ...resolved,
+      pinned: resolved.pinned || this._contextPinnedNodeIds.has(resolved.id),
+    };
+  }
+
   private reflowAllGroups(): void {
     const groups = Array.from(this.nodes.values())
       .filter((node): node is CanvasNodeState => node.type === 'group')
@@ -1379,7 +1387,7 @@ class CanvasStateManager {
 
   getNode(id: string): CanvasNodeState | undefined {
     const node = this.nodes.get(id);
-    return node ? structuredClone(this.resolveNodeDataBlobs(node)) : undefined;
+    return node ? structuredClone(this.nodeForRead(node)) : undefined;
   }
 
   getNodeForPersistence(id: string): CanvasNodeState | undefined {
@@ -1482,7 +1490,7 @@ class CanvasStateManager {
     return {
       viewport: structuredClone(this._viewport),
       theme: this._theme,
-      nodes: Array.from(this.nodes.values(), (node) => structuredClone(node)),
+      nodes: Array.from(this.nodes.values(), (node) => structuredClone(this.nodeForRead(node))),
       edges: Array.from(this.edges.values(), (edge) => structuredClone(edge)),
       annotations: this.getAnnotations(),
     };

package/src/server/index.ts

@@ -13,6 +13,7 @@ import {
   addCanvasNode,
   addCanvasEdge,
   MARKDOWN_NODE_DEFAULT_SIZE,
+  MCP_APP_NODE_DEFAULT_SIZE,
   applyCanvasNodeUpdates,
   arrangeCanvasNodes,
   clearCanvas,
@@ -183,8 +184,16 @@ export class PmxCanvas extends EventEmitter {
     }
     const { id, needsCodeGraphRecompute } = addCanvasNode({
       ...input,
-      defaultWidth: input.type === 'markdown' ? MARKDOWN_NODE_DEFAULT_SIZE.width : 360,
-      defaultHeight: input.type === 'markdown' ? MARKDOWN_NODE_DEFAULT_SIZE.height : 200,
+      defaultWidth: input.type === 'markdown'
+        ? MARKDOWN_NODE_DEFAULT_SIZE.width
+        : input.type === 'mcp-app'
+          ? MCP_APP_NODE_DEFAULT_SIZE.width
+          : 360,
+      defaultHeight: input.type === 'markdown'
+        ? MARKDOWN_NODE_DEFAULT_SIZE.height
+        : input.type === 'mcp-app'
+          ? MCP_APP_NODE_DEFAULT_SIZE.height
+          : 200,
       fileMode: 'path',
       ...(input.strictSize ? { strictSize: true } : {}),
     });

package/src/server/mutation-history.ts

@@ -66,6 +66,13 @@ export interface SnapshotDiffResult {
   removedEdges: { id: string; from: string; to: string; type: string }[];
 }
 
+function comparableNodeData(data: Record<string, unknown>): Record<string, unknown> {
+  const comparable = { ...data };
+  delete comparable.title;
+  delete comparable.content;
+  return comparable;
+}
+
 // ── Ring Buffer ──────────────────────────────────────────────────────
 
 const MAX_ENTRIES = 200;
@@ -258,6 +265,10 @@ export function diffLayouts(
       changes.push(`content changed (${lenDiff >= 0 ? '+' : ''}${lenDiff} chars)`);
     }
 
+    if (JSON.stringify(comparableNodeData(snapNode.data)) !== JSON.stringify(comparableNodeData(curNode.data))) {
+      changes.push('data changed');
+    }
+
     if (changes.length > 0) {
       modifiedNodes.push({
         id,

package/src/server/server.ts

@@ -47,7 +47,7 @@ import type {
   ListResourceTemplatesResult,
   ListToolsResult,
 } from '@modelcontextprotocol/sdk/types.js';
-import { type CanvasAnnotation, type CanvasEdge, type CanvasNodeState, IMAGE_MIME_MAP, canvasState } from './canvas-state.js';
+import { type CanvasAnnotation, type CanvasEdge, type CanvasLayout, type CanvasNodeState, IMAGE_MIME_MAP, canvasState } from './canvas-state.js';
 import { findCanvasExtAppNodeId as findCanvasExtAppNodeIdShared } from './ext-app-lookup.js';
 import { normalizeExtAppToolResult } from './ext-app-tool-result.js';
 import { getMcpAppHostSnapshot } from './mcp-app-host.js';
@@ -84,6 +84,7 @@ import {
   addCanvasNode,
   addCanvasEdge,
   MARKDOWN_NODE_DEFAULT_SIZE,
+  MCP_APP_NODE_DEFAULT_SIZE,
   applyCanvasNodeUpdates,
   buildStructuredNodeUpdate,
   arrangeCanvasNodes,
@@ -790,6 +791,64 @@ function parseGraphPayloadData(value: unknown): Array<Record<string, unknown>> |
   return value as Array<Record<string, unknown>>;
 }
 
+type StringListField = { value?: string[]; error?: string };
+
+function parseStringListField(field: string, value: unknown): StringListField {
+  if (value === undefined) return {};
+  if (!Array.isArray(value)) return { error: `"${field}" must be an array of node IDs.` };
+  const invalid = value.find((item) => typeof item !== 'string' || item.trim().length === 0);
+  if (invalid !== undefined) return { error: `"${field}" must contain only non-empty node IDs.` };
+  return { value };
+}
+
+function pickGroupChildIds(body: Record<string, unknown>): StringListField {
+  if ('children' in body) return parseStringListField('children', body.children);
+  if ('childIds' in body) return parseStringListField('childIds', body.childIds);
+  const data = isRecord(body.data) ? body.data : undefined;
+  return data && 'children' in data ? parseStringListField('data.children', data.children) : {};
+}
+
+function validateGroupChildIds(groupId: string, childIds: string[]): string | null {
+  const missingChildIds = childIds.filter((id) => !canvasState.getNode(id));
+  if (missingChildIds.length > 0) {
+    return `Missing child node ID${missingChildIds.length === 1 ? '' : 's'}: ${missingChildIds.join(', ')}.`;
+  }
+  const invalidChildIds = childIds.filter((id) => {
+    const node = canvasState.getNode(id);
+    return id === groupId || node?.type === 'group';
+  });
+  if (invalidChildIds.length > 0) {
+    return `Invalid group child ID${invalidChildIds.length === 1 ? '' : 's'}: ${invalidChildIds.join(', ')}.`;
+  }
+  return null;
+}
+
+function setGroupChildrenFromApi(groupId: string, childIds: string[]): boolean {
+  const group = canvasState.getNode(groupId);
+  if (!group || group.type !== 'group') return false;
+
+  const dataChildIds = Array.isArray(group.data.children)
+    ? group.data.children.filter((id): id is string => typeof id === 'string')
+    : [];
+  const parentBackrefIds = canvasState.getLayout().nodes
+    .filter((node) => node.id !== groupId && node.data.parentGroup === groupId)
+    .map((node) => node.id);
+  const currentChildIds = [...new Set([...dataChildIds, ...parentBackrefIds])];
+  if (currentChildIds.length > 0) {
+    if (currentChildIds.length !== dataChildIds.length || currentChildIds.some((id) => !dataChildIds.includes(id))) {
+      canvasState.updateNode(groupId, { data: { ...group.data, children: currentChildIds } });
+    }
+    canvasState.ungroupNodes(groupId);
+  }
+  if (childIds.length === 0) return true;
+
+  const latestGroup = canvasState.getNode(groupId);
+  return canvasState.groupNodes(groupId, childIds, {
+    preservePositions: true,
+    keepGroupFrame: latestGroup?.data.frameMode === 'manual',
+  });
+}
+
 function getExtAppNodeCheckpointId(node: CanvasNodeState): string {
   const appCheckpoint = isRecord(node.data.appCheckpoint) ? node.data.appCheckpoint : null;
   const storedCheckpointId = appCheckpoint?.id;
@@ -1467,6 +1526,20 @@ function buildNodeResponse(node: CanvasNodeState): Record<string, unknown> {
   };
 }
 
+function withContextPinReadState(node: CanvasNodeState): CanvasNodeState {
+  return {
+    ...node,
+    pinned: node.pinned || canvasState.contextPinnedNodeIds.has(node.id),
+  };
+}
+
+function withContextPinLayoutReadState(layout: CanvasLayout): CanvasLayout {
+  return {
+    ...layout,
+    nodes: layout.nodes.map(withContextPinReadState),
+  };
+}
+
 async function createCanvasWebpageNode(body: Record<string, unknown>): Promise<Response> {
   const rawUrl = typeof body.url === 'string' && body.url.trim().length > 0
     ? body.url
@@ -1547,6 +1620,23 @@ async function handleCanvasAddNode(req: Request): Promise<Response> {
     return createCanvasHtmlPrimitiveNode(body);
   }
 
+  if (type === 'group') {
+    const geometry = resolveCreateGeometry(body);
+    const childList = pickGroupChildIds(body);
+    if (childList.error) return responseJson({ ok: false, error: `Cannot create group: ${childList.error}` }, 400);
+    const childIds = childList.value ?? [];
+    const childError = validateGroupChildIds('', childIds);
+    if (childError) return responseJson({ ok: false, error: `Cannot create group: ${childError}` }, 400);
+    const { node } = createCanvasGroup({
+      ...(typeof body.title === 'string' ? { title: body.title } : {}),
+      childIds,
+      ...(typeof body.color === 'string' ? { color: body.color } : {}),
+      ...geometry,
+    });
+    emitPrimaryWorkbenchEvent('canvas-layout-update', { layout: canvasState.getLayout() });
+    return responseJson(buildNodeResponse(node));
+  }
+
   const extraData = body.data && typeof body.data === 'object' && !Array.isArray(body.data)
     ? body.data as Record<string, unknown>
     : undefined;
@@ -1592,8 +1682,20 @@ async function handleCanvasAddNode(req: Request): Promise<Response> {
       ...(type === 'trace' && typeof body.error === 'string' ? { error: body.error } : {}),
       ...(body.strictSize === true ? { strictSize: true } : {}),
       ...geometry,
-      defaultWidth: type === 'html' ? 720 : type === 'markdown' ? MARKDOWN_NODE_DEFAULT_SIZE.width : 360,
-      defaultHeight: type === 'html' ? 640 : type === 'markdown' ? MARKDOWN_NODE_DEFAULT_SIZE.height : 200,
+      defaultWidth: type === 'html'
+        ? 720
+        : type === 'markdown'
+          ? MARKDOWN_NODE_DEFAULT_SIZE.width
+          : type === 'mcp-app'
+            ? MCP_APP_NODE_DEFAULT_SIZE.width
+            : 360,
+      defaultHeight: type === 'html'
+        ? 640
+        : type === 'markdown'
+          ? MARKDOWN_NODE_DEFAULT_SIZE.height
+          : type === 'mcp-app'
+            ? MCP_APP_NODE_DEFAULT_SIZE.height
+            : 200,
       fileMode: 'auto',
     });
   } catch (error) {
@@ -1797,6 +1899,13 @@ async function handleCanvasUpdateNode(nodeId: string, req: Request): Promise<Res
   if (existing.type === 'webpage' && body.refresh === true) {
     return handleCanvasRefreshWebpageNode(nodeId, req);
   }
+  const groupChildList = existing.type === 'group' ? pickGroupChildIds(body) : {};
+  if (groupChildList.error) return responseJson({ ok: false, error: `Cannot update group: ${groupChildList.error}` }, 400);
+  const groupChildIds = groupChildList.value;
+  if (groupChildIds !== undefined) {
+    const childError = validateGroupChildIds(nodeId, groupChildIds);
+    if (childError) return responseJson({ ok: false, error: `Cannot update group: ${childError}` }, 400);
+  }
   const patch: Record<string, unknown> = resolvePatchGeometry(body, existing);
   if (body.collapsed !== undefined) patch.collapsed = body.collapsed;
   if (body.pinned !== undefined) patch.pinned = Boolean(body.pinned);
@@ -1855,6 +1964,9 @@ async function handleCanvasUpdateNode(nodeId: string, req: Request): Promise<Res
   });
   if (error) return responseJson({ ok: false, error }, 400);
   canvasState.updateNode(nodeId, patch as Partial<CanvasNodeState>);
+  if (groupChildIds !== undefined && !setGroupChildrenFromApi(nodeId, groupChildIds)) {
+    return responseJson({ ok: false, error: `Group "${nodeId}" not found.` }, 404);
+  }
   emitPrimaryWorkbenchEvent('canvas-layout-update', { layout: canvasState.getLayout() });
   const updated = canvasState.getNode(nodeId);
   return responseJson(updated ? buildNodeResponse(updated) : { ok: true, id: nodeId });
@@ -4346,7 +4458,7 @@ export function startCanvasServer(options: CanvasServerOptions = {}): string | n
             const includeBlobs = url.searchParams.get('includeBlobs') === 'true';
             return responseJson(includeBlobs
               ? serializeCanvasLayout(canvasState.getLayout())
-              : serializeCanvasLayoutWithBlobSummaries(canvasState.getLayoutForPersistence()));
+              : serializeCanvasLayoutWithBlobSummaries(withContextPinLayoutReadState(canvasState.getLayoutForPersistence())));
           }
 
           if (url.pathname === '/api/canvas/summary' && req.method === 'GET') {
@@ -4416,9 +4528,10 @@ export function startCanvasServer(options: CanvasServerOptions = {}): string | n
             const includeBlobs = url.searchParams.get('includeBlobs') === 'true';
             const node = includeBlobs ? canvasState.getNode(nodeId) : canvasState.getNodeForPersistence(nodeId);
             if (!node) return responseJson({ ok: false, error: `Node "${nodeId}" not found.` }, 404);
+            const responseNode = withContextPinReadState(node);
             return responseJson(includeBlobs
-              ? serializeCanvasNode(node)
-              : serializeCanvasNodeWithBlobSummaries(node));
+              ? serializeCanvasNode(responseNode)
+              : serializeCanvasNodeWithBlobSummaries(responseNode));
           }
 
           if (url.pathname.startsWith('/api/canvas/node/') && req.method === 'PATCH') {