feat(dashboard): workflow flow-graph island

graph_builder + ReactFlow nodes (step, start, end, gateway, child-workflow) and the animated status edge, with dagre layout and runtime status overlay.

Author: kasvith

durable_dashboard/assets/src/lib/graph-layout.ts

@@ -11,40 +11,83 @@
  */
 
 import dagre from "@dagrejs/dagre";
-import type { Edge, Node } from "@xyflow/react";
+import { type Edge, MarkerType, type Node } from "@xyflow/react";
 import type { GraphData, GraphEdge } from "./types";
 
 // ---------------------------------------------------------------------------
 // Sizing — must match the React node components in `assets/src/react/nodes`.
-// Every node is a uniform 88×96 cell (64×64 icon box + label region below)
-// for the n8n-inspired rhythm. See DESIGN.md §11.
+// Horizontal status cards (Argo/Dagster/GitHub-style), uniform height so the
+// LR ranks read like an execution timeline. `child_workflow` nodes share the
+// step cell's exact footprint — they're the same card with a stacked sheet
+// behind it (the drill-in signature), which only peeks a few px beyond the
+// box and so doesn't change the dagre footprint. See DESIGN.md §11.
 // ---------------------------------------------------------------------------
-const CELL_WIDTH = 88;
-const CELL_HEIGHT = 96;
-
-const NODESEP = 40;
-const RANKSEP = 80;
-const MARGIN = 32;
+const CELL_WIDTH = 200;
+const CELL_HEIGHT = 56;
+
+// Start/End render as small terminal pills, not full cards.
+const TERMINAL_WIDTH = 52;
+const TERMINAL_HEIGHT = 28;
+
+// Spacing chosen to keep neighbouring rows visually separate even when
+// goto branches force dagre to splay nodes onto extra rows. Previous
+// 40/80 was too tight (sub-row goto targets dipped *into* the main
+// lane); 60/110 was an improvement but still left branch-merge
+// patterns reading as "node sitting in a half-row dip." The current
+// 100/120 makes a goto sub-lane read as deliberate vertical
+// separation rather than misalignment.
+// Cards are wider + uniform-height now, so they need less vertical splay;
+// near-equal rank/node gaps read grid-like (Argo's ranksep≈nodesep insight).
+const NODESEP = 70;
+const RANKSEP = 110;
+const MARGIN = 40;
 
 const START_NODE_ID = "__durable_start__";
 const END_NODE_ID = "__durable_end__";
 
+const ARROW_MARKER = {
+  type: MarkerType.ArrowClosed,
+  width: 14,
+  height: 14,
+  color: "var(--muted-foreground)",
+};
+
 interface Dim {
   width: number;
   height: number;
 }
 
-// Every node renders as the same 88×96 cell (64 icon + 32 label). Keeps
-// the visual rhythm and makes dagre's collision math trivial.
-function dimsFor(_type: string): Dim {
+function dimsFor(type: string): Dim {
+  if (type === "start" || type === "end") {
+    return { width: TERMINAL_WIDTH, height: TERMINAL_HEIGHT };
+  }
+  // child_workflow shares the step cell footprint (see sizing note above).
   return { width: CELL_WIDTH, height: CELL_HEIGHT };
 }
 
 // ---------------------------------------------------------------------------
 // Public entry point
 // ---------------------------------------------------------------------------
 
-export function layoutGraph(graph: GraphData): { nodes: Node[]; edges: Edge[] } {
+type PositionMap = Map<string, { x: number; y: number }>;
+
+/**
+ * Lay out a graph for ReactFlow.
+ *
+ * `prevPositions` is the position map from a previous layout of the SAME
+ * topology. When supplied and complete (covers every node we're about to
+ * render, including the synthesized start/end markers), dagre is skipped
+ * and the cached coordinates are reused verbatim. This is what stops the
+ * canvas from re-laying-out and snapping nodes on every realtime status
+ * tick during an active run — the bug that made the graph "jump around"
+ * while a workflow was executing. The caller only passes `prevPositions`
+ * when the topology signature (node ids + types + edge ids) is unchanged,
+ * so reusing positions is always geometrically correct here.
+ */
+export function layoutGraph(
+  graph: GraphData,
+  prevPositions?: PositionMap,
+): { nodes: Node[]; edges: Edge[]; positions: PositionMap } {
   // Synthesize start/end markers wrapping the whole flow.
   const allNodes = [
     ...graph.nodes.map((n) => ({ id: n.id, type: n.type, data: n.data })),
@@ -60,7 +103,8 @@ export function layoutGraph(graph: GraphData): { nodes: Node[]; edges: Edge[] }
     ...leafIds.map((l) => boundaryEdge(l, END_NODE_ID)),
   ];
 
-  const positions = layoutDagre(allNodes, allEdges);
+  const canReuse = prevPositions !== undefined && allNodes.every((n) => prevPositions.has(n.id));
+  const positions = canReuse ? (prevPositions as PositionMap) : layoutDagre(allNodes, allEdges);
 
   const nodes: Node[] = allNodes.map((n) => {
     const pos = positions.get(n.id) || { x: 0, y: 0 };
@@ -81,9 +125,13 @@ export function layoutGraph(graph: GraphData): { nodes: Node[]; edges: Edge[] }
     label: e.label,
     className: e.className,
     type: "animated_flow",
+    // A subtle arrowhead reinforces execution direction. Neutral fill (a CSS
+    // var so it tracks the theme) keeps status legible on the stroke, not the
+    // marker. Suppressed into the END terminal so arrows don't pile on it.
+    markerEnd: e.target === END_NODE_ID ? undefined : ARROW_MARKER,
   }));
 
-  return { nodes, edges };
+  return { nodes, edges, positions };
 }
 
 // ---------------------------------------------------------------------------
@@ -135,6 +183,12 @@ function layoutDagre(
     ranksep: RANKSEP,
     marginx: MARGIN,
     marginy: MARGIN,
+    // `tight-tree` produces visibly cleaner layouts for branch-and-merge
+    // workflows than the default `network-simplex`: it keeps merging
+    // siblings on a clearly-distinct sub-lane rather than dropping them
+    // into a half-row dip below the main flow. n8n's editor uses a
+    // similar layered approach.
+    ranker: "tight-tree",
   });
 
   for (const n of nodes) {

durable_dashboard/assets/src/lib/types.ts

@@ -7,9 +7,17 @@
 
 export type StepStatus = "pending" | "running" | "completed" | "failed" | "waiting";
 
+// Types the server (`graph_builder.ex`) currently emits. `start`/`end` are
+// synthesized client-side in `graph-layout.ts`; `child_workflow` is the wider
+// n8n-style card for parallel/sub-workflow children. The `*_fork`/`*_join`
+// markers are no longer emitted (fan-out/in is pure edge geometry) but remain
+// in the union as a documented stale-BEAM fallback (mapped to HiddenNode).
 export type NodeType =
   | "step"
   | "decision"
+  | "child_workflow"
+  | "start"
+  | "end"
   | "branch_fork"
   | "branch_join"
   | "parallel_fork"
@@ -27,6 +35,24 @@ export interface GraphNode {
     duration_ms?: number;
     clause?: string;
     parallel?: boolean;
+    /** Set by `graph_builder.overlay_status/3` once a runtime step
+     * execution has been matched to this graph node. */
+    started_at?: string;
+    completed_at?: string;
+    step_execution_id?: string;
+    workflow_execution_id?: string;
+    is_current?: boolean;
+    /** Truncated 1-line JSON previews of step input/output, suitable for
+     * rendering in an n8n-style card. The full payload is fetched on
+     * demand when the user opens the side drawer — keeping the graph
+     * over-the-wire payload lean. */
+    input_preview?: string;
+    output_preview?: string;
+    has_error?: boolean;
+    /** Set when this step represents a parallel child running in its own
+     * `WorkflowExecution`. The card surfaces an expand/drill-in
+     * affordance and the LV translates the click into a navigate. */
+    child_workflow_id?: string;
   };
 }
 

durable_dashboard/assets/src/react/edges/animated_flow_edge.tsx

@@ -1,13 +1,15 @@
 /**
- * Workflow edge — bezier path with optional label chip rendered through
- * ReactFlow's portal. Status-driven stroke styling is applied via the
- * `flow-edge-{completed,running,pending}` classes set on the edge wrapper
- * by `graph_builder.overlay_status/3` (DESIGN.md §11). This component
- * focuses on label rendering; we keep edge stroke handled by CSS so the
- * theme can shift it without a re-render.
+ * Workflow edge — orthogonal **smoothstep** path with an optional label chip.
+ * Smoothstep (vs the old free bezier) is the load-bearing fix for "odd
+ * branching": edges leave the source's right face, run straight, then step to
+ * each target's Y, so fan-out/fan-in form clean parallel trunks instead of
+ * overlapping swoops (the Argo/Dagster/GitHub-Actions look). Status stroke is
+ * applied via the `flow-edge-{completed,running,pending,conditional}` classes
+ * set by `graph_builder.overlay_status/3` (DESIGN.md §11), so the theme/status
+ * can shift the stroke without a re-render.
  */
 
-import { BaseEdge, EdgeLabelRenderer, type EdgeProps, getBezierPath } from "@xyflow/react";
+import { BaseEdge, EdgeLabelRenderer, type EdgeProps, getSmoothStepPath } from "@xyflow/react";
 import { memo } from "react";
 
 function AnimatedFlowEdgeComponent({
@@ -21,13 +23,17 @@ function AnimatedFlowEdgeComponent({
   label,
   markerEnd,
 }: EdgeProps) {
-  const [path, labelX, labelY] = getBezierPath({
+  const [path, labelX, labelY] = getSmoothStepPath({
     sourceX,
     sourceY,
     targetX,
     targetY,
     sourcePosition,
     targetPosition,
+    // Soft modern corners + a 20px straight run out of each handle so sibling
+    // branches share a clean trunk before splaying to their lanes.
+    borderRadius: 8,
+    offset: 20,
   });
 
   return (

durable_dashboard/assets/src/react/flow_graph.tsx

@@ -18,13 +18,15 @@ import {
   type Node,
   ReactFlow,
   ReactFlowProvider,
+  useReactFlow,
 } from "@xyflow/react";
-import { useEffect, useMemo, useState } from "react";
+import { useEffect, useMemo, useRef, useState } from "react";
 import { createRoot, type Root } from "react-dom/client";
 import { layoutGraph } from "../lib/graph-layout";
 import { resolveToken } from "../lib/tokens";
 import type { GraphData } from "../lib/types";
 import { AnimatedFlowEdge } from "./edges/animated_flow_edge";
+import { ChildWorkflowNode } from "./nodes/child_workflow_node";
 import { EndNode } from "./nodes/end_node";
 import { GatewayNode } from "./nodes/gateway_node";
 import { HiddenNode } from "./nodes/hidden_node";
@@ -39,11 +41,16 @@ import { StepNode } from "./nodes/step_node";
 // `HiddenNode` fallback so a stale BEAM that still emits them doesn't
 // surface as floating "Parallel" / "Join" text on the canvas (which is
 // what ReactFlow's default node renderer would do for unknown types).
+//
+// `child_workflow` is the n8n-style wider card emitted by
+// `graph_builder.attach_child_workflow_id/2` for parallel children that
+// have their own WorkflowExecution row — see DESIGN.md §11.
 const NODE_TYPES = {
   step: StepNode,
   decision: GatewayNode,
   start: StartNode,
   end: EndNode,
+  child_workflow: ChildWorkflowNode,
   parallel_fork: HiddenNode,
   parallel_join: HiddenNode,
   branch_fork: HiddenNode,
@@ -108,8 +115,34 @@ interface FlowIslandRootProps {
   ) => void;
 }
 
+// Topology signature: node ids + types + edge ids. Status/data/className
+// changes do NOT alter it. The layout (dagre) only needs to re-run when this
+// changes; a realtime status tick keeps the same signature and reuses cached
+// positions, so the canvas no longer reflows on every update.
+function topoSignature(graph: GraphData): string {
+  const nodes = graph.nodes
+    .map((n) => `${n.id}:${n.type}`)
+    .sort()
+    .join("|");
+  const edges = graph.edges
+    .map((e) => e.id)
+    .sort()
+    .join("|");
+  return `${nodes}__${edges}`;
+}
+
 function FlowIslandRoot({ initialGraph, registerHandlers }: FlowIslandRootProps) {
   const [graph, setGraphState] = useState<GraphData>(initialGraph);
+  const { fitView } = useReactFlow();
+
+  // Cache of the last layout's positions + the topology they belong to.
+  const layoutRef = useRef<{
+    sig: string;
+    positions: Map<string, { x: number; y: number }>;
+  }>({ sig: "", positions: new Map() });
+  // Fit the viewport on first paint and whenever topology grows/shrinks,
+  // never on a plain status tick (which would yank the viewport mid-read).
+  const fitPendingRef = useRef(true);
 
   useEffect(() => {
     registerHandlers(
@@ -126,31 +159,60 @@ function FlowIslandRoot({ initialGraph, registerHandlers }: FlowIslandRootProps)
     );
   }, [registerHandlers]);
 
-  const { nodes, edges } = useMemo(() => layoutGraph(graph), [graph]);
+  const { nodes, edges } = useMemo(() => {
+    const sig = topoSignature(graph);
+    const reuse = sig === layoutRef.current.sig && layoutRef.current.positions.size > 0;
+    const result = layoutGraph(graph, reuse ? layoutRef.current.positions : undefined);
+    layoutRef.current = { sig, positions: result.positions };
+    if (!reuse) fitPendingRef.current = true;
+    return { nodes: result.nodes, edges: result.edges };
+  }, [graph]);
+
+  // Re-fit only when a relayout happened (topology change / first paint).
+  // requestAnimationFrame lets ReactFlow measure the new nodes first.
+  useEffect(() => {
+    if (!fitPendingRef.current || nodes.length === 0) return;
+    fitPendingRef.current = false;
+    const raf = requestAnimationFrame(() => fitView({ padding: 0.2, duration: 200 }));
+    return () => cancelAnimationFrame(raf);
+  }, [nodes, fitView]);
 
   return (
     <ReactFlow
       nodes={nodes as Node[]}
       edges={edges as Edge[]}
       nodeTypes={NODE_TYPES}
       edgeTypes={EDGE_TYPES}
-      fitView
       fitViewOptions={{ padding: 0.2 }}
       proOptions={{ hideAttribution: true }}
       defaultEdgeOptions={{ type: "animated_flow" }}
       minZoom={0.2}
-      maxZoom={1.5}
+      maxZoom={2}
+      // Explicit viewport interaction props — defaults are already on
+      // for these, but spelling them out makes the intent obvious and
+      // guards against silent regressions. Dashboard users should be
+      // able to zoom, pan, and rearrange nodes when inspecting a run.
+      nodesDraggable
+      nodesConnectable={false}
+      panOnDrag
+      zoomOnScroll
+      zoomOnPinch
+      panOnScroll={false}
+      selectionOnDrag={false}
     >
       <Background gap={24} size={1} />
       <Controls position="bottom-right" showInteractive={false} />
       <MiniMap
         position="top-right"
         nodeStrokeWidth={1}
+        nodeBorderRadius={4}
         pannable
         zoomable
         nodeColor={miniMapNodeColor}
         nodeStrokeColor={miniMapNodeStroke}
-        maskColor={resolveToken("--background", "rgba(0,0,0,0.5)")}
+        // Translucent mask (was a solid --background that read as an all-black
+        // wash hiding the nodes). A CSS color-mix string stays theme-reactive.
+        maskColor="color-mix(in oklch, var(--background) 55%, transparent)"
       />
     </ReactFlow>
   );