pmx-canvas 0.1.22 → 0.1.24

package/src/client/types.ts

@@ -108,6 +108,7 @@ export function isExcalidrawNode(node: CanvasNodeState): boolean {
 
 export interface CanvasLayout {
   viewport: ViewportState;
+  theme?: 'dark' | 'light' | 'high-contrast';
   nodes: CanvasNodeState[];
   edges: CanvasEdge[];
   annotations?: CanvasAnnotation[];

package/src/mcp/canvas-access.ts

@@ -9,6 +9,7 @@ import {
   type CanvasSnapshot,
   type PmxCanvas,
 } from '../server/index.js';
+import type { PmxAxSource } from '../server/ax-state.js';
 
 type AddNodeInput = Parameters<PmxCanvas['addNode']>[0];
 type AddWebpageNodeInput = Parameters<PmxCanvas['addWebpageNode']>[0];
@@ -31,6 +32,9 @@ type ArrangeLayout = Parameters<PmxCanvas['arrange']>[0];
 type FocusNodeResult = ReturnType<PmxCanvas['focusNode']>;
 type FitViewOptions = Parameters<PmxCanvas['fitView']>[0];
 type FitViewResult = ReturnType<PmxCanvas['fitView']>;
+type AxStateResult = ReturnType<PmxCanvas['getAxState']>;
+type AxContextResult = ReturnType<PmxCanvas['getAxContext']>;
+type SetAxFocusResult = ReturnType<PmxCanvas['setAxFocus']>;
 type SearchResult = ReturnType<PmxCanvas['search']>;
 type UndoRedoResult = Awaited<ReturnType<PmxCanvas['undo']>>;
 type HistoryResult = ReturnType<PmxCanvas['getHistory']>;
@@ -118,6 +122,9 @@ export interface CanvasAccess {
   arrange(layout?: ArrangeLayout): Promise<void>;
   focusNode(id: string, options?: { noPan?: boolean }): Promise<FocusNodeResult>;
   fitView(options?: FitViewOptions): Promise<FitViewResult>;
+  getAxState(): Promise<AxStateResult>;
+  getAxContext(): Promise<AxContextResult>;
+  setAxFocus(nodeIds: string[], options?: { source?: PmxAxSource }): Promise<SetAxFocusResult>;
   clear(): Promise<void>;
   search(query: string): Promise<SearchResult>;
   undo(): Promise<UndoRedoResult>;
@@ -247,6 +254,18 @@ class LocalCanvasAccess implements CanvasAccess {
     return this.canvas.fitView(options);
   }
 
+  async getAxState(): Promise<AxStateResult> {
+    return this.canvas.getAxState();
+  }
+
+  async getAxContext(): Promise<AxContextResult> {
+    return this.canvas.getAxContext();
+  }
+
+  async setAxFocus(nodeIds: string[], options?: { source?: PmxAxSource }): Promise<SetAxFocusResult> {
+    return this.canvas.setAxFocus(nodeIds, { source: options?.source ?? 'mcp' });
+  }
+
   async clear(): Promise<void> {
     this.canvas.clear();
   }
@@ -587,6 +606,25 @@ class RemoteCanvasAccess implements CanvasAccess {
     return await this.requestJson<HistoryResult>('GET', '/api/canvas/history');
   }
 
+  async getAxState(): Promise<AxStateResult> {
+    const response = await this.requestJson<{ state?: AxStateResult }>('GET', '/api/canvas/ax');
+    if (!response.state) throw new Error('Remote canvas did not return AX state.');
+    return response.state;
+  }
+
+  async getAxContext(): Promise<AxContextResult> {
+    return await this.requestJson<AxContextResult>('GET', '/api/canvas/ax/context');
+  }
+
+  async setAxFocus(nodeIds: string[], options?: { source?: PmxAxSource }): Promise<SetAxFocusResult> {
+    const response = await this.requestJson<{ focus?: SetAxFocusResult }>('POST', '/api/canvas/ax/focus', {
+      nodeIds,
+      source: options?.source ?? 'mcp',
+    });
+    if (!response.focus) throw new Error('Remote canvas did not return AX focus.');
+    return response.focus;
+  }
+
   async setContextPins(nodeIds: string[], mode: 'set' | 'add' | 'remove' = 'set'): Promise<SetContextPinsResult> {
     const existing = mode === 'set' ? [] : await this.getPinnedNodeIds();
     const requested = new Set(nodeIds);

package/src/mcp/server.ts

@@ -100,13 +100,17 @@ function sleep(ms: number): Promise<void> {
   return new Promise((resolveSleep) => setTimeout(resolveSleep, ms));
 }
 
-function sendCanvasResourceNotifications(type: 'nodes' | 'pins' = 'nodes'): void {
+function sendCanvasResourceNotifications(type: 'nodes' | 'pins' | 'ax' = 'nodes'): void {
   const server = resourceNotificationServer;
   if (!server) return;
   try {
     if (type === 'pins') {
       server.server.sendResourceUpdated({ uri: 'canvas://pinned-context' });
     }
+    if (type === 'pins' || type === 'ax') {
+      server.server.sendResourceUpdated({ uri: 'canvas://ax' });
+      server.server.sendResourceUpdated({ uri: 'canvas://ax-context' });
+    }
     server.server.sendResourceUpdated({ uri: 'canvas://layout' });
     server.server.sendResourceUpdated({ uri: 'canvas://summary' });
     server.server.sendResourceUpdated({ uri: 'canvas://spatial-context' });
@@ -121,7 +125,9 @@ function handleRemoteSseFrame(frame: string): void {
   const eventLine = frame.split('\n').find((line) => line.startsWith('event: '));
   const event = eventLine?.slice('event: '.length).trim() ?? '';
   if (!event || event === 'connected' || event === 'ping') return;
-  sendCanvasResourceNotifications(event === 'context-pins-changed' ? 'pins' : 'nodes');
+  sendCanvasResourceNotifications(
+    event === 'context-pins-changed' ? 'pins' : event === 'ax-state-changed' ? 'ax' : 'nodes',
+  );
 }
 
 async function watchRemoteCanvasEvents(baseUrl: string): Promise<void> {
@@ -904,7 +910,7 @@ export async function startMcpServer(): Promise<void> {
   // ── canvas_update_node ─────────────────────────────────────────
   server.tool(
     'canvas_update_node',
-    'Update an existing node. You can change its content, title, position, size, or data.',
+    'Update an existing node. You can change its content, title, position, size, dock placement, or data.',
     {
       id: z.string().describe('Node ID to update'),
       title: z.string().optional().describe('New title'),
@@ -926,12 +932,14 @@ export async function startMcpServer(): Promise<void> {
       resultSummary: z.string().optional().describe('Trace node result summary'),
       error: z.string().optional().describe('Trace node error message'),
       collapsed: z.boolean().optional().describe('Collapse or expand the node'),
+      dockPosition: z.enum(['left', 'right']).nullable().optional().describe('Dock the node to the left/right HUD column, or pass null to return it to the canvas'),
+      pinned: z.boolean().optional().describe('Pin or unpin the node to exclude it from auto-arrange'),
       arrangeLocked: z.boolean().optional().describe('Prevent auto-arrange from moving this node. Pinned nodes are also skipped.'),
       full: z.boolean().optional().describe('Return the full updated node payload. Default false returns compact metadata.'),
       verbose: z.boolean().optional().describe('Alias for full:true.'),
     },
     async (input) => {
-      const { id, title, content, x, y, width, height, spec, graphType, data, xKey, yKey, chartHeight, collapsed, arrangeLocked, toolName, category, status, duration, resultSummary, error } = input;
+      const { id, title, content, x, y, width, height, spec, graphType, data, xKey, yKey, chartHeight, collapsed, dockPosition, pinned, arrangeLocked, toolName, category, status, duration, resultSummary, error } = input;
       const c = await ensureCanvas();
       const node = await c.getNode(id);
       if (!node) {
@@ -950,6 +958,12 @@ export async function startMcpServer(): Promise<void> {
       if (collapsed !== undefined) {
         patch.collapsed = collapsed;
       }
+      if (dockPosition !== undefined) {
+        patch.dockPosition = dockPosition;
+      }
+      if (pinned !== undefined) {
+        patch.pinned = pinned;
+      }
       if (title !== undefined) patch.title = title;
       if (content !== undefined) patch.content = content;
       if (spec !== undefined) patch.spec = spec;
@@ -1120,6 +1134,55 @@ export async function startMcpServer(): Promise<void> {
     },
   );
 
+  // ── AX context and focus ───────────────────────────────────────
+  server.tool(
+    'canvas_get_ax',
+    'Read the host-agnostic PMX AX state and agent-ready AX context. Use this when you need pinned context plus the current focus field.',
+    {
+      includeContext: z.boolean().optional().describe('Include serialized agent-ready AX context. Default true.'),
+    },
+    async ({ includeContext }) => {
+      const c = await ensureCanvas();
+      const state = await c.getAxState();
+      const context = includeContext === false ? undefined : await c.getAxContext();
+      return {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify({
+              ok: true,
+              state,
+              ...(context ? { context } : {}),
+            }),
+          },
+        ],
+      };
+    },
+  );
+
+  server.tool(
+    'canvas_set_ax_focus',
+    'Set the PMX AX focus field without requiring viewport movement. Focus is persisted and available through canvas://ax-context.',
+    {
+      nodeIds: z.array(z.string()).describe('Node IDs to place in the AX focus field. Missing nodes are ignored.'),
+      source: z.enum(['agent', 'api', 'browser', 'cli', 'codex', 'copilot', 'mcp', 'sdk', 'system'])
+        .optional()
+        .describe('Optional host/source label for adapter-originated focus. Defaults to mcp. Use codex from the Codex app adapter.'),
+    },
+    async ({ nodeIds, source }) => {
+      const c = await ensureCanvas();
+      const focus = await c.setAxFocus(nodeIds, { source: source ?? 'mcp' });
+      return {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify({ ok: true, focus }),
+          },
+        ],
+      };
+    },
+  );
+
   server.tool(
     'canvas_fit_view',
     'Fit the canvas viewport to all nodes or a selected subset. Useful before screenshots and whole-board review.',
@@ -1497,6 +1560,52 @@ export async function startMcpServer(): Promise<void> {
     },
   );
 
+  server.resource(
+    'ax-state',
+    'canvas://ax',
+    {
+      description:
+        'Host-agnostic PMX AX state. This includes canvas-bound collaboration primitives such as the current AX focus.',
+      mimeType: 'application/json',
+    },
+    async () => {
+      const c = await ensureCanvas();
+      const state = await c.getAxState();
+      return {
+        contents: [
+          {
+            uri: 'canvas://ax',
+            mimeType: 'application/json',
+            text: JSON.stringify({ state }, null, 2),
+          },
+        ],
+      };
+    },
+  );
+
+  server.resource(
+    'ax-context',
+    'canvas://ax-context',
+    {
+      description:
+        'Agent-ready PMX AX context combining pinned context, focus, and surface metadata.',
+      mimeType: 'application/json',
+    },
+    async () => {
+      const c = await ensureCanvas();
+      const context = await c.getAxContext();
+      return {
+        contents: [
+          {
+            uri: 'canvas://ax-context',
+            mimeType: 'application/json',
+            text: JSON.stringify(context, null, 2),
+          },
+        ],
+      };
+    },
+  );
+
   server.resource(
     'canvas-layout',
     'canvas://layout',

package/src/server/ax-context.ts

@@ -0,0 +1,38 @@
+import { buildAgentContextPreamble, serializeNodeForAgentContext } from './agent-context.js';
+import { buildAxContext, type PmxAxContext, type PmxAxPinnedContext } from './ax-state.js';
+import { canvasState, type CanvasNodeState } from './canvas-state.js';
+
+function serializeNodes(nodes: CanvasNodeState[]) {
+  return nodes.map((node) => serializeNodeForAgentContext(node, {
+    defaultTextLength: 700,
+    webpageTextLength: 1600,
+    includePosition: true,
+  }));
+}
+
+export function buildCanvasAxPinnedContext(): PmxAxPinnedContext {
+  const nodeIds = Array.from(canvasState.contextPinnedNodeIds);
+  const nodes = nodeIds
+    .map((id) => canvasState.getNode(id))
+    .filter((node): node is CanvasNodeState => node !== undefined);
+  return {
+    preamble: nodes.length > 0 ? buildAgentContextPreamble(nodes) : '',
+    nodeIds,
+    count: nodeIds.length,
+    nodes: serializeNodes(nodes),
+  };
+}
+
+export function buildCanvasAxContext(): PmxAxContext {
+  const layout = canvasState.getLayout();
+  const focus = canvasState.getAxFocus();
+  const focusNodes = focus.nodeIds
+    .map((id) => canvasState.getNode(id))
+    .filter((node): node is CanvasNodeState => node !== undefined);
+  return buildAxContext({
+    layout,
+    pinned: buildCanvasAxPinnedContext(),
+    focus,
+    focusNodes: serializeNodes(focusNodes),
+  });
+}

package/src/server/ax-state.ts

@@ -0,0 +1,130 @@
+import type { CanvasLayout, CanvasNodeState } from './canvas-state.js';
+import type { AgentContextNode } from './agent-context.js';
+
+export type PmxAxSource = 'agent' | 'api' | 'browser' | 'cli' | 'codex' | 'copilot' | 'mcp' | 'sdk' | 'system';
+
+export interface PmxAxFocusState {
+  nodeIds: string[];
+  primaryNodeId: string | null;
+  updatedAt: string | null;
+  source: PmxAxSource | null;
+}
+
+export interface PmxAxState {
+  version: 1;
+  focus: PmxAxFocusState;
+}
+
+export interface PmxAxPinnedContext {
+  preamble: string;
+  nodeIds: string[];
+  count: number;
+  nodes: AgentContextNode[];
+}
+
+export interface PmxAxFocusContext extends PmxAxFocusState {
+  nodes: AgentContextNode[];
+}
+
+export interface PmxAxContext {
+  version: 1;
+  generatedAt: string;
+  surface: {
+    nodeCount: number;
+    edgeCount: number;
+  };
+  pinned: PmxAxPinnedContext;
+  focus: PmxAxFocusContext;
+}
+
+const AX_SOURCES = new Set<PmxAxSource>(['agent', 'api', 'browser', 'cli', 'codex', 'copilot', 'mcp', 'sdk', 'system']);
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function normalizeSource(value: unknown): PmxAxSource | null {
+  return typeof value === 'string' && AX_SOURCES.has(value as PmxAxSource)
+    ? value as PmxAxSource
+    : null;
+}
+
+function normalizeTimestamp(value: unknown): string | null {
+  if (typeof value !== 'string') return null;
+  const parsed = Date.parse(value);
+  return Number.isFinite(parsed) ? new Date(parsed).toISOString() : null;
+}
+
+function normalizeNodeIds(value: unknown, validNodeIds?: Set<string>): string[] {
+  if (!Array.isArray(value)) return [];
+  const ids: string[] = [];
+  for (const item of value) {
+    if (typeof item !== 'string') continue;
+    if (validNodeIds && !validNodeIds.has(item)) continue;
+    if (!ids.includes(item)) ids.push(item);
+  }
+  return ids;
+}
+
+export function createEmptyAxFocusState(): PmxAxFocusState {
+  return {
+    nodeIds: [],
+    primaryNodeId: null,
+    updatedAt: null,
+    source: null,
+  };
+}
+
+export function createEmptyAxState(): PmxAxState {
+  return {
+    version: 1,
+    focus: createEmptyAxFocusState(),
+  };
+}
+
+export function normalizeAxFocusState(input: unknown, validNodeIds?: Set<string>): PmxAxFocusState {
+  if (!isRecord(input)) return createEmptyAxFocusState();
+  const nodeIds = normalizeNodeIds(input.nodeIds, validNodeIds);
+  const primaryNodeId = typeof input.primaryNodeId === 'string' && nodeIds.includes(input.primaryNodeId)
+    ? input.primaryNodeId
+    : nodeIds[0] ?? null;
+  return {
+    nodeIds,
+    primaryNodeId,
+    updatedAt: normalizeTimestamp(input.updatedAt),
+    source: normalizeSource(input.source),
+  };
+}
+
+export function normalizeAxState(input: unknown, validNodeIds?: Set<string>): PmxAxState {
+  if (!isRecord(input)) return createEmptyAxState();
+  return {
+    version: 1,
+    focus: normalizeAxFocusState(input.focus, validNodeIds),
+  };
+}
+
+export function buildAxContext(input: {
+  layout: CanvasLayout;
+  pinned: PmxAxPinnedContext;
+  focus: PmxAxFocusState;
+  focusNodes: AgentContextNode[];
+}): PmxAxContext {
+  return {
+    version: 1,
+    generatedAt: new Date().toISOString(),
+    surface: {
+      nodeCount: input.layout.nodes.length,
+      edgeCount: input.layout.edges.length,
+    },
+    pinned: input.pinned,
+    focus: {
+      ...input.focus,
+      nodes: input.focusNodes,
+    },
+  };
+}
+
+export function nodeSetFromLayout(nodes: CanvasNodeState[]): Set<string> {
+  return new Set(nodes.map((node) => node.id));
+}