pmx-canvas 0.11.0 → 0.12.0

package/src/server/server.ts

@@ -78,10 +78,10 @@ import { validateLocalImageFile } from './image-source.js';
 import {
   addCanvasNode,
   cancelCodeGraphRecompute,
-  primeCanvasRuntimeBackends,
   setCanvasLayoutUpdateEmitter,
-  syncCanvasRuntimeBackends,
+  startBoardRuntime,
 } from './canvas-operations.js';
+import { createBoardLocal } from './board-local.js';
 import { MAX_ATTACHMENT_BYTES, MAX_ATTACHMENT_NAME_LENGTH } from './document-import.js';
 import { dispatchOperationRoute, setOperationEventEmitter } from './operations/index.js';
 import { intentRegistry } from './intent-registry.js';
@@ -105,7 +105,10 @@ const DEFAULT_PORT = 4313;
 
 let server: ReturnType<typeof Bun.serve> | null = null;
 let activeWorkspaceRoot = resolve(process.cwd());
-let primaryWorkbenchPath: string | null = null;
+const boardReplay = createBoardLocal(() => ({
+  path: null as string | null,
+  contextCards: null as Record<string, unknown> | null,
+}));
 let primaryWorkbenchSessionId = `pmx-${Date.now().toString(36)}`;
 let nextWorkbenchEventId = 1;
 let nextWorkbenchSubscriberId = 1;
@@ -113,7 +116,6 @@ const workbenchSubscribers = new Map<number, ReadableStreamDefaultController<Uin
 const textEncoder = new TextEncoder();
 let primaryWorkbenchAutoOpenEnabled = true;
 const initialCanvasThemeSetting = normalizeCanvasTheme(process.env.PMX_CANVAS_THEME);
-let lastWorkbenchContextCardsEnvelope: Record<string, unknown> | null = null;
 
 // Operation-registry SSE wiring (plan-005): the registry never imports this
 // module — the workbench event emitter is injected here, mirroring the
@@ -941,6 +943,21 @@ export function onWorkbenchEvent(listener: (event: string) => void): () => void
 }
 
 function broadcastWorkbenchEvent(event: string, payload: PrimaryWorkbenchEventPayload): void {
+  if (canvasState.isBackgroundBoard) {
+    if (event === 'canvas-layout-update' || event === 'boards-changed')
+      canvasState.withVisibleBoard(() => broadcastWorkbenchEvent('boards-changed', boardsPayload()));
+    else if (event === 'ax-state-changed') {
+      const ownerBoardId = canvasState.activeBoardId;
+      canvasState.withVisibleBoard(() => {
+        const layout = canvasState.getLayout();
+        if (layout.nodes.some((node) => node.type === 'status' && node.data.workItemBoardId === ownerBoardId))
+          broadcastWorkbenchEvent('canvas-layout-update', { layout });
+      });
+    } else if (event === 'agent-presence')
+      canvasState.withVisibleBoard(() => broadcastWorkbenchEvent(event, { ...payload, ...agentPresence.snapshot() }));
+    return;
+  }
+  payload = { ...payload, boardId: canvasState.visibleBoardId };
   let remoteEdgesChanged = false;
   if (event === 'canvas-layout-update') {
     // Remote footer titles come from the catalog. Refresh it on endpoint changes
@@ -960,7 +977,7 @@ function broadcastWorkbenchEvent(event: string, payload: PrimaryWorkbenchEventPa
     payload = {
       ...payload,
       catalogEpoch: boardCatalogEpoch,
-      boardGeneration: canvasState.boardGeneration,
+      boardGeneration: canvasState.visibleBoardGeneration,
       boardId: canvasState.activeBoardId,
     };
   }
@@ -990,8 +1007,8 @@ function broadcastWorkbenchEvent(event: string, payload: PrimaryWorkbenchEventPa
 
 function setPrimaryWorkbenchPath(safePath: string, source: string): void {
   const resolved = resolve(safePath);
-  if (primaryWorkbenchPath === resolved) return;
-  primaryWorkbenchPath = resolved;
+  if (boardReplay.current.path === resolved) return;
+  boardReplay.current.path = resolved;
   broadcastWorkbenchEvent('workbench-open', {
     path: resolved,
     title: basename(resolved),
@@ -2073,6 +2090,7 @@ function handleRead(pathLike: string): Response {
 
 function handleWorkbenchState(): Response {
   const mcpAppHost = getMcpAppHostSnapshot();
+  const primaryWorkbenchPath = boardReplay.current.path;
   if (!primaryWorkbenchPath) {
     return responseJson({
       sessionId: primaryWorkbenchSessionId,
@@ -2085,7 +2103,7 @@ function handleWorkbenchState(): Response {
 
   const safePath = resolveWorkspaceMarkdownPath(primaryWorkbenchPath);
   if (!safePath || !existsSync(safePath)) {
-    primaryWorkbenchPath = null;
+    boardReplay.current.path = null;
     return responseJson({
       sessionId: primaryWorkbenchSessionId,
       path: null,
@@ -2202,6 +2220,7 @@ async function handleWorkbenchIntent(req: Request): Promise<Response> {
 function buildWorkbenchConnectSnapshot(
   requestedSessionId: string,
 ): Array<{ event: string; payload: Record<string, unknown> }> {
+  const { path: primaryWorkbenchPath, contextCards: lastWorkbenchContextCardsEnvelope } = boardReplay.current;
   const continuity =
     requestedSessionId.length === 0
       ? 'fresh'
@@ -3311,10 +3330,16 @@ export function emitPrimaryWorkbenchEvent(event: string, payload: PrimaryWorkben
     timestamp: new Date().toISOString(),
   };
   if (event === 'context-cards') {
-    lastWorkbenchContextCardsEnvelope = { ...envelope };
+    boardReplay.current.contextCards = { ...envelope };
   }
   syncEventToCanvasState(event, envelope);
-  if (primaryWorkbenchAutoOpenEnabled && (event === 'workbench-open' || event === 'ext-app-open')) {
+  // Events can create server state. Apply them to their producer's board before
+  // deciding whether they belong in the human's currently visible projection.
+  if (
+    !canvasState.isBackgroundBoard &&
+    primaryWorkbenchAutoOpenEnabled &&
+    (event === 'workbench-open' || event === 'ext-app-open')
+  ) {
     ensureCanvasBrowserOpen();
   }
   broadcastWorkbenchEvent(event, envelope);
@@ -3401,6 +3426,27 @@ export interface CanvasServerOptions {
   allowExternalMcp?: boolean;
 }
 
+// SDK/MCP producers can own cards before an HTTP listener starts.
+canvasState.setMoveRuntimeBlockers(() => {
+  const blockers = new Map<string, string>();
+  for (const id of traceManager.ownedNodeIds) blockers.set(id, 'the trace manager still owns this card');
+  for (const [response, prompt] of serverResponseToThreadMap) {
+    blockers.set(response, 'an active response is routed to this card');
+    blockers.set(prompt, 'an active response is routed to this prompt');
+  }
+  for (const intent of pendingWorkbenchIntents) {
+    if (intent.type !== 'canvas-prompt') continue;
+    for (const id of [
+      intent.payload.nodeId,
+      intent.payload.parentNodeId,
+      ...(Array.isArray(intent.payload.contextNodeIds) ? intent.payload.contextNodeIds : []),
+    ]) {
+      if (typeof id === 'string') blockers.set(id, 'a queued prompt still refers to this card');
+    }
+  }
+  return blockers;
+});
+
 export function startCanvasServer(options: CanvasServerOptions = {}): string | null {
   if (server) {
     return typeof server.port === 'number' ? loopbackBaseUrl(server.port) : null;
@@ -3447,12 +3493,9 @@ export function startCanvasServer(options: CanvasServerOptions = {}): string | n
   });
   if (loaded) {
     console.log('  Canvas state restored from .pmx-canvas/canvas.db');
-    primeCanvasRuntimeBackends({ forceRehydrateExtApps: true });
-    const rehydrate = () => syncCanvasRuntimeBackends({ forceRehydrateExtApps: true, alreadyPrimed: true });
-    const pending = options.allowExternalMcp === false ? withoutExternalMcp(rehydrate) : rehydrate();
-    void pending.finally(() => {
-      emitPrimaryWorkbenchEvent('canvas-layout-update', { layout: canvasState.getLayout() });
-    });
+    const rehydrate = () => startBoardRuntime({ forceRehydrateExtApps: true });
+    if (options.allowExternalMcp === false) withoutExternalMcp(rehydrate);
+    else rehydrate();
   }
 
   rotatePrimaryWorkbenchSessionIfNeeded();
@@ -3507,6 +3550,9 @@ export function startCanvasServer(options: CanvasServerOptions = {}): string | n
               workspace: activeWorkspaceRoot,
               pid: process.pid,
               version: serverPackageVersion(),
+              // The stamp open tabs reload on, read once per process: after a rebuild it lags
+              // dist/ on disk, and already-open tabs keep old JS until the server restarts.
+              bundleStamp: canvasBundleStamp(),
               contracts: [CANVAS_APP_WRITE_CONTRACT],
               persistence: canvasState.persistenceHealth,
             });

package/src/server/tour-control.ts

@@ -21,6 +21,7 @@ import {
 import { boardCatalogEpoch, canvasState } from './canvas-state.js';
 import { getClientViewportSize } from './canvas-operations.js';
 import { OperationError } from './operations/types.js';
+import { createBoardLocal } from './board-local.js';
 
 export type TourStep = number | 'next' | 'previous';
 
@@ -46,19 +47,28 @@ export interface TourState {
   position: number | null;
 }
 
-let cursor: { boardGeneration: number; tour: string; index: number } | null = null;
+const boardTour = createBoardLocal(() => ({
+  cursor: null as { boardGeneration: number; viewGeneration: number; tour: string; index: number } | null,
+  presenterGeneration: -1,
+  presenterIntents: new Map<string, number>(),
+}));
 // One order for both HTTP acknowledgements and event delivery in this server run.
 let sequence = 0;
-let presenterGeneration = -1;
-const presenterIntents = new Map<string, number>();
 
 function claimPresenter(presenter: TourPresenter | undefined): boolean {
   if (presenter === undefined) return true;
+  const state = boardTour.current;
+  const { presenterIntents } = state;
   const { clientId, intent, catalogEpoch, boardGeneration } = tourPresenterSchema.parse(presenter);
-  if (catalogEpoch !== boardCatalogEpoch || boardGeneration !== canvasState.boardGeneration) return false;
-  if (presenterGeneration !== boardGeneration) {
+  if (
+    canvasState.isBackgroundBoard ||
+    catalogEpoch !== boardCatalogEpoch ||
+    boardGeneration !== canvasState.visibleBoardGeneration
+  )
+    return false;
+  if (state.presenterGeneration !== boardGeneration) {
     presenterIntents.clear();
-    presenterGeneration = boardGeneration;
+    state.presenterGeneration = boardGeneration;
   }
   const previous = presenterIntents.get(clientId);
   if (previous !== undefined && intent <= previous) return false;
@@ -74,7 +84,11 @@ function claimPresenter(presenter: TourPresenter | undefined): boolean {
 }
 
 function nextDelivery(): TourDelivery {
-  return { catalogEpoch: boardCatalogEpoch, boardGeneration: canvasState.boardGeneration, sequence: ++sequence };
+  return {
+    catalogEpoch: boardCatalogEpoch,
+    boardGeneration: canvasState.isBackgroundBoard ? canvasState.boardGeneration : canvasState.visibleBoardGeneration,
+    sequence: ++sequence,
+  };
 }
 
 export function currentTour(): TourState {
@@ -85,10 +99,16 @@ export function currentTour(): TourState {
 
 /** The stop the tour is on for the active board, or null when not touring. */
 function tourPosition(tour: Tour): number | null {
-  if (cursor && (cursor.boardGeneration !== canvasState.boardGeneration || cursor.tour !== JSON.stringify(tour))) {
-    cursor = null;
+  const { cursor } = boardTour.current;
+  if (
+    cursor &&
+    (cursor.boardGeneration !== canvasState.boardLifetimeGeneration ||
+      (!canvasState.isBackgroundBoard && cursor.viewGeneration !== canvasState.visibleBoardGeneration) ||
+      cursor.tour !== JSON.stringify(tour))
+  ) {
+    boardTour.current.cursor = null;
   }
-  return cursor?.index ?? null;
+  return boardTour.current.cursor?.index ?? null;
 }
 
 /** Move the shared cursor. `next`/`previous` clamp at the ends; an explicit index must exist. */
@@ -106,7 +126,12 @@ export function goToTourStop(step: TourStep, presenter?: TourPresenter): TourSte
   else if (step === 'previous') index = at === null ? 0 : Math.max(0, Math.min(stops.length - 1, at - 1));
   else if (Number.isInteger(step) && step >= 0 && step < stops.length) index = step;
   else throw new OperationError(`Tour stop ${step} does not exist (stops 0–${stops.length - 1}).`, 400);
-  cursor = { boardGeneration: canvasState.boardGeneration, tour: JSON.stringify(tour), index };
+  boardTour.current.cursor = {
+    boardGeneration: canvasState.boardLifetimeGeneration,
+    viewGeneration: canvasState.visibleBoardGeneration,
+    tour: JSON.stringify(tour),
+    index,
+  };
   return {
     ...nextDelivery(),
     index,
@@ -119,7 +144,7 @@ export function exitTour(): TourDelivery;
 export function exitTour(presenter: TourPresenter | undefined): TourDelivery | TourSuperseded;
 export function exitTour(presenter?: TourPresenter): TourDelivery | TourSuperseded {
   if (!claimPresenter(presenter)) return { superseded: true };
-  cursor = null;
+  boardTour.current.cursor = null;
   return nextDelivery();
 }
 

package/src/server/trace-manager.ts

@@ -72,6 +72,10 @@ class TraceManager {
     return this._enabled;
   }
 
+  get ownedNodeIds(): readonly string[] {
+    return this.traceNodeIds;
+  }
+
   setEnabled(value: boolean): void {
     this._enabled = value;
     if (value) {

package/src/server/web-artifacts/scripts/init-artifact.sh

@@ -146,8 +146,8 @@ fi
 
 echo "🚀 Creating new React + Vite project: $PROJECT_NAME"
 
-# Create new Vite project (always use latest create-vite, pin vite version later)
-run_pnpm_quiet create vite "$PROJECT_NAME" --template react-ts --no-interactive
+# 9.3.2 shipped without templates; keep scaffolding on the verified complete package.
+run_pnpm_quiet create vite@9.3.1 "$PROJECT_NAME" --template react-ts --no-interactive
 
 # Navigate into project directory
 cd "$PROJECT_NAME"

package/src/shared/agent-context.ts

@@ -374,8 +374,14 @@ export function summarizeNodeForAgentContext(node: CanvasNodeState, options: Age
       return truncateContextText(`${prefix}${fileContent}`, defaultTextLength);
     }
     case 'status':
+      if (typeof node.data.workItemId === 'string') {
+        return truncateContextText(
+          `Read-only live task: ${node.data.workItemId}\n${node.data.liveWorkAvailable === false ? 'Task unavailable' : textFields(node.data, ['title', 'workState', 'detail', 'liveWorkSource'])}`,
+          defaultTextLength,
+        );
+      }
       return truncateContextText(
-        `Status: ${textFields(node.data, ['phase']) || textFields(node.data, ['content']) || textFields(node.data, ['status']) || 'unknown'}\n${textFields(node.data, ['detail', 'message', 'activeTool'])}`,
+        `Status: ${textFields(node.data, ['workState']) || textFields(node.data, ['phase']) || textFields(node.data, ['content']) || textFields(node.data, ['status']) || 'unknown'}\n${textFields(node.data, ['detail', 'message', 'activeTool'])}${typeof node.data.progress === 'number' ? `\nProgress: ${node.data.progress}%` : ''}`,
         defaultTextLength,
       );
     case 'context':

package/src/shared/auto-arrange.ts

@@ -463,10 +463,11 @@ export function computeAutoArrange(
   const { outgoing, undirected, indegree, outdegree } = buildUnitGraphs(units, nodeToUnit, allEdges);
   const clusters = collectSpatialClusters(units, undirected);
   const absoluteUnitPositions = new Map<string, ArrangePosition>();
-  // Already-packed cluster rects: a cluster that grew past its old bounds is
-  // shifted below earlier clusters instead of overlapping them. Clusters are
-  // processed top-left first, so the cascade is deterministic.
-  const packedRects: Array<ArrangePosition & ArrangeSize> = [];
+  // Reserve fixed cards as well as already-packed clusters. A growing cluster
+  // shifts below blockers without moving pinned cards or splitting its groups.
+  const packedRects: Array<ArrangePosition & ArrangeSize> = allNodes
+    .filter((node) => node.pinned)
+    .map((node) => ({ ...node.position, ...node.size }));
 
   for (const clusterUnits of clusters) {
     const components = collectComponents(clusterUnits, undirected).map((component) =>

package/src/shared/ax-kinds.ts

@@ -5,6 +5,19 @@
  */
 export type AxWorkItemStatus = 'todo' | 'in-progress' | 'blocked' | 'done' | 'cancelled';
 
+/** Authored work cards use the task vocabulary without creating an AX task. */
+export const WORK_CARD_STATES: Record<AxWorkItemStatus, { label: string; glyph: string }> = {
+  todo: { label: 'To do', glyph: '○' },
+  'in-progress': { label: 'In progress', glyph: '◐' },
+  blocked: { label: 'Blocked', glyph: '⧗' },
+  done: { label: 'Done', glyph: '✓' },
+  cancelled: { label: 'Cancelled', glyph: '×' },
+};
+
+export function isWorkCardState(value: unknown): value is AxWorkItemStatus {
+  return typeof value === 'string' && Object.hasOwn(WORK_CARD_STATES, value);
+}
+
 /** `held` = auto-held by the unattended-approval policy: the action did NOT proceed. */
 export type AxApprovalStatus = 'pending' | 'approved' | 'rejected' | 'held';
 

package/src/shared/ax-surface-protocol.ts

@@ -20,3 +20,25 @@ export const HTML_SURFACE_PUSH_SOURCE = 'pmx-canvas-html-node';
 
 /** Tab-local JSON viewer state handoff, independent of AX capabilities. */
 export const JSON_VIEWER_STATE_SOURCE = 'pmx-canvas-json-state';
+
+/** MCP apps share their window channel with an SDK JSON-RPC transport. */
+export const MCP_SURFACE_METHOD = 'notifications/pmx/surface';
+
+export function surfaceNotification(params: Record<string, unknown>) {
+  return { jsonrpc: '2.0' as const, method: MCP_SURFACE_METHOD, params };
+}
+
+export function readSurfaceNotification(message: unknown): unknown {
+  if (
+    message &&
+    typeof message === 'object' &&
+    'jsonrpc' in message &&
+    message.jsonrpc === '2.0' &&
+    'method' in message &&
+    message.method === MCP_SURFACE_METHOD &&
+    !('id' in message) &&
+    'params' in message
+  )
+    return message.params;
+  return null;
+}

package/src/shared/human-presence.ts

@@ -21,6 +21,7 @@ export interface HumanPresenceSnapshot {
   humans: HumanPresence[];
 }
 
+export const HUMAN_NAME_MAX_LENGTH = 40;
 /** A tab that stops reporting is gone after this. */
 export const HUMAN_PRESENCE_TTL_MS = 30_000;
 /** A grab the tab stops renewing (crash, tab closed mid-drag) releases after this. */

package/src/shared/lifecycle-status.ts

@@ -21,6 +21,8 @@ export interface LifecycleQualification {
   contentChangedAt: string | null;
   /** The revisions a validating reviewer must have inspected, qualified by source relation. */
   observations: Record<string, number | null>;
+  /** Warnings keyed by the same qualified source identity as observations. */
+  sourceWarnings?: Record<string, string[]>;
   sources: SourceQualification[];
   relevance: 'card-pinned' | 'board-pinned' | 'not-selected';
 }

package/dist/canvas/chunks/architecture-TIHT7OUA-9tffvpsv.js

@@ -1 +0,0 @@
-import{ci}from"./index-tb1wf525.js";export{ci as createArchitectureServices};

package/dist/canvas/chunks/classDiagram-JCYQIIEL-nc6g5x1r.js

@@ -1 +0,0 @@
-import{e}from"./index-1r72hdzb.js";import"./index-6qmsnxwy.js";import"./index-qj8fxwsf.js";import{Sr,Er,_r,Ar}from"./index-w2mra17t.js";import"./index-nprm96xp.js";import"./index-s4j678gj.js";import"./index-3cy1bzwh.js";var k={parser:Sr,get db(){return new Er},renderer:Ar,styles:_r,init:e((r)=>{if(!r.class)r.class={};r.class.arrowMarkerAbsolute=r.arrowMarkerAbsolute},"init")};export{k as diagram};

package/dist/canvas/chunks/classDiagram-v2-OCEON4UE-0qnbpwvh.js

@@ -1 +0,0 @@
-import{e}from"./index-1r72hdzb.js";import"./index-6qmsnxwy.js";import"./index-qj8fxwsf.js";import{Sr,Er,_r,Ar}from"./index-w2mra17t.js";import"./index-nprm96xp.js";import"./index-s4j678gj.js";import"./index-3cy1bzwh.js";var k={parser:Sr,get db(){return new Er},renderer:Ar,styles:_r,init:e((r)=>{if(!r.class)r.class={};r.class.arrowMarkerAbsolute=r.arrowMarkerAbsolute},"init")};export{k as diagram};

package/dist/canvas/chunks/cynefin-VYW2F7L2-ys8p46ts.js

@@ -1 +0,0 @@
-import{ni}from"./index-tb1wf525.js";export{ni as createCynefinServices};

package/dist/canvas/chunks/eventmodeling-45OFAUF4-v9q6dn4c.js

@@ -1 +0,0 @@
-import{ui}from"./index-tb1wf525.js";export{ui as createEventModelingServices};

package/dist/canvas/chunks/flowDiagram-UKHOOZJN-yrr5z8tc.js

@@ -1 +0,0 @@
-import"./index-1r72hdzb.js";import"./index-6qmsnxwy.js";import"./index-qj8fxwsf.js";import{qi}from"./index-yw8h9vha.js";import"./index-nprm96xp.js";import"./index-g3pwnqeb.js";import"./index-s4j678gj.js";import"./index-3cy1bzwh.js";export{qi as diagram};

package/dist/canvas/chunks/gitGraph-TEB2WS4Q-kdwb8m0a.js

@@ -1 +0,0 @@
-import{ii}from"./index-tb1wf525.js";export{ii as createGitGraphServices};