pmx-canvas 0.4.6 → 0.4.8

package/src/client/theme/global.css

@@ -643,6 +643,10 @@ body,
   overflow: hidden;
   text-overflow: ellipsis;
   flex: 1;
+  /* The name is the one thing that must survive a cramped title bar. Everything
+     else in the bar is flex-shrink: 0, so without a floor the title absorbed all
+     the pressure and collapsed to an ellipsis on narrow nodes. */
+  min-width: 9ch;
   min-width: 0;
 }
 
@@ -670,6 +674,13 @@ body,
 }
 
 .canvas-node .node-ax-status {
+  /* A long status ("in-progress") must not push the node's NAME out of the bar;
+     the pill is a glance-level cue, the name is the identity. */
+  max-width: 11ch;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  flex-shrink: 1;
   font-size: calc(9px * var(--node-chrome-scale, 1));
   padding: calc(1px * var(--node-chrome-scale, 1)) calc(6px * var(--node-chrome-scale, 1));
   border-radius: calc(4px * var(--node-chrome-scale, 1));
@@ -1846,10 +1857,11 @@ html.is-node-resizing .ext-app-preview-catcher {
   border-radius: 999px;
 }
 
-/* Edge labels */
+/* Edge labels — --edge-chrome-scale is set on the edge <svg> so labels keep a
+   constant screen size while zoomed out (see edgeChromeScale in EdgeLayer). */
 .edge-label {
   font-family: var(--font);
-  font-size: 11px;
+  font-size: calc(11px * var(--edge-chrome-scale, 1));
   pointer-events: none;
   user-select: none;
 }
@@ -1857,7 +1869,7 @@ html.is-node-resizing .ext-app-preview-catcher {
 .edge-label-bg {
   fill: var(--c-panel-glass);
   stroke: var(--c-line);
-  stroke-width: 0.5;
+  stroke-width: calc(0.5 * var(--edge-chrome-scale, 1));
 }
 
 /* Trace nodes — compact pills for agent tool/subagent visualization */
@@ -1963,6 +1975,92 @@ html.is-node-resizing .ext-app-preview-catcher {
   color: var(--c-text-soft);
 }
 
+/* File nodes — delimited-data tables and non-text placeholders */
+.file-table-shell {
+  display: flex;
+  flex-direction: column;
+  height: 100%;
+  min-height: 0;
+}
+
+.file-node-notice {
+  flex-shrink: 0;
+  padding: 4px 10px;
+  color: var(--c-muted);
+  font-size: 10px;
+}
+
+/* Own scroll port so a wide CSV scrolls inside the node instead of blowing out
+   the layout — and so the sticky header row has something to stick to. */
+.file-table-wrap {
+  flex: 1;
+  min-height: 0;
+  overflow: auto;
+}
+
+/* The shell/wrap prefix is load-bearing: these rules must out-specify the markdown
+   table styles (`.canvas-node .node-body table` / `th` / `td`), whose 0.5em
+   margin and translucent header background break the sticky header. Borders are
+   separate, not collapsed — collapsed borders belong to the table element, so
+   the header leaks the rows scrolling beneath it. */
+.file-table-shell .file-table-wrap .file-table {
+  margin: 0;
+  border-collapse: separate;
+  border-spacing: 0;
+  width: max-content;
+  min-width: 100%;
+  font-family: var(--mono);
+  color: var(--c-text);
+}
+
+.file-table-shell .file-table-wrap .file-table th,
+.file-table-shell .file-table-wrap .file-table td {
+  max-width: 320px;
+  padding: 3px 8px;
+  border: none;
+  border-right: 1px solid var(--c-line);
+  border-bottom: 1px solid var(--c-line);
+  text-align: left;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.file-table-shell .file-table-wrap .file-table th {
+  position: sticky;
+  top: 0;
+  z-index: 1;
+  /* Opaque in every theme — rows must not bleed through while scrolling. */
+  background: var(--c-panel);
+  color: var(--c-text-soft);
+  font-weight: 600;
+}
+
+.file-table-shell .file-table-wrap .file-table tbody tr:nth-child(even) {
+  background: var(--c-surface-subtle);
+}
+
+.file-node-placeholder {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: 4px;
+  height: 100%;
+  padding: 16px;
+  color: var(--c-muted);
+  text-align: center;
+}
+
+.file-node-placeholder-name {
+  color: var(--c-text-soft);
+  word-break: break-all;
+}
+
+.file-node-link {
+  color: var(--c-accent);
+}
+
 /* Docked node — compact toolbar-flanking panel */
 .docked-node {
   min-width: 200px;

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.`);
   }