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

package/dist/subsystem/SubsystemComponentGraph.js

@@ -3,10 +3,10 @@ import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-run
  * SubsystemComponentGraph — a clickable, read-only React Flow component graph
  * for a subsystem snapshot.
  *
- * Nodes are positioned with ELK auto-layout (layered, minimized crossings) and
- * colored by package. Only cross-package edges leave a package region. Clicking
- * a component invokes `onSelect`. (Package frames are deferred — nodes are
- * color-coded by package for now.)
+ * Nodes are positioned with ELK auto-layout (layered, minimized crossings,
+ * process-aware compound groups). Components sharing a `process` render
+ * inside one labeled boundary frame; nodes without one sit outside every
+ * boundary. Clicking a component invokes `onSelect`.
  *
  * This is a focused fork of the package's `GraphRenderer` pipeline (same ELK
  * edge routing, delayed fitView, Background/Controls/MiniMap, node/edge type
@@ -15,18 +15,24 @@ 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, SubsystemGroupNode, SubsystemEdge, SUBSYSTEM_CALLBACKS, hexWithAlpha, EDGE_DIM_ALPHA, fileMatchForNode, flowElementVisibility } from './nodes';
 import { SubsystemFileTree } from './SubsystemFileTree';
 import { GraphLayoutCover } from './GraphLayoutCover';
 import { ComponentDeclaration } from './ComponentDeclaration';
 import { FileDrawer } from './FileDrawer';
 import { EdgeLegendModal, MECHANISM_DESCRIPTIONS } from './EdgeLegendModal';
 import { buildRepoGroups, repoAvatarUrl } from './paths';
+/** Cap screen-space edge labels to this fraction of the edge's on-screen length. */
+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;
 const nodeTypes = {
     'subsystem-component': SubsystemComponentNode,
+    'subsystem-group': SubsystemGroupNode,
 };
 const edgeTypes = {
     'subsystem-edge': SubsystemEdge,
@@ -40,7 +46,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 +64,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);
@@ -109,16 +125,19 @@ function Inner({ components, edges, onSelect, onEdgeSelect, measured: _measured,
     // These arrive as { type: 'dimensions', id, dimensions } in onNodesChange.
     const measuredDimsRef = useRef(new Map());
     const pendingMeasuredRef = useRef(false);
-    // Pass 2: once every node has a measured dimension, re-run ELK.
+    // Pass 2: once every leaf node has a measured dimension, re-run ELK.
+    // Group parents are sized by ELK, not measured — exclude them or pass 2
+    // would wait forever for dimensions that never arrive.
     const prevMeasuredSigRef = useRef('');
     const pass2DoneRef = useRef(false);
     const triggerPass2 = useCallback(() => {
         if (pass2DoneRef.current)
             return;
         const dims = measuredDimsRef.current;
-        if (dims.size < built.nodes.length)
+        const leafNodes = built.nodes.filter((n) => n.type !== 'subsystem-group');
+        if (dims.size < leafNodes.length)
             return;
-        const sig = built.nodes.map((n) => `${n.id}:${dims.get(n.id)?.width ?? '?'}`).join(',');
+        const sig = leafNodes.map((n) => `${n.id}:${dims.get(n.id)?.width ?? '?'}`).join(',');
         if (sig.includes('?:'))
             return;
         if (sig === prevMeasuredSigRef.current)
@@ -126,8 +145,8 @@ function Inner({ components, edges, onSelect, onEdgeSelect, measured: _measured,
         prevMeasuredSigRef.current = sig;
         pendingMeasuredRef.current = false;
         pass2DoneRef.current = true;
-        const measuredWidths = new Map(built.nodes.map((n) => [n.id, dims.get(n.id).width]));
-        const measuredHeights = new Map(built.nodes.map((n) => [n.id, dims.get(n.id).height]));
+        const measuredWidths = new Map(leafNodes.map((n) => [n.id, dims.get(n.id).width]));
+        const measuredHeights = new Map(leafNodes.map((n) => [n.id, dims.get(n.id).height]));
         let alive = true;
         void buildSubsystemGraph({ components, edges }, { maxNodeWidth, showEdgeLabels, measuredWidths, measuredHeights }).then(({ nodes, edges: e }) => {
             if (!alive)
@@ -150,6 +169,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 +188,8 @@ function Inner({ components, edges, onSelect, onEdgeSelect, measured: _measured,
                 }
                 setSelected(comp);
                 setSelectedEdgeId(null);
+                setFocusedThroughlineId(null);
+                setFocusedStepIndex(null);
                 onSelect?.(id);
             }
         };
@@ -182,49 +206,177 @@ 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) => {
+            // Boundary frames follow their members: hidden when no member is
+            // visible, dimmed when members are dimmed. Never selectable.
+            if (n.type === 'subsystem-group') {
+                const memberIds = (n.data?.region?.memberIds) ?? [];
+                const vis = flowElementVisibility({
+                    inOpened: memberIds.some((id) => openedNodeIds?.has(id) === true),
+                    inSelected: memberIds.some((id) => brightNodeIds?.has(id) === true),
+                    anyOpened: openedNodeIds != null,
+                    anySelected: brightNodeIds != null,
+                });
+                return {
+                    ...n,
+                    hidden: vis.hidden,
+                    selectable: false,
+                    data: {
+                        ...n.data,
+                        ...(vis.dimmed && { dimmed: true }),
+                    },
+                };
+            }
             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).
+        // Group parents are ELK-sized — ignore their measurements.
+        const groupIds = new Set(dispNodes.filter((n) => n.type === 'subsystem-group').map((n) => n.id));
         for (const ch of changes) {
-            if (ch.type === 'dimensions' && ch.dimensions) {
+            if (ch.type === 'dimensions' && ch.dimensions && !groupIds.has(ch.id)) {
                 measuredDimsRef.current.set(ch.id, ch.dimensions);
                 pendingMeasuredRef.current = true;
             }
@@ -250,6 +402,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 +423,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 +460,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 +540,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 +558,11 @@ function Inner({ components, edges, onSelect, onEdgeSelect, measured: _measured,
                 dimmed: d?.dimmed === true,
                 midX: d?.labelX ?? 0,
                 midY: d?.labelY ?? 0,
+                pathLength: d?.pathLength ?? 0,
+                stepNos: selectedFlowStepNos?.get(e.id),
             };
         });
-    }, [dispEdges]);
+    }, [dispEdges, selectedFlowStepNos]);
     const usedMechanisms = useMemo(() => {
         return new Set(edgeLabels.map((l) => l.mechanism));
     }, [edgeLabels]);
@@ -372,7 +591,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 +613,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 +621,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',
@@ -424,6 +668,16 @@ function Inner({ components, edges, onSelect, onEdgeSelect, measured: _measured,
                                     const verifiable = MECHANISM_DESCRIPTIONS.find(([m]) => m === mechanism)?.[2] ?? true;
                                     const screenX = lbl.midX * viewport.zoom + viewport.x;
                                     const screenY = lbl.midY * viewport.zoom + viewport.y;
+                                    const text = lbl.stepNos?.length
+                                        ? `${lbl.stepNos.map((n) => `${n}:`).join(' ')} ${lbl.mechanism}`
+                                        : lbl.mechanism;
+                                    // Labels stay readable at full size until they'd exceed a share of
+                                    // the edge's screen length, then shrink with zoom.
+                                    const estWidth = text.length * EDGE_LABEL_CHAR_PX + EDGE_LABEL_PAD_PX;
+                                    const screenEdgeLen = lbl.pathLength * viewport.zoom;
+                                    const scale = lbl.pathLength > 0 && estWidth > 0
+                                        ? Math.min(1, (screenEdgeLen * EDGE_LABEL_MAX_EDGE_FRACTION) / estWidth)
+                                        : 1;
                                     return (_jsx("div", { "data-edge-label": lbl.id, title: verifiable ? undefined : 'Not directly verifiable with graphify', onClick: (e) => {
                                             e.stopPropagation();
                                             selectEdge(lbl.id);
@@ -431,19 +685,27 @@ 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%) scale(${scale})`,
+                                            transformOrigin: 'center center',
+                                            display: 'flex',
+                                            alignItems: 'center',
                                             fontSize: 10,
+                                            lineHeight: 1,
                                             fontFamily: theme.fonts.monospace,
                                             fontWeight: 500,
                                             color,
                                             background: 'rgba(21,21,21,0.9)',
                                             border: verifiable ? `0.5px solid ${color}` : `1px dashed ${color}`,
                                             borderRadius: verifiable ? 4 : '10px 14px 12px 16px / 14px 10px 16px 12px',
-                                            padding: '1px 5px',
+                                            padding: '3px 8px',
                                             cursor: 'pointer',
                                             pointerEvents: 'auto',
                                             opacity: lbl.dimmed ? 0.15 : 1,
                                             whiteSpace: 'nowrap',
-                                        }, children: lbl.mechanism }, lbl.id));
+                                        }, children: text }, 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 +783,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);