pmx-canvas 0.8.0 → 0.9.0

package/src/server/edit-summary.ts

@@ -0,0 +1,74 @@
+import type { CanvasNodeState } from './canvas-state.js';
+
+const ORDINALS = ['first', 'second', 'third', 'fourth', 'fifth', 'sixth', 'seventh', 'eighth', 'ninth', 'tenth'];
+/** "See change" shows this much of each side, centred on the first difference. */
+export const CHANGE_EXCERPT = 1200;
+
+export function cardText(node: CanvasNodeState): string {
+  const { content, text } = node.data;
+  return typeof content === 'string' ? content : typeof text === 'string' ? text : '';
+}
+
+function cardTitle(node: CanvasNodeState): string {
+  return typeof node.data.title === 'string' ? node.data.title : '';
+}
+
+const paragraphs = (text: string) =>
+  text
+    .split(/\n\s*\n/)
+    .map((paragraph) => paragraph.trim().replace(/\s+/g, ' '))
+    .filter(Boolean);
+
+/**
+ * What an agent's edit did to a card, in a few words, from the card before
+ * the session and now (AgentContext.dc.html: "rewrote the second paragraph").
+ * Paragraphs are aligned on their shared start and end, so a paragraph added
+ * at the top reads as added, not as everything rewritten.
+ */
+export function describeEdit(before: CanvasNodeState, after: CanvasNodeState): string {
+  const parts: string[] = [];
+  if (cardTitle(before) !== cardTitle(after)) parts.push(`renamed it “${cardTitle(after)}”`);
+  const was = cardText(before);
+  const now = cardText(after);
+  if (was !== now) {
+    const a = paragraphs(was);
+    const b = paragraphs(now);
+    let head = 0;
+    while (head < a.length && head < b.length && a[head] === b[head]) head += 1;
+    let tail = 0;
+    while (tail < a.length - head && tail < b.length - head && a[a.length - 1 - tail] === b[b.length - 1 - tail])
+      tail += 1;
+    const removed = a.length - head - tail;
+    const added = b.length - head - tail;
+    const count = (n: number) => `${n} paragraph${n === 1 ? '' : 's'}`;
+    if (removed === 0 && added === 0) parts.push('reformatted its text');
+    else if (a.length === 0) parts.push('wrote its text');
+    else if (b.length === 0) parts.push('cleared its text');
+    else if (removed === 0) parts.push(`added ${count(added)}`);
+    else if (added === 0) parts.push(`removed ${count(removed)}`);
+    else if (removed === 1 && added === 1) parts.push(`rewrote the ${ORDINALS[head] ?? `#${head + 1}`} paragraph`);
+    else if (Math.max(removed, added) > Math.max(a.length, b.length) / 2) parts.push('rewrote most of it');
+    else parts.push(`changed ${count(Math.max(removed, added))} of ${Math.max(a.length, b.length)}`);
+  }
+  return parts.join(' and ') || 'changed its settings';
+}
+
+/**
+ * Before and after for "See change": each side cut to CHANGE_EXCERPT around
+ * the first character that differs, with "…" where text was cut, so a change
+ * deep in a long card is what shows.
+ */
+export function changeExcerpts(was: string, now: string): { before: string; after: string } {
+  let at = 0;
+  while (at < was.length && at < now.length && was[at] === now[at]) at += 1;
+  const from = Math.max(0, at - Math.floor(CHANGE_EXCERPT / 4));
+  // Never cut between the two halves of a surrogate pair (an emoji).
+  const low = (text: string, index: number) => /[\uDC00-\uDFFF]/.test(text[index] ?? '');
+  const cut = (text: string) => {
+    const start = low(text, from) ? from - 1 : from;
+    let end = start + CHANGE_EXCERPT;
+    if (low(text, end)) end -= 1;
+    return `${start > 0 ? '…' : ''}${text.slice(start, end)}${end < text.length ? '…' : ''}`;
+  };
+  return { before: cut(was), after: cut(now) };
+}

package/src/server/html-surface.ts

@@ -60,7 +60,14 @@ function buildThemeBridge(themeToken: string): string {
 const PMX_CANVAS_THEME_TOKEN = ${token};
 window.addEventListener('message', (event) => {
   const message = event.data;
-  if (!message || message.source !== '${HTML_SURFACE_PUSH_SOURCE}' || message.type !== 'theme-update' || message.token !== PMX_CANVAS_THEME_TOKEN) return;
+  if (event.source !== window.parent || !message || message.source !== '${HTML_SURFACE_PUSH_SOURCE}' || message.token !== PMX_CANVAS_THEME_TOKEN) return;
+  if (message.type === 'check-ready') {
+    const reply = (type) => window.parent.postMessage({ source: '${HTML_SURFACE_PUSH_SOURCE}', type, token: PMX_CANVAS_THEME_TOKEN }, '*');
+    reply('mounted');
+    requestAnimationFrame(() => requestAnimationFrame(() => reply('ready')));
+    return;
+  }
+  if (message.type !== 'theme-update') return;
   if (typeof message.theme !== 'string') return;
   document.documentElement.setAttribute('data-pmx-canvas-theme', message.theme);
   document.documentElement.setAttribute('data-theme', message.theme);

package/src/server/index.ts

@@ -1,6 +1,8 @@
 import { EventEmitter } from 'node:events';
-import { derivedTour, type Tour } from '../shared/tour.js';
+import { derivedTour, type Camera, type Tour, type TourStop } from '../shared/tour.js';
+import { exitTour, goToTourStop, moveCamera, type TourStep, type TourStepResult } from './tour-control.js';
 export type { Tour, TourStop } from '../shared/tour.js';
+export type { TourStep, TourStepResult } from './tour-control.js';
 import { agentPresence } from './agent-presence.js';
 import { checkFenceTarget, type FenceTarget } from './scope-fence.js';
 import type { AgentPhase, AgentPresence, AgentPresenceSnapshot } from '../shared/agent-presence.js';
@@ -38,6 +40,7 @@ import type {
   PmxAxWorkItemStatus,
 } from './ax-state.js';
 import type { AxTimelineQuery, CanvasBoard } from './canvas-db.js';
+import type { MemoryGraph } from '../shared/memory-graph.js';
 import type { Attachment, DocumentImport, ImportSection } from './document-import.js';
 import { workbenchToken } from './workbench-auth.js';
 import type { BackupFile, BackupStatus } from './backup.js';
@@ -45,7 +48,8 @@ import type { ExportManifest } from './board-export.js';
 import { onFileNodeChanged } from './file-watcher.js';
 import { findOpenCanvasPosition, computeGroupBounds } from './placement.js';
 import { overlapsAny } from '../shared/placement.js';
-import { searchNodes, buildSpatialContext } from './spatial-analysis.js';
+import { buildSpatialContext } from './spatial-analysis.js';
+import { searchCanvasNodes } from './operations/ops/query.js';
 import { mutationHistory, diffLayouts, formatDiff } from './mutation-history.js';
 import { recomputeCodeGraph, buildCodeGraphSummary, formatCodeGraph } from './code-graph.js';
 import {
@@ -75,14 +79,17 @@ import {
 import {
   buildNodePatch,
   createBasicCanvasNode,
+  createDestinationNode,
   removeNodeCore,
   setGroupChildrenFromApi,
 } from './operations/ops/nodes.js';
 import { streamJsonRenderCore } from './operations/ops/json-render.js';
+import { boardsPayload } from './operations/ops/boards.js';
 import { executeOperation, runCanvasBatchOperation, type OpenMcpAppCoreResult } from './operations/index.js';
 import { validateCanvasLayout } from './canvas-validation.js';
 import { describeCanvasSchema, validateStructuredCanvasPayload } from './canvas-schema.js';
 import { serializeCanvasNode, type SerializedCanvasNode } from './canvas-serialization.js';
+import { contextReadFromPayload } from './context-reads.js';
 import {
   buildHtmlPrimitive,
   getHtmlPrimitiveSemanticMetadata,
@@ -288,10 +295,14 @@ export class PmxCanvas extends EventEmitter {
    * or keep the whole node — both work. (Previously returned a bare id string.)
    */
   addNode(input: {
+    destinationBoardId?: string;
+    requestId?: string;
+    expectedBoardId?: string | null;
     intentId?: string;
     type: CanvasNodeState['type'];
     title?: string;
     content?: string;
+    data?: Record<string, unknown>;
     children?: string[];
     childIds?: string[];
     childLayout?: 'grid' | 'column' | 'flow';
@@ -308,6 +319,19 @@ export class PmxCanvas extends EventEmitter {
     height?: number;
     strictSize?: boolean;
   }): SdkCanvasNode {
+    if (input.expectedBoardId !== undefined && input.expectedBoardId !== canvasState.activeBoardId)
+      throw new Error('The active board changed. Refresh before retrying this action.');
+    if (input.destinationBoardId !== undefined || input.requestId !== undefined) {
+      const revision = canvasState.getContentRevision().revision;
+      const node = createDestinationNode(input);
+      if (
+        (input.destinationBoardId ?? canvasState.activeBoardId) === canvasState.activeBoardId ||
+        revision !== canvasState.getContentRevision().revision
+      )
+        emitPrimaryWorkbenchEvent('canvas-layout-update', { layout: canvasState.getLayout() });
+      emitPrimaryWorkbenchEvent('boards-changed', boardsPayload());
+      return toSdkNode(node);
+    }
     assertInsideFence(
       'node.add',
       createTarget(input, input.type === 'group' ? (input.childIds ?? input.children ?? []) : []),
@@ -441,17 +465,41 @@ export class PmxCanvas extends EventEmitter {
   }
 
   addEdge(input: {
+    destinationBoardId?: string;
+    requestId?: string;
+    expectedBoardId?: string | null;
     intentId?: string;
     from?: string;
     to?: string;
+    toBoardId?: string;
     fromSearch?: string;
     toSearch?: string;
     type: CanvasEdge['type'];
+    kind?: string;
+    reason?: string;
     label?: string;
     style?: CanvasEdge['style'];
     animated?: boolean;
   }): string {
-    assertInsideFence('edge.add', { nodeIds: [input.from ?? '', input.to ?? ''] });
+    if (input.expectedBoardId !== undefined && input.expectedBoardId !== canvasState.activeBoardId)
+      throw new Error('The active board changed. Refresh before retrying this action.');
+    if (input.destinationBoardId !== undefined || input.requestId !== undefined) {
+      const revision = canvasState.getContentRevision().revision;
+      const edge = addCanvasEdge(input);
+      if (
+        (input.destinationBoardId ?? canvasState.activeBoardId) === canvasState.activeBoardId ||
+        revision !== canvasState.getContentRevision().revision
+      )
+        emitPrimaryWorkbenchEvent('canvas-layout-update', { layout: canvasState.getLayout() });
+      emitPrimaryWorkbenchEvent('boards-changed', boardsPayload());
+      return edge.id;
+    }
+    assertInsideFence('edge.add', {
+      nodeIds:
+        input.toBoardId && input.toBoardId !== canvasState.activeBoardId
+          ? [input.from ?? '']
+          : [input.from ?? '', input.to ?? ''],
+    });
     return this.runIntentCommit(
       input.intentId,
       ['connect'],
@@ -464,6 +512,13 @@ export class PmxCanvas extends EventEmitter {
     );
   }
 
+  async updateEdge(
+    id: string,
+    patch: Partial<Pick<CanvasEdge, 'type' | 'kind' | 'reason' | 'label' | 'style' | 'animated'>>,
+  ): Promise<CanvasEdge> {
+    return (await executeOperation('edge.update', { id, ...patch }, { source: 'sdk' })) as CanvasEdge;
+  }
+
   addAnnotation(input: Omit<CanvasAnnotation, 'id' | 'createdAt'> & { id?: string; createdAt?: string }): string {
     const id = input.id ?? `ann-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
     canvasState.addAnnotation({
@@ -483,7 +538,8 @@ export class PmxCanvas extends EventEmitter {
 
   removeEdge(id: string): void {
     const edge = canvasState.getEdges().find((entry) => entry.id === id);
-    if (edge) assertInsideFence('edge.remove', { nodeIds: [edge.from, edge.to] });
+    if (edge)
+      assertInsideFence('edge.remove', { nodeIds: edge.toBoardId !== undefined ? [edge.from] : [edge.from, edge.to] });
     removeCanvasEdge(id);
     emitPrimaryWorkbenchEvent('canvas-layout-update', { layout: canvasState.getLayout() });
   }
@@ -493,6 +549,9 @@ export class PmxCanvas extends EventEmitter {
    * If childIds are provided, the group auto-sizes to contain them with padding.
    */
   createGroup(input: {
+    destinationBoardId?: string;
+    requestId?: string;
+    expectedBoardId?: string | null;
     intentId?: string;
     title?: string;
     childIds?: string[];
@@ -503,6 +562,19 @@ export class PmxCanvas extends EventEmitter {
     color?: string;
     childLayout?: 'grid' | 'column' | 'flow';
   }): string {
+    if (input.expectedBoardId !== undefined && input.expectedBoardId !== canvasState.activeBoardId)
+      throw new Error('The active board changed. Refresh before retrying this action.');
+    if (input.destinationBoardId !== undefined || input.requestId !== undefined) {
+      const revision = canvasState.getContentRevision().revision;
+      const { id } = createCanvasGroup(input);
+      if (
+        (input.destinationBoardId ?? canvasState.activeBoardId) === canvasState.activeBoardId ||
+        revision !== canvasState.getContentRevision().revision
+      )
+        emitPrimaryWorkbenchEvent('canvas-layout-update', { layout: canvasState.getLayout() });
+      emitPrimaryWorkbenchEvent('boards-changed', boardsPayload());
+      return id;
+    }
     assertInsideFence('group.create', { nodeIds: input.childIds ?? [] });
     return this.runIntentCommit(
       input.intentId,
@@ -570,6 +642,26 @@ export class PmxCanvas extends EventEmitter {
     emitPrimaryWorkbenchEvent('canvas-layout-update', { layout: canvasState.getLayout() });
   }
 
+  /** Present a tour stop (index, `next` or `previous`) in the workbench. Not recorded in undo history. */
+  goToTourStop(step: TourStep, options?: { present?: boolean }): TourStepResult {
+    const result = goToTourStop(step);
+    emitPrimaryWorkbenchEvent('canvas-tour-step', { ...result, present: options?.present !== false });
+    return result;
+  }
+
+  /** Leave presentation in every viewer. */
+  exitTour(): void {
+    exitTour();
+    emitPrimaryWorkbenchEvent('canvas-tour-exit', {});
+  }
+
+  /** Ease the camera to a node, world rect or viewport. Not recorded in undo history. */
+  moveCamera(stop: TourStop): { viewport: Camera } {
+    const result = moveCamera(stop);
+    emitPrimaryWorkbenchEvent('canvas-camera-move', result);
+    return { viewport: result.viewport };
+  }
+
   clear(): void {
     assertInsideFence('canvas.clear', { boardWide: true });
     for (const node of canvasState.getLayout().nodes) {
@@ -804,10 +896,10 @@ export class PmxCanvas extends EventEmitter {
     )) as { import: DocumentImport; nodeIds: string[] };
   }
 
-  async createBoard(name: string, category?: string): Promise<CanvasBoard> {
+  async createBoard(name: string, folder?: string): Promise<CanvasBoard> {
     const result = (await executeOperation(
       'board.create',
-      { name, ...(category ? { category } : {}) },
+      { name, ...(folder ? { folder } : {}) },
       { source: 'sdk' },
     )) as {
       board: CanvasBoard;
@@ -815,8 +907,27 @@ export class PmxCanvas extends EventEmitter {
     return result.board;
   }
 
-  /** Rename a board and/or file it under a category (`category: null` removes it). */
-  async updateBoard(id: string, patch: { name?: string; category?: string | null }): Promise<void> {
+  /** Workspace category and folder actions do not open a board. */
+  async knowledge<T extends import('./knowledge-lifecycle.js').KnowledgeInput>(
+    input: T,
+  ): Promise<import('./knowledge-lifecycle.js').KnowledgeResults[T['action']]> {
+    const { action, ...payload } = input;
+    return (await executeOperation(`knowledge.${action}`, payload, {
+      source: 'sdk',
+    })) as import('./knowledge-lifecycle.js').KnowledgeResults[T['action']];
+  }
+
+  async lifecycle<T extends import('./knowledge-lifecycle.js').LifecycleInput>(
+    input: T,
+  ): Promise<import('./knowledge-lifecycle.js').LifecycleResults[T['action']]> {
+    const { action, ...payload } = input;
+    return (await executeOperation(action === 'review' ? 'node.review' : `node.lifecycle-${action}`, payload, {
+      source: 'sdk',
+    })) as import('./knowledge-lifecycle.js').LifecycleResults[T['action']];
+  }
+
+  /** Rename a board and/or file it under a folder (`folder: null` unfiles it). */
+  async updateBoard(id: string, patch: Parameters<typeof canvasState.updateBoard>[1]): Promise<void> {
     await executeOperation('board.update', { id, ...patch }, { source: 'sdk' });
   }
 
@@ -824,10 +935,19 @@ export class PmxCanvas extends EventEmitter {
     await executeOperation('board.update', { id, readmeNodeId }, { source: 'sdk' });
   }
 
+  /** Pin a board into the agent's working set (its README and pinned cards reach every brief). */
+  async pinBoard(id: string, reason?: string): Promise<void> {
+    await executeOperation('board.pin', { id, ...(reason ? { reason } : {}) }, { source: 'sdk' });
+  }
+
+  async unpinBoard(id: string): Promise<void> {
+    await executeOperation('board.unpin', { id }, { source: 'sdk' });
+  }
+
   async createBoardFrom(input: {
     sourceBoardId: string;
     name: string;
-    category?: string;
+    folder?: string;
     nodeIds?: string[];
     includeReadme?: boolean;
     includeStructure?: boolean;
@@ -843,6 +963,13 @@ export class PmxCanvas extends EventEmitter {
     >;
   }
 
+  /** Same projection as Home Graph. Discovery summaries never count as full-content reads. */
+  async getMemoryGraph(
+    options: { focus?: string; depth?: number; projection?: 'full' | 'boards' } = {},
+  ): Promise<MemoryGraph> {
+    return (await executeOperation('memory-graph.get', options, { source: 'sdk' })) as MemoryGraph;
+  }
+
   /** Budgeted cross-board brief. Budget is measured in UTF-16 characters. */
   async getContextBrief(
     options: { consumer?: string; since?: number; budget?: number } = {},
@@ -911,6 +1038,11 @@ export class PmxCanvas extends EventEmitter {
     return canvasState.getNodeReadStatus(board ?? canvasState.activeBoardId);
   }
 
+  /** A board's latest agent read of any kind (a pinned board's map counts), or null. */
+  getBoardLastRead(board?: string): ReturnType<typeof canvasState.getBoardLastRead> {
+    return canvasState.getBoardLastRead(board ?? canvasState.activeBoardId);
+  }
+
   listWorkItems(): PmxAxWorkItem[] {
     return canvasState.getWorkItems();
   }
@@ -1253,14 +1385,36 @@ export class PmxCanvas extends EventEmitter {
   }
 
   getNode(id: string, options?: { board?: string }): SdkCanvasNode | undefined {
+    const boardId = options?.board ?? canvasState.activeBoardId;
+    const board = options?.board ? canvasState.readBoard(options.board) : null;
+    if (options?.board && !board) throw new Error(`Board "${options.board}" not found.`);
     const node = options?.board
-      ? this.getLayout(options).nodes.find((candidate) => candidate.id === id)
+      ? board?.layout.nodes.find((candidate) => candidate.id === id)
       : canvasState.getNode(id);
-    return node ? toSdkNode(node) : undefined;
+    if (!node) return undefined;
+    const result = toSdkNode(node);
+    canvasState.recordContextRead(
+      contextReadFromPayload(
+        {
+          channel: 'operation',
+          resource: 'node.get',
+          source: 'sdk',
+          consumer: null,
+          agentId: null,
+          pinnedNodeIds: options?.board ? (board?.state.contextPins ?? []) : [...canvasState.contextPinnedNodeIds],
+        },
+        result,
+      ),
+      boardId,
+    );
+    return result;
   }
 
-  search(query: string): ReturnType<typeof searchNodes> {
-    return searchNodes(canvasState.getLayout().nodes, query);
+  search(
+    query: string,
+    options: { scope?: 'active' | 'library'; boardId?: string; folder?: string; limit?: number } = {},
+  ) {
+    return searchCanvasNodes(query, options).results;
   }
 
   getSpatialContext() {
@@ -1273,6 +1427,10 @@ export class PmxCanvas extends EventEmitter {
     if (!entry) return { ok: false, description: 'Nothing to undo' };
     await syncCanvasRuntimeBackends();
     emitPrimaryWorkbenchEvent('canvas-layout-update', { layout: canvasState.getLayout() });
+    emitPrimaryWorkbenchEvent('context-pins-changed', {
+      count: canvasState.contextPinnedNodeIds.size,
+      nodeIds: Array.from(canvasState.contextPinnedNodeIds),
+    });
     // Undo can reverse an AX mutation (work item, focus, …); nudge AX surfaces to
     // re-fetch so a live board reflects the reversal (debounced client-side).
     emitPrimaryWorkbenchEvent('ax-state-changed', {});
@@ -1284,6 +1442,10 @@ export class PmxCanvas extends EventEmitter {
     if (!entry) return { ok: false, description: 'Nothing to redo' };
     await syncCanvasRuntimeBackends();
     emitPrimaryWorkbenchEvent('canvas-layout-update', { layout: canvasState.getLayout() });
+    emitPrimaryWorkbenchEvent('context-pins-changed', {
+      count: canvasState.contextPinnedNodeIds.size,
+      nodeIds: Array.from(canvasState.contextPinnedNodeIds),
+    });
     emitPrimaryWorkbenchEvent('ax-state-changed', {});
     return { ok: true, description: `Redid: ${entry.description}` };
   }
@@ -1339,6 +1501,24 @@ export class PmxCanvas extends EventEmitter {
     return result;
   }
 
+  /** Put one card back to its content in a snapshot (the receipt's Undo on an edit). */
+  async restoreSnapshotNode(
+    snapshotId: string,
+    nodeId: string,
+    options: { preserveHumanEdits?: boolean } = {},
+  ): Promise<{ ok: boolean; id: string; restored: boolean; skipped?: 'human-edit' }> {
+    return (await executeOperation(
+      'snapshot.restore-node',
+      { id: snapshotId, nodeId, ...options },
+      { source: 'sdk' },
+    )) as {
+      ok: boolean;
+      id: string;
+      restored: boolean;
+      skipped?: 'human-edit';
+    };
+  }
+
   deleteSnapshot(id: string): { ok: boolean } {
     return deleteCanvasSnapshot(id);
   }
@@ -1759,3 +1939,13 @@ export type {
   PmxAxWorkItemStatus,
 } from './ax-state.js';
 export type { AxTimelineQuery } from './canvas-db.js';
+export type {
+  Lifecycle,
+  KnowledgeCategory,
+  FolderProperties,
+  ReviewRecord,
+  KnowledgeInput,
+  KnowledgeResults,
+  LifecycleInput,
+  LifecycleResults,
+} from './knowledge-lifecycle.js';