pmx-canvas 0.4.5 → 0.4.7

package/src/server/ax-interaction.ts

@@ -16,7 +16,9 @@
  */
 
 import { z } from 'zod';
-import type { CanvasNodeState } from './canvas-state.js';
+import { clampAxFlowMaxRuns, type AxFlowStamp, type AxFlowStepStamp } from '../shared/ax-flow.js';
+import { findOpenCanvasPosition, overlapsAny, type CanvasPlacementRect } from '../shared/placement.js';
+import type { CanvasEdge, CanvasLayout, CanvasNodeState } from './canvas-state.js';
 import type { CanvasNodeType } from './canvas-provenance.js';
 import type {
   PmxAxApprovalGate,
@@ -54,6 +56,7 @@ export const AX_INTERACTION_TYPES = [
   'ax.command.invoke',
   'ax.elicitation.request',
   'ax.mode.request',
+  'ax.flow.materialize',
 ] as const;
 
 export type AxInteractionType = (typeof AX_INTERACTION_TYPES)[number];
@@ -86,9 +89,21 @@ function caps(
  * a node can anchor AX state but only eligible types may EMIT interactions.
  */
 export const DEFAULT_NODE_AX_CAPABILITIES: Record<CanvasNodeType, NodeAxCapabilities> = {
+  // `ax.work.update` is what the native step controls (Start/Done/Blocked) on a
+  // materialized flow step emit, and every step node is a `markdown` node. Two
+  // reasons this is not an escalation: it is no broader in kind than the
+  // `ax.work.create` / `ax.steer` this type already grants (creating work and
+  // steering the agent are strictly more powerful than flipping a status), and a
+  // markdown node has no sandboxed emit bridge — `window.PMX_AX` is injected only
+  // into `html` / `mcp-app` surfaces, so the only emitters here are the trusted
+  // native controls in the canvas app and direct local API calls, which can
+  // already PATCH a work item with no node capability at all.
+  // NB: markdown IS rendered as HTML into the parent document (see the trust
+  // boundary note in MarkdownNode.tsx — localhost, user-owned content), so the
+  // justification is "no sandboxed emitter", NOT "no scriptable surface".
   markdown: caps(
     true,
-    ['ax.steer', 'ax.work.create', 'ax.evidence.add', 'ax.command.invoke', 'ax.event.record'],
+    ['ax.steer', 'ax.work.create', 'ax.work.update', 'ax.evidence.add', 'ax.command.invoke', 'ax.event.record'],
     'notify-agent',
   ),
   context: caps(
@@ -102,6 +117,12 @@ export const DEFAULT_NODE_AX_CAPABILITIES: Record<CanvasNodeType, NodeAxCapabili
     'notify-agent',
   ),
   file: caps(true, ['ax.evidence.add', 'ax.review.add', 'ax.focus.set', 'ax.event.record']),
+  diff: caps(true, ['ax.evidence.add', 'ax.review.add', 'ax.focus.set', 'ax.event.record']),
+  mermaid: caps(
+    true,
+    ['ax.steer', 'ax.work.create', 'ax.evidence.add', 'ax.command.invoke', 'ax.event.record'],
+    'notify-agent',
+  ),
   'json-render': caps(true, [
     'ax.work.create',
     'ax.work.update',
@@ -131,6 +152,11 @@ export const DEFAULT_NODE_AX_CAPABILITIES: Record<CanvasNodeType, NodeAxCapabili
       'ax.mode.request',
       'ax.command.invoke',
       'ax.event.record',
+      // Only `html` gets the flow materializer: a panel is the one surface that
+      // authors a flow the human then wants ON the board. The output shape is
+      // server-owned (fixed markdown/flow/references geometry), so this grants no
+      // arbitrary node creation — see materializeFlow.
+      'ax.flow.materialize',
     ],
     'notify-agent',
   ),
@@ -240,6 +266,23 @@ export interface AxInteractionInput {
   metadata?: Record<string, unknown>;
 }
 
+// ── ax.flow.materialize bounds + fixed layout ──────────────────
+/** Hard cap on materialized steps: one screen-band of nodes, not a node bomb. */
+const FLOW_MAX_STEPS = 12;
+const FLOW_TITLE_MAX = 120;
+const FLOW_DETAIL_MAX = 2000;
+const FLOW_MAX_LOOP_RUNS = 20;
+/**
+ * Step node geometry. 360 is markdown's minimum create size, but it is too
+ * narrow for a step's NAME: the title bar also carries the type icon, the work
+ * status pill and the control cluster, so a title like "3. Regenerate + verify"
+ * ellipsised away at 100% zoom. Wide enough that the step reads at a glance.
+ */
+const FLOW_STEP_WIDTH = 460;
+const FLOW_STEP_HEIGHT = 200;
+const FLOW_STEP_GAP = 48;
+const FLOW_STEP_COLUMNS = 4;
+
 const PAYLOAD_SCHEMAS: Record<string, z.ZodType> = {
   'ax.event.record': z.object({
     kind: z.enum(EVENT_KINDS),
@@ -305,6 +348,27 @@ const PAYLOAD_SCHEMAS: Record<string, z.ZodType> = {
     name: z.string().min(1),
     args: z.record(z.string(), z.unknown()).optional(),
   }),
+  // TEXT ONLY. The caller never supplies a node type, geometry, or node data —
+  // the server owns the materialized shape (see materializeFlow), which is what
+  // keeps this from being "a sandboxed panel can create arbitrary canvas nodes".
+  'ax.flow.materialize': z.object({
+    title: z.string().trim().max(FLOW_TITLE_MAX).optional(),
+    steps: z
+      .array(
+        z.object({
+          title: z.string().trim().min(1).max(FLOW_TITLE_MAX),
+          detail: z.string().trim().max(FLOW_DETAIL_MAX).optional(),
+        }),
+      )
+      .min(1)
+      .max(FLOW_MAX_STEPS),
+    loop: z
+      .object({
+        enabled: z.boolean().optional(),
+        maxRuns: z.number().int().min(1).max(FLOW_MAX_LOOP_RUNS).optional(),
+      })
+      .optional(),
+  }),
 };
 
 // ── Dispatch ───────────────────────────────────────────────────
@@ -315,6 +379,13 @@ const PAYLOAD_SCHEMAS: Record<string, z.ZodType> = {
  */
 export interface AxInteractionManager {
   getNode(id: string): CanvasNodeState | undefined;
+  /** Canvas read for `ax.flow.materialize` (placement obstacles + stale flow sweep). */
+  getLayout(): CanvasLayout;
+  addNode(node: CanvasNodeState): void;
+  updateNode(id: string, patch: Partial<CanvasNodeState>): void;
+  /** Also drops the node's edges — the flow's replace path relies on that. */
+  removeNode(id: string): void;
+  addEdge(edge: CanvasEdge): boolean;
   recordAxEvent(
     input: {
       kind: PmxAxEventKind;
@@ -422,6 +493,227 @@ function accept(
   };
 }
 
+/**
+ * Add a layout broadcast to a work-item result when the item is linked to nodes.
+ *
+ * A linked work item mirrors its status onto `data.axWorkStatus` of every node it
+ * names, so a work interaction IS a node-data change even though the op itself is
+ * layout-neutral. Without this the browser keeps rendering a stale status chip
+ * (the AX SSE frames carry AX state, not nodes) — the same reason materializeFlow
+ * emits one.
+ */
+function withLayoutBroadcast(
+  result: AxInteractionResult,
+  manager: AxInteractionManager,
+  workItems: PmxAxWorkItem[],
+): AxInteractionResult {
+  if (!workItems.some((item) => item.nodeIds.length > 0)) return result;
+  result.events.push({ event: 'canvas-layout-update', payload: { layout: manager.getLayout() } });
+  return result;
+}
+
+// ── ax.flow.materialize ────────────────────────────────────────
+
+export interface AxFlowMaterializeInput {
+  title?: string;
+  steps: Array<{ title: string; detail?: string }>;
+  loop?: { enabled?: boolean; maxRuns?: number };
+}
+
+/** Shared tag on every node this source materialized — the unit of idempotent replace. */
+function axFlowId(sourceNodeId: string): string {
+  return `axflow-${sourceNodeId}`;
+}
+
+/**
+ * Ids the source node recorded the last time it materialized. This manifest — not
+ * the `axFlowId` tag alone — is what the replace sweep deletes from: `axFlowId` is
+ * ordinary node data, so any actor could stamp a plausible-looking one onto an
+ * unrelated node and get it swept. A node is only removed when the source node
+ * says it created it AND the node still carries the matching tag.
+ */
+function axFlowManifest(source: CanvasNodeState): string[] {
+  const ids = source.data.axFlowNodeIds;
+  return Array.isArray(ids) ? ids.filter((id): id is string => typeof id === 'string') : [];
+}
+
+/**
+ * A clear band for the flow: directly under the source panel when that space is
+ * free, otherwise the canvas's normal open-position search. The band is placed
+ * as ONE rect, so the steps inside it are collision-free by construction.
+ */
+function flowBandOrigin(
+  source: CanvasNodeState | undefined,
+  obstacles: CanvasPlacementRect[],
+  width: number,
+  height: number,
+): { x: number; y: number } {
+  if (source) {
+    const below = { x: source.position.x, y: source.position.y + source.size.height + FLOW_STEP_GAP };
+    if (!overlapsAny(below, width, height, obstacles, FLOW_STEP_GAP)) return below;
+  }
+  return findOpenCanvasPosition(obstacles, width, height, FLOW_STEP_GAP);
+}
+
+/**
+ * Lay a validated, text-only flow out as real canvas nodes and edges.
+ *
+ * The SERVER owns the entire output shape — one `markdown` node per step, `flow`
+ * edges in order, a dashed `references` loop-back edge when looping, and one AX
+ * work item per step linked to its node so the existing work-item→node status
+ * mirror lights the `axWorkStatus` chip. The caller supplies text only, which is
+ * why this can be granted to a sandboxed panel at all.
+ *
+ * Idempotent: the source node records the ids it created in `data.axFlowNodeIds`
+ * and a re-materialize removes exactly those first (removeNode takes their edges
+ * with them) instead of stacking a second copy. Work items from a previous
+ * materialize survive with their dangling node ref stripped — they are the durable
+ * AX record, exactly as for any other node deletion.
+ */
+function materializeFlow(
+  manager: AxInteractionManager,
+  sourceNode: CanvasNodeState,
+  input: AxFlowMaterializeInput,
+  source: PmxAxSource,
+): AxInteractionResult {
+  const sourceNodeId = sourceNode.id;
+  const flowId = axFlowId(sourceNodeId);
+  const title = input.title?.trim() || 'Flow';
+  const loopEnabled = input.loop?.enabled === true;
+  const maxRuns = input.loop?.maxRuns ?? 3;
+
+  // Replace, never duplicate — and only what this panel actually created: the id
+  // must be on the source's manifest AND still carry the matching tag. The source
+  // itself is excluded so a self-tagged panel cannot delete itself.
+  const owned = new Set(axFlowManifest(sourceNode));
+  const stale = manager
+    .getLayout()
+    .nodes.filter((node) => node.id !== sourceNodeId && owned.has(node.id) && node.data.axFlowId === flowId);
+  for (const node of stale) manager.removeNode(node.id);
+
+  const layout = manager.getLayout();
+  const obstacles: CanvasPlacementRect[] = layout.nodes.map((node) => ({ position: node.position, size: node.size }));
+  const columns = Math.min(input.steps.length, FLOW_STEP_COLUMNS);
+  const rows = Math.ceil(input.steps.length / FLOW_STEP_COLUMNS);
+  const origin = flowBandOrigin(
+    layout.nodes.find((node) => node.id === sourceNodeId),
+    obstacles,
+    columns * FLOW_STEP_WIDTH + (columns - 1) * FLOW_STEP_GAP,
+    rows * FLOW_STEP_HEIGHT + (rows - 1) * FLOW_STEP_GAP,
+  );
+
+  const total = input.steps.length;
+  // Last-written data of the anchor step, so its `axFlow` stamp below never has
+  // to assume the manager can read a node back.
+  let anchorData: Record<string, unknown> = {};
+  const steps = input.steps.map((step, index) => {
+    const nodeId = `${flowId}-step-${index + 1}`;
+    const nodeData: Record<string, unknown> = {
+      title: `${index + 1}. ${step.title}`,
+      content: step.detail ?? `Step ${index + 1} of ${total} in "${title}".`,
+      axFlowId: flowId,
+      axFlowStep: index + 1,
+      axFlowSourceNodeId: sourceNodeId,
+    };
+    manager.addNode({
+      id: nodeId,
+      type: 'markdown',
+      position: {
+        x: origin.x + (index % FLOW_STEP_COLUMNS) * (FLOW_STEP_WIDTH + FLOW_STEP_GAP),
+        y: origin.y + Math.floor(index / FLOW_STEP_COLUMNS) * (FLOW_STEP_HEIGHT + FLOW_STEP_GAP),
+      },
+      size: { width: FLOW_STEP_WIDTH, height: FLOW_STEP_HEIGHT },
+      zIndex: 1,
+      collapsed: false,
+      pinned: false,
+      dockPosition: null,
+      data: nodeData,
+    });
+    const workItem = manager.addWorkItem(
+      {
+        title: `${title} — ${index + 1}. ${step.title}`,
+        status: 'todo',
+        detail: step.detail ?? null,
+        nodeIds: [nodeId],
+      },
+      { source },
+    );
+    // `data.axStep` is the contract the native step controls read (see
+    // shared/ax-flow.ts). It can only be stamped once the work item exists, and
+    // the node is re-read first because addWorkItem's status mirror has already
+    // written `axWorkStatus` onto it.
+    const axStep: AxFlowStepStamp = { flowId, index: index + 1, total, workItemId: workItem.id };
+    const stamped = { ...(manager.getNode(nodeId)?.data ?? nodeData), axStep };
+    manager.updateNode(nodeId, { data: stamped });
+    if (index === 0) anchorData = stamped;
+    return { index: index + 1, title: step.title, nodeId, workItemId: workItem.id };
+  });
+
+  const edgeIds: string[] = [];
+  for (let i = 0; i < steps.length - 1; i++) {
+    const edge: CanvasEdge = {
+      id: `${flowId}-edge-${i + 1}`,
+      from: steps[i].nodeId,
+      to: steps[i + 1].nodeId,
+      type: 'flow',
+      style: 'solid',
+    };
+    if (manager.addEdge(edge)) edgeIds.push(edge.id);
+  }
+  if (loopEnabled && steps.length > 1) {
+    const loopEdge: CanvasEdge = {
+      id: `${flowId}-loop`,
+      from: steps[steps.length - 1].nodeId,
+      to: steps[0].nodeId,
+      type: 'references',
+      label: 'loop',
+      style: 'dashed',
+      animated: true,
+    };
+    if (manager.addEdge(loopEdge)) edgeIds.push(loopEdge.id);
+  }
+
+  // `data.axFlow` on the anchor (first) step: the whole flow plus its loop state,
+  // so the anchor's native controls can run/stop the loop and the server loop
+  // (ax-flow-loop.ts) can advance it. Always stamped, at rest (`running: false`,
+  // no completed passes) — a loop only ever starts from an explicit human click.
+  const anchorId = steps[0].nodeId;
+  const axFlow: AxFlowStamp = {
+    flowId,
+    title,
+    steps: steps.map((step) => ({
+      index: step.index,
+      nodeId: step.nodeId,
+      workItemId: step.workItemId,
+      title: step.title,
+    })),
+    loop: { running: false, run: 0, maxRuns: clampAxFlowMaxRuns(maxRuns) },
+  };
+  manager.updateNode(anchorId, { data: { ...(manager.getNode(anchorId)?.data ?? anchorData), axFlow } });
+
+  // The manifest the NEXT materialize sweeps from.
+  manager.updateNode(sourceNodeId, {
+    data: { ...sourceNode.data, axFlowNodeIds: steps.map((step) => step.nodeId) },
+  });
+
+  const primitive = {
+    flowId,
+    title,
+    loop: { enabled: loopEnabled, maxRuns },
+    replacedNodeCount: stale.length,
+    steps,
+    edgeIds,
+  };
+  return {
+    result: { ok: true, type: 'ax.flow.materialize', sourceNodeId, primitive },
+    events: [
+      outcomeEvent({ ok: true, type: 'ax.flow.materialize', sourceNodeId }),
+      { event: 'canvas-layout-update', payload: { layout: manager.getLayout() } },
+      { event: 'ax-state-changed', payload: { flow: primitive } },
+    ],
+  };
+}
+
 /**
  * Validate + execute a node-originated AX interaction. Returns the public result
  * plus the SSE events the caller should emit (accepted/rejected outcome + the
@@ -542,7 +834,9 @@ export function applyAxInteraction(
         },
         opts,
       );
-      return accept(type, sourceNodeId, workItem, 'ax-state-changed', { workItem });
+      return withLayoutBroadcast(accept(type, sourceNodeId, workItem, 'ax-state-changed', { workItem }), manager, [
+        workItem,
+      ]);
     }
     case 'ax.work.update': {
       const p = payloadParsed.data as {
@@ -556,7 +850,9 @@ export function applyAxInteraction(
       if (scoped && patch.nodeIds !== undefined) patch.nodeIds = [sourceNodeId];
       const workItem = manager.updateWorkItem(id, patch, opts);
       if (!workItem) return reject(type, sourceNodeId, 404, 'work-item-not-found', `Work item "${id}" not found.`);
-      return accept(type, sourceNodeId, workItem, 'ax-state-changed', { workItem });
+      return withLayoutBroadcast(accept(type, sourceNodeId, workItem, 'ax-state-changed', { workItem }), manager, [
+        workItem,
+      ]);
     }
     case 'ax.evidence.add': {
       const p = payloadParsed.data as {
@@ -679,6 +975,11 @@ export function applyAxInteraction(
       if (!event) return reject(type, sourceNodeId, 400, 'unknown-command', `Unknown command "${p.name}".`);
       return accept(type, sourceNodeId, event, 'ax-event-created', { event });
     }
+    case 'ax.flow.materialize':
+      // No `nodeIds` in this payload, so `scopedNodeIds` never applies: the step
+      // nodes are created BY the server and their work-item links are server-owned
+      // ids, not caller-supplied ones. Sandboxed callers pass through unchanged.
+      return materializeFlow(manager, node, payloadParsed.data as AxFlowMaterializeInput, source);
     default:
       return reject(type, sourceNodeId, 501, 'not-executable', `"${type}" is recognized but not yet executable.`);
   }

package/src/server/canvas-operations.ts

@@ -8,6 +8,7 @@ import {
   type CanvasNodeUpdate,
   type CanvasSnapshot,
 } from './canvas-state.js';
+import { applyFileContentToNodeData, readFileNodeContent } from './file-content.js';
 import { rewatchAllFileNodes, unwatchAll, unwatchFileForNode, watchFileForNode } from './file-watcher.js';
 import {
   closeMcpAppSession,
@@ -17,6 +18,7 @@ import {
   type ExternalMcpTransportConfig,
 } from './mcp-app-runtime.js';
 import { mutationHistory } from './mutation-history.js';
+import { clampCreateNodeSize } from './canvas-validation.js';
 import { computeGroupBounds, findOpenCanvasPosition } from './placement.js';
 import { searchNodes } from './spatial-analysis.js';
 import { getCanvasNodeTitle } from './canvas-serialization.js';
@@ -114,6 +116,10 @@ export const MCP_APP_NODE_DEFAULT_SIZE = { width: 960, height: 600 };
 export const IMAGE_NODE_DEFAULT_SIZE = { width: 480, height: 360 };
 export const LEDGER_NODE_DEFAULT_SIZE = { width: 420, height: 280 };
 
+// Per-type minimum creation sizes + clamp live in canvas-validation.ts
+// (NODE_MIN_CREATE_SIZES / clampCreateNodeSize) — shared with the validate
+// surface's sizeWarnings.
+
 interface CanvasCreateGroupInput {
   title?: string;
   childIds?: string[];
@@ -360,11 +366,20 @@ export function buildJsonRenderNodeUpdate(
   if (node.type !== 'json-render') throw new Error(`Node "${node.id}" is not a json-render node.`);
   const spec = normalizeAndValidateJsonRenderSpec(input.spec);
   const title = input.title?.trim() || inferJsonRenderNodeTitle(spec);
+  // Bump specVersion so the viewer URL changes: the iframe src is keyed on
+  // nodeId + ?v=specVersion, and the viewer only reads the spec at document
+  // load. Without the bump the src is byte-identical after a content update,
+  // the iframe never reloads, and the node renders stale forever (the live
+  // workboard's refresh depends on this).
+  const prevVersion = typeof node.data.specVersion === 'number' ? node.data.specVersion : 0;
   return {
     spec,
     data: {
       ...node.data,
-      ...createJsonRenderNodeData(node.id, title, spec, { viewerType: 'json-render' }),
+      ...createJsonRenderNodeData(node.id, title, spec, {
+        viewerType: 'json-render',
+        specVersion: prevVersion + 1,
+      }),
     },
   };
 }
@@ -554,6 +569,11 @@ function prepareExtAppNodesForSessionSync(forceRehydrate: boolean): string[] {
 
       const transportConfig = normalizeTransportConfig(node.data.transportConfig);
       if (!transportConfig) {
+        // Only a node that HAD a session has one to fail restoring. A static
+        // ext-app node (no session, no transport — e.g. the demo board's
+        // showcase tile) would otherwise be stamped with a persisted error
+        // banner on every start after the first, for a session it never had.
+        if (!sessionId) continue;
         setExtAppRuntimeState(node.id, {
           appSessionId: null,
           sessionStatus: 'error',
@@ -734,19 +754,8 @@ function buildFileNodeData(input: CanvasAddNodeInput): Record<string, unknown> {
     title: input.title ?? fileName,
   };
 
-  try {
-    if (existsSync(resolved)) {
-      const fileContent = readFileSync(resolved, 'utf-8');
-      const stat = statSync(resolved);
-      data.fileContent = fileContent;
-      data.lineCount = fileContent.split('\n').length;
-      data.updatedAt = new Date(stat.mtimeMs).toISOString();
-    }
-  } catch {
-    // Missing or unreadable files still render as path-backed file nodes.
-  }
-
-  return data;
+  // Missing or unreadable files still render as path-backed file nodes.
+  return applyFileContentToNodeData(data, readFileNodeContent(resolved));
 }
 
 function buildImageNodeData(input: CanvasAddNodeInput): Record<string, unknown> {
@@ -819,7 +828,7 @@ function normalizeTraceNodeData(input: CanvasAddNodeInput): Record<string, unkno
   return data;
 }
 
-function buildNodeData(input: CanvasAddNodeInput): Record<string, unknown> {
+function buildNodeDataForType(input: CanvasAddNodeInput): Record<string, unknown> {
   if (input.type === 'file') return buildFileNodeData(input);
   if (input.type === 'image') return buildImageNodeData(input);
   if (input.type === 'webpage') return buildWebpageNodeData(input);
@@ -828,10 +837,21 @@ function buildNodeData(input: CanvasAddNodeInput): Record<string, unknown> {
     ...(input.data ?? {}),
     ...(input.title ? { title: input.title } : {}),
     ...(input.content ? { content: input.content } : {}),
-    ...(input.strictSize ? { strictSize: true } : {}),
   };
 }
 
+function buildNodeData(input: CanvasAddNodeInput): Record<string, unknown> {
+  const data = buildNodeDataForType(input);
+  // `strictSize` is type-agnostic — it exempts a node from BOTH the creation
+  // size clamp and the browser's auto-fit. It used to be applied inside each
+  // per-type builder, and the file / image / webpage builders return a fresh
+  // object without it, so those three silently dropped the flag: the clamp
+  // honored it (it reads `input.strictSize` directly) but nothing persisted
+  // `data.strictSize`, so auto-fit resized the node in the browser anyway.
+  // Applying it once here makes it uniform for every type.
+  return input.strictSize ? { ...data, strictSize: true } : data;
+}
+
 export function mergeTraceNodeDataFields(
   base: Record<string, unknown>,
   input: Record<string, unknown>,
@@ -906,8 +926,12 @@ export function addCanvasNode(input: CanvasAddNodeInput): {
     throw new Error(`Use the dedicated ${input.type} node APIs for structured viewer nodes.`);
   }
 
-  const width = input.width ?? input.defaultWidth ?? 720;
-  const height = input.height ?? input.defaultHeight ?? 600;
+  const { width, height } = clampCreateNodeSize(
+    input.type,
+    input.width ?? input.defaultWidth ?? 720,
+    input.height ?? input.defaultHeight ?? 600,
+    input.strictSize,
+  );
   const position =
     input.x !== undefined && input.y !== undefined
       ? { x: input.x, y: input.y }
@@ -1540,8 +1564,12 @@ export function createCanvasJsonRenderNode(input: JsonRenderNodeInput): {
   node: CanvasNodeState;
 } {
   const spec = normalizeAndValidateJsonRenderSpec(input.spec);
-  const width = input.width ?? JSON_RENDER_NODE_SIZE.width;
-  const height = input.height ?? JSON_RENDER_NODE_SIZE.height;
+  const { width, height } = clampCreateNodeSize(
+    'json-render',
+    input.width ?? JSON_RENDER_NODE_SIZE.width,
+    input.height ?? JSON_RENDER_NODE_SIZE.height,
+    input.strictSize,
+  );
   const position =
     input.x !== undefined && input.y !== undefined
       ? { x: input.x, y: input.y }
@@ -1580,8 +1608,12 @@ export function createCanvasStreamingJsonRenderNode(input: {
   strictSize?: boolean;
 }): { id: string; url: string; spec: JsonRenderSpec; node: CanvasNodeState } {
   const spec = emptyStreamingSpec();
-  const width = input.width ?? JSON_RENDER_NODE_SIZE.width;
-  const height = input.height ?? JSON_RENDER_NODE_SIZE.height;
+  const { width, height } = clampCreateNodeSize(
+    'json-render',
+    input.width ?? JSON_RENDER_NODE_SIZE.width,
+    input.height ?? JSON_RENDER_NODE_SIZE.height,
+    input.strictSize,
+  );
   const position =
     input.x !== undefined && input.y !== undefined
       ? { x: input.x, y: input.y }
@@ -1652,8 +1684,12 @@ export function createCanvasGraphNode(input: GraphNodeInput): {
 } {
   const title = input.title?.trim() || 'Graph';
   const spec = buildGraphSpec(input);
-  const width = input.width ?? GRAPH_NODE_SIZE.width;
-  const height = input.heightPx ?? GRAPH_NODE_SIZE.height;
+  const { width, height } = clampCreateNodeSize(
+    'graph',
+    input.width ?? GRAPH_NODE_SIZE.width,
+    input.heightPx ?? GRAPH_NODE_SIZE.height,
+    input.strictSize,
+  );
   const position =
     input.x !== undefined && input.y !== undefined
       ? { x: input.x, y: input.y }
@@ -1679,9 +1715,30 @@ export function createCanvasGraphNode(input: GraphNodeInput): {
   return { id, url: String(node.data.url), spec, node };
 }
 
+/**
+ * The connected workbench's actual window size, reported by the client (0.4.6
+ * orb feedback #2). `fit` used to compute against a hardcoded 1440x900, so an
+ * agent calling fit without dimensions produced a scale sized for a window the
+ * human did not have — the board overflowed and clipped on both sides. The
+ * client reports its size on connect and on resize; explicit width/height in a
+ * fit call still win. In-memory only (a live client fact, never persisted);
+ * with several clients connected, the most recent reporter wins.
+ */
+let lastClientViewportSize: { width: number; height: number } | null = null;
+
+export function setClientViewportSize(width: unknown, height: unknown): void {
+  if (typeof width !== 'number' || typeof height !== 'number') return;
+  if (!Number.isFinite(width) || !Number.isFinite(height) || width <= 0 || height <= 0) return;
+  lastClientViewportSize = { width, height };
+}
+
+export function getClientViewportSize(): { width: number; height: number } | null {
+  return lastClientViewportSize ? { ...lastClientViewportSize } : null;
+}
+
 export function fitCanvasView(options: CanvasFitViewOptions = {}): CanvasFitViewResult {
-  const width = positiveNumber(options.width, 1440);
-  const height = positiveNumber(options.height, 900);
+  const width = positiveNumber(options.width, lastClientViewportSize?.width ?? 1440);
+  const height = positiveNumber(options.height, lastClientViewportSize?.height ?? 900);
   const padding = positiveNumber(options.padding, 60);
   const maxScale = positiveNumber(options.maxScale, 1);
   const nodeIdFilter = options.nodeIds && options.nodeIds.length > 0 ? new Set(options.nodeIds) : null;

package/src/server/canvas-provenance.ts

@@ -14,6 +14,8 @@ export type CanvasNodeType =
   | 'ledger'
   | 'trace'
   | 'file'
+  | 'diff'
+  | 'mermaid'
   | 'image'
   | 'html'
   | 'group';

package/src/server/canvas-schema.ts

@@ -209,6 +209,39 @@ const CANVAS_CREATE_TYPES: CanvasCreateTypeSchema[] = [
       'Path-backed file nodes automatically persist `data.provenance` with a file URI and file-watch refresh strategy.',
     ],
   },
+  {
+    type: 'diff',
+    kind: 'node',
+    description: 'Unified diff viewer with per-file sections and colored add/remove lines.',
+    endpoint: '/api/canvas/node',
+    mcpTool: 'canvas_node (action:"add")',
+    fields: [
+      { name: 'title', type: 'string', required: false, description: 'Optional node title.' },
+      { name: 'content', type: 'string', required: false, description: 'Unified diff text (git or raw hunks).' },
+    ],
+    example: {
+      type: 'diff',
+      title: 'Fix null check',
+      content: '--- a/src/app.ts\n+++ b/src/app.ts\n@@ -1,3 +1,3 @@\n-const a = b.c;\n+const a = b?.c;\n context',
+    },
+  },
+  {
+    type: 'mermaid',
+    kind: 'node',
+    description:
+      'Text-to-diagram node rendered client-side with Mermaid (flowcharts, sequence, state, class diagrams, …).',
+    endpoint: '/api/canvas/node',
+    mcpTool: 'canvas_node (action:"add")',
+    fields: [
+      { name: 'title', type: 'string', required: false, description: 'Optional node title.' },
+      { name: 'content', type: 'string', required: false, description: 'Mermaid diagram source text.' },
+    ],
+    example: {
+      type: 'mermaid',
+      title: 'Request flow',
+      content: 'graph TD; A[Client] --> B[Server]; B --> C[(DB)];',
+    },
+  },
   {
     type: 'image',
     kind: 'node',