@principal-ai/subsystems-react 0.18.0 → 0.19.1

package/dist/subsystem/SubsystemComponentGraph.js

@@ -15,7 +15,7 @@ import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-run
 import { memo, useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { ReactFlow, ReactFlowProvider, Background, BackgroundVariant, Controls, useReactFlow, useViewport, 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, MECHANISM_COLOR, MECHANISM_DESCRIPTIONS, subsystemGraphLayoutKey, } from './model';
 import { SubsystemComponentNode, SubsystemGroupNode, SubsystemEdge, SUBSYSTEM_CALLBACKS, hexWithAlpha, EDGE_DIM_ALPHA, fileMatchForNode, flowElementVisibility } from './nodes';
@@ -29,6 +29,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;
 const nodeTypes = {
     'subsystem-component': SubsystemComponentNode,
     'subsystem-group': SubsystemGroupNode,
@@ -46,7 +48,7 @@ const FileDrawerContent = memo(function FileDrawerContent({ render, file, startL
 const ThroughlineDrawerContent = memo(function ThroughlineDrawerContent({ render, throughline, stepIndex, }) {
     return _jsx(_Fragment, { children: render({ throughline, stepIndex }) });
 });
-function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measured: _measured, maxNodeWidth, showEdgeLabels, title, hideSidebar, graphTitle, description, canvasOverlay, sidebarExtra, sidebarAfterDescription, renderFileView, renderFileViewer, renderThroughlineViewer, onFileSelect, onVerifyComponent, componentVerification }) {
+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 }) {
     const { theme } = useTheme();
     const { fitView } = useReactFlow();
     const viewport = useViewport();
@@ -65,6 +67,9 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
     const [focusedThroughlineId, setFocusedThroughlineId] = useState(null);
     // `null` = whole flow focused; a number = that single step's edge focused.
     const [focusedStepIndex, setFocusedStepIndex] = useState(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(null);
     // Sidebar bottom half: which panel is shown when throughlines exist.
     const [sidebarView, setSidebarView] = useState(() => throughlines?.length ? 'flows' : 'files');
     // Throughline flows the user has expanded (via the title row). Closed by
@@ -76,6 +81,42 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
     const [descToggleHover, setDescToggleHover] = useState(false);
     // `true` only when a description exists AND the user opened it.
     const showDesc = !!description && descriptionVisible;
+    // Sidebar width (px). Draggable via the resize handle between the sidebar
+    // and the graph canvas; clamps to sensible bounds while dragging.
+    const [sidebarWidth, setSidebarWidth] = useState(340);
+    const [sidebarDrag, setSidebarDrag] = useState(false);
+    const sidebarDragStartX = useRef(0);
+    const sidebarDragStartWidth = useRef(340);
+    const sidebarMinWidth = 240;
+    const sidebarMaxWidth = useMemo(() => Math.max(Math.min((_measured?.w ?? 680) * 0.5, 600), sidebarMinWidth), [_measured?.w]);
+    // Resize drag: capture the drag state so document-level move/up listeners
+    // stay attached for the duration of the gesture, then release on mouseup.
+    const onSidebarResizeStart = useCallback((e) => {
+        e.preventDefault();
+        sidebarDragStartX.current = e.clientX;
+        sidebarDragStartWidth.current = sidebarWidth;
+        setSidebarDrag(true);
+    }, [sidebarWidth]);
+    useEffect(() => {
+        if (!sidebarDrag)
+            return;
+        const onMove = (e) => {
+            const delta = e.clientX - sidebarDragStartX.current;
+            const next = Math.min(Math.max(sidebarDragStartWidth.current + delta, sidebarMinWidth), sidebarMaxWidth);
+            setSidebarWidth(next);
+        };
+        const onUp = () => {
+            setSidebarDrag(false);
+            // Re-fit the canvas so the graph re-centers in the new available space.
+            requestAnimationFrame(() => fitView());
+        };
+        document.addEventListener('mousemove', onMove);
+        document.addEventListener('mouseup', onUp);
+        return () => {
+            document.removeEventListener('mousemove', onMove);
+            document.removeEventListener('mouseup', onUp);
+        };
+    }, [sidebarDrag, sidebarMaxWidth, fitView]);
     // Ref mirror of `selected` so the SUBSYSTEM_CALLBACKS click handler (a
     // closure over the effect deps) can toggle without a stale value.
     const selectedRef = useRef(null);
@@ -92,6 +133,50 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
             return null;
         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 = 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;
@@ -253,12 +338,13 @@ 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)
+        const activeId = focusedThroughlineId ?? hoveredThroughlineStep?.throughlineId;
+        if (activeId == null || !throughlines)
             return null;
-        const tl = throughlines.find((t) => t.id === focusedThroughlineId);
+        const tl = throughlines.find((t) => t.id === activeId);
         if (!tl)
             return null;
         const map = new Map();
@@ -268,7 +354,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(() => {
         if (!throughlines || expandedThroughlines.size === 0)
@@ -294,6 +380,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
     [baseEdges, openedEdgeIds]);
@@ -323,6 +422,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.
@@ -334,13 +435,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,
-                        ...(vis.dimmed && { dimmed: true }),
+                        ...(dimmed && { dimmed: true }),
                     },
                 };
             }
@@ -353,22 +458,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;
-                return { ...n, hidden: vis.hidden, data: rest };
+                return { ...n, hidden, data: rest };
             }
             return {
                 ...n,
-                hidden: vis.hidden,
+                hidden,
                 data: {
                     ...n.data,
                     ...(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(() => convertedEdges.map((e) => e.id).sort().join(','), [convertedEdges]);
     const dispEdges = useMemo(() => {
@@ -383,7 +490,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,
@@ -391,13 +498,15 @@ 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) => {
         // Capture dimension changes (React Flow's measurement callback).
         // Group parents are ELK-sized — ignore their measurements.
@@ -492,6 +601,8 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
     // live positions + measured dims — so the frame always includes BOTH
     // components the edge attaches to (and therefore the edge line between them).
     const fitFocusBounds = useCallback((ids) => {
+        if (!zoomOnThroughlineFocus)
+            return;
         const nodeIds = new Set();
         for (const e of baseEdges) {
             if (!ids.has(e.id))
@@ -506,35 +617,55 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
             padding: 0.25,
             duration: 300,
         });
-    }, [baseEdges, fitView]);
+    }, [baseEdges, fitView, zoomOnThroughlineFocus]);
     // Focus an entire flow: hide everything but the flow's nodes and edges, and
     // frame the flow on the canvas. Selection state is cleared — the graph now
     // 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) => {
         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, stepIndex) => {
         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({
@@ -550,7 +681,43 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
                 startLine: step.line,
             });
         }
-    }, [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 = 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(() => {
@@ -679,9 +846,9 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
     const throughlineViewerRef = useRef(renderThroughlineViewer);
     throughlineViewerRef.current = renderThroughlineViewer;
     const renderThroughlineDrawerContent = useCallback((ctx) => throughlineViewerRef.current?.(ctx) ?? null, []);
-    return (_jsxs("div", { style: { width: '100%', height: '100%', display: 'flex', flexDirection: 'row' }, children: [!hideSidebar && (title || description || sidebarExtra || sidebarAfterDescription || treeFilePaths.length > 0 || hasThroughlines) && (_jsxs("div", { style: {
-                    width: 340,
-                    minWidth: 340,
+    return (_jsxs("div", { style: { width: '100%', height: '100%', display: 'flex', flexDirection: 'row', userSelect: sidebarDrag ? 'none' : undefined }, children: [!hideSidebar && (title || description || sidebarExtra || sidebarAfterDescription || treeFilePaths.length > 0 || hasThroughlines) && (_jsxs("div", { style: {
+                    width: sidebarWidth,
+                    minWidth: sidebarWidth,
                     borderRight: `1px solid ${theme.colors.border}`,
                     background: theme.colors.backgroundSecondary ?? theme.colors.background,
                     display: 'flex',
@@ -749,8 +916,12 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
                                     flex: 1,
                                     minHeight: 0,
                                     overflowY: 'auto',
-                                    padding: '0 4px 12px',
-                                }, children: throughlines.map((tl) => (_jsx(ThroughlineFlow, { throughline: tl, edges: edges, collapsed: !expandedThroughlines.has(tl.id), active: focusedThroughlineId === tl.id ? { stepIndex: focusedStepIndex } : null, onToggleCollapsed: toggleThroughlineCollapsed, onFocusFlow: focusThroughlineEdges, onClearFocus: clearThroughlineFocus, onFocusStep: focusThroughlineStep }, tl.id))) })) : treeFilePaths.length > 0 ? (_jsx(_Fragment, { children: repoGroups.groups.map((group, i) => {
+                                    padding: '0 0 12px',
+                                }, children: throughlines.map((tl) => (_jsx(ThroughlineFlow, { throughline: tl, edges: edges, collapsed: !expandedThroughlines.has(tl.id), 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) }, tl.id))) })) : treeFilePaths.length > 0 ? (_jsx(_Fragment, { children: repoGroups.groups.map((group, i) => {
                                     const groupKey = group.repoKey ?? '__no-repo__';
                                     const collapsed = collapsedRepos.has(groupKey);
                                     return (_jsxs("div", { style: {
@@ -760,7 +931,14 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
                                             flexDirection: 'column',
                                             borderTop: i > 0 ? `1px solid ${theme.colors.border}` : undefined,
                                         }, children: [repoGroups.multiRepo && (_jsx(RepoGroupHeader, { group: group, collapsed: collapsed, onToggle: () => toggleRepoCollapsed(groupKey) })), !collapsed && (_jsx(SubsystemFileTree, { files: group.entries.map((e) => e.displayPath), selectedFile: selected?.file ?? openFile, hoveredFile: hoveredFile, onSelectFile: onTreeSelectFile, headerless: repoGroups.multiRepo }))] }, groupKey));
-                                }) })) : null] }))] })), _jsxs("div", { style: { flex: 1, position: 'relative', display: 'flex', flexDirection: 'column', minHeight: 0 }, children: [_jsxs("div", { style: { position: 'relative', flex: 1, minHeight: 0, display: 'flex', flexDirection: 'column' }, children: [showEdgeLabels !== false && (_jsx("div", { style: {
+                                }) })) : null] }))] })), !hideSidebar && (title || description || sidebarExtra || sidebarAfterDescription || treeFilePaths.length > 0 || hasThroughlines) && (_jsx("div", { onMouseDown: onSidebarResizeStart, "aria-label": "Resize sidebar", title: "Drag to resize", style: {
+                    width: 3,
+                    flexShrink: 0,
+                    cursor: 'col-resize',
+                    background: theme.colors.border,
+                    transition: 'background 120ms ease',
+                    zIndex: 1,
+                } })), _jsxs("div", { style: { flex: 1, position: 'relative', display: 'flex', flexDirection: 'column', minHeight: 0 }, children: [_jsxs("div", { style: { position: 'relative', flex: 1, minHeight: 0, display: 'flex', flexDirection: 'column' }, children: [showEdgeLabels !== false && (_jsx("div", { style: {
                                     position: 'absolute',
                                     inset: 0,
                                     overflow: 'hidden',
@@ -816,27 +994,88 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
                                     flex: 1,
                                     minHeight: 0,
                                     background: theme.colors.background,
-                                }, children: [_jsx(Background, { variant: BackgroundVariant.Dots, gap: 16, size: 1 }), _jsx(Controls, { showZoom: true, showFitView: true, showInteractive: true })] }, `${baseNodesKey}-${baseEdgesKey}`), graphTitle && (_jsx("div", { style: {
+                                }, children: [_jsx(Background, { variant: BackgroundVariant.Dots, gap: 16, size: 1 }), _jsx(Controls, { showZoom: true, showFitView: true, showInteractive: true })] }, `${baseNodesKey}-${baseEdgesKey}`), (graphTitle || overlayThroughlineTitle || overlayThroughlineStep) && (_jsxs("div", { style: {
                                     position: 'absolute',
                                     top: 10,
                                     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',
-                                }, children: graphTitle })), selected && (_jsx("div", { style: {
+                                }, children: [graphTitle && (_jsx("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)',
+                                        }, children: graphTitle })), overlayThroughlineTitle && (_jsxs("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, children: [_jsx("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',
+                                                }, children: overlayThroughlineTitle }), overlayThroughlineStep && overlayThroughlineStep.total > 0 && (_jsx("div", { style: {
+                                                    display: 'flex',
+                                                    gap: 3,
+                                                    padding: '0 6px 5px',
+                                                }, "aria-hidden": "true", children: Array.from({ length: overlayThroughlineStep.total }, (_, i) => {
+                                                    const n = i + 1;
+                                                    const active = n === overlayThroughlineStep.index;
+                                                    const done = n < overlayThroughlineStep.index;
+                                                    return (_jsx("span", { 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',
+                                                        } }, n));
+                                                }) }))] })), overlayThroughlineStep?.annotation && (_jsx("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,
+                                        }, children: overlayThroughlineStep.annotation }))] })), selected && (_jsx("div", { style: {
                                     position: 'absolute',
                                     top: 10,
                                     right: 10,
@@ -896,7 +1135,7 @@ function RepoGroupHeader({ group, collapsed, onToggle, }) {
  *  title: closed → open + select; open and unselected → select; open and
  *  selected → close + clear focus. The right-aligned close button collapses
  *  without selecting. A step row focuses that step's edge. */
-function ThroughlineFlow({ throughline, edges, collapsed, active, onToggleCollapsed, onFocusFlow, onClearFocus, onFocusStep, }) {
+function ThroughlineFlow({ throughline, edges, collapsed, active, onToggleCollapsed, onFocusFlow, onClearFocus, onFocusStep, onHoverStep, onLeaveStep, }) {
     const { theme } = useTheme();
     const muted = theme.colors.textMuted ?? theme.colors.textSecondary;
     const hoverBg = theme.colors.background;
@@ -904,8 +1143,52 @@ function ThroughlineFlow({ throughline, edges, collapsed, active, onToggleCollap
     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(null);
     const stepButtonRefs = useRef([]);
+    // Autoplay: stepping through the flow's steps with a pause between each.
+    const [playing, setPlaying] = useState(false);
+    const playTimerRef = useRef(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
     // clicked button.
@@ -914,11 +1197,10 @@ function ThroughlineFlow({ throughline, edges, collapsed, active, onToggleCollap
             return;
         stepButtonRefs.current[active.stepIndex]?.focus({ preventScroll: true });
     }, [active?.stepIndex]);
-    return (_jsxs("div", { style: { margin: '4px 0', borderRadius: 8 }, children: [_jsxs("div", { onMouseEnter: () => setHeaderHover(true), onMouseLeave: () => setHeaderHover(false), style: {
+    return (_jsxs("div", { children: [_jsxs("div", { onMouseEnter: () => setHeaderHover(true), onMouseLeave: () => setHeaderHover(false), style: {
                     display: 'flex',
                     alignItems: 'center',
                     gap: 4,
-                    borderRadius: 6,
                     background: wholeFlowActive || headerHover ? hoverBg : 'transparent',
                     transition: 'background 120ms ease',
                 }, children: [_jsx("button", { type: "button", onClick: () => {
@@ -938,8 +1220,7 @@ function ThroughlineFlow({ throughline, edges, collapsed, active, onToggleCollap
                             display: 'flex',
                             alignItems: 'center',
                             minWidth: 0,
-                            padding: '6px 8px',
-                            borderRadius: 6,
+                            padding: '10px 8px',
                             border: 'none',
                             background: 'transparent',
                             textAlign: 'left',
@@ -952,39 +1233,62 @@ function ThroughlineFlow({ throughline, edges, collapsed, active, onToggleCollap
                                 fontFamily: theme.fonts.monospace,
                                 fontWeight: 600,
                                 color: theme.colors.text,
-                            }, children: throughline.title }) }), !collapsed && (_jsx("button", { type: "button", "aria-label": `Close ${throughline.title}`, onMouseEnter: () => setCloseHover(true), onMouseLeave: () => setCloseHover(false), onClick: (e) => {
-                            e.stopPropagation();
-                            onToggleCollapsed(throughline.id);
-                            if (active !== null)
-                                onClearFocus();
-                        }, style: {
-                            display: 'inline-flex',
-                            alignItems: 'center',
-                            justifyContent: 'center',
-                            flexShrink: 0,
-                            width: 22,
-                            height: 22,
-                            marginRight: 4,
-                            padding: 0,
-                            border: 'none',
-                            borderRadius: 4,
-                            background: closeHover ? theme.colors.border : 'transparent',
-                            color: closeHover ? theme.colors.text : muted,
-                            cursor: 'pointer',
-                            transition: 'background 120ms ease, color 120ms ease',
-                        }, children: _jsx(X, { size: 12, strokeWidth: 2 }) }))] }), !collapsed && (_jsx("div", { style: { display: 'flex', flexDirection: 'column', gap: 1 }, children: throughline.steps.map((step, i) => {
+                            }, children: throughline.title }) }), !collapsed && (_jsxs(_Fragment, { children: [_jsx("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',
+                                }, children: playing ? _jsx(Pause, { size: 12, strokeWidth: 2 }) : _jsx(Play, { size: 12, strokeWidth: 2 }) }), _jsx("button", { type: "button", "aria-label": `Close ${throughline.title}`, onMouseEnter: () => setCloseHover(true), onMouseLeave: () => setCloseHover(false), onClick: (e) => {
+                                    e.stopPropagation();
+                                    onToggleCollapsed(throughline.id);
+                                    if (active !== null)
+                                        onClearFocus();
+                                }, style: {
+                                    display: 'inline-flex',
+                                    alignItems: 'center',
+                                    justifyContent: 'center',
+                                    flexShrink: 0,
+                                    width: 22,
+                                    height: 22,
+                                    marginRight: 4,
+                                    padding: 0,
+                                    border: 'none',
+                                    borderRadius: 4,
+                                    background: closeHover ? theme.colors.border : 'transparent',
+                                    color: closeHover ? theme.colors.text : muted,
+                                    cursor: 'pointer',
+                                    transition: 'background 120ms ease, color 120ms ease',
+                                }, children: _jsx(X, { size: 12, strokeWidth: 2 }) })] }))] }), !collapsed && (_jsx("div", { style: { display: 'flex', flexDirection: 'column', gap: 1 }, children: throughline.steps.map((step, i) => {
                     const edge = edgeById.get(step.edgeId);
                     const mech = edge?.mechanism;
                     const color = mech ? MECHANISM_COLOR[mech] : muted;
                     const stepActive = active !== null && active.stepIndex === i;
                     return (_jsxs("button", { ref: (el) => {
                             stepButtonRefs.current[i] = el;
-                        }, type: "button", onMouseEnter: () => setHoveredStep(i), onMouseLeave: () => setHoveredStep(null), onClick: () => onFocusStep(throughline, i), style: {
+                        }, type: "button", 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',
@@ -1004,9 +1308,9 @@ function ThroughlineFlow({ throughline, edges, collapsed, active, onToggleCollap
                                     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,
                                 }, children: step.symbol })) : (_jsxs(_Fragment, { children: [_jsx("span", { style: {
                                             flexShrink: 0,
                                             width: 74,
@@ -1024,7 +1328,7 @@ function ThroughlineFlow({ throughline, edges, collapsed, active, onToggleCollap
                                             whiteSpace: 'nowrap',
                                             fontSize: theme.fontSizes[0],
                                             fontFamily: theme.fonts.monospace,
-                                            color: stepActive ? theme.colors.text : muted,
+                                            color: theme.colors.text,
                                         }, children: [step.file.split('/').pop(), _jsxs("span", { style: { opacity: 0.7 }, children: [":", step.line] })] })] }))] }, `${step.edgeId}-${i}`));
                 }) }))] }));
 }