@principal-ai/principal-view-react 0.16.57 → 0.16.58

package/dist/subsystem/SubsystemComponentGraph.d.ts

@@ -12,12 +12,21 @@
  * injection, onNodeClick) adapted to the subsystem model — read-only.
  */
 import type { ReactNode } from 'react';
-import { type SubsystemComponentEdge, type SubsystemComponent } from './model';
+import { type SubsystemComponentEdge, type SubsystemComponent, type SubsystemThroughline } from './model';
 import type { SubsystemOpenFileOptions } from './declarationRef';
 import type { ComponentVerificationState } from './ComponentDeclaration';
 export interface SubsystemComponentGraphProps {
     components: SubsystemComponent[];
     edges: SubsystemComponentEdge[];
+    /**
+     * Ordered execution stories over the graph's edges — one throughline per
+     * flow. When present the sidebar's bottom half offers a Files/Flows toggle:
+     * the flows panel lists each throughline's steps (`symbol` or `file:line`);
+     * clicking a flow row toggles its steps; clicking a step focuses that
+     * step's edge. Opened flows stay on the canvas (unselected ones dimmed);
+     * everything else is hidden.
+     */
+    throughlines?: SubsystemThroughline[];
     onSelect?: (componentId: string) => void;
     /** Called when an edge is clicked (relationship / mechanism + refs seam). */
     onEdgeSelect?: (edge: SubsystemComponentEdge) => void;

package/dist/subsystem/SubsystemComponentGraph.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SubsystemComponentGraph.d.ts","sourceRoot":"","sources":["../../src/subsystem/SubsystemComponentGraph.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,KAAK,EAAiC,SAAS,EAAE,MAAM,OAAO,CAAC;AAqBtE,OAAO,EAIL,KAAK,sBAAsB,EAC3B,KAAK,kBAAkB,EAExB,MAAM,SAAS,CAAC;AACjB,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,kBAAkB,CAAC;AAKjE,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,wBAAwB,CAAC;AAKzE,MAAM,WAAW,4BAA4B;IAC3C,UAAU,EAAE,kBAAkB,EAAE,CAAC;IACjC,KAAK,EAAE,sBAAsB,EAAE,CAAC;IAChC,QAAQ,CAAC,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,IAAI,CAAC;IACzC,6EAA6E;IAC7E,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,sBAAsB,KAAK,IAAI,CAAC;IACtD;kFAC8E;IAC9E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,qEAAqE;IACrE,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,gDAAgD;IAChD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,oDAAoD;IACpD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0EAA0E;IAC1E,aAAa,CAAC,EAAE,SAAS,CAAC;IAC1B,6DAA6D;IAC7D,YAAY,CAAC,EAAE,SAAS,CAAC;IACzB,gFAAgF;IAChF,uBAAuB,CAAC,EAAE,SAAS,CAAC;IACpC;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,wBAAwB,KAAK,SAAS,CAAC;IAChF;;;;OAIG;IACH,cAAc,CAAC,EAAE,CAAC,SAAS,EAAE,kBAAkB,KAAK,SAAS,CAAC;IAC9D;;;OAGG;IACH,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACtC,0EAA0E;IAC1E,iBAAiB,CAAC,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,IAAI,CAAC;IAClD,2DAA2D;IAC3D,qBAAqB,CAAC,EAAE,0BAA0B,GAAG,IAAI,CAAC;CAC3D;AAywBD,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,4BAA4B,2CAsC1E"}
+{"version":3,"file":"SubsystemComponentGraph.d.ts","sourceRoot":"","sources":["../../src/subsystem/SubsystemComponentGraph.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,KAAK,EAAiC,SAAS,EAAE,MAAM,OAAO,CAAC;AAqBtE,OAAO,EAIL,KAAK,sBAAsB,EAC3B,KAAK,kBAAkB,EAEvB,KAAK,oBAAoB,EAC1B,MAAM,SAAS,CAAC;AACjB,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,kBAAkB,CAAC;AAKjE,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,wBAAwB,CAAC;AAKzE,MAAM,WAAW,4BAA4B;IAC3C,UAAU,EAAE,kBAAkB,EAAE,CAAC;IACjC,KAAK,EAAE,sBAAsB,EAAE,CAAC;IAChC;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,oBAAoB,EAAE,CAAC;IACtC,QAAQ,CAAC,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,IAAI,CAAC;IACzC,6EAA6E;IAC7E,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,sBAAsB,KAAK,IAAI,CAAC;IACtD;kFAC8E;IAC9E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,qEAAqE;IACrE,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,gDAAgD;IAChD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,oDAAoD;IACpD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0EAA0E;IAC1E,aAAa,CAAC,EAAE,SAAS,CAAC;IAC1B,6DAA6D;IAC7D,YAAY,CAAC,EAAE,SAAS,CAAC;IACzB,gFAAgF;IAChF,uBAAuB,CAAC,EAAE,SAAS,CAAC;IACpC;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,wBAAwB,KAAK,SAAS,CAAC;IAChF;;;;OAIG;IACH,cAAc,CAAC,EAAE,CAAC,SAAS,EAAE,kBAAkB,KAAK,SAAS,CAAC;IAC9D;;;OAGG;IACH,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACtC,0EAA0E;IAC1E,iBAAiB,CAAC,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,IAAI,CAAC;IAClD,2DAA2D;IAC3D,qBAAqB,CAAC,EAAE,0BAA0B,GAAG,IAAI,CAAC;CAC3D;AA6uCD,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,4BAA4B,2CAsC1E"}

package/dist/subsystem/SubsystemComponentGraph.js

@@ -15,10 +15,10 @@ 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 { Map as MapIcon } from 'lucide-react';
+import { Map as MapIcon, X } from 'lucide-react';
 import { IndustryMarkdownSlide } from 'themed-markdown';
 import { buildSubsystemGraph, MECHANISM_COLOR, subsystemGraphLayoutKey, } from './model';
-import { SubsystemComponentNode, SubsystemEdge, SUBSYSTEM_CALLBACKS } from './nodes';
+import { SubsystemComponentNode, SubsystemEdge, SUBSYSTEM_CALLBACKS, hexWithAlpha, EDGE_DIM_ALPHA, fileMatchForNode, flowElementVisibility } from './nodes';
 import { SubsystemFileTree } from './SubsystemFileTree';
 import { GraphLayoutCover } from './GraphLayoutCover';
 import { ComponentDeclaration } from './ComponentDeclaration';
@@ -40,7 +40,7 @@ const DrawerContent = memo(function DrawerContent({ render, file, startLine, })
         return null;
     return _jsx(_Fragment, { children: render(file, startLine != null ? { startLine } : undefined) });
 });
-function Inner({ components, edges, onSelect, onEdgeSelect, measured: _measured, maxNodeWidth, showEdgeLabels, title, description, canvasOverlay, sidebarExtra, sidebarAfterDescription, renderFileView, renderFileViewer, onFileSelect, onVerifyComponent, componentVerification }) {
+function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measured: _measured, maxNodeWidth, showEdgeLabels, title, description, canvasOverlay, sidebarExtra, sidebarAfterDescription, renderFileView, renderFileViewer, onFileSelect, onVerifyComponent, componentVerification }) {
     const { theme } = useTheme();
     const { fitView } = useReactFlow();
     const viewport = useViewport();
@@ -58,6 +58,16 @@ function Inner({ components, edges, onSelect, onEdgeSelect, measured: _measured,
     const [legendOpen, setLegendOpen] = useState(false);
     // Component the pointer is over (null on leave) → transient tree highlight.
     const [hoveredComponentId, setHoveredComponentId] = useState(null);
+    // Throughline focus — selected flow (or step) is full strength; other
+    // opened-flow members stay visible but dimmed; everything else is hidden.
+    const [focusedThroughlineId, setFocusedThroughlineId] = useState(null);
+    // `null` = whole flow focused; a number = that single step's edge focused.
+    const [focusedStepIndex, setFocusedStepIndex] = 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
+    // default so a graph with several flows doesn't dump every step list at once.
+    const [expandedThroughlines, setExpandedThroughlines] = useState(new Set());
     // 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);
@@ -150,6 +160,9 @@ function Inner({ components, edges, onSelect, onEdgeSelect, measured: _measured,
         }
         const src = edgeById.get(edgeId);
         setSelectedEdgeId(edgeId);
+        // A direct edge selection on the canvas supersedes any throughline focus.
+        setFocusedThroughlineId(null);
+        setFocusedStepIndex(null);
         if (src)
             onEdgeSelect?.(src);
     }, [edgeById, onEdgeSelect]);
@@ -166,6 +179,8 @@ function Inner({ components, edges, onSelect, onEdgeSelect, measured: _measured,
                 }
                 setSelected(comp);
                 setSelectedEdgeId(null);
+                setFocusedThroughlineId(null);
+                setFocusedStepIndex(null);
                 onSelect?.(id);
             }
         };
@@ -182,45 +197,151 @@ function Inner({ components, edges, onSelect, onEdgeSelect, measured: _measured,
     const { nodes, edges: convertedEdges } = built;
     const xyflowNodesBase = nodes;
     const baseEdges = convertedEdges;
+    // When an edge is selected, dim every other edge + its label to focus it.
+    const [selectedEdgeId, setSelectedEdgeId] = useState(null);
+    // Ref mirror so `selectEdge` (a useCallback over early deps) can toggle
+    // without a stale closure value.
+    const selectedEdgeIdRef = useRef(null);
+    selectedEdgeIdRef.current = selectedEdgeId;
+    // Edge ids in throughline focus (an active flow's edge set, or a single
+    // step's edge). Used to frame the camera. `null` = no throughline focus.
+    const focusEdgeIds = useMemo(() => {
+        if (focusedThroughlineId == null || !throughlines)
+            return null;
+        const tl = throughlines.find((t) => t.id === focusedThroughlineId);
+        if (!tl)
+            return null;
+        if (focusedStepIndex != null) {
+            const step = tl.steps[focusedStepIndex];
+            return step ? new Set([step.edgeId]) : null;
+        }
+        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).
+    const selectedFlowStepNos = useMemo(() => {
+        if (focusedThroughlineId == null || !throughlines)
+            return null;
+        const tl = throughlines.find((t) => t.id === focusedThroughlineId);
+        if (!tl)
+            return null;
+        const map = new Map();
+        tl.steps.forEach((s, i) => {
+            const list = map.get(s.edgeId) ?? [];
+            list.push(i + 1);
+            map.set(s.edgeId, list);
+        });
+        return map;
+    }, [throughlines, focusedThroughlineId]);
+    // Union of every expanded (opened) throughline's edges — the visible set.
+    const openedEdgeIds = useMemo(() => {
+        if (!throughlines || expandedThroughlines.size === 0)
+            return null;
+        const ids = new Set();
+        for (const tl of throughlines) {
+            if (!expandedThroughlines.has(tl.id))
+                continue;
+            for (const s of tl.steps)
+                ids.add(s.edgeId);
+        }
+        return ids.size > 0 ? ids : null;
+    }, [throughlines, expandedThroughlines]);
+    const endpointsOf = (edgeIds) => {
+        if (!edgeIds)
+            return null;
+        const ids = new Set();
+        for (const e of baseEdges) {
+            if (!edgeIds.has(e.id))
+                continue;
+            ids.add(e.source);
+            ids.add(e.target);
+        }
+        return ids.size > 0 ? ids : null;
+    };
+    const openedNodeIds = useMemo(() => endpointsOf(openedEdgeIds), 
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [baseEdges, openedEdgeIds]);
+    // Endpoints of the bright set: the selected step's edge, or the whole flow
+    // when no step is focused.
+    const brightNodeIds = useMemo(() => endpointsOf(focusEdgeIds), 
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [baseEdges, focusEdgeIds]);
+    // Source + target of the focused step/flow (or a canvas-selected edge). If a
+    // file is open, those endpoints stay undimmed even when they don't live in
+    // that file.
+    const focusNodeIds = useMemo(() => {
+        if (brightNodeIds)
+            return brightNodeIds;
+        if (selectedEdgeId) {
+            const e = baseEdges.find((x) => x.id === selectedEdgeId);
+            if (e)
+                return new Set([e.source, e.target]);
+        }
+        return null;
+    }, [baseEdges, brightNodeIds, selectedEdgeId]);
     // While a file is open in the drawer, tag each node with whether its
     // component lives in that file — the node renderer spotlights matches and
     // dims non-matches (mirrors the edge-dimming behavior on selection).
+    // Opened-but-unselected members are dimmed; a selected step further dims
+    // the rest of its own flow. Nodes not on any opened flow are hidden.
     // `isSelected` rides in data because the node's stopPropagation() keeps
-    // React Flow's own selection state from ever updating.
+    // React Flow's own selection state from updating.
     const dispNodes = useMemo(() => {
         return xyflowNodesBase.map((n) => {
             const comp = n.data?.component;
-            const fileMatch = openFile ? comp?.file === openFile : undefined;
+            const fileMatch = fileMatchForNode(comp?.file, openFile, focusNodeIds?.has(n.id) === true);
             const isSelected = selected?.id !== undefined && comp?.id === selected.id;
-            if (fileMatch === undefined && !isSelected) {
-                const { fileMatch: _f, isSelected: _s, ...rest } = n.data;
-                return { ...n, data: rest };
+            const vis = flowElementVisibility({
+                inOpened: openedNodeIds?.has(n.id) === true,
+                inSelected: brightNodeIds?.has(n.id) === true,
+                anyOpened: openedNodeIds != null,
+                anySelected: brightNodeIds != null,
+            });
+            if (fileMatch === undefined && !isSelected && !vis.dimmed) {
+                const { fileMatch: _f, isSelected: _s, dimmed: _d, ...rest } = n.data;
+                return { ...n, hidden: vis.hidden, data: rest };
             }
             return {
                 ...n,
-                data: { ...n.data, ...(fileMatch !== undefined && { fileMatch }), ...(isSelected && { isSelected }) },
+                hidden: vis.hidden,
+                data: {
+                    ...n.data,
+                    ...(fileMatch !== undefined && { fileMatch }),
+                    ...(isSelected && { isSelected }),
+                    ...(vis.dimmed && { dimmed: true }),
+                },
             };
         });
-    }, [xyflowNodesBase, openFile, selected]);
+    }, [xyflowNodesBase, openFile, selected, focusNodeIds, openedNodeIds, brightNodeIds]);
     const baseNodesKey = useMemo(() => nodes.map((n) => n.id).sort().join(','), [nodes]);
     const baseEdgesKey = useMemo(() => convertedEdges.map((e) => e.id).sort().join(','), [convertedEdges]);
-    // When an edge is selected, dim every other edge + its label to focus it.
-    const [selectedEdgeId, setSelectedEdgeId] = useState(null);
-    // Ref mirror so `selectEdge` (a useCallback over early deps) can toggle
-    // without a stale closure value.
-    const selectedEdgeIdRef = useRef(null);
-    selectedEdgeIdRef.current = selectedEdgeId;
     const dispEdges = useMemo(() => {
+        const paint = (e, dimmed) => {
+            const markerEnd = e.markerEnd;
+            const nextMarker = dimmed && markerEnd && typeof markerEnd === 'object' && typeof markerEnd.color === 'string'
+                ? { ...markerEnd, color: hexWithAlpha(markerEnd.color, EDGE_DIM_ALPHA) }
+                : markerEnd;
+            return {
+                ...e,
+                data: { ...e.data, dimmed },
+                markerEnd: nextMarker,
+            };
+        };
+        if (openedEdgeIds || focusEdgeIds) {
+            return baseEdges.map((e) => {
+                const vis = flowElementVisibility({
+                    inOpened: openedEdgeIds?.has(e.id) === true,
+                    inSelected: focusEdgeIds?.has(e.id) === true,
+                    anyOpened: openedEdgeIds != null,
+                    anySelected: focusEdgeIds != null,
+                });
+                return { ...paint(e, vis.dimmed), hidden: vis.hidden };
+            });
+        }
         if (!selectedEdgeId)
             return baseEdges;
-        return baseEdges.map((e) => ({
-            ...e,
-            data: {
-                ...e.data,
-                dimmed: e.id !== selectedEdgeId,
-            },
-        }));
-    }, [baseEdges, selectedEdgeId]);
+        return baseEdges.map((e) => paint(e, e.id !== selectedEdgeId));
+    }, [baseEdges, selectedEdgeId, openedEdgeIds, focusEdgeIds]);
     const onNodesChange = useCallback((changes) => {
         // Capture dimension changes (React Flow's measurement callback).
         for (const ch of changes) {
@@ -250,6 +371,8 @@ function Inner({ components, edges, onSelect, onEdgeSelect, measured: _measured,
     const onNodeClick = useCallback((_e, node) => {
         const comp = node.data?.component;
         setSelectedEdgeId(null);
+        setFocusedThroughlineId(null);
+        setFocusedStepIndex(null);
         if (node.type === 'subsystem-component' && comp) {
             // Clicking the already-selected node unselects it (toggle off).
             // Selection is independent of the file drawer — nodes never open it.
@@ -269,10 +392,13 @@ function Inner({ components, edges, onSelect, onEdgeSelect, measured: _measured,
     const onPaneClick = useCallback(() => {
         setSelected(null);
         setSelectedEdgeId(null);
+        setFocusedThroughlineId(null);
+        setFocusedStepIndex(null);
     }, []);
     // Sidebar file trees — one per repo on multi-repo graphs, each under its
     // own owner-avatar header. Clicking a header collapses that repo's tree.
     const repoGroups = useMemo(() => buildRepoGroups(components), [components]);
+    const hasThroughlines = useMemo(() => (throughlines?.length ?? 0) > 0, [throughlines]);
     const [collapsedRepos, setCollapsedRepos] = useState(new Set());
     const toggleRepoCollapsed = useCallback((key) => {
         setCollapsedRepos((prev) => {
@@ -303,6 +429,62 @@ function Inner({ components, edges, onSelect, onEdgeSelect, measured: _measured,
         setOpenFileTarget({ file, startLine });
         onFileSelect?.(file);
     }, [onFileSelect]);
+    // Camera helper shared by the throughline interactions: frames the focused
+    // edges' endpoint nodes via `fitView({ nodes })`, which uses the store's
+    // 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) => {
+        const nodeIds = new Set();
+        for (const e of baseEdges) {
+            if (!ids.has(e.id))
+                continue;
+            nodeIds.add(e.source);
+            nodeIds.add(e.target);
+        }
+        if (nodeIds.size === 0)
+            return;
+        fitView({
+            nodes: [...nodeIds].map((id) => ({ id })),
+            padding: 0.25,
+            duration: 300,
+        });
+    }, [baseEdges, fitView]);
+    // 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.
+    const focusThroughlineEdges = useCallback((tl) => {
+        setSelected(null);
+        setSelectedEdgeId(null);
+        setFocusedStepIndex(null);
+        setFocusedThroughlineId(tl.id);
+        fitFocusBounds(new Set(tl.steps.map((s) => s.edgeId)));
+    }, [fitFocusBounds]);
+    const clearThroughlineFocus = useCallback(() => {
+        setFocusedThroughlineId(null);
+        setFocusedStepIndex(null);
+    }, []);
+    // Focus a single step's edge on the canvas. The step's file:line is listed
+    // in the row; we don't open the drawer from here.
+    const focusThroughlineStep = useCallback((tl, stepIndex) => {
+        const step = tl.steps[stepIndex];
+        if (!step)
+            return;
+        setSelected(null);
+        setSelectedEdgeId(null);
+        setFocusedStepIndex(stepIndex);
+        setFocusedThroughlineId(tl.id);
+        fitFocusBounds(new Set([step.edgeId]));
+    }, [fitFocusBounds]);
+    const toggleThroughlineCollapsed = useCallback((tlId) => {
+        setExpandedThroughlines((prev) => {
+            const next = new Set(prev);
+            if (next.has(tlId))
+                next.delete(tlId);
+            else
+                next.add(tlId);
+            return next;
+        });
+    }, []);
     // Filename-badge clicks on nodes open the drawer through the same path as
     // the declaration panel's file link (toggle + tree sync, no start line).
     useEffect(() => {
@@ -327,13 +509,17 @@ function Inner({ components, edges, onSelect, onEdgeSelect, measured: _measured,
             return;
         setSelected(comp);
         setSelectedEdgeId(null);
+        setFocusedThroughlineId(null);
+        setFocusedStepIndex(null);
         onSelect?.(comp.id);
     }, [components, onSelect]);
     // Edge label data for the overlay (rendered OUTSIDE ReactFlow so the pane
     // doesn't intercept pointer events). Uses ELK-computed label midpoints from
     // the actual edge path (not node-center approximations).
     const edgeLabels = useMemo(() => {
-        return dispEdges.map((e) => {
+        return dispEdges
+            .filter((e) => !e.hidden)
+            .map((e) => {
             const d = e.data;
             return {
                 id: e.id,
@@ -341,9 +527,10 @@ function Inner({ components, edges, onSelect, onEdgeSelect, measured: _measured,
                 dimmed: d?.dimmed === true,
                 midX: d?.labelX ?? 0,
                 midY: d?.labelY ?? 0,
+                stepNos: selectedFlowStepNos?.get(e.id),
             };
         });
-    }, [dispEdges]);
+    }, [dispEdges, selectedFlowStepNos]);
     const usedMechanisms = useMemo(() => {
         return new Set(edgeLabels.map((l) => l.mechanism));
     }, [edgeLabels]);
@@ -372,7 +559,7 @@ function Inner({ components, edges, onSelect, onEdgeSelect, measured: _measured,
     const fileViewerRef = useRef(fileViewer);
     fileViewerRef.current = fileViewer;
     const renderDrawerContent = useCallback((file, opts) => fileViewerRef.current?.(file, opts) ?? null, []);
-    return (_jsxs("div", { style: { width: '100%', height: '100%', display: 'flex', flexDirection: 'row' }, children: [(title || description || sidebarExtra || sidebarAfterDescription || treeFilePaths.length > 0) && (_jsxs("div", { style: {
+    return (_jsxs("div", { style: { width: '100%', height: '100%', display: 'flex', flexDirection: 'row' }, children: [(title || description || sidebarExtra || sidebarAfterDescription || treeFilePaths.length > 0 || hasThroughlines) && (_jsxs("div", { style: {
                     width: 340,
                     minWidth: 340,
                     borderRight: `1px solid ${theme.colors.border}`,
@@ -394,7 +581,7 @@ function Inner({ components, edges, onSelect, onEdgeSelect, measured: _measured,
                                     fontWeight: 600,
                                     color: theme.colors.text,
                                     fontFamily: theme.fonts.heading,
-                                }, children: title })), description && (_jsx("div", { style: { fontSize: theme.fontSizes[0], lineHeight: 1.5 }, children: _jsx(IndustryMarkdownSlide, { content: description, slideIdPrefix: "subsystem-desc", slideIndex: 0, isVisible: true, theme: theme, disableScroll: true, fontSizeScale: 0.9, enableKeyboardScrolling: false, autoFocusOnVisible: false }) })), sidebarAfterDescription] }), treeFilePaths.length > 0 && (_jsx("div", { style: {
+                                }, children: title })), description && (_jsx("div", { style: { fontSize: theme.fontSizes[0], lineHeight: 1.5 }, children: _jsx(IndustryMarkdownSlide, { content: description, slideIdPrefix: "subsystem-desc", slideIndex: 0, isVisible: true, theme: theme, disableScroll: true, fontSizeScale: 0.9, enableKeyboardScrolling: false, autoFocusOnVisible: false }) })), sidebarAfterDescription] }), (treeFilePaths.length > 0 || hasThroughlines) && (_jsxs("div", { style: {
                             height: '50%',
                             minHeight: 160,
                             flexShrink: 0,
@@ -402,17 +589,42 @@ function Inner({ components, edges, onSelect, onEdgeSelect, measured: _measured,
                             display: 'flex',
                             flexDirection: 'column',
                             overflow: 'hidden',
-                        }, children: repoGroups.groups.map((group, i) => {
-                            const groupKey = group.repoKey ?? '__no-repo__';
-                            const collapsed = collapsedRepos.has(groupKey);
-                            return (_jsxs("div", { style: {
-                                    flex: collapsed ? '0 0 auto' : 1,
-                                    minHeight: collapsed ? 0 : undefined,
+                        }, children: [hasThroughlines && (_jsx("div", { role: "tablist", "aria-label": "Sidebar view", style: {
                                     display: 'flex',
-                                    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));
-                        }) }))] })), _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: {
+                                    width: '100%',
+                                    flexShrink: 0,
+                                    borderBottom: `1px solid ${theme.colors.border}`,
+                                    background: theme.colors.backgroundSecondary ?? theme.colors.background,
+                                }, children: ['files', 'flows'].map((view) => (_jsx("button", { type: "button", role: "tab", "aria-selected": sidebarView === view, onClick: () => setSidebarView(view), style: {
+                                        flex: 1,
+                                        minWidth: 0,
+                                        padding: '8px 8px',
+                                        border: 'none',
+                                        borderRadius: 0,
+                                        background: sidebarView === view ? theme.colors.background : 'transparent',
+                                        color: sidebarView === view
+                                            ? theme.colors.text
+                                            : theme.colors.textSecondary,
+                                        fontSize: theme.fontSizes[1],
+                                        fontFamily: theme.fonts.monospace,
+                                        textTransform: 'capitalize',
+                                        cursor: 'pointer',
+                                    }, children: view }, view))) })), sidebarView === 'flows' && throughlines && throughlines.length > 0 ? (_jsx("div", { style: {
+                                    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) => {
+                                    const groupKey = group.repoKey ?? '__no-repo__';
+                                    const collapsed = collapsedRepos.has(groupKey);
+                                    return (_jsxs("div", { style: {
+                                            flex: collapsed ? '0 0 auto' : 1,
+                                            minHeight: collapsed ? 0 : undefined,
+                                            display: 'flex',
+                                            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: {
                                     position: 'absolute',
                                     inset: 0,
                                     overflow: 'hidden',
@@ -431,6 +643,10 @@ function Inner({ components, edges, onSelect, onEdgeSelect, measured: _measured,
                                             position: 'absolute',
                                             left: screenX,
                                             top: screenY,
+                                            // Center on the flow-space midpoint. Labels live in screen
+                                            // space (fixed size when zoomed out), so top-left anchoring
+                                            // would drift them right/down of the edge as zoom drops.
+                                            transform: 'translate(-50%, -50%)',
                                             fontSize: 10,
                                             fontFamily: theme.fonts.monospace,
                                             fontWeight: 500,
@@ -443,7 +659,7 @@ function Inner({ components, edges, onSelect, onEdgeSelect, measured: _measured,
                                             pointerEvents: 'auto',
                                             opacity: lbl.dimmed ? 0.15 : 1,
                                             whiteSpace: 'nowrap',
-                                        }, children: lbl.mechanism }, lbl.id));
+                                        }, children: lbl.stepNos?.length ? `${lbl.stepNos.map((n) => `${n}:`).join(' ')} ${lbl.mechanism}` : lbl.mechanism }, lbl.id));
                                 }) })), _jsxs(ReactFlow, { nodes: dispNodes, edges: dispEdges, nodeTypes: nodeTypes, edgeTypes: edgeTypes, minZoom: 0.05, maxZoom: 4, onNodeClick: onNodeClick, onEdgeClick: onEdgeClick, onNodesChange: onNodesChange, onEdgesChange: onEdgesChange, proOptions: { hideAttribution: true }, nodesDraggable: false, elementsSelectable: true, selectNodesOnDrag: false, nodesConnectable: false, edgesReconnectable: false, onPaneClick: onPaneClick, panOnDrag: true, panOnScroll: true, zoomOnScroll: false, zoomOnPinch: true, zoomOnDoubleClick: false, style: {
                                     width: '100%',
                                     height: '100%',
@@ -521,6 +737,130 @@ function RepoGroupHeader({ group, collapsed, onToggle, }) {
                     whiteSpace: 'nowrap',
                 }, children: label })] }));
 }
+/** One collapsible throughline in the sidebar's flows panel. Clicking the
+ *  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, }) {
+    const { theme } = useTheme();
+    const muted = theme.colors.textMuted ?? theme.colors.textSecondary;
+    const hoverBg = theme.colors.background;
+    const edgeById = useMemo(() => new Map(edges.map((e) => [e.id, e])), [edges]);
+    const wholeFlowActive = active !== null && active.stepIndex === null;
+    const [headerHover, setHeaderHover] = useState(false);
+    const [closeHover, setCloseHover] = useState(false);
+    const [hoveredStep, setHoveredStep] = useState(null);
+    return (_jsxs("div", { style: { margin: '4px 0', borderRadius: 8 }, 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: () => {
+                            if (collapsed) {
+                                onToggleCollapsed(throughline.id);
+                                onFocusFlow(throughline);
+                            }
+                            else if (active === null) {
+                                onFocusFlow(throughline);
+                            }
+                            else {
+                                onToggleCollapsed(throughline.id);
+                                onClearFocus();
+                            }
+                        }, style: {
+                            flex: 1,
+                            display: 'flex',
+                            alignItems: 'center',
+                            minWidth: 0,
+                            padding: '6px 8px',
+                            borderRadius: 6,
+                            border: 'none',
+                            background: 'transparent',
+                            textAlign: 'left',
+                            cursor: 'pointer',
+                        }, children: _jsx("span", { style: {
+                                overflow: 'hidden',
+                                textOverflow: 'ellipsis',
+                                whiteSpace: 'nowrap',
+                                fontSize: theme.fontSizes[1],
+                                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) => {
+                    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", { type: "button", onMouseEnter: () => setHoveredStep(i), onMouseLeave: () => setHoveredStep(null), onClick: () => onFocusStep(throughline, i), style: {
+                            display: 'flex',
+                            alignItems: 'center',
+                            gap: 8,
+                            minWidth: 0,
+                            padding: '4px 8px 4px 12px',
+                            textAlign: 'left',
+                            borderRadius: 6,
+                            border: 'none',
+                            background: stepActive || hoveredStep === i ? hoverBg : 'transparent',
+                            cursor: 'pointer',
+                            transition: 'background 120ms ease',
+                        }, children: [_jsx("span", { style: {
+                                    flexShrink: 0,
+                                    width: 14,
+                                    fontSize: theme.fontSizes[0] * 0.8,
+                                    fontFamily: theme.fonts.monospace,
+                                    color: stepActive ? theme.colors.text : muted,
+                                }, children: i + 1 }), step.symbol ? (_jsx("span", { style: {
+                                    flex: 1,
+                                    minWidth: 0,
+                                    overflow: 'hidden',
+                                    textOverflow: 'ellipsis',
+                                    whiteSpace: 'nowrap',
+                                    fontSize: theme.fontSizes[0],
+                                    fontFamily: theme.fonts.monospace,
+                                    color: stepActive ? theme.colors.text : muted,
+                                }, children: step.symbol })) : (_jsxs(_Fragment, { children: [_jsx("span", { style: {
+                                            flexShrink: 0,
+                                            width: 74,
+                                            overflow: 'hidden',
+                                            textOverflow: 'ellipsis',
+                                            whiteSpace: 'nowrap',
+                                            fontSize: theme.fontSizes[0],
+                                            fontFamily: theme.fonts.monospace,
+                                            color,
+                                        }, children: mech ?? step.edgeId }), _jsxs("span", { style: {
+                                            flex: 1,
+                                            minWidth: 0,
+                                            overflow: 'hidden',
+                                            textOverflow: 'ellipsis',
+                                            whiteSpace: 'nowrap',
+                                            fontSize: theme.fontSizes[0],
+                                            fontFamily: theme.fonts.monospace,
+                                            color: stepActive ? theme.colors.text : muted,
+                                        }, children: [step.file.split('/').pop(), _jsxs("span", { style: { opacity: 0.7 }, children: [":", step.line] })] })] }))] }, `${step.edgeId}-${i}`));
+                }) }))] }));
+}
 export function SubsystemComponentGraph(props) {
     const wrapRef = useRef(null);
     const [size, setSize] = useState(null);