pmx-canvas 0.8.2 → 0.9.1

package/src/client/types.ts

@@ -33,6 +33,8 @@ export interface CanvasNodeState {
   collapsed: boolean;
   pinned: boolean;
   contentRevision?: number;
+  /** Revision of this node's latest link change, kept apart from its text. */
+  linksRevision?: number;
   /** Who created / last edited the node's content (server attribution). */
   createdBy?: NodeActor;
   lastEditedBy?: NodeActor;
@@ -49,10 +51,20 @@ export interface CanvasEdge {
   id: string;
   from: string;
   to: string;
+  toBoardId?: string;
   type: 'relation' | 'depends-on' | 'flow' | 'references';
+  kind?: string;
+  reason?: string;
   label?: string;
   style?: 'solid' | 'dashed' | 'dotted';
   animated?: boolean;
+  /** Board revision of this link's latest add, retype or relabel. */
+  revision?: number;
+  changedBy?: NodeActor;
+  changedAt?: string;
+  /** Who first drew the link, and when (LinkAuthorship.dc.html). */
+  createdBy?: NodeActor;
+  createdAt?: string;
 }
 
 export interface CanvasAnnotationPoint {

package/src/client/utils/keyboard.ts

@@ -0,0 +1,10 @@
+/** Overlays and text editors get Escape before the underlying view selection. */
+export function isSelectionEscape(event: KeyboardEvent): boolean {
+  const target = event.target instanceof HTMLElement ? event.target : null;
+  return (
+    event.key === 'Escape' &&
+    !event.defaultPrevented &&
+    !target?.closest('input, textarea, [contenteditable="true"]') &&
+    !document.querySelector('[role="dialog"], [role="menu"], .context-menu, .shortcut-overlay-backdrop')
+  );
+}

package/src/client/utils/time-ago.ts

@@ -0,0 +1,14 @@
+/** How long ago, compact: "just now", "5m", "3h", "2d". */
+export function age(iso: string): string {
+  const mins = Math.max(0, Math.floor((Date.now() - new Date(iso).getTime()) / 60000));
+  if (mins < 1) return 'just now';
+  if (mins < 60) return `${mins}m`;
+  const hours = Math.floor(mins / 60);
+  return hours < 24 ? `${hours}h` : `${Math.floor(hours / 24)}d`;
+}
+
+/** "just now", "5m ago", "3h ago", "2d ago". */
+export function timeAgo(iso: string): string {
+  const value = age(iso);
+  return value === 'just now' ? value : `${value} ago`;
+}

package/src/json-render/renderer/index.tsx

@@ -14,6 +14,7 @@ import {
   JSON_VIEWER_STATE_SOURCE,
 } from '../../shared/ax-surface-protocol.js';
 import { createRoot } from 'react-dom/client';
+import { useLayoutEffect } from 'react';
 import { defineRegistry, JSONUIProvider, Renderer } from '@json-render/react';
 import { shadcnComponents } from '@json-render/shadcn';
 import { catalog } from '../catalog';
@@ -173,6 +174,36 @@ function applyTheme(theme: unknown): void {
 }
 
 function App({ store }: { store: StateStore }) {
+  useLayoutEffect(() => {
+    const token = window.__PMX_CANVAS_UI_STATE_TOKEN__;
+    if (!token) return;
+    // Mount is runtime health, not paint. Offscreen frames may not run rAF;
+    // acknowledge the commit now so the parent never times out a healthy viewer.
+    window.parent.postMessage(
+      {
+        source: JSON_VIEWER_STATE_SOURCE,
+        type: 'mounted',
+        token,
+        nodeId: window.__PMX_CANVAS_JSON_RENDER_NODE_ID__,
+      },
+      '*',
+    );
+    // Let this document's rendering cycle advance after React's commit;
+    // parent animation frames alone do not advance a child frame's paint.
+    requestAnimationFrame(() =>
+      requestAnimationFrame(() => {
+        window.parent.postMessage(
+          {
+            source: JSON_VIEWER_STATE_SOURCE,
+            type: 'ready',
+            token,
+            nodeId: window.__PMX_CANVAS_JSON_RENDER_NODE_ID__,
+          },
+          '*',
+        );
+      }),
+    );
+  }, []);
   const spec = window.__PMX_CANVAS_JSON_RENDER_SPEC__;
 
   if (!spec) {

package/src/mcp/canvas-app.ts

@@ -187,8 +187,18 @@ export function registerCanvasApp(server: McpServer, ensureCanvas: () => Promise
           position: node.position,
           size: node.size,
           edges: layout.edges
-            .filter((edge) => edge.from === node.id || edge.to === node.id)
-            .map(({ id, from, to, type, label }) => ({ id, from, to, type, label: label ?? '' })),
+            .filter(
+              (edge) =>
+                edge.from === node.id || ((!edge.toBoardId || edge.toBoardId === input.boardId) && edge.to === node.id),
+            )
+            .map(({ id, from, to, toBoardId, type, label }) => ({
+              id,
+              from,
+              to,
+              ...(toBoardId !== undefined ? { toBoardId } : {}),
+              type,
+              label: label ?? '',
+            })),
         };
         return { content: [{ type: 'text', text: JSON.stringify(result) }], structuredContent: result };
       }),

package/src/mcp/context-uri-template.ts

@@ -2,8 +2,11 @@ import { UriTemplate } from '@modelcontextprotocol/sdk/shared/uriTemplate.js';
 
 /** SDK v1 matches {?a,b} as two required, ordered parameters, unlike its expansion. */
 export class ContextUriTemplate extends UriTemplate {
-  constructor() {
-    super('canvas://context{?budget,consumer,since}');
+  constructor(
+    private readonly host = 'context',
+    private readonly parameters = ['budget', 'consumer', 'since'],
+  ) {
+    super(`canvas://${host}{?${parameters.join(',')}}`);
   }
 
   override match(uri: string): Record<string, string> | null {
@@ -11,7 +14,7 @@ export class ContextUriTemplate extends UriTemplate {
     const url = new URL(uri);
     if (
       url.protocol !== 'canvas:' ||
-      url.host !== 'context' ||
+      url.host !== this.host ||
       url.pathname ||
       url.hash ||
       url.username ||
@@ -20,7 +23,7 @@ export class ContextUriTemplate extends UriTemplate {
       return null;
     const variables: Record<string, string> = {};
     for (const [key, value] of url.searchParams) {
-      if (!['budget', 'consumer', 'since'].includes(key) || key in variables) return null;
+      if (!this.parameters.includes(key) || key in variables) return null;
       variables[key] = value;
     }
     return variables;

package/src/mcp/server.ts

@@ -32,10 +32,10 @@ import { AX_INTERACTION_TYPES } from '../server/ax-interaction.js';
 import { buildPendingAxActivity } from '../server/ax-state.js';
 import { registerOperationTools, registerCompositeTools } from '../server/operations/index.js';
 import { agentSourceLabel } from '../server/operations/invoker.js';
-import { contextReadFromPayload } from '../server/context-reads.js';
+import { contextReadFromPayload, pinnedBoardReads, graphReads } from '../server/context-reads.js';
+import type { MemoryGraph } from '../shared/memory-graph.js';
 import { createCanvasAccess, refreshCanvasAccess, type CanvasAccess } from './canvas-access.js';
-import { serializeNodeForAgentContext } from '../shared/agent-context.js';
-import { buildSpatialContext, findNeighborhoods } from '../server/spatial-analysis.js';
+import { buildSpatialContext } from '../server/spatial-analysis.js';
 import {
   getCanvasNodeTitle,
   serializeCanvasLayoutForAgent,
@@ -89,7 +89,7 @@ function sendCanvasResourceNotifications(type: 'nodes' | 'pins' | 'ax' | 'ax-tim
   const server = resourceNotificationServer;
   if (!server) return;
   try {
-    if (type === 'pins') {
+    if (type === 'pins' || type === 'nodes') {
       server.server.sendResourceUpdated({ uri: 'canvas://pinned-context' });
     }
     if (type === 'pins' || type === 'ax') {
@@ -108,6 +108,7 @@ function sendCanvasResourceNotifications(type: 'nodes' | 'pins' | 'ax' | 'ax-tim
     server.server.sendResourceUpdated({ uri: 'canvas://boards' });
     server.server.sendResourceUpdated({ uri: 'canvas://summary' });
     server.server.sendResourceUpdated({ uri: 'canvas://context' });
+    server.server.sendResourceUpdated({ uri: 'canvas://graph' });
     server.server.sendResourceUpdated({ uri: 'canvas://spatial-context' });
     server.server.sendResourceUpdated({ uri: 'canvas://history' });
     server.server.sendResourceUpdated({ uri: 'canvas://code-graph' });
@@ -121,7 +122,8 @@ function handleRemoteSseFrame(frame: string): void {
   const event = eventLine?.slice('event: '.length).trim() ?? '';
   if (!event || event === 'connected' || event === 'ping') return;
   sendCanvasResourceNotifications(
-    event === 'context-pins-changed'
+    // boards-changed covers board pins and switches, both of which change pinned context.
+    event === 'context-pins-changed' || event === 'boards-changed'
       ? 'pins'
       : event === 'ax-state-changed'
         ? 'ax'
@@ -508,45 +510,18 @@ export async function startMcpServer(): Promise<void> {
       description:
         'Content of all pinned nodes on the canvas. When the human pins nodes, ' +
         'they are telling the agent "this is what matters right now." Read this ' +
-        'resource to get structured context from the canvas.',
+        'resource to get structured context from the canvas. pinnedBoards lists the ' +
+        'boards in the working set (README summary and pinned card titles); their ' +
+        'content arrives through canvas://context.',
       mimeType: 'application/json',
     },
     async () => {
       const c = await ensureCanvas();
       const readTarget = await c.prepareContextRead();
       const board = readTarget.boardId ?? undefined;
-      const pinnedIds = new Set(readTarget.pinnedNodeIds);
-      const layout = await c.getLayout(board);
-
-      const pinnedNodes = layout.nodes.filter((n) => pinnedIds.has(n.id));
-      const pinnedEdges = layout.edges.filter((e) => pinnedIds.has(e.from) && pinnedIds.has(e.to));
-
-      // Compute neighborhoods: for each pinned node, find nearby unpinned nodes
-      const neighborhoods = findNeighborhoods(layout.nodes, pinnedIds);
-
-      const context = {
-        pinnedCount: pinnedNodes.length,
-        nodes: pinnedNodes.map((n) =>
-          serializeNodeForAgentContext(n, {
-            defaultTextLength: 700,
-            webpageTextLength: 1600,
-            includePosition: true,
-          }),
-        ),
-        edges: pinnedEdges.map((e) => ({
-          id: e.id,
-          from: e.from,
-          to: e.to,
-          type: e.type,
-          label: e.label ?? null,
-        })),
-        neighborhoods: neighborhoods.map((nh) => ({
-          pinnedNodeId: nh.pinnedNodeId,
-          pinnedNodeTitle: nh.pinnedNodeTitle,
-          nearbyNodes: nh.neighbors,
-        })),
-      };
-
+      // Content and lifecycle are captured by one synchronous server operation,
+      // never joined across separate HTTP reads with different retirement state.
+      const context = await c.invoker().invoke('pinned-context.get', { board });
       const text = JSON.stringify(context, null, 2);
       await recordContextRead(c, 'mcp-resource', 'canvas://pinned-context', text, readTarget);
       return {
@@ -575,19 +550,66 @@ export async function startMcpServer(): Promise<void> {
       if (uri.searchParams.has('consumer')) input.consumer = uri.searchParams.get('consumer');
       if (uri.searchParams.has('budget')) input.budget = uri.searchParams.get('budget');
       if (uri.searchParams.has('since')) input.since = uri.searchParams.get('since');
-      const document = await c.invoker().invoke('context.get', input);
+      // MCP invokers skip registry recording (proxied reads), so record here like
+      // the other context resources: the open board, then each pinned board
+      // delivered in full.
+      const readTarget = await c.prepareContextRead();
+      const document = await c.invoker().invoke('context.get', { ...input, expectedBoardId: readTarget.boardId });
+      const text = JSON.stringify(document);
+      await recordContextRead(c, 'mcp-resource', 'canvas://context', text, readTarget);
+      try {
+        const base = {
+          channel: 'mcp-resource' as const,
+          resource: 'canvas://context',
+          source: agentSourceLabel('mcp'),
+          consumer: server.server.getClientVersion()?.name ?? null,
+          agentId: null,
+        };
+        for (const read of pinnedBoardReads(base, text)) await c.recordContextRead(read);
+      } catch (error) {
+        console.error('[pmx-canvas mcp] recording a pinned-board read failed:', error);
+      }
       return {
         contents: [
           {
             uri: uri.href,
             mimeType: 'application/json',
-            text: JSON.stringify(document),
+            text,
           },
         ],
       };
     },
   );
 
+  server.resource(
+    'memory-graph',
+    new ResourceTemplate(new ContextUriTemplate('graph', ['focus', 'depth']), { list: undefined }),
+    {
+      description:
+        'The same connected-memory projection Home draws. Focus on a board ID, qualified card key, or pins; depth 0–4. Summaries are seen, not full reads.',
+      mimeType: 'application/json',
+    },
+    async (uri) => {
+      const c = await ensureCanvas();
+      const input: Record<string, unknown> = {};
+      if (uri.searchParams.has('focus')) input.focus = uri.searchParams.get('focus');
+      if (uri.searchParams.has('depth')) input.depth = uri.searchParams.get('depth');
+      const graph = (await c.invoker().invoke('memory-graph.get', input)) as MemoryGraph;
+      for (const read of graphReads(
+        {
+          channel: 'mcp-resource',
+          resource: 'canvas://graph',
+          source: agentSourceLabel('mcp'),
+          consumer: server.server.getClientVersion()?.name ?? null,
+          agentId: null,
+        },
+        graph,
+      ))
+        await c.recordContextRead(read);
+      return { contents: [{ uri: uri.href, mimeType: 'application/json', text: JSON.stringify(graph) }] };
+    },
+  );
+
   server.resource(
     'ax-state',
     'canvas://ax',
@@ -797,7 +819,7 @@ export async function startMcpServer(): Promise<void> {
     'canvas://boards',
     {
       description:
-        'The boards in this workspace with their categories, most recently opened first, and which one is ' +
+        'The boards in this workspace with their folders, most recently opened first, and which one is ' +
         'open (activeBoardId; null = Home). Writes go to the open board; use canvas_board action "open" to switch the shared workbench.',
       mimeType: 'application/json',
     },

package/src/mcp/workbench-app.ts

@@ -10,6 +10,8 @@ const writes = new Set([
   'board.create',
   'board.open',
   'board.update',
+  'board.pin',
+  'board.unpin',
   'board.create-from',
   'board.delete',
   'node.add',
@@ -18,6 +20,14 @@ const writes = new Set([
   'node.update',
   'node.remove',
   'node.refresh',
+  'node.lifecycle-set',
+  'node.review',
+  'node.lifecycle-restore',
+  'knowledge.category-set',
+  'knowledge.category-remove',
+  'knowledge.folder-set',
+  'knowledge.relation-preset-set',
+  'knowledge.relation-preset-remove',
   'edge.add',
   'edge.update',
   'edge.remove',
@@ -28,6 +38,7 @@ const writes = new Set([
   'annotation.add',
   'annotation.remove',
   'theme.set',
+  'settings.set',
   'viewport.set',
   'canvas.apply-updates',
   'canvas.clear',
@@ -38,6 +49,8 @@ const writes = new Set([
   'snapshot.restore',
   'snapshot.delete',
   'tour.set',
+  'tour.go',
+  'tour.exit',
   'ax.focus.set',
   'ax.policy.set',
   'ax.work.create',
@@ -157,6 +170,23 @@ export function registerWorkbenchApp(server: McpServer, ensureCanvas: () => Prom
             const node = await canvas.getNode(String(args.id));
             if (node?.data.path) throw new OperationError('Edit file-linked content in the local PMX workbench.', 403);
           }
+          if (op.name === 'settings.set') {
+            // Only this app-only UI preference request carries the workbench
+            // marker. Canvas edits still use the agent invoker below; never
+            // fetch or forward the daemon's human-author capability.
+            const response = await fetch(new URL('/api/canvas/settings', base), {
+              method: 'POST',
+              headers: {
+                'Content-Type': 'application/json',
+                'X-PMX-Workbench': '1',
+                'X-PMX-Source': 'mcp',
+              },
+              body: JSON.stringify(args),
+              redirect: 'error',
+              signal: AbortSignal.timeout(15_000),
+            });
+            return reply(response.status, await response.text());
+          }
           const result = await canvas.invoker().invoke(op.name, args);
           return reply(route.status ? route.status(result) : 200, JSON.stringify(result));
         }
@@ -191,12 +221,15 @@ export function registerWorkbenchApp(server: McpServer, ensureCanvas: () => Prom
           throw new OperationError('This asset is too large for the MCP connection.');
         const contentType = response.headers.get('content-type') ?? 'application/octet-stream';
         const text = /^(text\/|application\/(json|javascript))/.test(contentType);
-        return reply(
-          response.status,
-          text ? new TextDecoder().decode(bytes) : Buffer.from(bytes).toString('base64'),
-          contentType,
-          text ? 'text' : 'base64',
-        );
+        let body = text ? new TextDecoder().decode(bytes) : Buffer.from(bytes).toString('base64');
+        if (target.pathname === '/api/workbench/poll') {
+          // Hosted frames act as agents; the direct workbench's human capability
+          // must not escape in private tool hydration metadata either.
+          const poll = JSON.parse(body) as { events: Array<{ payload: Record<string, unknown> }> };
+          for (const event of poll.events) delete event.payload.workbenchToken;
+          body = JSON.stringify(poll);
+        }
+        return reply(response.status, body, contentType, text ? 'text' : 'base64');
       } catch (error) {
         if (error instanceof OperationError)
           return reply(error.status, JSON.stringify({ ok: false, error: error.message }));