pmx-canvas 0.4.6 → 0.4.7

package/src/server/ax-flow-loop.ts

@@ -0,0 +1,114 @@
+/**
+ * Server-side bounded loop for materialized AX flows.
+ *
+ * A flow's loop lives on the CANVAS, not in a panel: the anchor step node carries
+ * `data.axFlow.loop` (see shared/ax-flow.ts), so it survives a browser refresh, an
+ * iframe reload, and a server restart — where a panel-driven loop dies with its
+ * document. The driver is `canvasState`'s work-item change hook: whenever a step's
+ * work item reaches `done`, the next step is opened; when the LAST step finishes,
+ * the next run starts — until the run cap is reached or a human presses Stop.
+ *
+ * Bounds (non-negotiable, enforced here rather than trusted from node data):
+ *   - advances only while `loop.running` is true
+ *   - stops at `maxRuns`, itself clamped to AX_FLOW_LOOP_HARD_CAP (20)
+ *   - a `blocked`/`cancelled` step halts advancement (the loop waits, it does not
+ *     skip); a step whose work item no longer exists stops the loop outright
+ *   - re-entrancy: every write this module makes fires the same work-item change
+ *     hook, so `advancing` drops the nested call. State is recomputed from scratch
+ *     on each pass, so dropping nested calls loses nothing.
+ */
+import { AX_FLOW_LOOP_HARD_CAP, readAxFlow, type AxFlowLoopState, type AxFlowStamp } from '../shared/ax-flow.js';
+import type { PmxAxWorkItem } from './ax-state.js';
+import { emitCanvasLayoutUpdate } from './canvas-operations.js';
+import { canvasState, type CanvasNodeState } from './canvas-state.js';
+import { refreshWorkboardNodes } from './workboard.js';
+
+/** Re-entrancy guard: true while an advance pass is writing. */
+let advancing = false;
+
+/** Persist a new loop state on the anchor node (durable: this is what Stop writes). */
+function writeLoopState(node: CanvasNodeState, flow: AxFlowStamp, loop: AxFlowLoopState): void {
+  const current = canvasState.getNode(node.id);
+  if (!current) return;
+  canvasState.updateNode(node.id, { data: { ...current.data, axFlow: { ...flow, loop } } });
+}
+
+/**
+ * Advance one flow by at most one step (or one run boundary). Returns true when
+ * anything changed, so the caller knows whether to broadcast a layout update.
+ */
+function advanceFlow(node: CanvasNodeState, flow: AxFlowStamp, byId: Map<string, PmxAxWorkItem>): boolean {
+  const items = flow.steps.map((step) => byId.get(step.workItemId));
+  if (items.some((item) => !item)) {
+    // The flow was partially dismantled (work items cleared/deleted). Stop rather
+    // than keep a loop armed against state it can no longer drive.
+    writeLoopState(node, flow, { ...flow.loop, running: false });
+    return true;
+  }
+  const statuses = items as PmxAxWorkItem[];
+  // A blocked/cancelled step is a deliberate halt — hold position, stay armed.
+  if (statuses.some((item) => item.status === 'blocked' || item.status === 'cancelled')) return false;
+
+  const openIndex = statuses.findIndex((item) => item.status !== 'done');
+  if (openIndex >= 0) {
+    // Every earlier step is done by construction. Open this one exactly once:
+    // an already in-progress step is the loop's own previous advance.
+    if (statuses[openIndex].status !== 'todo') return false;
+    canvasState.updateWorkItem(statuses[openIndex].id, { status: 'in-progress' }, { source: 'system' });
+    return true;
+  }
+
+  // Every step is done — one full run just completed.
+  const maxRuns = Math.min(flow.loop.maxRuns, AX_FLOW_LOOP_HARD_CAP);
+  const run = flow.loop.run + 1;
+  if (run >= maxRuns) {
+    // The cap is reached WITH this run recorded: no run `maxRuns + 1` is opened.
+    writeLoopState(node, flow, { running: false, run, maxRuns });
+    return true;
+  }
+  // Write the counter before re-opening the steps, so a crash mid-pass can never
+  // replay a run for free.
+  writeLoopState(node, flow, { running: true, run, maxRuns });
+  for (const step of flow.steps) {
+    canvasState.updateWorkItem(step.workItemId, { status: 'todo' }, { source: 'system' });
+  }
+  canvasState.updateWorkItem(flow.steps[0].workItemId, { status: 'in-progress' }, { source: 'system' });
+  return true;
+}
+
+/**
+ * Advance every running flow loop on the canvas. Safe to call on any work-item
+ * change: flows that are not running, not ready, or already advanced are no-ops.
+ */
+export function advanceAxFlowLoops(): void {
+  if (advancing) return;
+  advancing = true;
+  try {
+    const anchors = canvasState
+      .getLayout()
+      .nodes.map((node) => ({ node, flow: readAxFlow(node.data) }))
+      .filter((entry): entry is { node: CanvasNodeState; flow: AxFlowStamp } => entry.flow?.loop.running === true);
+    if (anchors.length === 0) return;
+    const byId = new Map(canvasState.getWorkItems().map((item) => [item.id, item]));
+    let changed = false;
+    // Suppressed: loop bookkeeping (status chips, the run counter) is automatic
+    // and must not fill undo history — same contract as the live workboard.
+    canvasState.withSuppressedRecording(() => {
+      for (const { node, flow } of anchors) {
+        if (advanceFlow(node, flow, byId)) changed = true;
+      }
+    });
+    if (changed) emitCanvasLayoutUpdate();
+  } finally {
+    advancing = false;
+  }
+}
+
+// canvasState exposes ONE work-item listener slot, so this module owns the
+// composition: the live workboard refresh first (unchanged behaviour), then the
+// flow advance. Importing workboard also guarantees ordering — its own
+// registration runs while this module is still evaluating, so this one wins.
+canvasState.setWorkItemsChangedListener(() => {
+  refreshWorkboardNodes();
+  advanceAxFlowLoops();
+});

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(
@@ -137,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',
   ),
@@ -246,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),
@@ -311,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 ───────────────────────────────────────────────────
@@ -321,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;
@@ -428,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
@@ -548,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 {
@@ -562,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 {
@@ -685,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,
@@ -568,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',
@@ -748,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> {
@@ -833,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);
@@ -842,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>,
@@ -1709,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-state.ts

@@ -1320,16 +1320,15 @@ class CanvasStateManager {
   }
 
   addNode(node: CanvasNodeState): void {
-    // Context nodes default to a right-docked, collapsed pill when created without
-    // an explicit dock position. CREATE-time default only — once placed, updates
-    // (including undock → dockPosition null) are respected (see normalizeNode).
-    // Skip during suppressed replay (undo/redo re-add) so a deliberately-undocked
-    // context node is restored verbatim instead of being snapped back to the dock.
-    const seeded =
-      node.type === 'context' && node.dockPosition == null && this._suppressRecordingDepth === 0
-        ? { ...node, dockPosition: 'right' as const, collapsed: true }
-        : node;
-    const cloned = structuredClone(this.normalizeNode(seeded));
+    // Docking is EXPLICIT (0.4.6). Context nodes used to auto-dock to a collapsed
+    // right-hand pill when created without a dock position, which meant an agent
+    // creating a context node — even at explicit coordinates — got a node that
+    // existed in the API and passed validation but never rendered on the canvas,
+    // and any edge to it terminated in empty space (0.4.6 orb feedback #1). The
+    // seeded HUD widgets (status-main / context-main) pass `dockPosition` on
+    // create, so the docked pills are unaffected; anything else reaches the
+    // canvas where the caller put it. Dock deliberately via node.update.
+    const cloned = structuredClone(this.normalizeNode(node));
     this.nodes.set(node.id, cloned);
     this.scheduleSave();
     this.notifyChange('nodes');
@@ -1722,6 +1721,17 @@ class CanvasStateManager {
     return this.ax.getAxState();
   }
 
+  /**
+   * Replace the canvas-bound AX partition from a persisted blob, normalized against
+   * the current node set — the same operation snapshot restore performs internally
+   * (`applyPersistedState`), exposed for the demo seed. Both restore nodes whose
+   * `data.axStep.workItemId` only resolves if the work items come back with their
+   * original ids, so this preserves them verbatim rather than re-creating them.
+   */
+  applyPersistedAxState(ax: unknown): void {
+    this.ax.applyPersistedAx(ax);
+  }
+
   getAxFocus(): PmxAxFocusState {
     return this.ax.getAxFocus();
   }