pmx-canvas 0.4.5 → 0.4.7

package/src/server/web-artifacts.ts

@@ -27,6 +27,19 @@ const LEGACY_SKILL_WEB_ARTIFACT_SCRIPTS_DIR = join(
 );
 const DEFAULT_TIMEOUT_MS = 10 * 60_000;
 const DEFAULT_PACKAGE_MANAGER = 'pnpm@10.33.0';
+const NODE_VERSION_PROBE_TIMEOUT_MS = 15_000;
+/**
+ * Minimum Node.js (`major.minor`) each pnpm major declares in its published
+ * `engines.node` — pnpm 10.x is `>=18.12`, pnpm 11.x is `>=22.13`. The pnpm that
+ * runs a build is not a local dependency (the scripts take it from PATH, `bun x`,
+ * or a global install), so its engines field cannot be read from disk; this table
+ * carries the same constraint keyed by the pinned major. An unlisted major
+ * imposes no preflight floor rather than an invented one.
+ */
+const PNPM_MAJOR_MIN_NODE: Record<string, string> = {
+  '10': '18.12',
+  '11': '22.13',
+};
 const DEFAULT_WEB_ARTIFACT_NODE_SIZE = { width: 960, height: 720 };
 const FALLBACK_PATH_DIRS = ['/opt/homebrew/bin', '/usr/local/bin', '/usr/bin', '/bin'];
 const WEB_ARTIFACT_CONTEXT_MAX_LENGTH = 1200;
@@ -470,6 +483,101 @@ function summarizeArtifactLog(text: string): WebArtifactLogSummary | undefined {
   };
 }
 
+export type NodeVersionCheck = { ok: true } | { ok: false; message: string };
+
+function parseMajorMinor(value: string): { major: number; minor: number } | null {
+  const match = /^v?(\d+)\.(\d+)/.exec(value.trim());
+  if (!match) return null;
+  return { major: Number(match[1]), minor: Number(match[2]) };
+}
+
+/**
+ * Pure preflight comparison used before any package-manager invocation.
+ * `detected` is raw `node --version` output ("v20.11.1"), or null when no node
+ * executable answered; `required` is a `major.minor` floor; `packageManager` is
+ * the pin that imposes it (e.g. "pnpm@11.1.2"). Returns an actionable message
+ * instead of throwing so every caller surfaces it on its own error channel.
+ */
+export function checkWebArtifactNodeVersion(
+  detected: string | null,
+  required: string,
+  packageManager: string,
+): NodeVersionCheck {
+  const requiredParts = parseMajorMinor(required);
+  if (!requiredParts) return { ok: true };
+
+  const detectedLabel = detected === null ? null : detected.trim();
+  const detectedParts = detectedLabel === null ? null : parseMajorMinor(detectedLabel);
+  if (
+    detectedParts &&
+    (detectedParts.major > requiredParts.major ||
+      (detectedParts.major === requiredParts.major && detectedParts.minor >= requiredParts.minor))
+  ) {
+    return { ok: true };
+  }
+
+  const found =
+    detectedLabel && detectedParts
+      ? `the build environment has Node.js ${detectedLabel}`
+      : 'no usable `node` executable was found on the build PATH';
+  return {
+    ok: false,
+    message:
+      `Web-artifact build preflight failed: ${packageManager} requires Node.js >= ${required}, but ${found}. ` +
+      `Run PMX Canvas under Node.js ${required} or newer, then retry the build.`,
+  };
+}
+
+/** `node --version` as the build subprocesses see it, or null when node is unavailable. */
+async function detectSubprocessNodeVersion(cwd: string): Promise<string | null> {
+  try {
+    const { stdout } = await runProcess('node', ['--version'], { cwd, timeoutMs: NODE_VERSION_PROBE_TIMEOUT_MS });
+    return stdout.trim() || null;
+  } catch {
+    // A missing or non-runnable node IS the preflight failure — reported below
+    // with the required version, not rethrown as a spawn error here.
+    return null;
+  }
+}
+
+/**
+ * The `packageManager` pin that governs this build: a reused artifact project
+ * carries its own pin, a fresh one gets the bundled default that init-artifact.sh
+ * and ensurePackageManagerBoundary write.
+ */
+function resolvePinnedPackageManager(projectPath: string): string {
+  const packageJsonPath = join(projectPath, 'package.json');
+  if (!existsSync(packageJsonPath)) return DEFAULT_PACKAGE_MANAGER;
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+      const pinned = (parsed as Record<string, unknown>).packageManager;
+      if (typeof pinned === 'string' && pinned.includes('@')) return pinned;
+    }
+  } catch {
+    // A corrupt project package.json is the init script's problem; the preflight
+    // falls back to the pin PMX Canvas would write anyway.
+  }
+  return DEFAULT_PACKAGE_MANAGER;
+}
+
+/**
+ * Fail fast when the Node.js available to the build subprocesses is older than
+ * the pinned package manager supports. Without this, pnpm's engine error lands
+ * deep inside the init/bundle script output and reads as an unrelated build
+ * failure (reported: pnpm 11 needs Node 22.13+, the build ran on Node 20).
+ */
+async function preflightBuildRuntime(cwd: string, projectPath: string): Promise<void> {
+  const packageManager = resolvePinnedPackageManager(projectPath);
+  const [name, version] = packageManager.split('@');
+  if (name !== 'pnpm') return;
+  const required = PNPM_MAJOR_MIN_NODE[version.split('.')[0]];
+  if (!required) return;
+
+  const check = checkWebArtifactNodeVersion(await detectSubprocessNodeVersion(cwd), required, packageManager);
+  if (!check.ok) throw new Error(check.message);
+}
+
 export async function executeWebArtifactBuild(input: WebArtifactBuildInput): Promise<WebArtifactBuildOutput> {
   const workspaceRoot = currentWorkspaceRoot();
   const artifactsDir = ensureArtifactsDir(workspaceRoot);
@@ -490,6 +598,7 @@ export async function executeWebArtifactBuild(input: WebArtifactBuildInput): Pro
   const parentDir = dirname(projectPath);
   mkdirSync(parentDir, { recursive: true });
   ensurePackageManagerBoundary(parentDir);
+  await preflightBuildRuntime(parentDir, projectPath);
 
   let stdout = '';
   let stderr = '';

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-flow.ts

@@ -0,0 +1,102 @@
+/**
+ * The node-data contract for a materialized AX flow.
+ *
+ * `ax.flow.materialize` stamps every step node with `data.axStep` and the anchor
+ * (first) step with `data.axFlow`. Three consumers read those stamps and none of
+ * them owns the shape, so it lives here:
+ *   - the server loop (`ax-flow-loop.ts`) advances the flow from work-item changes
+ *   - the browser renders native Start/Done/Blocked + Run loop/Stop controls
+ *   - snapshots/restore carry the stamps as ordinary node data
+ *
+ * Node data is `Record<string, unknown>` on both sides, so the readers below are
+ * the ONLY way to narrow it: they validate rather than cast, because a stamp can
+ * also arrive from a restored snapshot or a hand-edited node.
+ */
+
+/** Hard ceiling on loop passes, whatever a node's stamped `maxRuns` claims. */
+export const AX_FLOW_LOOP_HARD_CAP = 20;
+
+/** One step of a flow, as recorded on the anchor node. */
+export interface AxFlowStepRef {
+  /** 1-based position in the flow. */
+  index: number;
+  nodeId: string;
+  workItemId: string;
+  title: string;
+}
+
+export interface AxFlowLoopState {
+  /** The loop only advances while this is true; Stop persists `false`. */
+  running: boolean;
+  /** Completed passes. `run >= maxRuns` ends the loop. */
+  run: number;
+  maxRuns: number;
+}
+
+/** `data.axStep` — stamped on EVERY step node, including the anchor. */
+export interface AxFlowStepStamp {
+  flowId: string;
+  index: number;
+  total: number;
+  workItemId: string;
+}
+
+/** `data.axFlow` — stamped on the anchor (first) step node only. */
+export interface AxFlowStamp {
+  flowId: string;
+  title: string;
+  steps: AxFlowStepRef[];
+  loop: AxFlowLoopState;
+}
+
+/** Clamp a stamped `maxRuns` into [1, AX_FLOW_LOOP_HARD_CAP]. */
+export function clampAxFlowMaxRuns(value: unknown): number {
+  const n = typeof value === 'number' && Number.isFinite(value) ? Math.floor(value) : 1;
+  return Math.max(1, Math.min(AX_FLOW_LOOP_HARD_CAP, n));
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function nonEmptyString(value: unknown): value is string {
+  return typeof value === 'string' && value.length > 0;
+}
+
+/** Read `data.axStep`, or null when the node carries no valid step stamp. */
+export function readAxStep(data: Record<string, unknown>): AxFlowStepStamp | null {
+  const step = data.axStep;
+  if (!isRecord(step)) return null;
+  if (!nonEmptyString(step.flowId) || !nonEmptyString(step.workItemId)) return null;
+  if (typeof step.index !== 'number' || typeof step.total !== 'number') return null;
+  return { flowId: step.flowId, index: step.index, total: step.total, workItemId: step.workItemId };
+}
+
+/** Read `data.axFlow`, or null when the node is not a flow anchor. */
+export function readAxFlow(data: Record<string, unknown>): AxFlowStamp | null {
+  const flow = data.axFlow;
+  if (!isRecord(flow) || !nonEmptyString(flow.flowId) || !Array.isArray(flow.steps)) return null;
+  const steps: AxFlowStepRef[] = [];
+  for (const raw of flow.steps) {
+    if (!isRecord(raw) || !nonEmptyString(raw.nodeId) || !nonEmptyString(raw.workItemId)) return null;
+    if (typeof raw.index !== 'number') return null;
+    steps.push({
+      index: raw.index,
+      nodeId: raw.nodeId,
+      workItemId: raw.workItemId,
+      title: typeof raw.title === 'string' ? raw.title : '',
+    });
+  }
+  if (steps.length === 0) return null;
+  const loop = isRecord(flow.loop) ? flow.loop : {};
+  return {
+    flowId: flow.flowId,
+    title: typeof flow.title === 'string' ? flow.title : 'Flow',
+    steps,
+    loop: {
+      running: loop.running === true,
+      run: typeof loop.run === 'number' && Number.isFinite(loop.run) ? Math.max(0, Math.floor(loop.run)) : 0,
+      maxRuns: clampAxFlowMaxRuns(loop.maxRuns),
+    },
+  };
+}

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/node-sizes.ts

@@ -0,0 +1,52 @@
+/**
+ * Per-type minimum node size — the readability floor.
+ *
+ * Agents frequently create nodes with explicit frames far too small for their
+ * content (clipped markdown, charts squeezed behind inner scrollbars), so the
+ * server clamps undersized explicit sizes UP at creation and `validate` reports
+ * anything below the floor.
+ *
+ * This lives in `shared/` because BOTH sides must honor it. The 0.4.6 report's
+ * Finding AA: the server clamped a 200x100 markdown node up to 360x180, and
+ * then the browser's DOM auto-fit measured the (short) content and persisted
+ * 360x132 — undoing the guarantee on the most common path, a connected
+ * workbench. A floor only one side knows about is not a floor.
+ *
+ * `strictSize: true` is the escape hatch for a deliberately small fixed frame,
+ * and it exempts a node from both the creation clamp and the auto-fit floor.
+ * Types absent from the table are intentionally unclamped — `trace` is small by
+ * design, `group` sizes to its children.
+ */
+export const NODE_MIN_SIZES: Record<string, { width: number; height: number }> = {
+  markdown: { width: 360, height: 180 },
+  context: { width: 360, height: 180 },
+  file: { width: 360, height: 200 },
+  diff: { width: 420, height: 240 },
+  mermaid: { width: 360, height: 240 },
+  status: { width: 280, height: 120 },
+  ledger: { width: 320, height: 200 },
+  image: { width: 240, height: 180 },
+  html: { width: 420, height: 280 },
+  webpage: { width: 420, height: 280 },
+  'json-render': { width: 420, height: 280 },
+  graph: { width: 420, height: 280 },
+  'mcp-app': { width: 480, height: 320 },
+};
+
+/** The readability floor for a node type, or undefined when it has none. */
+export function nodeMinSize(type: string): { width: number; height: number } | undefined {
+  return NODE_MIN_SIZES[type];
+}
+
+/** Creation-time clamp: an explicit size below the floor is raised to it. */
+export function clampCreateNodeSize(
+  type: string,
+  width: number,
+  height: number,
+  strictSize?: boolean,
+): { width: number; height: number } {
+  if (strictSize === true) return { width, height };
+  const min = nodeMinSize(type);
+  if (!min) return { width, height };
+  return { width: Math.max(width, min.width), height: Math.max(height, min.height) };
+}

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/dist/types/server/chart-template.d.ts

@@ -1,29 +0,0 @@
-/**
- * Chart HTML template generator — produces self-contained ext-app HTML
- * documents that render interactive Chart.js charts inside the canvas
- * ExtAppFrame iframe.
- *
- * The generated HTML:
- * 1. Renders immediately from inline data (no bridge needed)
- * 2. Connects to host AppBridge via the embedded ext-app App SDK runtime
- * 3. Accepts updated data via toolInput for re-rendering
- */
-export interface ChartDataset {
-    label: string;
-    values: number[];
-    color?: string;
-}
-export interface ChartConfig {
-    title: string;
-    chartType: 'bar' | 'line' | 'pie' | 'scatter' | 'doughnut' | 'radar';
-    labels: string[];
-    datasets: ChartDataset[];
-    xAxisLabel?: string;
-    yAxisLabel?: string;
-    stacked?: boolean;
-}
-/**
- * Generate a self-contained HTML document that renders a Chart.js chart
- * and optionally connects to the host via the ext-app App SDK.
- */
-export declare function generateChartHtml(config: ChartConfig): string;