pmx-canvas 0.4.5 → 0.4.7

package/src/client/canvas/EdgeLayer.tsx

@@ -1,5 +1,5 @@
 import type { Signal } from '@preact/signals';
-import { activeNodeId, draggingEdge, searchHighlightIds } from '../state/canvas-store';
+import { activeNodeId, draggingEdge, searchHighlightIds, viewport } from '../state/canvas-store';
 import type { CanvasEdge, CanvasNodeState } from '../types';
 
 // ── Edge type visual styles ──────────────────────────────────
@@ -7,15 +7,30 @@ const EDGE_COLORS: Record<CanvasEdge['type'], string> = {
   relation: 'var(--c-muted)',
   'depends-on': 'var(--c-warn)',
   flow: 'var(--c-accent)',
-  references: 'var(--c-dim)',
+  // --c-dim is a very low-contrast hairline in dark palettes (forest: #5D7566
+  // on #0C1712); the dashed style is what distinguishes `references`.
+  references: 'var(--c-muted)',
 };
 
 const DIRECTED_TYPES = new Set<CanvasEdge['type']>(['depends-on', 'flow']);
 
-function dashArray(edge: CanvasEdge): string | undefined {
-  if (edge.style === 'dashed') return '8 4';
-  if (edge.style === 'dotted') return '3 3';
-  if (edge.type === 'references' && !edge.style) return '8 4';
+/**
+ * Edges are drawn in world space, so a 1.5px stroke renders as 0.4 screen px at
+ * 26% zoom. Full inverse compensation keeps edge chrome at a constant SCREEN
+ * size while zoomed out (standard graph-editor behaviour). Deliberately
+ * uncapped — the 2.2 cap used for node chrome still leaves hairlines invisible
+ * at overview zoom.
+ */
+export function edgeChromeScale(scale: number): number {
+  if (!Number.isFinite(scale) || scale <= 0) return 1;
+  return scale < 1 ? 1 / scale : 1;
+}
+
+function dashArray(edge: CanvasEdge, scale: number): string | undefined {
+  const dashed = `${8 * scale} ${4 * scale}`;
+  if (edge.style === 'dashed') return dashed;
+  if (edge.style === 'dotted') return `${3 * scale} ${3 * scale}`;
+  if (edge.type === 'references' && !edge.style) return dashed;
   return undefined;
 }
 
@@ -84,9 +99,10 @@ interface EdgePathProps {
   toNode: CanvasNodeState;
   focused: boolean; // connected to the active node
   dimmed: boolean; // active node exists but this edge is NOT connected
+  scale: number; // inverse-viewport compensation, see edgeChromeScale()
 }
 
-function EdgePath({ edge, fromNode, toNode, focused, dimmed }: EdgePathProps) {
+function EdgePath({ edge, fromNode, toNode, focused, dimmed, scale }: EdgePathProps) {
   const start = computeAnchor(fromNode, toNode);
   const end = computeAnchor(toNode, fromNode);
 
@@ -106,7 +122,7 @@ function EdgePath({ edge, fromNode, toNode, focused, dimmed }: EdgePathProps) {
   const d = `M ${start.x} ${start.y} C ${cx1} ${cy1}, ${cx2} ${cy2}, ${end.x} ${end.y}`;
   const color = EDGE_COLORS[edge.type];
   const directed = DIRECTED_TYPES.has(edge.type);
-  const dash = dashArray(edge);
+  const dash = dashArray(edge, scale);
 
   const mid = edge.label ? bezierMidpoint(start.x, start.y, cx1, cy1, cx2, cy2, end.x, end.y) : null;
 
@@ -115,7 +131,7 @@ function EdgePath({ edge, fromNode, toNode, focused, dimmed }: EdgePathProps) {
   return (
     <g>
       {/* Invisible wide hitbox for hover/click */}
-      <path d={d} fill="none" stroke="transparent" stroke-width="12" style={{ cursor: 'pointer' }} />
+      <path d={d} fill="none" stroke="transparent" stroke-width={12 * scale} style={{ cursor: 'pointer' }} />
 
       {/* Glow layer for focused edges */}
       {focused && (
@@ -123,29 +139,30 @@ function EdgePath({ edge, fromNode, toNode, focused, dimmed }: EdgePathProps) {
           d={d}
           fill="none"
           stroke={color}
-          stroke-width="6"
+          stroke-width={6 * scale}
           stroke-dasharray={dash}
           opacity="0.15"
           style={{ filter: 'blur(3px)' }}
         />
       )}
 
-      {/* Visible edge */}
+      {/* Visible edge — the `edge-arrow` marker uses the default
+          markerUnits="strokeWidth", so the arrowhead scales with this. */}
       <path
         id={pathId}
         d={d}
         fill="none"
         stroke={color}
-        stroke-width={focused ? 2.5 : 1.5}
+        stroke-width={(focused ? 2.5 : 1.5) * scale}
         stroke-dasharray={dash}
         marker-end={directed ? 'url(#edge-arrow)' : undefined}
-        opacity={dimmed ? 0.2 : focused ? 1 : 0.75}
+        opacity={dimmed ? 0.2 : focused ? 1 : 0.85}
         style={{ transition: 'opacity 0.2s, stroke-width 0.2s' }}
       />
 
       {/* Animated pulse dot */}
       {edge.animated && (
-        <circle r="3" fill={color} opacity="0.9">
+        <circle r={3 * scale} fill={color} opacity="0.9">
           <animateMotion dur="2s" repeatCount="indefinite">
             <mpath href={`#${pathId}`} />
           </animateMotion>
@@ -157,13 +174,13 @@ function EdgePath({ edge, fromNode, toNode, focused, dimmed }: EdgePathProps) {
         <g transform={`translate(${mid.x}, ${mid.y})`}>
           <rect
             class="edge-label-bg"
-            x={-(edge.label.length * 3.5 + 8)}
-            y="-10"
-            width={edge.label.length * 7 + 16}
-            height="20"
-            rx="4"
+            x={-(edge.label.length * 3.5 + 8) * scale}
+            y={-10 * scale}
+            width={(edge.label.length * 7 + 16) * scale}
+            height={20 * scale}
+            rx={4 * scale}
           />
-          <text class="edge-label" text-anchor="middle" dominant-baseline="central" fill="var(--c-text)" font-size="11">
+          <text class="edge-label" text-anchor="middle" dominant-baseline="central" fill="var(--c-text)">
             {edge.label}
           </text>
         </g>
@@ -185,6 +202,7 @@ export function EdgeLayer({ nodes, edges }: EdgeLayerProps) {
   const hasFocus = focusId !== null;
   const searchSet = searchHighlightIds.value;
   const hasSearch = searchSet !== null;
+  const scale = edgeChromeScale(viewport.value.scale);
 
   if (edgeList.length === 0) return null;
 
@@ -210,6 +228,7 @@ export function EdgeLayer({ nodes, edges }: EdgeLayerProps) {
         left: `${minX}px`,
         pointerEvents: 'none',
         overflow: 'visible',
+        '--edge-chrome-scale': scale.toFixed(3),
       }}
     >
       <title>Canvas connections</title>
@@ -240,6 +259,7 @@ export function EdgeLayer({ nodes, edges }: EdgeLayerProps) {
             toNode={toNode}
             focused={isConnected}
             dimmed={(hasFocus && !isConnected) || searchDimmed}
+            scale={scale}
           />
         );
       })}
@@ -260,7 +280,7 @@ export function EdgeLayer({ nodes, edges }: EdgeLayerProps) {
                 d={previewD}
                 fill="none"
                 stroke="var(--c-accent)"
-                stroke-width="6"
+                stroke-width={6 * scale}
                 opacity="0.1"
                 style={{ filter: 'blur(3px)' }}
               />
@@ -268,11 +288,11 @@ export function EdgeLayer({ nodes, edges }: EdgeLayerProps) {
                 d={previewD}
                 fill="none"
                 stroke="var(--c-accent)"
-                stroke-width="2"
-                stroke-dasharray="6 4"
+                stroke-width={2 * scale}
+                stroke-dasharray={`${6 * scale} ${4 * scale}`}
                 opacity="0.8"
               />
-              <circle cx={de.cursorX} cy={de.cursorY} r="5" fill="var(--c-accent)" opacity="0.5" />
+              <circle cx={de.cursorX} cy={de.cursorY} r={5 * scale} fill="var(--c-accent)" opacity="0.5" />
             </g>
           );
         })()}

package/src/client/canvas/ExpandedNodeOverlay.tsx

@@ -1,9 +1,11 @@
 import { HTML_SURFACE_PUSH_SOURCE } from '../../shared/ax-surface-protocol.js';
 import { useCallback, useEffect, useLayoutEffect, useRef, useState } from 'preact/hooks';
 import { ContextNode } from '../nodes/ContextNode';
+import { DiffNode } from '../nodes/DiffNode';
 import { FileNode } from '../nodes/FileNode';
 import { LedgerNode } from '../nodes/LedgerNode';
 import { MarkdownNode } from '../nodes/MarkdownNode';
+import { MermaidNode } from '../nodes/MermaidNode';
 import { McpAppNode } from '../nodes/McpAppNode';
 import { StatusNode } from '../nodes/StatusNode';
 import { ImageNode } from '../nodes/ImageNode';
@@ -11,6 +13,7 @@ import { WebpageNode } from '../nodes/WebpageNode';
 import { HtmlNode, shouldShowPresentationControls } from '../nodes/HtmlNode';
 import { canOpenAsSite, openNodeAsSite } from '../nodes/surface-url';
 import { PromptNode } from '../nodes/PromptNode';
+import { AxStepControls } from '../nodes/AxStepControls';
 import { ResponseNode } from '../nodes/ResponseNode';
 import { TraceNode } from '../nodes/TraceNode';
 import {
@@ -50,6 +53,10 @@ function renderContent(node: CanvasNodeState, expanded: boolean) {
       return <TraceNode node={node} />;
     case 'file':
       return <FileNode node={node} expanded={expanded} />;
+    case 'diff':
+      return <DiffNode node={node} />;
+    case 'mermaid':
+      return <MermaidNode node={node} expanded={expanded} />;
     case 'image':
       return <ImageNode node={node} expanded={expanded} />;
     case 'html':
@@ -64,6 +71,10 @@ function getNodeTextContent(node: CanvasNodeState): string {
   switch (node.type) {
     case 'markdown':
       return (node.data.content as string) || '';
+    case 'diff':
+      return (node.data.content as string) || '';
+    case 'mermaid':
+      return (node.data.content as string) || '';
     case 'file':
       return (node.data.fileContent as string) || '';
     case 'webpage':
@@ -395,6 +406,16 @@ export function ExpandedNodeOverlay() {
             renderContent(node, true)
           )}
         </div>
+        {/* AX step controls follow the node into focus mode. Without this,
+            expanding a materialized flow step showed only its text — the
+            Start/Done/Blocked and loop controls live in CanvasNode's body,
+            which the overlay does not render. */}
+        {/* Here the dock is a SIBLING of the padded content area, so it is
+            already flush with the panel: no bleed, and 16px of its own padding
+            to line its labels up with the content above. */}
+        <div style={{ '--ax-dock-bleed': '0px', '--ax-dock-pad': '16px' } as Record<string, string>}>
+          <AxStepControls node={node} />
+        </div>
         {canPresent && presenting && (
           <div
             ref={presentationOverlayRef}

package/src/client/canvas/Minimap.tsx

@@ -36,6 +36,8 @@ function getNodeColors(): Record<CanvasNodeState['type'], string> {
     ledger: t.dim,
     trace: t.purple,
     file: t.accent,
+    diff: t.ok,
+    mermaid: t.purple,
     image: t.ok,
     html: t.warn,
     group: t.dim,

package/src/client/canvas/auto-fit.ts

@@ -1,4 +1,5 @@
 import type { CanvasNodeState } from '../types';
+import { nodeMinSize } from '../../shared/node-sizes.js';
 
 export const AUTO_FIT_TITLEBAR_HEIGHT = 37;
 export const AUTO_FIT_MAX_HEIGHT = 600;
@@ -21,6 +22,7 @@ export const AUTO_FIT_BODY_PADDING = 24;
 function isIframeNode(node: CanvasNodeState): boolean {
   return (
     node.type === 'html' ||
+    node.type === 'mermaid' ||
     node.type === 'json-render' ||
     node.type === 'graph' ||
     node.type === 'mcp-app' ||
@@ -33,6 +35,7 @@ function isIframeNode(node: CanvasNodeState): boolean {
  *  viewers (unbounded/scrolling content that must not drive node height). */
 function isContentFitSurface(node: CanvasNodeState): boolean {
   if (node.type === 'html') return node.data.presentation !== true;
+  if (node.type === 'mermaid') return true;
   if (node.type === 'json-render' || node.type === 'graph') return true;
   if (node.type === 'mcp-app') return node.data.viewerType === 'web-artifact';
   return false;
@@ -58,7 +61,15 @@ export function shouldAutoFitNode(node: CanvasNodeState): boolean {
 
 export function computeAutoFitHeight(node: CanvasNodeState, contentHeight: number): number | null {
   if (!shouldAutoFitNode(node) || contentHeight <= 0) return null;
-  return Math.min(contentHeight + AUTO_FIT_TITLEBAR_HEIGHT, AUTO_FIT_MAX_HEIGHT);
+  const fitted = Math.min(contentHeight + AUTO_FIT_TITLEBAR_HEIGHT, AUTO_FIT_MAX_HEIGHT);
+  // Honor the shared readability floor (0.4.6 report Finding AA): the server
+  // clamps an undersized create up to the floor, then this auto-fit measured
+  // the short content and persisted a SMALLER height — undoing the clamp on
+  // the most common path (a connected workbench). Auto-fit may grow a node and
+  // may shrink it toward its content, but never below the type's floor.
+  // strictSize nodes never reach here (isAutoSizeExempt).
+  const min = nodeMinSize(node.type);
+  return min ? Math.max(fitted, min.height) : fitted;
 }
 
 /** Iframe surfaces that should GROW to fit their reported content height. */

package/src/client/canvas/use-pan-zoom.ts

@@ -44,13 +44,28 @@ export function usePanZoom({ viewport, onViewportChange, onViewportCommit, disab
     [onViewportCommit],
   );
 
+  /**
+   * A mouse wheel should zoom the canvas; a trackpad two-finger scroll should still
+   * pan. The events are the same type, so distinguish them by shape: wheels emit
+   * coarse, whole-number vertical deltas with no horizontal component, while
+   * trackpads emit small and/or fractional deltas and usually some deltaX. Pinch
+   * arrives as ctrl+wheel and is handled alongside this.
+   */
+  function isMouseWheel(e: WheelEvent): boolean {
+    // Line/page deltaMode is only ever produced by a real wheel (Firefox emits
+    // DOM_DELTA_LINE with deltaY ~3 per notch, which the pixel heuristic below
+    // would never match — wheel zoom simply never fired there).
+    if (e.deltaMode !== 0) return e.deltaX === 0;
+    return e.deltaX === 0 && Number.isInteger(e.deltaY) && Math.abs(e.deltaY) >= 50;
+  }
+
   const handleWheel = useCallback(
     (e: WheelEvent) => {
       if (disabled) return;
       e.preventDefault();
       const v = viewport.value;
 
-      if (e.ctrlKey || e.metaKey) {
+      if (e.ctrlKey || e.metaKey || isMouseWheel(e)) {
         // Zoom centered on pointer
         const rect = containerRef.current?.getBoundingClientRect();
         if (!rect) return;

package/src/client/icons.tsx

@@ -473,6 +473,10 @@ export function getNodeIcon(type: string): (p: IconProps) => JSX.Element {
       return IconNodeResponse;
     case 'file':
       return IconNodeFile;
+    case 'diff':
+      return IconNodeFile;
+    case 'mermaid':
+      return IconNodeGraph;
     case 'image':
       return IconNodeImage;
     case 'webpage':

package/src/client/mermaid-entry.ts

@@ -0,0 +1,76 @@
+/**
+ * Surface-side renderer for `mermaid` nodes — the entry point of the separately
+ * built dist/canvas/mermaid-entry.js bundle (see package.json build:client).
+ * The server (handleNodeSurface) serves a themed surface document containing the
+ * HTML-escaped diagram source in `<pre class="mermaid-source">`; this script
+ * reads it back via textContent, renders it to SVG, and re-renders when the
+ * parent canvas live-switches the theme (the theme bridge toggles the document's
+ * `data-theme` attribute). Keeping mermaid out of the main SPA bundle keeps the
+ * canvas boot lean — only mermaid-node surfaces pay for the library.
+ */
+
+import mermaid from 'mermaid';
+import { canvasThemeScheme } from '../shared/themes.js';
+
+function documentScheme(): 'dark' | 'light' {
+  return canvasThemeScheme(document.documentElement.getAttribute('data-theme'));
+}
+
+function showError(container: HTMLElement, message: string): void {
+  container.innerHTML = '';
+  const block = document.createElement('pre');
+  block.className = 'mermaid-error';
+  block.style.cssText =
+    'margin:12px;padding:12px;border-radius:6px;color:var(--c-dim,#8a93a6);' +
+    'font-family:ui-monospace,SFMono-Regular,Menlo,monospace;font-size:12px;white-space:pre-wrap;';
+  block.textContent = message;
+  container.appendChild(block);
+}
+
+let renderSeq = 0;
+
+async function renderDiagram(source: string, container: HTMLElement): Promise<void> {
+  const scheme = documentScheme();
+  mermaid.initialize({
+    startOnLoad: false,
+    theme: scheme === 'dark' ? 'dark' : 'default',
+    securityLevel: 'strict',
+  });
+  renderSeq += 1;
+  try {
+    const { svg } = await mermaid.render(`pmx-mermaid-${renderSeq}`, source);
+    container.innerHTML = svg;
+  } catch (error) {
+    // Never leave a blank/black frame: show the parse/render error instead.
+    showError(container, error instanceof Error ? error.message : String(error));
+  }
+}
+
+function boot(): void {
+  const sourceEl = document.querySelector('.mermaid-source');
+  const source = sourceEl?.textContent ?? '';
+  const container = document.createElement('div');
+  container.className = 'mermaid-diagram';
+  document.body.appendChild(container);
+  if (!source.trim()) {
+    showError(container, 'Empty mermaid diagram');
+    return;
+  }
+  void renderDiagram(source, container);
+  // Live theme switching: the parent's theme bridge toggles data-theme on the
+  // root element; re-render so the diagram palette follows the canvas theme.
+  let lastScheme = documentScheme();
+  const observer = new MutationObserver(() => {
+    const scheme = documentScheme();
+    if (scheme === lastScheme) return;
+    lastScheme = scheme;
+    void renderDiagram(source, container);
+  });
+  observer.observe(document.documentElement, { attributes: true, attributeFilter: ['data-theme'] });
+}
+
+if (document.readyState === 'loading') {
+  document.addEventListener('DOMContentLoaded', boot);
+} else {
+  boot();
+}

package/src/client/nodes/AxStepControls.tsx

@@ -0,0 +1,226 @@
+import { useState } from 'preact/hooks';
+import { readAxFlow, readAxStep, type AxFlowStamp } from '../../shared/ax-flow.js';
+import { nodes, updateNodeData } from '../state/canvas-store';
+import { updateNodeFromClient } from '../state/intent-bridge';
+import type { CanvasNodeState } from '../types';
+import { axNodeActionButtonStyle, runNodeAxInteraction } from './ax-node-actions';
+
+/**
+ * Native AX controls for a materialized flow step — the same capability the
+ * ax-flow HTML panel has, on an ORDINARY canvas node.
+ *
+ * Rendered by CanvasNode for any node carrying `data.axStep`, whatever its type,
+ * so the flow is driven from the board itself: Start/Done/Blocked emit
+ * `ax.work.update` for the step's work item through the trusted `native-node`
+ * surface, and the anchor step additionally runs/stops the durable server loop
+ * (ax-flow-loop.ts) and steers the agent.
+ */
+
+/**
+ * The rows sit in a dock stuck to the bottom of the scrollable node body: a step
+ * node is short (360x200 as materialized), so a control row that simply followed
+ * the content scrolled out of sight. Sticky keeps it reachable at any node height
+ * while still being INSIDE the body, which is what auto-fit measures.
+ */
+/**
+ * The dock reads as a real footer toolbar rather than stray text at the bottom
+ * edge. It bleeds to the container's edges via negative margins (`.node-body`
+ * has 12px padding; the expanded overlay's content area has 16px, and the dock
+ * is a sibling of that area, so it starts flush) and then re-applies its own
+ * padding — otherwise the first label sits hard against the left edge and looks
+ * clipped. `--c-panel-overlay` separates it from the content above it.
+ */
+const dockStyle = {
+  position: 'sticky',
+  // Bleed OUT of the container's padding so the bar spans edge to edge, then
+  // re-apply padding inside it. These are two different numbers: in a node body
+  // the dock sits INSIDE 12px of padding and must pull back out of it, while in
+  // the expanded overlay it is a sibling of the padded content area and is
+  // already flush — bleeding there would push it off the panel.
+  bottom: 'calc(-1 * var(--ax-dock-bleed, 12px))',
+  marginTop: '12px',
+  marginLeft: 'calc(-1 * var(--ax-dock-bleed, 12px))',
+  marginRight: 'calc(-1 * var(--ax-dock-bleed, 12px))',
+  marginBottom: 'calc(-1 * var(--ax-dock-bleed, 12px))',
+  padding: '9px var(--ax-dock-pad, 12px) 10px',
+  background: 'var(--c-panel-overlay)',
+  borderTop: '1px solid var(--c-line)',
+  backdropFilter: 'blur(6px)',
+} as const;
+
+const rowStyle = {
+  display: 'flex',
+  alignItems: 'center',
+  gap: '6px',
+  flexWrap: 'wrap',
+} as const;
+
+const labelStyle = {
+  fontSize: '10px',
+  color: 'var(--c-muted)',
+  textTransform: 'uppercase',
+  letterSpacing: '0.04em',
+  marginRight: 'auto',
+} as const;
+
+const activeButtonStyle = {
+  ...axNodeActionButtonStyle,
+  background: 'var(--c-accent-25)',
+  color: 'var(--c-text)',
+} as const;
+
+const STEP_ACTIONS = [
+  { status: 'in-progress', label: 'Start', toast: 'Step started' },
+  { status: 'done', label: 'Done', toast: 'Step done' },
+  { status: 'blocked', label: 'Blocked', toast: 'Step blocked' },
+] as const;
+
+/** Persist a new loop state on the anchor node (optimistic locally, durable on the server). */
+async function persistLoop(node: CanvasNodeState, flow: AxFlowStamp, loop: AxFlowStamp['loop']): Promise<void> {
+  const axFlow: AxFlowStamp = { ...flow, loop };
+  updateNodeData(node.id, { axFlow });
+  await updateNodeFromClient(node.id, { data: { axFlow } });
+}
+
+/** The work-item status mirrored onto a node by the server (`data.axWorkStatus`). */
+function mirroredStatus(data: Record<string, unknown> | undefined): string {
+  return typeof data?.axWorkStatus === 'string' ? data.axWorkStatus : 'todo';
+}
+
+function FlowLoopControls({ node, flow }: { node: CanvasNodeState; flow: AxFlowStamp }) {
+  const [message, setMessage] = useState('');
+  const { running, run, maxRuns } = flow.loop;
+
+  const handleRun = async () => {
+    // A finished loop restarts from zero rather than stopping on its first check.
+    await persistLoop(node, flow, { running: true, run: run >= maxRuns ? 0 : run, maxRuns });
+    // The server loop only advances on a WORK-ITEM change, so starting it has to
+    // produce one: open the first unfinished step, or re-assert the last step's
+    // `done` when the flow is already complete (which closes the run and opens
+    // the next one server-side).
+    const next = flow.steps.find((step) => mirroredStatus(nodes.value.get(step.nodeId)?.data) !== 'done');
+    const target = next ?? flow.steps[flow.steps.length - 1];
+    await runNodeAxInteraction(
+      node,
+      'ax.work.update',
+      { id: target.workItemId, status: next ? 'in-progress' : 'done' },
+      'Loop running',
+    );
+  };
+
+  const handleSteer = async () => {
+    const text = message.trim();
+    if (!text) return;
+    await runNodeAxInteraction(node, 'ax.steer', { message: text }, 'Steering sent');
+    setMessage('');
+  };
+
+  return (
+    <div class="ax-flow-controls" style={{ ...rowStyle, marginTop: '6px', rowGap: '4px' }}>
+      <span class="ax-flow-runs" style={labelStyle}>
+        {running ? `Loop running · run ${run + 1}/${maxRuns}` : `Loop idle · ${run}/${maxRuns} runs`}
+      </span>
+      {running ? (
+        <button
+          type="button"
+          class="ax-node-action"
+          style={activeButtonStyle}
+          title="Stop the loop now. The stop is persisted on this node, so it survives a refresh and no further step is opened."
+          onClick={(e) => {
+            e.stopPropagation();
+            void persistLoop(node, flow, { ...flow.loop, running: false });
+          }}
+        >
+          Stop
+        </button>
+      ) : (
+        <button
+          type="button"
+          class="ax-node-action"
+          style={axNodeActionButtonStyle}
+          title="Run this flow as a loop: each completed step opens the next one, and the last step starts the next run — until the run cap is reached or you press Stop."
+          onClick={(e) => {
+            e.stopPropagation();
+            void handleRun();
+          }}
+        >
+          Run loop
+        </button>
+      )}
+      <input
+        class="ax-flow-steer-input"
+        value={message}
+        placeholder="Steer the agent…"
+        aria-label="Steer the agent"
+        onInput={(e) => setMessage((e.target as HTMLInputElement).value)}
+        onClick={(e) => e.stopPropagation()}
+        onKeyDown={(e) => {
+          if (e.key !== 'Enter') return;
+          e.stopPropagation();
+          void handleSteer();
+        }}
+        style={{
+          flex: '1 1 120px',
+          minWidth: '90px',
+          fontSize: '10px',
+          padding: '3px 6px',
+          borderRadius: '4px',
+          border: '1px solid var(--c-line)',
+          background: 'var(--c-panel-overlay)',
+          color: 'var(--c-text)',
+        }}
+      />
+      <button
+        type="button"
+        class="ax-node-action"
+        style={axNodeActionButtonStyle}
+        title="Send a steering message to the agent working this flow."
+        onClick={(e) => {
+          e.stopPropagation();
+          void handleSteer();
+        }}
+      >
+        Steer
+      </button>
+    </div>
+  );
+}
+
+export function AxStepControls({ node }: { node: CanvasNodeState }) {
+  const step = readAxStep(node.data);
+  if (!step) return null;
+  const flow = readAxFlow(node.data);
+  const status = mirroredStatus(node.data);
+
+  return (
+    <div class="ax-step-dock" style={dockStyle}>
+      <div class="ax-step-controls" style={rowStyle}>
+        <span class="ax-step-position" style={labelStyle}>
+          Step {step.index}/{step.total}
+        </span>
+        {STEP_ACTIONS.map((action) => (
+          <button
+            key={action.status}
+            type="button"
+            class="ax-node-action"
+            aria-pressed={status === action.status}
+            style={status === action.status ? activeButtonStyle : axNodeActionButtonStyle}
+            title={`Set this step's work item to "${action.status}".`}
+            onClick={(e) => {
+              e.stopPropagation();
+              void runNodeAxInteraction(
+                node,
+                'ax.work.update',
+                { id: step.workItemId, status: action.status },
+                action.toast,
+              );
+            }}
+          >
+            {action.label}
+          </button>
+        ))}
+      </div>
+      {flow && <FlowLoopControls node={node} flow={flow} />}
+    </div>
+  );
+}