pmx-canvas 0.1.26 → 0.1.27

package/src/server/server.ts

@@ -77,7 +77,15 @@ import {
 import { buildCodeGraphSummary, formatCodeGraph } from './code-graph.js';
 import { buildAgentContextPreamble, serializeNodeForAgentContext } from './agent-context.js';
 import { buildCanvasAxContext } from './ax-context.js';
-import type { PmxAxSource } from './ax-state.js';
+import { isAxEventKind, isAxEvidenceKind } from './ax-state.js';
+import type {
+  PmxAxReviewAnchorType,
+  PmxAxReviewKind,
+  PmxAxReviewRegion,
+  PmxAxReviewSeverity,
+  PmxAxReviewStatus,
+  PmxAxSource,
+} from './ax-state.js';
 import { normalizeCanvasTheme, type CanvasTheme } from './canvas-db.js';
 import { validateLocalImageFile } from './image-source.js';
 import {
@@ -86,12 +94,14 @@ import {
   MARKDOWN_NODE_DEFAULT_SIZE,
   MCP_APP_NODE_DEFAULT_SIZE,
   applyCanvasNodeUpdates,
+  appendCanvasJsonRenderStream,
   buildStructuredNodeUpdate,
   arrangeCanvasNodes,
   clearCanvas,
   createCanvasGraphNode,
   createCanvasGroup,
   createCanvasJsonRenderNode,
+  createCanvasStreamingJsonRenderNode,
   deleteCanvasSnapshot,
   executeCanvasBatch,
   fitCanvasView,
@@ -101,6 +111,7 @@ import {
   refreshCanvasWebpageNode,
   removeCanvasNode,
   removeCanvasEdge,
+  resolveHtmlContent,
   restoreCanvasSnapshot,
   saveCanvasSnapshot,
   scheduleCodeGraphRecompute,
@@ -1656,7 +1667,7 @@ async function handleCanvasAddNode(req: Request): Promise<Response> {
   const htmlMergedData = type === 'html'
     ? {
         ...(extraData ?? {}),
-        ...(typeof body.html === 'string' ? { html: body.html } : {}),
+        ...(typeof body.html === 'string' ? { html: resolveHtmlContent(body.html) } : {}),
         ...(typeof body.summary === 'string' ? { summary: body.summary } : {}),
         ...(typeof body.agentSummary === 'string' ? { agentSummary: body.agentSummary } : {}),
         ...(typeof body.description === 'string' ? { description: body.description } : {}),
@@ -2214,6 +2225,34 @@ async function handleCanvasAddJsonRender(req: Request): Promise<Response> {
   }
 }
 
+async function handleJsonRenderStream(req: Request): Promise<Response> {
+  const body = await readJson(req);
+  const patches = Array.isArray(body.patches) ? body.patches : [];
+  const done = body.done === true;
+  const geometry = resolveCreateGeometry(body);
+  try {
+    let nodeId = typeof body.nodeId === 'string' && body.nodeId ? body.nodeId : undefined;
+    let url = '';
+    if (!nodeId) {
+      const created = createCanvasStreamingJsonRenderNode({
+        ...(typeof body.title === 'string' ? { title: body.title } : {}),
+        ...(body.strictSize === true ? { strictSize: true } : {}),
+        ...geometry,
+      });
+      nodeId = created.id;
+      url = created.url;
+    }
+    const result = appendCanvasJsonRenderStream(nodeId, patches, done);
+    if (!result.ok) return responseJson({ ok: false, error: result.error }, 400);
+    emitPrimaryWorkbenchEvent('canvas-layout-update', { layout: canvasState.getLayout() });
+    const node = canvasState.getNode(nodeId);
+    return responseJson({ id: nodeId, url: url || String(node?.data.url ?? ''), ...result });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return responseJson({ ok: false, error: message }, 400);
+  }
+}
+
 async function handleCanvasAddGraph(req: Request): Promise<Response> {
   const body = await readJson(req);
   const title = typeof body.title === 'string' && body.title.trim() ? body.title.trim() : 'Graph';
@@ -2242,6 +2281,16 @@ async function handleCanvasAddGraph(req: Request): Promise<Response> {
     const nodeHeight = pickPositiveNumber(body, 'nodeHeight') ?? (size ? pickPositiveNumber(size, 'height') : undefined);
     const showLegend = typeof body.showLegend === 'boolean' ? body.showLegend : undefined;
     const showLabels = typeof body.showLabels === 'boolean' ? body.showLabels : undefined;
+    const colorBy =
+      body.colorBy === 'series' || body.colorBy === 'category' || body.colorBy === 'value' || body.colorBy === 'none'
+        ? body.colorBy
+        : undefined;
+    const highlight =
+      typeof body.highlight === 'number' || body.highlight === 'max' || body.highlight === 'min' || body.highlight === null
+        ? body.highlight
+        : undefined;
+    const sort =
+      body.sort === 'asc' || body.sort === 'desc' || body.sort === 'none' ? body.sort : undefined;
     const result = createCanvasGraphNode({
       title,
       graphType,
@@ -2258,8 +2307,23 @@ async function handleCanvasAddGraph(req: Request): Promise<Response> {
       ...(typeof body.lineKey === 'string' ? { lineKey: body.lineKey } : {}),
       ...(aggregate ? { aggregate } : {}),
       ...(typeof body.color === 'string' ? { color: body.color } : {}),
+      ...(colorBy ? { colorBy } : {}),
+      ...(highlight !== undefined ? { highlight } : {}),
       ...(typeof body.barColor === 'string' ? { barColor: body.barColor } : {}),
       ...(typeof body.lineColor === 'string' ? { lineColor: body.lineColor } : {}),
+      ...(typeof body.labelKey === 'string' ? { labelKey: body.labelKey } : {}),
+      ...(typeof body.targetKey === 'string' ? { targetKey: body.targetKey } : {}),
+      ...(typeof body.rangesKey === 'string' ? { rangesKey: body.rangesKey } : {}),
+      ...(typeof body.beforeKey === 'string' ? { beforeKey: body.beforeKey } : {}),
+      ...(typeof body.afterKey === 'string' ? { afterKey: body.afterKey } : {}),
+      ...(typeof body.beforeLabel === 'string' ? { beforeLabel: body.beforeLabel } : {}),
+      ...(typeof body.afterLabel === 'string' ? { afterLabel: body.afterLabel } : {}),
+      ...(sort ? { sort } : {}),
+      ...(typeof body.fill === 'boolean' ? { fill: body.fill } : {}),
+      ...(typeof body.showEndDot === 'boolean' ? { showEndDot: body.showEndDot } : {}),
+      ...(typeof body.showMinMax === 'boolean' ? { showMinMax: body.showMinMax } : {}),
+      ...(typeof body.showValue === 'boolean' ? { showValue: body.showValue } : {}),
+      ...(typeof body.colorByDirection === 'boolean' ? { colorByDirection: body.colorByDirection } : {}),
       ...(typeof body.height === 'number' ? { height: body.height } : {}),
       ...(showLegend !== undefined ? { showLegend } : {}),
       ...(showLabels !== undefined ? { showLabels } : {}),
@@ -2334,11 +2398,17 @@ async function handleJsonRenderView(url: URL): Promise<Response> {
       ? themeValue
       : undefined;
   const title = (node.data.title as string) || node.id;
+  // Devtools panel is double-gated: the operator must opt in via the env flag
+  // AND the request must carry ?devtools=1. Off by default in all normal runs.
+  const devtoolsEnabled =
+    process.env.PMX_CANVAS_JSON_RENDER_DEVTOOLS === '1' &&
+    url.searchParams.get('devtools') === '1';
   const html = await buildJsonRenderViewerHtml({
     title,
     spec,
     ...(theme ? { theme } : {}),
     ...(url.searchParams.get('display') === 'expanded' ? { display: 'expanded' as const } : {}),
+    ...(devtoolsEnabled ? { devtools: true } : {}),
   });
   return new Response(html, {
     headers: {
@@ -3653,6 +3723,284 @@ async function handleAxStatePatch(req: Request): Promise<Response> {
   return responseJson({ ok: true, state: canvasState.getAxState() });
 }
 
+async function handleAxEventAdd(req: Request): Promise<Response> {
+  const body = await readJson(req);
+  if (!isAxEventKind(body.kind) || typeof body.summary !== 'string') {
+    return responseJson({ ok: false, error: 'event requires kind and summary.' }, 400);
+  }
+  const event = canvasState.recordAxEvent(
+    {
+      kind: body.kind,
+      summary: body.summary,
+      detail: typeof body.detail === 'string' ? body.detail : null,
+      nodeIds: normalizeAxNodeIds(body.nodeIds),
+      data: isRecord(body.data) ? body.data : null,
+    },
+    { source: normalizeAxSource(body.source, 'api') },
+  );
+  broadcastWorkbenchEvent('ax-event-created', {
+    event,
+    sessionId: primaryWorkbenchSessionId,
+    timestamp: new Date().toISOString(),
+  });
+  return responseJson({ ok: true, event });
+}
+
+async function handleAxSteer(req: Request): Promise<Response> {
+  const body = await readJson(req);
+  if (typeof body.message !== 'string' || !body.message.trim()) {
+    return responseJson({ ok: false, error: 'steer requires a non-empty message.' }, 400);
+  }
+  const steering = canvasState.recordSteeringMessage(body.message, {
+    source: normalizeAxSource(body.source, 'api'),
+  });
+  broadcastWorkbenchEvent('ax-event-created', {
+    steering,
+    sessionId: primaryWorkbenchSessionId,
+    timestamp: new Date().toISOString(),
+  });
+  return responseJson({ ok: true, steering });
+}
+
+function handleAxTimelineGet(url: URL): Response {
+  const limit = Number(url.searchParams.get('limit') ?? '');
+  return responseJson({
+    ok: true,
+    ...canvasState.getAxTimeline(Number.isFinite(limit) && limit > 0 ? { limit } : {}),
+  });
+}
+
+const AX_WORK_STATUSES = new Set(['todo', 'in-progress', 'blocked', 'done', 'cancelled']);
+
+function normalizeAxWorkItemStatus(value: unknown): 'todo' | 'in-progress' | 'blocked' | 'done' | 'cancelled' | undefined {
+  return typeof value === 'string' && AX_WORK_STATUSES.has(value)
+    ? value as 'todo' | 'in-progress' | 'blocked' | 'done' | 'cancelled'
+    : undefined;
+}
+
+function handleAxWorkList(): Response {
+  return responseJson({ ok: true, workItems: canvasState.getWorkItems() });
+}
+
+async function handleAxWorkAdd(req: Request): Promise<Response> {
+  const body = await readJson(req);
+  if (typeof body.title !== 'string' || !body.title.trim()) {
+    return responseJson({ ok: false, error: 'work item requires a title.' }, 400);
+  }
+  const status = normalizeAxWorkItemStatus(body.status);
+  const workItem = canvasState.addWorkItem(
+    {
+      title: body.title,
+      ...(status ? { status } : {}),
+      ...(typeof body.detail === 'string' ? { detail: body.detail } : {}),
+      ...(Array.isArray(body.nodeIds) ? { nodeIds: normalizeAxNodeIds(body.nodeIds) } : {}),
+    },
+    { source: normalizeAxSource(body.source, 'api') },
+  );
+  broadcastWorkbenchEvent('ax-state-changed', {
+    workItem,
+    sessionId: primaryWorkbenchSessionId,
+    timestamp: new Date().toISOString(),
+  });
+  return responseJson({ ok: true, workItem });
+}
+
+async function handleAxWorkUpdate(req: Request, id: string): Promise<Response> {
+  const body = await readJson(req);
+  const status = normalizeAxWorkItemStatus(body.status);
+  const workItem = canvasState.updateWorkItem(
+    id,
+    {
+      ...(typeof body.title === 'string' ? { title: body.title } : {}),
+      ...(status ? { status } : {}),
+      ...(typeof body.detail === 'string' || body.detail === null ? { detail: body.detail as string | null } : {}),
+      ...(Array.isArray(body.nodeIds) ? { nodeIds: normalizeAxNodeIds(body.nodeIds) } : {}),
+    },
+    { source: normalizeAxSource(body.source, 'api') },
+  );
+  if (!workItem) return responseJson({ ok: false, error: 'work item not found.' }, 404);
+  broadcastWorkbenchEvent('ax-state-changed', {
+    workItem,
+    sessionId: primaryWorkbenchSessionId,
+    timestamp: new Date().toISOString(),
+  });
+  return responseJson({ ok: true, workItem });
+}
+
+function handleAxApprovalList(): Response {
+  return responseJson({ ok: true, approvalGates: canvasState.getApprovalGates() });
+}
+
+async function handleAxApprovalRequest(req: Request): Promise<Response> {
+  const body = await readJson(req);
+  if (typeof body.title !== 'string' || !body.title.trim()) {
+    return responseJson({ ok: false, error: 'approval request requires a title.' }, 400);
+  }
+  const approvalGate = canvasState.requestApproval(
+    {
+      title: body.title,
+      ...(typeof body.detail === 'string' ? { detail: body.detail } : {}),
+      ...(typeof body.action === 'string' ? { action: body.action } : {}),
+      ...(Array.isArray(body.nodeIds) ? { nodeIds: normalizeAxNodeIds(body.nodeIds) } : {}),
+    },
+    { source: normalizeAxSource(body.source, 'api') },
+  );
+  broadcastWorkbenchEvent('ax-state-changed', {
+    approvalGate,
+    sessionId: primaryWorkbenchSessionId,
+    timestamp: new Date().toISOString(),
+  });
+  return responseJson({ ok: true, approvalGate });
+}
+
+async function handleAxApprovalResolve(req: Request, id: string): Promise<Response> {
+  const body = await readJson(req);
+  if (body.decision !== 'approved' && body.decision !== 'rejected') {
+    return responseJson({ ok: false, error: 'resolve requires decision approved or rejected.' }, 400);
+  }
+  const approvalGate = canvasState.resolveApproval(
+    id,
+    body.decision,
+    {
+      ...(typeof body.resolution === 'string' ? { resolution: body.resolution } : {}),
+      source: normalizeAxSource(body.source, 'api'),
+    },
+  );
+  if (!approvalGate) return responseJson({ ok: false, error: 'approval gate not found or already resolved.' }, 404);
+  broadcastWorkbenchEvent('ax-state-changed', {
+    approvalGate,
+    sessionId: primaryWorkbenchSessionId,
+    timestamp: new Date().toISOString(),
+  });
+  return responseJson({ ok: true, approvalGate });
+}
+
+async function handleAxEvidenceAdd(req: Request): Promise<Response> {
+  const body = await readJson(req);
+  if (!isAxEvidenceKind(body.kind) || typeof body.title !== 'string' || !body.title.trim()) {
+    return responseJson({ ok: false, error: 'evidence requires kind and title.' }, 400);
+  }
+  const evidence = canvasState.addEvidence(
+    {
+      kind: body.kind,
+      title: body.title,
+      body: typeof body.body === 'string' ? body.body : null,
+      ref: typeof body.ref === 'string' ? body.ref : null,
+      nodeIds: normalizeAxNodeIds(body.nodeIds),
+      data: isRecord(body.data) ? body.data : null,
+    },
+    { source: normalizeAxSource(body.source, 'api') },
+  );
+  broadcastWorkbenchEvent('ax-event-created', {
+    evidence,
+    sessionId: primaryWorkbenchSessionId,
+    timestamp: new Date().toISOString(),
+  });
+  return responseJson({ ok: true, evidence });
+}
+
+const AX_REVIEW_KINDS = new Set(['comment', 'finding']);
+const AX_REVIEW_SEVERITIES = new Set(['info', 'warning', 'error']);
+const AX_REVIEW_STATUSES = new Set(['open', 'resolved', 'dismissed']);
+const AX_REVIEW_ANCHORS = new Set(['node', 'file', 'region']);
+
+function normalizeAxReviewKind(value: unknown): PmxAxReviewKind | undefined {
+  return typeof value === 'string' && AX_REVIEW_KINDS.has(value) ? value as PmxAxReviewKind : undefined;
+}
+function normalizeAxReviewSeverity(value: unknown): PmxAxReviewSeverity | undefined {
+  return typeof value === 'string' && AX_REVIEW_SEVERITIES.has(value) ? value as PmxAxReviewSeverity : undefined;
+}
+function normalizeAxReviewStatus(value: unknown): PmxAxReviewStatus | undefined {
+  return typeof value === 'string' && AX_REVIEW_STATUSES.has(value) ? value as PmxAxReviewStatus : undefined;
+}
+function normalizeAxReviewAnchor(value: unknown): PmxAxReviewAnchorType | undefined {
+  return typeof value === 'string' && AX_REVIEW_ANCHORS.has(value) ? value as PmxAxReviewAnchorType : undefined;
+}
+function normalizeAxReviewRegion(value: unknown): PmxAxReviewRegion | undefined {
+  if (!isRecord(value)) return undefined;
+  return {
+    ...(typeof value.line === 'number' ? { line: value.line } : {}),
+    ...(typeof value.endLine === 'number' ? { endLine: value.endLine } : {}),
+    ...(typeof value.label === 'string' ? { label: value.label } : {}),
+  };
+}
+
+function handleAxReviewList(): Response {
+  return responseJson({ ok: true, reviewAnnotations: canvasState.getReviewAnnotations() });
+}
+
+async function handleAxReviewAdd(req: Request): Promise<Response> {
+  const body = await readJson(req);
+  if (typeof body.body !== 'string' || !body.body.trim()) {
+    return responseJson({ ok: false, error: 'review annotation requires a body.' }, 400);
+  }
+  const kind = normalizeAxReviewKind(body.kind);
+  const severity = normalizeAxReviewSeverity(body.severity);
+  const anchorType = normalizeAxReviewAnchor(body.anchorType);
+  const region = normalizeAxReviewRegion(body.region);
+  const reviewAnnotation = canvasState.addReviewAnnotation(
+    {
+      body: body.body,
+      ...(kind ? { kind } : {}),
+      ...(severity ? { severity } : {}),
+      ...(anchorType ? { anchorType } : {}),
+      ...(typeof body.nodeId === 'string' ? { nodeId: body.nodeId } : {}),
+      ...(typeof body.file === 'string' ? { file: body.file } : {}),
+      ...(region ? { region } : {}),
+      ...(typeof body.author === 'string' ? { author: body.author } : {}),
+    },
+    { source: normalizeAxSource(body.source, 'api') },
+  );
+  if (!reviewAnnotation) {
+    return responseJson({ ok: false, error: 'node-anchored review annotation requires a nodeId that exists on the canvas.' }, 400);
+  }
+  broadcastWorkbenchEvent('ax-state-changed', {
+    reviewAnnotation,
+    sessionId: primaryWorkbenchSessionId,
+    timestamp: new Date().toISOString(),
+  });
+  return responseJson({ ok: true, reviewAnnotation });
+}
+
+async function handleAxReviewUpdate(req: Request, id: string): Promise<Response> {
+  const body = await readJson(req);
+  const status = normalizeAxReviewStatus(body.status);
+  const severity = normalizeAxReviewSeverity(body.severity);
+  const kind = normalizeAxReviewKind(body.kind);
+  const reviewAnnotation = canvasState.updateReviewAnnotation(
+    id,
+    {
+      ...(typeof body.body === 'string' ? { body: body.body } : {}),
+      ...(status ? { status } : {}),
+      ...(severity ? { severity } : {}),
+      ...(kind ? { kind } : {}),
+    },
+    { source: normalizeAxSource(body.source, 'api') },
+  );
+  if (!reviewAnnotation) return responseJson({ ok: false, error: 'review annotation not found.' }, 404);
+  broadcastWorkbenchEvent('ax-state-changed', {
+    reviewAnnotation,
+    sessionId: primaryWorkbenchSessionId,
+    timestamp: new Date().toISOString(),
+  });
+  return responseJson({ ok: true, reviewAnnotation });
+}
+
+function handleAxHostCapabilityGet(): Response {
+  return responseJson({ ok: true, host: canvasState.getHostCapability() });
+}
+
+async function handleAxHostCapabilityReport(req: Request): Promise<Response> {
+  const body = await readJson(req);
+  const host = canvasState.setHostCapability(body, { source: normalizeAxSource(body.source, 'api') });
+  broadcastWorkbenchEvent('ax-state-changed', {
+    host,
+    sessionId: primaryWorkbenchSessionId,
+    timestamp: new Date().toISOString(),
+  });
+  return responseJson({ ok: true, host });
+}
+
 // ── Port resolution ───────────────────────────────────────────
 
 function buildPortCandidates(preferredPort: number): number[] {
@@ -4641,6 +4989,71 @@ export function startCanvasServer(options: CanvasServerOptions = {}): string | n
             return handleAxFocusUpdate(req);
           }
 
+          if (url.pathname === '/api/canvas/ax/event' && req.method === 'POST') {
+            return handleAxEventAdd(req);
+          }
+
+          if (url.pathname === '/api/canvas/ax/steer' && req.method === 'POST') {
+            return handleAxSteer(req);
+          }
+
+          if (url.pathname === '/api/canvas/ax/timeline' && req.method === 'GET') {
+            return handleAxTimelineGet(url);
+          }
+
+          if (url.pathname === '/api/canvas/ax/work' && req.method === 'GET') {
+            return handleAxWorkList();
+          }
+
+          if (url.pathname === '/api/canvas/ax/work' && req.method === 'POST') {
+            return handleAxWorkAdd(req);
+          }
+
+          if (url.pathname.startsWith('/api/canvas/ax/work/') && req.method === 'PATCH') {
+            const workItemId = decodeURIComponent(url.pathname.slice('/api/canvas/ax/work/'.length));
+            return handleAxWorkUpdate(req, workItemId);
+          }
+
+          if (url.pathname === '/api/canvas/ax/approval' && req.method === 'GET') {
+            return handleAxApprovalList();
+          }
+
+          if (url.pathname === '/api/canvas/ax/approval' && req.method === 'POST') {
+            return handleAxApprovalRequest(req);
+          }
+
+          if (url.pathname.startsWith('/api/canvas/ax/approval/') && url.pathname.endsWith('/resolve') && req.method === 'POST') {
+            const approvalId = decodeURIComponent(
+              url.pathname.slice('/api/canvas/ax/approval/'.length, -'/resolve'.length),
+            );
+            return handleAxApprovalResolve(req, approvalId);
+          }
+
+          if (url.pathname === '/api/canvas/ax/evidence' && req.method === 'POST') {
+            return handleAxEvidenceAdd(req);
+          }
+
+          if (url.pathname === '/api/canvas/ax/review' && req.method === 'GET') {
+            return handleAxReviewList();
+          }
+
+          if (url.pathname === '/api/canvas/ax/review' && req.method === 'POST') {
+            return handleAxReviewAdd(req);
+          }
+
+          if (url.pathname.startsWith('/api/canvas/ax/review/') && req.method === 'PATCH') {
+            const reviewId = decodeURIComponent(url.pathname.slice('/api/canvas/ax/review/'.length));
+            return handleAxReviewUpdate(req, reviewId);
+          }
+
+          if (url.pathname === '/api/canvas/ax/host-capability' && req.method === 'GET') {
+            return handleAxHostCapabilityGet();
+          }
+
+          if (url.pathname === '/api/canvas/ax/host-capability' && req.method === 'PUT') {
+            return handleAxHostCapabilityReport(req);
+          }
+
           // Spatial context API
           if (url.pathname === '/api/canvas/spatial-context' && req.method === 'GET') {
             const layout = canvasState.getLayout();
@@ -4703,6 +5116,10 @@ export function startCanvasServer(options: CanvasServerOptions = {}): string | n
             return handleCanvasAddJsonRender(req);
           }
 
+          if (url.pathname === '/api/canvas/json-render/stream' && req.method === 'POST') {
+            return handleJsonRenderStream(req);
+          }
+
           if (url.pathname === '/api/canvas/graph' && req.method === 'POST') {
             return handleCanvasAddGraph(req);
           }