pmx-canvas 0.1.26 → 0.1.28

package/src/server/index.ts

@@ -2,7 +2,27 @@ import { EventEmitter } from 'node:events';
 import { canvasState, IMAGE_MIME_MAP } from './canvas-state.js';
 import type { CanvasAnnotation, CanvasNodeState, CanvasEdge, CanvasLayout, ViewportState } from './canvas-state.js';
 import { buildCanvasAxContext } from './ax-context.js';
-import type { PmxAxContext, PmxAxFocusState, PmxAxSource, PmxAxState } from './ax-state.js';
+import type {
+  PmxAxApprovalGate,
+  PmxAxContext,
+  PmxAxEvent,
+  PmxAxEvidence,
+  PmxAxEvidenceKind,
+  PmxAxFocusState,
+  PmxAxHostCapability,
+  PmxAxReviewAnchorType,
+  PmxAxReviewAnnotation,
+  PmxAxReviewKind,
+  PmxAxReviewRegion,
+  PmxAxReviewSeverity,
+  PmxAxReviewStatus,
+  PmxAxSource,
+  PmxAxState,
+  PmxAxSteeringMessage,
+  PmxAxWorkItem,
+  PmxAxWorkItemStatus,
+} from './ax-state.js';
+import type { AxTimelineQuery } from './canvas-db.js';
 import { findCanvasExtAppNodeId } from './ext-app-lookup.js';
 import { onFileNodeChanged } from './file-watcher.js';
 import { findOpenCanvasPosition, computeGroupBounds } from './placement.js';
@@ -12,8 +32,12 @@ import { recomputeCodeGraph, buildCodeGraphSummary, formatCodeGraph } from './co
 import {
   addCanvasNode,
   addCanvasEdge,
+  appendCanvasJsonRenderStream,
+  createCanvasStreamingJsonRenderNode,
   MARKDOWN_NODE_DEFAULT_SIZE,
   MCP_APP_NODE_DEFAULT_SIZE,
+  IMAGE_NODE_DEFAULT_SIZE,
+  LEDGER_NODE_DEFAULT_SIZE,
   applyCanvasNodeUpdates,
   arrangeCanvasNodes,
   clearCanvas,
@@ -30,6 +54,7 @@ import {
   refreshCanvasWebpageNode,
   removeCanvasNode,
   removeCanvasEdge,
+  resolveHtmlContent,
   restoreCanvasSnapshot,
   saveCanvasSnapshot,
   scheduleCodeGraphRecompute,
@@ -163,6 +188,11 @@ export class PmxCanvas extends EventEmitter {
     this._server = null;
   }
 
+  /**
+   * Add a node to the canvas and return the created node (including its `id`,
+   * resolved geometry, and data). Destructure `const { id } = canvas.addNode(...)`
+   * or keep the whole node — both work. (Previously returned a bare id string.)
+   */
   addNode(input: {
     type: CanvasNodeState['type'];
     title?: string;
@@ -182,12 +212,12 @@ export class PmxCanvas extends EventEmitter {
     width?: number;
     height?: number;
     strictSize?: boolean;
-  }): string {
+  }): CanvasNodeState {
     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({
+      const groupId = this.createGroup({
         ...(typeof input.title === 'string' ? { title: input.title } : {}),
         childIds: input.childIds ?? input.children ?? [],
         ...(typeof input.x === 'number' ? { x: input.x } : {}),
@@ -197,6 +227,9 @@ export class PmxCanvas extends EventEmitter {
         ...(typeof input.color === 'string' ? { color: input.color } : {}),
         ...(input.childLayout ? { childLayout: input.childLayout } : {}),
       });
+      const groupNode = canvasState.getNode(groupId);
+      if (!groupNode) throw new Error(`Group node "${groupId}" was not created.`);
+      return groupNode;
     }
     const { id, needsCodeGraphRecompute } = addCanvasNode({
       ...input,
@@ -204,12 +237,20 @@ export class PmxCanvas extends EventEmitter {
         ? MARKDOWN_NODE_DEFAULT_SIZE.width
         : input.type === 'mcp-app'
           ? MCP_APP_NODE_DEFAULT_SIZE.width
-          : 360,
+          : input.type === 'image'
+            ? IMAGE_NODE_DEFAULT_SIZE.width
+            : input.type === 'ledger'
+              ? LEDGER_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,
+          : input.type === 'image'
+            ? IMAGE_NODE_DEFAULT_SIZE.height
+            : input.type === 'ledger'
+              ? LEDGER_NODE_DEFAULT_SIZE.height
+              : 200,
       fileMode: 'path',
       ...(input.strictSize ? { strictSize: true } : {}),
     });
@@ -222,7 +263,9 @@ export class PmxCanvas extends EventEmitter {
       });
     }
 
-    return id;
+    const node = canvasState.getNode(id);
+    if (!node) throw new Error(`Node "${id}" was not created.`);
+    return node;
   }
 
   async addWebpageNode(input: {
@@ -453,6 +496,132 @@ export class PmxCanvas extends EventEmitter {
     return focus;
   }
 
+  recordAxEvent(
+    input: { kind: PmxAxEvent['kind']; summary: string; detail?: string | null; nodeIds?: string[]; data?: Record<string, unknown> | null },
+    options?: { source?: PmxAxSource },
+  ): PmxAxEvent {
+    const event = canvasState.recordAxEvent(input, { source: options?.source ?? 'sdk' });
+    emitPrimaryWorkbenchEvent('ax-event-created', { event });
+    return event;
+  }
+
+  sendSteering(message: string, options?: { source?: PmxAxSource }): PmxAxSteeringMessage {
+    const steering = canvasState.recordSteeringMessage(message, { source: options?.source ?? 'sdk' });
+    emitPrimaryWorkbenchEvent('ax-event-created', { steering });
+    return steering;
+  }
+
+  markSteeringDelivered(id: string): boolean {
+    const ok = canvasState.markSteeringDelivered(id);
+    if (ok) emitPrimaryWorkbenchEvent('ax-event-created', { steeringDelivered: id });
+    return ok;
+  }
+
+  getAxTimeline(query?: AxTimelineQuery): ReturnType<typeof canvasState.getAxTimeline> {
+    return canvasState.getAxTimeline(query);
+  }
+
+  listWorkItems(): PmxAxWorkItem[] {
+    return canvasState.getWorkItems();
+  }
+
+  addWorkItem(
+    input: { title: string; status?: PmxAxWorkItemStatus; detail?: string | null; nodeIds?: string[] },
+    options?: { source?: PmxAxSource },
+  ): PmxAxWorkItem {
+    const workItem = canvasState.addWorkItem(input, { source: options?.source ?? 'sdk' });
+    emitPrimaryWorkbenchEvent('ax-state-changed', { workItem });
+    return workItem;
+  }
+
+  updateWorkItem(
+    id: string,
+    patch: { title?: string; status?: PmxAxWorkItemStatus; detail?: string | null; nodeIds?: string[] },
+    options?: { source?: PmxAxSource },
+  ): PmxAxWorkItem | null {
+    const workItem = canvasState.updateWorkItem(id, patch, { source: options?.source ?? 'sdk' });
+    if (workItem) emitPrimaryWorkbenchEvent('ax-state-changed', { workItem });
+    return workItem;
+  }
+
+  listApprovalGates(): PmxAxApprovalGate[] {
+    return canvasState.getApprovalGates();
+  }
+
+  requestApproval(
+    input: { title: string; detail?: string | null; action?: string | null; nodeIds?: string[] },
+    options?: { source?: PmxAxSource },
+  ): PmxAxApprovalGate {
+    const approvalGate = canvasState.requestApproval(input, { source: options?.source ?? 'sdk' });
+    emitPrimaryWorkbenchEvent('ax-state-changed', { approvalGate });
+    return approvalGate;
+  }
+
+  resolveApproval(
+    id: string,
+    decision: 'approved' | 'rejected',
+    options?: { resolution?: string; source?: PmxAxSource },
+  ): PmxAxApprovalGate | null {
+    const approvalGate = canvasState.resolveApproval(id, decision, {
+      ...(options?.resolution !== undefined ? { resolution: options.resolution } : {}),
+      source: options?.source ?? 'sdk',
+    });
+    if (approvalGate) emitPrimaryWorkbenchEvent('ax-state-changed', { approvalGate });
+    return approvalGate;
+  }
+
+  addEvidence(
+    input: { kind: PmxAxEvidenceKind; title: string; body?: string | null; ref?: string | null; nodeIds?: string[]; data?: Record<string, unknown> | null },
+    options?: { source?: PmxAxSource },
+  ): PmxAxEvidence {
+    const evidence = canvasState.addEvidence(input, { source: options?.source ?? 'sdk' });
+    emitPrimaryWorkbenchEvent('ax-event-created', { evidence });
+    return evidence;
+  }
+
+  listReviewAnnotations(): PmxAxReviewAnnotation[] {
+    return canvasState.getReviewAnnotations();
+  }
+
+  addReviewAnnotation(
+    input: {
+      body: string;
+      kind?: PmxAxReviewKind;
+      severity?: PmxAxReviewSeverity;
+      anchorType?: PmxAxReviewAnchorType;
+      nodeId?: string | null;
+      file?: string | null;
+      region?: PmxAxReviewRegion | null;
+      author?: string | null;
+    },
+    options?: { source?: PmxAxSource },
+  ): PmxAxReviewAnnotation | null {
+    const reviewAnnotation = canvasState.addReviewAnnotation(input, { source: options?.source ?? 'sdk' });
+    if (!reviewAnnotation) return null;
+    emitPrimaryWorkbenchEvent('ax-state-changed', { reviewAnnotation });
+    return reviewAnnotation;
+  }
+
+  updateReviewAnnotation(
+    id: string,
+    patch: { body?: string; status?: PmxAxReviewStatus; severity?: PmxAxReviewSeverity; kind?: PmxAxReviewKind },
+    options?: { source?: PmxAxSource },
+  ): PmxAxReviewAnnotation | null {
+    const reviewAnnotation = canvasState.updateReviewAnnotation(id, patch, { source: options?.source ?? 'sdk' });
+    if (reviewAnnotation) emitPrimaryWorkbenchEvent('ax-state-changed', { reviewAnnotation });
+    return reviewAnnotation;
+  }
+
+  getHostCapability(): PmxAxHostCapability | null {
+    return canvasState.getHostCapability();
+  }
+
+  reportHostCapability(input: unknown, options?: { source?: PmxAxSource }): PmxAxHostCapability {
+    const host = canvasState.setHostCapability(input, { source: options?.source ?? 'sdk' });
+    emitPrimaryWorkbenchEvent('ax-state-changed', { host });
+    return host;
+  }
+
   fitView(options?: {
     width?: number;
     height?: number;
@@ -687,6 +856,65 @@ export class PmxCanvas extends EventEmitter {
     return result;
   }
 
+  /**
+   * Progressively build a json-render node from SpecStream patches. Omit nodeId
+   * to create a new streaming node; pass the same nodeId on later calls to
+   * append more patches. The server accumulates the spec and the browser
+   * reloads the viewer as the specVersion bumps.
+   */
+  streamJsonRenderNode(input: {
+    nodeId?: string;
+    title?: string;
+    patches?: unknown[];
+    done?: boolean;
+    x?: number;
+    y?: number;
+    width?: number;
+    height?: number;
+    strictSize?: boolean;
+  }): {
+    id: string;
+    url: string;
+    applied: number;
+    skipped: number;
+    specVersion: number;
+    elementCount: number;
+    streamStatus: 'open' | 'closed';
+  } {
+    let nodeId = input.nodeId;
+    let url = '';
+    if (!nodeId) {
+      const created = createCanvasStreamingJsonRenderNode({
+        ...(input.title !== undefined ? { title: input.title } : {}),
+        ...(input.x !== undefined ? { x: input.x } : {}),
+        ...(input.y !== undefined ? { y: input.y } : {}),
+        ...(input.width !== undefined ? { width: input.width } : {}),
+        ...(input.height !== undefined ? { height: input.height } : {}),
+        ...(input.strictSize ? { strictSize: true } : {}),
+      });
+      nodeId = created.id;
+      url = created.url;
+    } else {
+      url = String(canvasState.getNode(nodeId)?.data.url ?? '');
+    }
+    const result = appendCanvasJsonRenderStream(
+      nodeId,
+      Array.isArray(input.patches) ? input.patches : [],
+      input.done === true,
+    );
+    if (!result.ok) throw new Error(result.error);
+    emitPrimaryWorkbenchEvent('canvas-layout-update', { layout: canvasState.getLayout() });
+    return {
+      id: nodeId,
+      url,
+      applied: result.applied,
+      skipped: result.skipped,
+      specVersion: result.specVersion,
+      elementCount: result.elementCount,
+      streamStatus: result.streamStatus,
+    };
+  }
+
   addHtmlNode(input: {
     html: string;
     title?: string;
@@ -707,7 +935,7 @@ export class PmxCanvas extends EventEmitter {
       type: 'html',
       ...(typeof input.title === 'string' ? { title: input.title } : {}),
       data: {
-        html: input.html,
+        html: resolveHtmlContent(input.html),
         ...(typeof input.summary === 'string' ? { summary: input.summary } : {}),
         ...(typeof input.agentSummary === 'string' ? { agentSummary: input.agentSummary } : {}),
         ...(typeof input.description === 'string' ? { description: input.description } : {}),
@@ -875,3 +1103,27 @@ export type {
 export type { GraphNodeInput, JsonRenderNodeInput, JsonRenderSpec } from '../json-render/server.js';
 export type { HtmlPrimitiveKind, HtmlPrimitiveDescriptor, HtmlPrimitiveInput, HtmlPrimitiveBuildResult } from './html-primitives.js';
 export { traceManager } from './trace-manager.js';
+export type {
+  PmxAxApprovalGate,
+  PmxAxApprovalStatus,
+  PmxAxContext,
+  PmxAxEvent,
+  PmxAxEventKind,
+  PmxAxEvidence,
+  PmxAxEvidenceKind,
+  PmxAxFocusState,
+  PmxAxHostCapability,
+  PmxAxReviewAnchorType,
+  PmxAxReviewAnnotation,
+  PmxAxReviewKind,
+  PmxAxReviewRegion,
+  PmxAxReviewSeverity,
+  PmxAxReviewStatus,
+  PmxAxSource,
+  PmxAxState,
+  PmxAxSteeringMessage,
+  PmxAxTimelineSummary,
+  PmxAxWorkItem,
+  PmxAxWorkItemStatus,
+} from './ax-state.js';
+export type { AxTimelineQuery } from './canvas-db.js';

package/src/server/mutation-history.ts

@@ -29,6 +29,12 @@ export type MutationOp =
   | 'restoreSnapshot'
   | 'setPins'
   | 'setAxFocus'
+  | 'addWorkItem'
+  | 'updateWorkItem'
+  | 'requestApproval'
+  | 'resolveApproval'
+  | 'addReviewAnnotation'
+  | 'updateReviewAnnotation'
   | 'batch'
   | 'viewport'
   | 'groupNodes'