@principal-ai/subsystems-react 0.18.0 → 0.19.0

package/src/subsystem/SubsystemComponentGraph.tsx

@@ -32,7 +32,7 @@ import {
   applyNodeChanges,
 } from '@xyflow/react';
 import { useTheme } from '@principal-ade/industry-theme';
-import { ChevronDown, ChevronUp, X } from 'lucide-react';
+import { ChevronDown, ChevronUp, Pause, Play, X } from 'lucide-react';
 import { IndustryMarkdownSlide } from 'themed-markdown';
 import {
   buildSubsystemGraph,
@@ -58,6 +58,8 @@ const EDGE_LABEL_MAX_EDGE_FRACTION = 0.55;
 /** Rough monospace width at fontSize 10 + horizontal padding/border. */
 const EDGE_LABEL_CHAR_PX = 6.2;
 const EDGE_LABEL_PAD_PX = 18;
+/** Pause (ms) between steps when a throughline autoplays. */
+const THROUGHLINE_PLAY_PAUSE_MS = 2500;
 
 /** Context passed to `renderThroughlineViewer` when a flow/step is focused. */
 export interface ThroughlineViewerContext {
@@ -99,12 +101,37 @@ export interface SubsystemComponentGraphProps {
    * subsystem name visible as an overlay on the canvas.
    */
   hideSidebar?: boolean;
+  /**
+   * How throughline step highlighting behaves on the canvas.
+   * - `focus` (default): zoom to the step, hide non-participants, open drawer
+   * - `dim`: keep the full graph, dim non-participants (same as hovering a step)
+   */
+  throughlineStepMode?: 'focus' | 'dim';
+  /**
+   * When true, cycles throughline steps automatically using `dim` highlighting
+   * (no zoom, no drawer). Loops across all throughlines that have steps.
+   * Useful for graph-only embeds (`hideSidebar`).
+   */
+  autoPlayThroughlines?: boolean;
+  /** Pause between autoplay steps in ms. @default 2500 */
+  throughlineAutoPlayIntervalMs?: number;
+  /**
+   * When false, focusing a throughline/step does not call `fitView`.
+   * @default true
+   */
+  zoomOnThroughlineFocus?: boolean;
   /**
    * Subsystem title rendered as a non-interactive overlay chip on the graph
    * canvas (top-center). Does not trigger the sidebar — for graph-only
    * embeds that still need to name what they show.
    */
   graphTitle?: string;
+  /**
+   * When true, shows the active throughline's title as a non-interactive
+   * overlay chip on the canvas (under `graphTitle` when both are set).
+   * Uses the focused or hover-highlighted throughline.
+   */
+  showThroughlineTitle?: boolean;
   /** Markdown description rendered in the sidebar. */
   description?: string;
   /** Rendered over the graph canvas only (not the title/legend sidebar). */
@@ -183,7 +210,7 @@ interface InnerProps extends SubsystemComponentGraphProps {
   measured: { w: number; h: number } | null;
 }
 
-function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measured: _measured, maxNodeWidth, showEdgeLabels, title, hideSidebar, graphTitle, description, canvasOverlay, sidebarExtra, sidebarAfterDescription, renderFileView, renderFileViewer, renderThroughlineViewer, onFileSelect, onVerifyComponent, componentVerification }: InnerProps) {
+function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measured: _measured, maxNodeWidth, showEdgeLabels, title, hideSidebar, throughlineStepMode = 'focus', autoPlayThroughlines = false, throughlineAutoPlayIntervalMs = THROUGHLINE_PLAY_PAUSE_MS, zoomOnThroughlineFocus = true, graphTitle, showThroughlineTitle = false, description, canvasOverlay, sidebarExtra, sidebarAfterDescription, renderFileView, renderFileViewer, renderThroughlineViewer, onFileSelect, onVerifyComponent, componentVerification }: InnerProps) {
   const { theme } = useTheme();
   const { fitView } = useReactFlow();
   const viewport = useViewport();
@@ -202,6 +229,12 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
   const [focusedThroughlineId, setFocusedThroughlineId] = useState<string | null>(null);
   // `null` = whole flow focused; a number = that single step's edge focused.
   const [focusedStepIndex, setFocusedStepIndex] = useState<number | null>(null);
+  // Hovered step in the flows panel: dims every canvas node/edge not involved
+  // with that step (transient — no camera move, no drawer, no focus change).
+  const [hoveredThroughlineStep, setHoveredThroughlineStep] = useState<{
+    throughlineId: string;
+    stepIndex: number;
+  } | null>(null);
   // Sidebar bottom half: which panel is shown when throughlines exist.
   const [sidebarView, setSidebarView] = useState<'files' | 'flows'>(() =>
     throughlines?.length ? 'flows' : 'files',
@@ -233,6 +266,46 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
     return throughlines.find((t) => t.id === drawerTarget.throughlineId) ?? null;
   }, [drawerTarget, throughlines]);
 
+  // Throughline shown on the canvas title chip (focus or hover/autoplay highlight).
+  const overlayThroughlineTitle = useMemo(() => {
+    if (!showThroughlineTitle || !throughlines?.length) return null;
+    const id = focusedThroughlineId ?? hoveredThroughlineStep?.throughlineId;
+    if (!id) return null;
+    return throughlines.find((t) => t.id === id)?.title ?? null;
+  }, [
+    showThroughlineTitle,
+    throughlines,
+    focusedThroughlineId,
+    hoveredThroughlineStep,
+  ]);
+
+  // Active step for the bottom-of-title progress + annotation chip.
+  const overlayThroughlineStep = useMemo(() => {
+    if (!showThroughlineTitle || !throughlines?.length) return null;
+    const tlId = focusedThroughlineId ?? hoveredThroughlineStep?.throughlineId ?? null;
+    let stepIndex: number | null = null;
+    if (focusedThroughlineId != null) {
+      stepIndex = focusedStepIndex;
+    } else if (hoveredThroughlineStep != null) {
+      stepIndex = hoveredThroughlineStep.stepIndex;
+    }
+    if (tlId == null || stepIndex == null) return null;
+    const tl = throughlines.find((t) => t.id === tlId);
+    const step = tl?.steps[stepIndex];
+    if (!step || !tl) return null;
+    return {
+      index: stepIndex + 1,
+      total: tl.steps.length,
+      annotation: step.annotation,
+    };
+  }, [
+    showThroughlineTitle,
+    throughlines,
+    focusedThroughlineId,
+    focusedStepIndex,
+    hoveredThroughlineStep,
+  ]);
+
   const drawerTitle = useMemo(() => {
     if (!drawerTarget) return null;
     if (drawerTarget.kind === 'file') return drawerTarget.file;
@@ -398,11 +471,12 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
     return new Set(tl.steps.map((s) => s.edgeId));
   }, [throughlines, focusedThroughlineId, focusedStepIndex]);
 
-  // 1-based step numbers per edge of the selected flow (an edge can appear
-  // in more than one step).
+  // 1-based step numbers per edge of the active flow (focused or
+  // hover/autoplay-highlighted). An edge can appear in more than one step.
   const selectedFlowStepNos = useMemo(() => {
-    if (focusedThroughlineId == null || !throughlines) return null;
-    const tl = throughlines.find((t) => t.id === focusedThroughlineId);
+    const activeId = focusedThroughlineId ?? hoveredThroughlineStep?.throughlineId;
+    if (activeId == null || !throughlines) return null;
+    const tl = throughlines.find((t) => t.id === activeId);
     if (!tl) return null;
     const map = new Map<string, number[]>();
     tl.steps.forEach((s, i) => {
@@ -411,7 +485,7 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
       map.set(s.edgeId, list);
     });
     return map;
-  }, [throughlines, focusedThroughlineId]);
+  }, [throughlines, focusedThroughlineId, hoveredThroughlineStep]);
 
   // Union of every expanded (opened) throughline's edges — the visible set.
   const openedEdgeIds = useMemo(() => {
@@ -434,6 +508,19 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
     }
     return ids.size > 0 ? ids : null;
   };
+  // Edge/nodes involved in the hovered step — dim everything else.
+  const hoverEdgeIds = useMemo(() => {
+    if (!hoveredThroughlineStep || !throughlines) return null;
+    const tl = throughlines.find((t) => t.id === hoveredThroughlineStep.throughlineId);
+    if (!tl) return null;
+    const step = tl.steps[hoveredThroughlineStep.stepIndex];
+    return step ? new Set([step.edgeId]) : null;
+  }, [throughlines, hoveredThroughlineStep]);
+  const hoverNodeIds = useMemo(
+    () => endpointsOf(hoverEdgeIds),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [baseEdges, hoverEdgeIds],
+  );
   const openedNodeIds = useMemo(
     () => endpointsOf(openedEdgeIds),
     // eslint-disable-next-line react-hooks/exhaustive-deps
@@ -467,6 +554,8 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
   // `isSelected` rides in data because the node's stopPropagation() keeps
   // React Flow's own selection state from updating.
   const dispNodes = useMemo(() => {
+    // While a step is hovered, only the hovered step's endpoints stay bright;
+    // everything else is dimmed (never hidden) so the step's context survives.
     return xyflowNodesBase.map((n) => {
       // Boundary frames follow their members: hidden when no member is
       // visible, dimmed when members are dimmed. Never selectable.
@@ -478,13 +567,17 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
           anyOpened: openedNodeIds != null,
           anySelected: brightNodeIds != null,
         });
+        const dimmed = hoverNodeIds
+          ? !memberIds.some((id) => hoverNodeIds.has(id))
+          : vis.dimmed;
+        const hidden = hoverNodeIds ? false : vis.hidden;
         return {
           ...n,
-          hidden: vis.hidden,
+          hidden,
           selectable: false,
           data: {
             ...(n.data as object),
-            ...(vis.dimmed && { dimmed: true }),
+            ...(dimmed && { dimmed: true }),
           },
         };
       }
@@ -497,22 +590,24 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
         anyOpened: openedNodeIds != null,
         anySelected: brightNodeIds != null,
       });
-      if (fileMatch === undefined && !isSelected && !vis.dimmed) {
+      const dimmed = hoverNodeIds ? !hoverNodeIds.has(n.id) : vis.dimmed;
+      const hidden = hoverNodeIds ? false : vis.hidden;
+      if (fileMatch === undefined && !isSelected && !dimmed) {
         const { fileMatch: _f, isSelected: _s, dimmed: _d, ...rest } = n.data as Record<string, unknown>;
-        return { ...n, hidden: vis.hidden, data: rest };
+        return { ...n, hidden, data: rest };
       }
       return {
         ...n,
-        hidden: vis.hidden,
+        hidden,
         data: {
           ...(n.data as object),
           ...(fileMatch !== undefined && { fileMatch }),
           ...(isSelected && { isSelected }),
-          ...(vis.dimmed && { dimmed: true }),
+          ...(dimmed && { dimmed: true }),
         },
       };
     });
-  }, [xyflowNodesBase, openFile, selected, focusNodeIds, openedNodeIds, brightNodeIds]);
+  }, [xyflowNodesBase, openFile, selected, focusNodeIds, openedNodeIds, brightNodeIds, hoverNodeIds]);
 
   const baseNodesKey = useMemo(() => nodes.map((n) => n.id).sort().join(','), [nodes]);
   const baseEdgesKey = useMemo(
@@ -533,7 +628,7 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
         markerEnd: nextMarker,
       };
     };
-    if (openedEdgeIds || focusEdgeIds) {
+    if (openedEdgeIds || focusEdgeIds || hoverEdgeIds) {
       return baseEdges.map((e) => {
         const vis = flowElementVisibility({
           inOpened: openedEdgeIds?.has(e.id) === true,
@@ -541,12 +636,14 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
           anyOpened: openedEdgeIds != null,
           anySelected: focusEdgeIds != null,
         });
-        return { ...paint(e, vis.dimmed), hidden: vis.hidden };
+        const dimmed = hoverEdgeIds ? !hoverEdgeIds.has(e.id) : vis.dimmed;
+        const hidden = hoverEdgeIds ? false : vis.hidden;
+        return { ...paint(e, dimmed), hidden };
       });
     }
     if (!selectedEdgeId) return baseEdges;
     return baseEdges.map((e) => paint(e, e.id !== selectedEdgeId));
-  }, [baseEdges, selectedEdgeId, openedEdgeIds, focusEdgeIds]);
+  }, [baseEdges, selectedEdgeId, openedEdgeIds, focusEdgeIds, hoverEdgeIds]);
 
   const onNodesChange = useCallback(
     (changes: NodeChange[]) => {
@@ -672,6 +769,7 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
   // components the edge attaches to (and therefore the edge line between them).
   const fitFocusBounds = useCallback(
     (ids: ReadonlySet<string>) => {
+      if (!zoomOnThroughlineFocus) return;
       const nodeIds = new Set<string>();
       for (const e of baseEdges) {
         if (!ids.has(e.id)) continue;
@@ -685,7 +783,7 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
         duration: 300,
       });
     },
-    [baseEdges, fitView],
+    [baseEdges, fitView, zoomOnThroughlineFocus],
   );
 
   // Focus an entire flow: hide everything but the flow's nodes and edges, and
@@ -693,34 +791,54 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
   // reads as the narrative. No drawer: the code view only opens on a step
   // click. A stale throughline drawer (from a previously focused flow's step)
   // closes; an explicitly opened file drawer stays.
+  // In `dim` mode: clear step highlight and leave the full graph visible
+  // (no zoom / hide) — matching "step away from a hovered step".
   const focusThroughlineEdges = useCallback(
     (tl: SubsystemThroughline) => {
       setSelected(null);
       setSelectedEdgeId(null);
+      setHoveredThroughlineStep(null);
+      if (throughlineStepMode === 'dim') {
+        setFocusedStepIndex(null);
+        setFocusedThroughlineId(null);
+        setDrawerTarget((prev) => (prev?.kind === 'throughline' ? null : prev));
+        return;
+      }
       setFocusedStepIndex(null);
       setFocusedThroughlineId(tl.id);
       fitFocusBounds(new Set(tl.steps.map((s) => s.edgeId)));
       setDrawerTarget((prev) => (prev?.kind === 'throughline' ? null : prev));
     },
-    [fitFocusBounds],
+    [fitFocusBounds, throughlineStepMode],
   );
 
   const clearThroughlineFocus = useCallback(() => {
     setFocusedThroughlineId(null);
     setFocusedStepIndex(null);
+    setHoveredThroughlineStep(null);
     setDrawerTarget((prev) => (prev?.kind === 'throughline' ? null : prev));
   }, []);
 
   // Focus a single step's edge on the canvas and open/scroll the throughline
   // drawer to that step's snippet.
+  // In `dim` mode: only dim non-participants (same as hovering a step) —
+  // no camera move, no drawer, no hide.
   const focusThroughlineStep = useCallback(
     (tl: SubsystemThroughline, stepIndex: number) => {
       const step = tl.steps[stepIndex];
       if (!step) return;
       setSelected(null);
       setSelectedEdgeId(null);
+      if (throughlineStepMode === 'dim') {
+        setFocusedStepIndex(null);
+        setFocusedThroughlineId(null);
+        setHoveredThroughlineStep({ throughlineId: tl.id, stepIndex });
+        setDrawerTarget((prev) => (prev?.kind === 'throughline' ? null : prev));
+        return;
+      }
       setFocusedStepIndex(stepIndex);
       setFocusedThroughlineId(tl.id);
+      setHoveredThroughlineStep(null);
       fitFocusBounds(new Set([step.edgeId]));
       if (renderThroughlineViewer) {
         setDrawerTarget({
@@ -736,9 +854,45 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
         });
       }
     },
-    [fitFocusBounds, renderThroughlineViewer],
+    [fitFocusBounds, renderThroughlineViewer, throughlineStepMode],
   );
 
+  // Graph-only embeds: cycle throughline steps with hover-style dimming.
+  useEffect(() => {
+    if (!autoPlayThroughlines || !throughlines?.length || !layoutReady) return;
+    const playable = throughlines.filter((tl) => tl.steps.length > 0);
+    if (playable.length === 0) return;
+
+    let cancelled = false;
+    let tlIdx = 0;
+    let stepIdx = 0;
+    let timer: number | null = null;
+    const interval = Math.max(400, throughlineAutoPlayIntervalMs);
+
+    const tick = () => {
+      if (cancelled) return;
+      const tl = playable[tlIdx]!;
+      setSelected(null);
+      setSelectedEdgeId(null);
+      setFocusedThroughlineId(null);
+      setFocusedStepIndex(null);
+      setHoveredThroughlineStep({ throughlineId: tl.id, stepIndex: stepIdx });
+      stepIdx += 1;
+      if (stepIdx >= tl.steps.length) {
+        stepIdx = 0;
+        tlIdx = (tlIdx + 1) % playable.length;
+      }
+      timer = window.setTimeout(tick, interval);
+    };
+
+    tick();
+    return () => {
+      cancelled = true;
+      if (timer != null) window.clearTimeout(timer);
+      setHoveredThroughlineStep(null);
+    };
+  }, [autoPlayThroughlines, throughlines, throughlineAutoPlayIntervalMs, layoutReady]);
+
   // Arrow keys step through the focused throughline once a step is active
   // (sidebar click or drawer open). Ignores typing targets and chords.
   useEffect(() => {
@@ -1045,7 +1199,7 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
                     flex: 1,
                     minHeight: 0,
                     overflowY: 'auto',
-                    padding: '0 4px 12px',
+                    padding: '0 0 12px',
                   }}
                 >
                   {throughlines.map((tl) => (
@@ -1054,11 +1208,21 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
                       throughline={tl}
                       edges={edges}
                       collapsed={!expandedThroughlines.has(tl.id)}
-                      active={focusedThroughlineId === tl.id ? { stepIndex: focusedStepIndex } : null}
+                      active={
+                        focusedThroughlineId === tl.id
+                          ? { stepIndex: focusedStepIndex }
+                          : hoveredThroughlineStep?.throughlineId === tl.id
+                            ? { stepIndex: hoveredThroughlineStep.stepIndex }
+                            : null
+                      }
                       onToggleCollapsed={toggleThroughlineCollapsed}
                       onFocusFlow={focusThroughlineEdges}
                       onClearFocus={clearThroughlineFocus}
                       onFocusStep={focusThroughlineStep}
+                      onHoverStep={(tl, i) =>
+                        setHoveredThroughlineStep({ throughlineId: tl.id, stepIndex: i })
+                      }
+                      onLeaveStep={() => setHoveredThroughlineStep(null)}
                     />
                   ))}
                 </div>
@@ -1213,10 +1377,9 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
         <Background variant={BackgroundVariant.Dots} gap={16} size={1} />
         <Controls showZoom showFitView showInteractive />
       </ReactFlow>
-      {/* Graph title — non-interactive chip centered at the top of the canvas
-          (clear of the top-right declaration card). Lets graph-only embeds
-          name the subsystem they show. */}
-      {graphTitle && (
+      {/* Graph / throughline / step titles — non-interactive chips at the top
+          of the canvas. Graph-only embeds use these without opening the sidebar. */}
+      {(graphTitle || overlayThroughlineTitle || overlayThroughlineStep) && (
         <div
           style={{
             position: 'absolute',
@@ -1224,23 +1387,124 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
             left: '50%',
             transform: 'translateX(-50%)',
             zIndex: 6,
-            maxWidth: '60%',
-            overflow: 'hidden',
-            textOverflow: 'ellipsis',
-            whiteSpace: 'nowrap',
-            padding: '6px 18px',
-            fontSize: theme.fontSizes[3],
-            fontWeight: 600,
-            fontFamily: theme.fonts.monospace,
-            color: theme.colors.text,
-            background: theme.colors.backgroundSecondary ?? theme.colors.background,
-            border: `1px solid ${theme.colors.border}`,
-            borderRadius: 6,
-            boxShadow: '0 1px 4px rgba(0,0,0,0.25)',
+            display: 'flex',
+            flexDirection: 'column',
+            alignItems: 'center',
+            gap: 6,
+            maxWidth: '70%',
             pointerEvents: 'none',
           }}
         >
-          {graphTitle}
+          {graphTitle && (
+            <div
+              style={{
+                maxWidth: '100%',
+                overflow: 'hidden',
+                textOverflow: 'ellipsis',
+                whiteSpace: 'nowrap',
+                padding: '6px 18px',
+                fontSize: theme.fontSizes[3],
+                fontWeight: 600,
+                fontFamily: theme.fonts.monospace,
+                color: theme.colors.text,
+                background: theme.colors.backgroundSecondary ?? theme.colors.background,
+                border: `1px solid ${theme.colors.border}`,
+                borderRadius: 6,
+                boxShadow: '0 1px 4px rgba(0,0,0,0.25)',
+              }}
+            >
+              {graphTitle}
+            </div>
+          )}
+          {overlayThroughlineTitle && (
+            <div
+              style={{
+                maxWidth: '100%',
+                minWidth: overlayThroughlineStep ? 160 : undefined,
+                display: 'flex',
+                flexDirection: 'column',
+                background: theme.colors.backgroundSecondary ?? theme.colors.background,
+                border: `1px solid ${theme.colors.border}`,
+                borderRadius: 6,
+                boxShadow: '0 1px 4px rgba(0,0,0,0.25)',
+                overflow: 'hidden',
+                opacity: 0.95,
+              }}
+              aria-label={
+                overlayThroughlineStep
+                  ? `${overlayThroughlineTitle}, step ${overlayThroughlineStep.index} of ${overlayThroughlineStep.total}`
+                  : overlayThroughlineTitle
+              }
+            >
+              <div
+                style={{
+                  padding: '5px 14px',
+                  fontSize: theme.fontSizes[2] ?? theme.fontSizes[1],
+                  fontWeight: 600,
+                  fontFamily: theme.fonts.monospace,
+                  color: theme.colors.text,
+                  overflow: 'hidden',
+                  textOverflow: 'ellipsis',
+                  whiteSpace: 'nowrap',
+                  textAlign: 'center',
+                }}
+              >
+                {overlayThroughlineTitle}
+              </div>
+              {overlayThroughlineStep && overlayThroughlineStep.total > 0 && (
+                <div
+                  style={{
+                    display: 'flex',
+                    gap: 3,
+                    padding: '0 6px 5px',
+                  }}
+                  aria-hidden="true"
+                >
+                  {Array.from({ length: overlayThroughlineStep.total }, (_, i) => {
+                    const n = i + 1;
+                    const active = n === overlayThroughlineStep.index;
+                    const done = n < overlayThroughlineStep.index;
+                    return (
+                      <span
+                        key={n}
+                        style={{
+                          flex: 1,
+                          height: 2,
+                          borderRadius: 1,
+                          background: active
+                            ? (theme.colors.accent ?? theme.colors.primary ?? theme.colors.text)
+                            : done
+                              ? (theme.colors.textSecondary ?? theme.colors.text)
+                              : (theme.colors.border ?? 'rgba(127,127,127,0.45)'),
+                          opacity: active ? 1 : done ? 0.75 : 0.4,
+                          transition: 'opacity 120ms ease, background 120ms ease',
+                        }}
+                      />
+                    );
+                  })}
+                </div>
+              )}
+            </div>
+          )}
+          {overlayThroughlineStep?.annotation && (
+            <div
+              style={{
+                maxWidth: '100%',
+                padding: '6px 14px',
+                background: theme.colors.backgroundSecondary ?? theme.colors.background,
+                border: `1px solid ${theme.colors.border}`,
+                borderRadius: 6,
+                boxShadow: '0 1px 4px rgba(0,0,0,0.25)',
+                textAlign: 'center',
+                fontSize: theme.fontSizes[0],
+                fontFamily: theme.fonts.body,
+                color: theme.colors.textMuted ?? theme.colors.textSecondary,
+                lineHeight: 1.35,
+              }}
+            >
+              {overlayThroughlineStep.annotation}
+            </div>
+          )}
         </div>
       )}
         {/* Selected-component declaration — floating card over the canvas
@@ -1388,6 +1652,8 @@ function ThroughlineFlow({
   onFocusFlow,
   onClearFocus,
   onFocusStep,
+  onHoverStep,
+  onLeaveStep,
 }: {
   throughline: SubsystemThroughline;
   edges: SubsystemComponentEdge[];
@@ -1398,6 +1664,8 @@ function ThroughlineFlow({
   onFocusFlow: (tl: SubsystemThroughline) => void;
   onClearFocus: () => void;
   onFocusStep: (tl: SubsystemThroughline, stepIndex: number) => void;
+  onHoverStep: (tl: SubsystemThroughline, stepIndex: number) => void;
+  onLeaveStep: () => void;
 }) {
   const { theme } = useTheme();
   const muted = theme.colors.textMuted ?? theme.colors.textSecondary;
@@ -1406,8 +1674,52 @@ function ThroughlineFlow({
   const wholeFlowActive = active !== null && active.stepIndex === null;
   const [headerHover, setHeaderHover] = useState(false);
   const [closeHover, setCloseHover] = useState(false);
+  const [playHover, setPlayHover] = useState(false);
   const [hoveredStep, setHoveredStep] = useState<number | null>(null);
   const stepButtonRefs = useRef<(HTMLButtonElement | null)[]>([]);
+  // Autoplay: stepping through the flow's steps with a pause between each.
+  const [playing, setPlaying] = useState(false);
+  const playTimerRef = useRef<number | null>(null);
+
+  const stopPlaying = useCallback(() => {
+    if (playTimerRef.current != null) {
+      window.clearTimeout(playTimerRef.current);
+      playTimerRef.current = null;
+    }
+    setPlaying(false);
+  }, []);
+
+  // Clear any pending timer on unmount.
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  useEffect(() => () => stopPlaying(), []);
+
+  const startPlaying = useCallback(() => {
+    if (collapsed) onToggleCollapsed(throughline.id);
+    if (active === null || active.stepIndex !== null) onFocusFlow(throughline);
+    const stepCount = throughline.steps.length;
+    if (stepCount === 0) return;
+    setPlaying(true);
+    let i = 0;
+    const tick = () => {
+      if (i >= stepCount) {
+        playTimerRef.current = null;
+        setPlaying(false);
+        return;
+      }
+      onFocusStep(throughline, i);
+      i += 1;
+      playTimerRef.current = window.setTimeout(tick, THROUGHLINE_PLAY_PAUSE_MS);
+    };
+    tick();
+  }, [collapsed, active, onToggleCollapsed, onFocusFlow, throughline, onFocusStep]);
+
+  const togglePlay = useCallback(() => {
+    if (playing) {
+      stopPlaying();
+    } else {
+      startPlaying();
+    }
+  }, [playing, stopPlaying, startPlaying]);
 
   // Keep DOM focus on the active step so the browser focus ring (and
   // subsequent arrow keys) follow arrow navigation, not the originally
@@ -1418,7 +1730,7 @@ function ThroughlineFlow({
   }, [active?.stepIndex]);
 
   return (
-    <div style={{ margin: '4px 0', borderRadius: 8 }}>
+    <div>
       <div
         onMouseEnter={() => setHeaderHover(true)}
         onMouseLeave={() => setHeaderHover(false)}
@@ -1426,7 +1738,6 @@ function ThroughlineFlow({
           display: 'flex',
           alignItems: 'center',
           gap: 4,
-          borderRadius: 6,
           background: wholeFlowActive || headerHover ? hoverBg : 'transparent',
           transition: 'background 120ms ease',
         }}
@@ -1449,8 +1760,7 @@ function ThroughlineFlow({
             display: 'flex',
             alignItems: 'center',
             minWidth: 0,
-            padding: '6px 8px',
-            borderRadius: 6,
+            padding: '10px 8px',
             border: 'none',
             background: 'transparent',
             textAlign: 'left',
@@ -1472,6 +1782,35 @@ function ThroughlineFlow({
           </span>
         </button>
         {!collapsed && (
+          <>
+          <button
+            type="button"
+            aria-label={playing ? `Pause ${throughline.title} autoplay` : `Play ${throughline.title}`}
+            title={playing ? 'Pause' : 'Play through steps'}
+            onMouseEnter={() => setPlayHover(true)}
+            onMouseLeave={() => setPlayHover(false)}
+            onClick={(e) => {
+              e.stopPropagation();
+              togglePlay();
+            }}
+            style={{
+              display: 'inline-flex',
+              alignItems: 'center',
+              justifyContent: 'center',
+              flexShrink: 0,
+              width: 22,
+              height: 22,
+              padding: 0,
+              border: 'none',
+              borderRadius: 4,
+              background: playing || playHover ? theme.colors.border : 'transparent',
+              color: playing || playHover ? theme.colors.text : muted,
+              cursor: 'pointer',
+              transition: 'background 120ms ease, color 120ms ease',
+            }}
+          >
+            {playing ? <Pause size={12} strokeWidth={2} /> : <Play size={12} strokeWidth={2} />}
+          </button>
           <button
             type="button"
             aria-label={`Close ${throughline.title}`}
@@ -1501,6 +1840,7 @@ function ThroughlineFlow({
           >
             <X size={12} strokeWidth={2} />
           </button>
+          </>
         )}
       </div>
       {!collapsed && (
@@ -1517,15 +1857,21 @@ function ThroughlineFlow({
                   stepButtonRefs.current[i] = el;
                 }}
                 type="button"
-                onMouseEnter={() => setHoveredStep(i)}
-                onMouseLeave={() => setHoveredStep(null)}
+                onMouseEnter={() => {
+                  setHoveredStep(i);
+                  onHoverStep(throughline, i);
+                }}
+                onMouseLeave={() => {
+                  setHoveredStep(null);
+                  onLeaveStep();
+                }}
                 onClick={() => onFocusStep(throughline, i)}
                 style={{
                   display: 'flex',
                   alignItems: 'center',
                   gap: 8,
                   minWidth: 0,
-                  padding: '4px 8px 4px 12px',
+                  padding: '8px 8px 8px 12px',
                   textAlign: 'left',
                   borderRadius: 6,
                   border: 'none',
@@ -1554,9 +1900,9 @@ function ThroughlineFlow({
                       overflow: 'hidden',
                       textOverflow: 'ellipsis',
                       whiteSpace: 'nowrap',
-                      fontSize: theme.fontSizes[0],
+                      fontSize: theme.fontSizes[1],
                       fontFamily: theme.fonts.monospace,
-                      color: stepActive ? theme.colors.text : muted,
+                      color: theme.colors.text,
                     }}
                   >
                     {step.symbol}
@@ -1586,7 +1932,7 @@ function ThroughlineFlow({
                         whiteSpace: 'nowrap',
                         fontSize: theme.fontSizes[0],
                         fontFamily: theme.fonts.monospace,
-                        color: stepActive ? theme.colors.text : muted,
+                        color: theme.colors.text,
                       }}
                     >
                       {step.file.split('/').pop()}