pmx-canvas 0.4.6 → 0.4.8

package/src/client/App.tsx

@@ -36,10 +36,11 @@ import {
   traceEnabled,
   viewport,
   walkGraph,
+  zoomByFactor,
 } from './state/canvas-store';
 import { connectSSE } from './state/sse-bridge';
 import { intents } from './state/intent-store';
-import { saveCanvasTheme } from './state/intent-bridge';
+import { reportClientViewportSize, saveCanvasTheme } from './state/intent-bridge';
 import {
   IconArrange,
   IconClearTrace,
@@ -258,20 +259,12 @@ function Toolbar({
           </button>
         </ToolbarHint>
         <ToolbarHint label="Zoom in" shortcut={`${MOD_KEY}++`}>
-          <button
-            type="button"
-            onClick={() => animateViewport({ ...v, scale: Math.min(4, v.scale * 1.25) }, 150)}
-            aria-label="Zoom in"
-          >
+          <button type="button" onClick={() => zoomByFactor(1.25)} aria-label="Zoom in">
             <IconZoomIn />
           </button>
         </ToolbarHint>
         <ToolbarHint label="Zoom out" shortcut={`${MOD_KEY}+-`}>
-          <button
-            type="button"
-            onClick={() => animateViewport({ ...v, scale: Math.max(0.1, v.scale / 1.25) }, 150)}
-            aria-label="Zoom out"
-          >
+          <button type="button" onClick={() => zoomByFactor(1 / 1.25)} aria-label="Zoom out">
             <IconZoomOut />
           </button>
         </ToolbarHint>
@@ -585,6 +578,25 @@ export function App() {
     return connectSSE();
   }, []);
 
+  // Keep the server's idea of this window's size current (0.4.6 orb feedback
+  // #2) so an agent `fit` computes a scale that actually fits the human's
+  // window. Connect-time reporting lives in the SSE bridge; this covers resizes.
+  useEffect(() => {
+    let timer: number | null = null;
+    const schedule = () => {
+      if (timer !== null) window.clearTimeout(timer);
+      timer = window.setTimeout(() => {
+        timer = null;
+        void reportClientViewportSize();
+      }, 400);
+    };
+    window.addEventListener('resize', schedule);
+    return () => {
+      if (timer !== null) window.clearTimeout(timer);
+      window.removeEventListener('resize', schedule);
+    };
+  }, []);
+
   useEffect(() => {
     const handleKeyDown = (e: KeyboardEvent) => {
       const mod = e.metaKey || e.ctrlKey;
@@ -640,12 +652,13 @@ export function App() {
         animateViewport({ x: 0, y: 0, scale: 1 }, 250);
       } else if (mod && (e.key === '=' || e.key === '+')) {
         e.preventDefault();
-        const cur = viewport.value;
-        animateViewport({ ...cur, scale: Math.min(4, cur.scale * 1.25) }, 150);
+        // Same centre-anchored zoom as the toolbar +/- buttons these shortcuts
+        // are advertised on (the tooltip names this key) — a raw scale change
+        // is origin-anchored and drifts the board away under the cursor.
+        zoomByFactor(1.25);
       } else if (mod && e.key === '-') {
         e.preventDefault();
-        const cur = viewport.value;
-        animateViewport({ ...cur, scale: Math.max(0.1, cur.scale / 1.25) }, 150);
+        zoomByFactor(1 / 1.25);
       } else if (e.key === 'Escape') {
         if (selectedNodeIds.value.size > 0) {
           clearSelection();

package/src/client/canvas/CanvasNode.tsx

@@ -21,15 +21,54 @@ import {
   viewport,
 } from '../state/canvas-store';
 import { removeNodeFromClient, updateNodeFromClient } from '../state/intent-bridge';
+import { AxStepControls } from '../nodes/AxStepControls';
 import { canOpenAsSite, openNodeAsSite } from '../nodes/surface-url';
 import { getNodeIcon } from '../icons';
 import { EXPANDABLE_TYPES, TYPE_LABELS } from '../types';
 import type { CanvasNodeState } from '../types';
-import { computeAutoFitHeight, shouldAutoFitNode } from './auto-fit';
+import { AUTO_FIT_TITLEBAR_HEIGHT, computeAutoFitHeight, shouldAutoFitNode } from './auto-fit';
 import { activeGuides, buildSnapCache, clearSnapCache, snapToGuides } from './snap-guides';
 import { useNodeDrag } from './use-node-drag';
 import { useNodeResize } from './use-node-resize';
 
+/** Fraction of a node's height the title bar may occupy before it starts
+ *  crowding out the content it is labelling. */
+const MAX_TITLEBAR_HEIGHT_RATIO = 0.4;
+/** Fraction of a node's width the fixed title-bar chrome may occupy before it
+ *  starts eating the node's NAME. */
+const MAX_TITLEBAR_CHROME_WIDTH_RATIO = 0.55;
+/** Unscaled width of everything in the bar that is not the title: type icon,
+ *  status/type pill, the control cluster, and the gaps between them. */
+const TITLEBAR_CHROME_BASE_WIDTH = 175;
+
+/**
+ * How much to enlarge node chrome (title bar, badges, icons) when zoomed out so
+ * it stays legible. Full inverse compensation is capped at 2.2x — but the cap
+ * alone ignored the node it is drawn on, so on SHORT nodes the growing bar ate
+ * the body: a 116px-tall section label at 46% zoom gave the title bar 72% of the
+ * node and left 14px for text that needed 41, so the markdown was simply cut off.
+ * The scale is therefore also bounded by the node's own height, keeping the bar
+ * under MAX_TITLEBAR_HEIGHT_RATIO of it. Tall nodes are unaffected (their height
+ * never binds); pass height 0 for collapsed/auto-height nodes to skip the bound.
+ */
+export function nodeChromeScale(viewportScale: number, nodeHeight: number, nodeWidth = 0): number {
+  if (!Number.isFinite(viewportScale) || viewportScale >= 1) return 1;
+  const zoomScale = Math.min(2.2, 1 / Math.max(viewportScale, 0.01));
+  let bounded = zoomScale;
+  if (Number.isFinite(nodeHeight) && nodeHeight > 0) {
+    bounded = Math.min(bounded, (nodeHeight * MAX_TITLEBAR_HEIGHT_RATIO) / AUTO_FIT_TITLEBAR_HEIGHT);
+  }
+  // Width matters as much as height: the icon, pill and control cluster are all
+  // flex-shrink: 0, so the NAME is the only thing that gives way. Unbounded, a
+  // 360px step node at 52% zoom spent 100 of 187 bar pixels on controls alone and
+  // the title collapsed to nothing. Bound the scale so the fixed chrome can never
+  // take more than MAX_TITLEBAR_CHROME_WIDTH_RATIO of the node.
+  if (Number.isFinite(nodeWidth) && nodeWidth > 0) {
+    bounded = Math.min(bounded, (nodeWidth * MAX_TITLEBAR_CHROME_WIDTH_RATIO) / TITLEBAR_CHROME_BASE_WIDTH);
+  }
+  return Math.max(1, bounded);
+}
+
 interface CanvasNodeProps {
   node: CanvasNodeState;
   children: preact.ComponentChildren;
@@ -220,7 +259,7 @@ export function CanvasNode({ node, children, onContextMenu }: CanvasNodeProps) {
   const isGroup = node.type === 'group';
   const isStrictSize = node.data.strictSize === true;
   const viewportScale = Math.max(viewport.value.scale, 0.01);
-  const chromeScale = viewportScale < 1 ? Math.min(2.2, 1 / viewportScale) : 1;
+  const chromeScale = nodeChromeScale(viewportScale, node.collapsed ? 0 : node.size.height, node.size.width);
 
   const groupColor = isGroup && node.data.color ? (node.data.color as string) : undefined;
   const nodeStyle: Record<string, string | number> = {
@@ -261,9 +300,13 @@ export function CanvasNode({ node, children, onContextMenu }: CanvasNodeProps) {
             return <NodeIcon size={Math.round(14 * chromeScale)} />;
           })()}
         </span>
-        <span class="node-type-badge">{TYPE_LABELS[node.type]}</span>
-        {typeof node.data.axWorkStatus === 'string' && (
+        {/* The icon already says what type this is, so the type badge yields to
+            the status chip rather than stacking two pills in front of the name —
+            on a narrow node that combination pushed the title to an ellipsis. */}
+        {typeof node.data.axWorkStatus === 'string' ? (
           <span class={`node-ax-status node-ax-status-${node.data.axWorkStatus}`}>{node.data.axWorkStatus}</span>
+        ) : (
+          <span class="node-type-badge">{TYPE_LABELS[node.type]}</span>
         )}
         {renaming ? (
           <input
@@ -278,7 +321,7 @@ export function CanvasNode({ node, children, onContextMenu }: CanvasNodeProps) {
             onClick={(e) => e.stopPropagation()}
           />
         ) : (
-          <span class="node-title" onDblClick={handleTitleDblClick} title="Double-click to rename">
+          <span class="node-title" onDblClick={handleTitleDblClick} title={`${title} — double-click to rename`}>
             {title}
           </span>
         )}
@@ -356,6 +399,12 @@ export function CanvasNode({ node, children, onContextMenu }: CanvasNodeProps) {
       {!node.collapsed && (
         <div ref={bodyRef} class="node-body">
           {children}
+          {/* AX flow step controls — rendered here rather than in a node renderer
+              because a materialized step can be ANY node type, and because the
+              body is what auto-fit measures (a footer outside it would be clipped
+              on a content-fitted node). Renders nothing unless the node carries a
+              `data.axStep` stamp. */}
+          <AxStepControls node={node} />
         </div>
       )}
       {!node.collapsed && (

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

@@ -13,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 {
@@ -405,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/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;
@@ -60,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/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>
+  );
+}