pmx-canvas 0.4.4 → 0.4.6

package/src/server/operations/registry.ts

@@ -105,6 +105,19 @@ function allowedIntentKinds(name: string, rawInput: unknown): readonly PmxAxInte
   return INTENT_KINDS_BY_OPERATION[name];
 }
 
+/**
+ * Ops exempt from auto-ghost SYNTHESIS only (explicit intent linking above is
+ * unaffected). Stream appends arrive in rapid succession — a fresh ghost per
+ * chunk is exactly the high-frequency churn class the batch exemption exists
+ * for; the stream's CREATING call (no nodeId yet) still ghosts once.
+ */
+function autoGhostExempt(name: string, rawInput: unknown): boolean {
+  if (name !== 'jsonrender.stream') return false;
+  const input =
+    rawInput && typeof rawInput === 'object' && !Array.isArray(rawInput) ? (rawInput as Record<string, unknown>) : {};
+  return typeof input.nodeId === 'string' && input.nodeId.length > 0;
+}
+
 function settledNodeId(result: unknown, intent: PmxAxIntent): string | undefined {
   if (intent.kind === 'connect' || intent.kind === 'remove') return undefined;
   if (!result || typeof result !== 'object' || Array.isArray(result)) return undefined;
@@ -118,7 +131,75 @@ function settledNodeId(result: unknown, intent: PmxAxIntent): string | undefined
   return typeof record.id === 'string' ? record.id : undefined;
 }
 
-export async function executeOperation(name: string, rawInput: unknown): Promise<unknown> {
+/** Verb for the synthesized auto-ghost chip, per intent kind. */
+const AUTO_GHOST_VERBS: Record<string, string> = {
+  create: 'Adding',
+  move: 'Moving',
+  edit: 'Updating',
+  connect: 'Connecting',
+  remove: 'Removing',
+};
+
+const AUTO_GHOST_EDGE_TYPES = new Set(['flow', 'depends-on', 'relation', 'references']);
+
+/**
+ * Build a valid signal input for a synthesized ghost, or null when the raw
+ * input can't satisfy the kind's required fields (e.g. a create with server
+ * auto-placement has no position to ghost at) — in that case the mutation
+ * simply runs unghosted.
+ */
+function autoGhostInput(name: string, rawInput: unknown, kind: string): Record<string, unknown> | null {
+  const body =
+    rawInput && typeof rawInput === 'object' && !Array.isArray(rawInput) ? (rawInput as Record<string, unknown>) : {};
+  const subject =
+    typeof body.title === 'string' && body.title.trim()
+      ? body.title.trim().slice(0, 80)
+      : typeof body.type === 'string'
+        ? `${body.type} node`
+        : typeof body.id === 'string'
+          ? body.id
+          : name.split('.')[0];
+  const base = {
+    kind,
+    label: `${AUTO_GHOST_VERBS[kind] ?? 'Changing'} ${subject}`,
+    ...(typeof body.type === 'string' ? { nodeType: body.type } : {}),
+    source: 'auto',
+    auto: true,
+    ttlMs: 6000,
+  };
+  const position = typeof body.x === 'number' && typeof body.y === 'number' ? { x: body.x, y: body.y } : undefined;
+  switch (kind) {
+    case 'create':
+      return position ? { ...base, position } : null;
+    case 'move':
+      return typeof body.id === 'string' && position ? { ...base, nodeId: body.id, position } : null;
+    case 'edit':
+    case 'remove':
+      return typeof body.id === 'string' ? { ...base, nodeId: body.id } : null;
+    case 'connect': {
+      if (typeof body.from !== 'string' || typeof body.to !== 'string') return null;
+      const edgeType = typeof body.type === 'string' && AUTO_GHOST_EDGE_TYPES.has(body.type) ? body.type : 'flow';
+      return { ...base, nodeType: undefined, edge: { from: body.from, to: body.to, type: edgeType } };
+    }
+    default:
+      return null;
+  }
+}
+
+export interface ExecuteOperationMeta {
+  /**
+   * Skip the synthesized auto-ghost: set by the workbench's own HTTP calls
+   * (a human dragging a node is not agent activity) and by canvas.batch for
+   * its inner dispatches (batch churn is exempt, matching the skill contract).
+   */
+  suppressAutoGhost?: boolean;
+}
+
+export async function executeOperation(
+  name: string,
+  rawInput: unknown,
+  meta: ExecuteOperationMeta = {},
+): Promise<unknown> {
   const op = getOperation(name);
   const intentId = linkedIntentId(rawInput);
   const allowedKinds = intentId ? allowedIntentKinds(name, rawInput) : undefined;
@@ -140,6 +221,46 @@ export async function executeOperation(name: string, rawInput: unknown): Promise
     );
   }
 
+  // Auto-ghost: an agent-originated visible mutation with NO explicit intent
+  // still shows its move on the canvas — a server-synthesized ghost that
+  // settles the moment the mutation lands (the client's minimum-dwell keeps
+  // the flash perceptible). Explicit canvas_intent signalling stays the
+  // richer path (labels, reasons, a real veto window before the mutation).
+  const autoKinds = allowedIntentKinds(name, rawInput);
+  if (
+    autoKinds &&
+    !meta.suppressAutoGhost &&
+    !autoGhostExempt(name, rawInput) &&
+    process.env.PMX_CANVAS_AUTO_INTENT !== '0'
+  ) {
+    // Ghost synthesis must NEVER break the mutation: skip silently when the
+    // input can't satisfy a kind's required fields or signalling throws.
+    let ghost: PmxAxIntent | null = null;
+    try {
+      for (const kind of autoKinds) {
+        const input = autoGhostInput(name, rawInput, kind);
+        if (input) {
+          ghost = intentRegistry.signal(input);
+          break;
+        }
+      }
+    } catch {
+      ghost = null;
+    }
+    if (ghost) {
+      const ghostId = ghost.id;
+      try {
+        const result = await op.execute(rawInput, operationContext);
+        if (op.mutates) emitOperationEvent('canvas-layout-update', { layout: canvasState.getLayout() });
+        intentRegistry.clear(ghostId, { settledNodeId: settledNodeId(result, ghost) ?? undefined });
+        return result;
+      } catch (error) {
+        intentRegistry.clear(ghostId);
+        throw error;
+      }
+    }
+  }
+
   const result = await op.execute(rawInput, operationContext);
   if (op.mutates) emitOperationEvent('canvas-layout-update', { layout: canvasState.getLayout() });
   return result;

package/src/server/server.ts

@@ -47,6 +47,7 @@ import {
   buildAxStateBridge,
   buildContentHeightReporter,
   buildHtmlSurfaceDocument,
+  buildMermaidSurfaceHtml,
   HTML_SURFACE_SANDBOX,
   normalizeSurfaceTheme,
 } from './html-surface.js';
@@ -455,7 +456,7 @@ export async function startCanvasAutomationWebView(
   return runCanvasAutomationWebViewTask(async () => {
     const WebView = getCanvasWebViewConstructor();
     if (!WebView) {
-      const message = 'Bun.WebView is not available in this Bun runtime. Bun >=1.3.12 is required.';
+      const message = `Bun.WebView is not available in this Bun runtime (Bun ${Bun.version}). Bun >=1.3.12 is required — the canvas itself keeps working; only WebView automation/screenshots are unavailable.`;
       canvasAutomationWebViewStatus = {
         ...canvasAutomationWebViewStatus,
         lastError: message,
@@ -1004,6 +1005,7 @@ function canvasSpaHtml(): string {
     // (see src/client/state/iframe-mode.ts).
     process.env.AMP_ORB ? '<script>window.__PMX_AMP_ORB = true;</script>' : ''
   }
+  <script>window.__PMX_BOOT_SERVER_VERSION = ${JSON.stringify(serverPackageVersion())};</script>
   <script type="module" src="/canvas/index.js?v=${CANVAS_ASSET_VERSION}"></script>
 </body>
 </html>`;
@@ -1271,6 +1273,28 @@ function handleNodeSurface(pathname: string, url: URL): Response {
 
   const theme = normalizeSurfaceTheme(url.searchParams.get('theme'));
 
+  if (node.type === 'mermaid') {
+    const source = typeof node.data.content === 'string' ? node.data.content : '';
+    if (!source.trim()) return responseText('Mermaid node has no content', 404);
+    const surfaceTitle = typeof node.data.title === 'string' && node.data.title.trim() ? node.data.title : node.id;
+    // Display-only surface: same theme/height plumbing as html nodes, but no AX
+    // bridge and no presentation mode — the document is our own wrapper around
+    // escaped diagram source, rendered by /canvas/mermaid-entry.js.
+    const doc = buildHtmlSurfaceDocument(buildMermaidSurfaceHtml(source), {
+      theme,
+      title: surfaceTitle,
+      themeToken: url.searchParams.get('themeToken') ?? undefined,
+      // Content-height reporter nonce (lets the node grow to fit the diagram).
+      ...(url.searchParams.get('frameToken')
+        ? { contentHeightToken: url.searchParams.get('frameToken') as string }
+        : {}),
+      // Inline the theme tokens so srcdoc-rendered surfaces (Amp orb portals)
+      // are styled without depending on the <link> subresource.
+      ...(surfaceThemeCssInline() ? { inlineThemeCss: surfaceThemeCssInline() as string } : {}),
+    });
+    return surfaceHtmlResponse(doc, HTML_SURFACE_SANDBOX);
+  }
+
   if (node.type === 'html') {
     const html =
       typeof node.data.html === 'string'
@@ -1449,6 +1473,23 @@ function responseJson(data: unknown, status = 200): Response {
   });
 }
 
+// Resolved from the sibling package.json so it stays accurate through bunx,
+// global npm installs, and repo-local runs — same mechanism as --version in
+// src/cli/index.ts and the MCP server. Memoized: /health is polled.
+let cachedPackageVersion: string | null = null;
+function serverPackageVersion(): string {
+  if (cachedPackageVersion !== null) return cachedPackageVersion;
+  try {
+    const pkg = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf-8')) as {
+      version?: string;
+    };
+    cachedPackageVersion = pkg.version ?? 'unknown';
+  } catch {
+    cachedPackageVersion = 'unknown';
+  }
+  return cachedPackageVersion;
+}
+
 // v0.4.0 (M4): every hand-written error response is a JSON envelope
 // ({ ok: false, error }, same status codes) matching the registry dispatcher —
 // consumers no longer need to branch on text/plain vs JSON error bodies.
@@ -1799,6 +1840,9 @@ function buildWorkbenchConnectSnapshot(
       continuity,
       path: primaryWorkbenchPath,
       theme: canvasState.theme,
+      // Lets a long-lived client detect that the server was upgraded under it
+      // (stale in-memory SPA — 0.4.5 report Finding W) and reload once.
+      version: serverPackageVersion(),
       timestamp: new Date().toISOString(),
     },
   });
@@ -2999,7 +3043,15 @@ export function startCanvasServer(options: CanvasServerOptions = {}): string | n
   // M11: PMX_WEB_CANVAS_PORT (server-specific) wins, then PMX_CANVAS_PORT — so
   // setting only the client var no longer splits the client and server ports.
   const preferredPort =
-    options.port ?? Number(process.env.PMX_WEB_CANVAS_PORT ?? process.env.PMX_CANVAS_PORT ?? DEFAULT_PORT);
+    options.port ??
+    Number(
+      process.env.PMX_WEB_CANVAS_PORT ??
+        process.env.PMX_CANVAS_PORT ??
+        // Amp orbs assign the portal port via $PORT (gated on AMP_ORB so a
+        // stray PORT in normal shells never shifts the default).
+        (process.env.AMP_ORB ? process.env.PORT || undefined : undefined) ??
+        DEFAULT_PORT,
+    );
   const portCandidates =
     options.port === 0
       ? [0]
@@ -3030,11 +3082,14 @@ export function startCanvasServer(options: CanvasServerOptions = {}): string | n
             // when the pid file is stale (e.g. an adapter respawned the server
             // outside `serve --daemon` — 0.3.2 report Finding P). `persistence`
             // surfaces silent save failures (M4): the canvas keeps serving from
-            // memory, but ok:false means durability is degraded.
+            // memory, but ok:false means durability is degraded. `version` lets
+            // `pmx-canvas smoke` verify the RUNNING server, not just the CLI —
+            // version skew between the two is a known failure mode.
             return responseJson({
               ok: true,
               workspace: activeWorkspaceRoot,
               pid: process.pid,
+              version: serverPackageVersion(),
               persistence: canvasState.persistenceHealth,
             });
           }

package/src/server/workboard.ts

@@ -0,0 +1,159 @@
+/**
+ * Live AX work-item board, materialized as a json-render node.
+ *
+ * `buildWorkboardSpec` is the pure spec builder (status columns of work-item
+ * cards); `renderWorkboard` is the operation core (create-or-rebuild the
+ * single `data.workboard === true` json-render node); `refreshWorkboardNodes`
+ * is the live-refresh hook this module registers on `canvasState` so every
+ * addWorkItem/updateWorkItem rebuilds the board from the fresh work-item list
+ * through the SAME spec/update path the operation uses.
+ *
+ * The refresh runs inside `withSuppressedRecording` so live board rebuilds do
+ * not spam undo/redo history (persistence and SSE emits are unaffected).
+ */
+import type { JsonRenderSpec } from '../json-render/server.js';
+import type { PmxAxWorkItem, PmxAxWorkItemStatus } from './ax-state.js';
+import { buildJsonRenderNodeUpdate, createCanvasJsonRenderNode, emitCanvasLayoutUpdate } from './canvas-operations.js';
+import { canvasState, type CanvasNodeState } from './canvas-state.js';
+
+export const WORKBOARD_NODE_TITLE = 'Work Board';
+export const WORKBOARD_NODE_SIZE = { width: 960, height: 560 };
+
+const WORKBOARD_STATUS_ORDER: PmxAxWorkItemStatus[] = ['todo', 'in-progress', 'blocked', 'done', 'cancelled'];
+
+const WORKBOARD_STATUS_LABELS: Record<PmxAxWorkItemStatus, string> = {
+  todo: 'To Do',
+  'in-progress': 'In Progress',
+  blocked: 'Blocked',
+  done: 'Done',
+  cancelled: 'Cancelled',
+};
+
+/**
+ * Build the workboard json-render spec from a work-item list: one column per
+ * status (todo → in-progress → blocked → done → cancelled; empty statuses are
+ * omitted), each item a Card with an agentId Badge and detail Text when
+ * present. An empty list renders a single muted "No work items" text block.
+ */
+export function buildWorkboardSpec(workItems: PmxAxWorkItem[]): JsonRenderSpec {
+  if (workItems.length === 0) {
+    return {
+      root: 'empty',
+      elements: {
+        empty: { type: 'Text', props: { text: 'No work items', variant: 'muted' }, children: [] },
+      },
+    };
+  }
+
+  const elements: Record<string, unknown> = {};
+  const columnIds: string[] = [];
+  for (const status of WORKBOARD_STATUS_ORDER) {
+    const items = workItems.filter((item) => item.status === status);
+    if (items.length === 0) continue;
+    const columnId = `col-${status}`;
+    const headerId = `${columnId}-header`;
+    elements[headerId] = {
+      type: 'Heading',
+      props: { level: 'h4', text: `${WORKBOARD_STATUS_LABELS[status]} (${items.length})` },
+      children: [],
+    };
+    const columnChildren = [headerId];
+    for (const item of items) {
+      const cardId = `item-${item.id}`;
+      const cardChildren: string[] = [];
+      if (item.agentId) {
+        elements[`${cardId}-agent`] = {
+          type: 'Badge',
+          props: { text: item.agentId, variant: 'secondary' },
+          children: [],
+        };
+        cardChildren.push(`${cardId}-agent`);
+      }
+      if (item.detail) {
+        elements[`${cardId}-detail`] = {
+          type: 'Text',
+          props: { text: item.detail, variant: 'muted' },
+          children: [],
+        };
+        cardChildren.push(`${cardId}-detail`);
+      }
+      elements[cardId] = { type: 'Card', props: { title: item.title }, children: cardChildren };
+      columnChildren.push(cardId);
+    }
+    elements[columnId] = {
+      type: 'Stack',
+      props: { direction: 'vertical', gap: 'sm' },
+      children: columnChildren,
+    };
+    columnIds.push(columnId);
+  }
+  elements.board = {
+    type: 'Stack',
+    props: { direction: 'horizontal', gap: 'md', align: 'start' },
+    children: columnIds,
+  };
+  return { root: 'board', elements };
+}
+
+function findWorkboardNodes(): CanvasNodeState[] {
+  return canvasState.getLayout().nodes.filter((node) => node.type === 'json-render' && node.data.workboard === true);
+}
+
+/** Rebuild one workboard node's spec in place (shared by the op and the live refresh). */
+function applyWorkboardSpec(node: CanvasNodeState, spec: JsonRenderSpec): void {
+  const title = typeof node.data.title === 'string' && node.data.title ? node.data.title : WORKBOARD_NODE_TITLE;
+  const update = buildJsonRenderNodeUpdate(node, { title, spec });
+  canvasState.updateNode(node.id, { data: update.data });
+}
+
+/**
+ * Operation core for `render.workboard`: rebuild the existing workboard node
+ * in place, or create one (tagged `data.workboard: true`) when none exists.
+ */
+export function renderWorkboard(input: { x?: number; y?: number } = {}): {
+  ok: true;
+  id: string;
+  created: boolean;
+  itemCount: number;
+} {
+  const workItems = canvasState.getWorkItems();
+  const spec = buildWorkboardSpec(workItems);
+  const existing = findWorkboardNodes()[0];
+  if (existing) {
+    applyWorkboardSpec(existing, spec);
+    return { ok: true, id: existing.id, created: false, itemCount: workItems.length };
+  }
+  const created = createCanvasJsonRenderNode({
+    title: WORKBOARD_NODE_TITLE,
+    spec,
+    width: WORKBOARD_NODE_SIZE.width,
+    height: WORKBOARD_NODE_SIZE.height,
+    ...(input.x !== undefined ? { x: input.x } : {}),
+    ...(input.y !== undefined ? { y: input.y } : {}),
+  });
+  // Tag the node as THE workboard. Suppressed: the tag is part of the single
+  // logical "create workboard" mutation, not a second undo step.
+  canvasState.withSuppressedRecording(() => {
+    canvasState.updateNode(created.id, { data: { ...created.node.data, workboard: true } });
+  });
+  return { ok: true, id: created.id, created: true, itemCount: workItems.length };
+}
+
+/**
+ * Live refresh: rebuild every workboard node's spec from the current work-item
+ * list. Registered below as the canvasState work-item change listener. Node
+ * updates never touch work items, so this cannot recurse.
+ */
+export function refreshWorkboardNodes(): void {
+  const nodes = findWorkboardNodes();
+  if (nodes.length === 0) return;
+  const spec = buildWorkboardSpec(canvasState.getWorkItems());
+  canvasState.withSuppressedRecording(() => {
+    for (const node of nodes) {
+      applyWorkboardSpec(node, spec);
+    }
+  });
+  emitCanvasLayoutUpdate();
+}
+
+canvasState.setWorkItemsChangedListener(refreshWorkboardNodes);

package/src/shared/ax-intent.ts

@@ -44,6 +44,12 @@ export interface PmxAxIntent {
   seq?: number;
   /** Source label of the surface that signalled the intent (mcp/api/sdk/...). */
   source?: string;
+  /**
+   * Server-synthesized ghost for an agent mutation that arrived WITHOUT an
+   * explicit canvas_intent signal (auto-ghost). Rendered visually lighter than
+   * a deliberate signal, and not vetoable — it settles immediately.
+   */
+  auto?: boolean;
   /** Epoch ms when the intent was first signalled. */
   createdAt: number;
   /** Epoch ms when the intent auto-dissolves if not settled/cleared first. */

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

@@ -20,3 +20,11 @@ export const HTML_SURFACE_PUSH_SOURCE = 'pmx-canvas-html-node';
 
 /** Ext-app boot beacon: the iframe's scripts executed (WebKit watchdog liveness). */
 export const EXT_APP_BOOT_BEACON_SOURCE = 'pmx-canvas-ext-app-alive';
+
+/**
+ * Parent→ext-app paint probe (Finding N): the parent asks the app document to
+ * answer with a double-rAF `paint-tick` beacon. A frame whose rendering
+ * pipeline is live answers within a frame or two; silence past the timeout is
+ * the paint-fail signal that drives the recovery ladder.
+ */
+export const EXT_APP_PAINT_PROBE_SOURCE = 'pmx-canvas-ext-app-paint-probe';

package/src/shared/surface.ts

@@ -17,6 +17,8 @@ export function canOpenNodeAsSurface(type: string, data: Record<string, unknown>
         (typeof data.html === 'string' && data.html.length > 0) ||
         (typeof data.content === 'string' && data.content.length > 0)
       );
+    case 'mermaid':
+      return typeof data.content === 'string' && data.content.trim().length > 0;
     case 'json-render':
     case 'graph':
       return true;

package/src/shared/themes.ts

@@ -51,7 +51,7 @@ export const CANVAS_THEME_META: Record<CanvasThemeName, CanvasThemeMeta> = {
   arctic: { label: 'Arctic', scheme: 'dark', swatchBg: '#20242E', swatchAccent: '#7FC8DE' },
   ember: { label: 'Ember', scheme: 'dark', swatchBg: '#0B0B0C', swatchAccent: '#F34E1C' },
   forest: { label: 'Forest', scheme: 'dark', swatchBg: '#0C1712', swatchAccent: '#5CCF8F' },
-  volt: { label: 'Volt', scheme: 'dark', swatchBg: '#0B0D0B', swatchAccent: '#F34E3F' },
+  volt: { label: 'Volt', scheme: 'dark', swatchBg: '#0B0D0B', swatchAccent: '#DFDFC1' },
 };
 
 /** Collapse a theme to the dark/light scheme embedded dark|light-only viewers understand. */