@principal-ai/subsystems-react 0.20.5 → 0.21.0

package/dist/subsystem/SubsystemComponentGraph.js

@@ -17,7 +17,7 @@ import { ReactFlow, ReactFlowProvider, Background, BackgroundVariant, Controls,
 import { useTheme } from '@principal-ade/industry-theme';
 import { ChevronDown, ChevronUp, Pause, Play, X } from 'lucide-react';
 import { IndustryMarkdownSlide } from 'themed-markdown';
-import { buildSubsystemGraph, MECHANISM_COLOR, MECHANISM_DESCRIPTIONS, subsystemGraphLayoutKey, } from './model';
+import { buildSubsystemGraph, deriveGraphEdges, MECHANISM_COLOR, MECHANISM_DESCRIPTIONS, subsystemGraphLayoutKey, walkthroughStepGraphEdgeId, } from './model';
 import { SubsystemComponentNode, SubsystemGroupNode, SubsystemEdge, SUBSYSTEM_CALLBACKS, hexWithAlpha, EDGE_DIM_ALPHA, fileMatchForNode, flowElementVisibility } from './nodes';
 import { SubsystemFileTree } from './SubsystemFileTree';
 import { GraphLayoutCover } from './GraphLayoutCover';
@@ -29,8 +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;
+/** Pause (ms) between steps when a walkthrough autoplays. */
+const WALKTHROUGH_PLAY_PAUSE_MS = 2500;
 const nodeTypes = {
     'subsystem-component': SubsystemComponentNode,
     'subsystem-group': SubsystemGroupNode,
@@ -45,20 +45,21 @@ const edgeTypes = {
 const FileDrawerContent = memo(function FileDrawerContent({ render, file, startLine, }) {
     return _jsx(_Fragment, { children: render(file, startLine != null ? { startLine } : undefined) });
 });
-const ThroughlineDrawerContent = memo(function ThroughlineDrawerContent({ render, throughline, stepIndex, }) {
-    return _jsx(_Fragment, { children: render({ throughline, stepIndex }) });
+const WalkthroughDrawerContent = memo(function WalkthroughDrawerContent({ render, walkthrough, stepIndex, }) {
+    return _jsx(_Fragment, { children: render({ walkthrough, stepIndex }) });
 });
-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 }) {
+function Inner({ components, relations, walkthroughs, onSelect, onEdgeSelect, measured: _measured, maxNodeWidth, showEdgeLabels, title, hideSidebar, walkthroughStepMode = 'focus', autoPlayWalkthroughs = false, walkthroughAutoPlayIntervalMs = WALKTHROUGH_PLAY_PAUSE_MS, zoomOnWalkthroughFocus = true, graphTitle, showWalkthroughTitle = false, description, canvasOverlay, sidebarExtra, sidebarAfterDescription, renderFileView, renderFileViewer, renderWalkthroughViewer, onFileSelect, onVerifyComponent, componentVerification }) {
     const { theme } = useTheme();
     const { fitView } = useReactFlow();
     const viewport = useViewport();
+    const graphEdges = useMemo(() => deriveGraphEdges({ relations, walkthroughs }), [relations, walkthroughs]);
     const [built, setBuilt] = useState({
         nodes: [],
         edges: [],
     });
     const [layoutReady, setLayoutReady] = useState(false);
     const [selected, setSelected] = useState(null);
-    /** Bottom drawer: single file or throughline multi-snippet mode. */
+    /** Bottom drawer: single file or walkthrough multi-snippet mode. */
     const [drawerTarget, setDrawerTarget] = useState(null);
     // Mirror so step-focus can decide whether to wait for the drawer open
     // transition before fitView (avoids framing against full-height canvas).
@@ -68,22 +69,22 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
     const pendingFocusFitRef = useRef(null);
     // 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
+    // Walkthrough 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);
+    const [focusedWalkthroughId, setFocusedWalkthroughId] = useState(null);
     // `null` = whole flow focused; a number = that single step's edge focused.
     const [focusedStepIndex, setFocusedStepIndex] = useState(null);
-    // Hovered throughline in the flows panel: dims every canvas node/edge not
+    // Hovered walkthrough in the flows panel: dims every canvas node/edge not
     // involved in the hover preview (or selected ∪ hovered when a step is
     // focused). `stepIndex: null` = whole flow (collapsed title hover);
     // a number = that step. Transient — no drawer. Camera only reframes when
     // a step is already selected.
-    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
+    const [hoveredWalkthroughStep, setHoveredWalkthroughStep] = useState(null);
+    // Sidebar bottom half: which panel is shown when walkthroughs exist.
+    const [sidebarView, setSidebarView] = useState(() => walkthroughs?.length ? 'walkthroughs' : 'files');
+    // Walkthrough 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());
+    const [expandedWalkthroughs, setExpandedWalkthroughs] = useState(new Set());
     // Sidebar description visibility. Hidden by default so the files/flows
     // panel gets the vertical room; the title-row toggle reveals it.
     const [descriptionVisible, setDescriptionVisible] = useState(false);
@@ -137,40 +138,40 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
         drawerTarget?.kind === 'file'
             ? { file: drawerTarget.file, startLine: drawerTarget.startLine }
             : null;
-    const focusedThroughline = useMemo(() => {
-        if (drawerTarget?.kind !== 'throughline' || !throughlines)
+    const focusedWalkthrough = useMemo(() => {
+        if (drawerTarget?.kind !== 'walkthrough' || !walkthroughs)
             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 walkthroughs.find((t) => t.id === drawerTarget.walkthroughId) ?? null;
+    }, [drawerTarget, walkthroughs]);
+    // Walkthrough shown on the canvas title chip (focus or hover/autoplay highlight).
+    const overlayWalkthroughTitle = useMemo(() => {
+        if (!showWalkthroughTitle || !walkthroughs?.length)
             return null;
-        const id = focusedThroughlineId ?? hoveredThroughlineStep?.throughlineId;
+        const id = focusedWalkthroughId ?? hoveredWalkthroughStep?.walkthroughId;
         if (!id)
             return null;
-        return throughlines.find((t) => t.id === id)?.title ?? null;
+        return walkthroughs.find((t) => t.id === id)?.title ?? null;
     }, [
-        showThroughlineTitle,
-        throughlines,
-        focusedThroughlineId,
-        hoveredThroughlineStep,
+        showWalkthroughTitle,
+        walkthroughs,
+        focusedWalkthroughId,
+        hoveredWalkthroughStep,
     ]);
     // Active step for the bottom-of-title progress + annotation chip.
-    const overlayThroughlineStep = useMemo(() => {
-        if (!showThroughlineTitle || !throughlines?.length)
+    const overlayWalkthroughStep = useMemo(() => {
+        if (!showWalkthroughTitle || !walkthroughs?.length)
             return null;
-        const tlId = focusedThroughlineId ?? hoveredThroughlineStep?.throughlineId ?? null;
+        const tlId = focusedWalkthroughId ?? hoveredWalkthroughStep?.walkthroughId ?? null;
         let stepIndex = null;
-        if (focusedThroughlineId != null) {
+        if (focusedWalkthroughId != null) {
             stepIndex = focusedStepIndex;
         }
-        else if (hoveredThroughlineStep != null) {
-            stepIndex = hoveredThroughlineStep.stepIndex;
+        else if (hoveredWalkthroughStep != null) {
+            stepIndex = hoveredWalkthroughStep.stepIndex;
         }
         if (tlId == null || stepIndex == null)
             return null;
-        const tl = throughlines.find((t) => t.id === tlId);
+        const tl = walkthroughs.find((t) => t.id === tlId);
         const step = tl?.steps[stepIndex];
         if (!step || !tl)
             return null;
@@ -180,18 +181,18 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
             annotation: step.annotation,
         };
     }, [
-        showThroughlineTitle,
-        throughlines,
-        focusedThroughlineId,
+        showWalkthroughTitle,
+        walkthroughs,
+        focusedWalkthroughId,
         focusedStepIndex,
-        hoveredThroughlineStep,
+        hoveredWalkthroughStep,
     ]);
     const drawerTitle = useMemo(() => {
         if (!drawerTarget)
             return null;
         if (drawerTarget.kind === 'file')
             return drawerTarget.file;
-        const tl = focusedThroughline;
+        const tl = focusedWalkthrough;
         if (!tl)
             return null;
         if (drawerTarget.stepIndex == null)
@@ -201,7 +202,7 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
             return tl.title;
         const site = `${step.file.split('/').pop() ?? step.file}:${step.line}`;
         return `${tl.title} · ${site}`;
-    }, [drawerTarget, focusedThroughline]);
+    }, [drawerTarget, focusedWalkthrough]);
     // Refresh selected component when the components list updates (e.g. verify
     // writes back declarationRef).
     useEffect(() => {
@@ -214,11 +215,13 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
     // Pass 1: build with estimated widths so React Flow can measure the DOM.
     // The pane stays hidden until Pass 2 completes. Key off layout-affecting
     // fields only — declarationRef updates after verify must not re-run ELK.
-    const layoutKey = useMemo(() => subsystemGraphLayoutKey({ components, edges }), [components, edges]);
+    const layoutKey = useMemo(() => subsystemGraphLayoutKey({ components, relations, walkthroughs }), [components, relations, walkthroughs]);
     const componentsRef = useRef(components);
-    const edgesRef = useRef(edges);
+    const relationsRef = useRef(relations);
+    const walkthroughsRef = useRef(walkthroughs);
     componentsRef.current = components;
-    edgesRef.current = edges;
+    relationsRef.current = relations;
+    walkthroughsRef.current = walkthroughs;
     // Track measured dimensions from React Flow's dimension changes.
     // These arrive as { type: 'dimensions', id, dimensions } in onNodesChange.
     // Retained across same-id layoutKey updates so Pass 2 can run without a remount.
@@ -233,7 +236,11 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
         prevMeasuredSigRef.current = '';
         // Bump generation so any in-flight Pass 2 from the prior layoutKey is ignored.
         pass2GenRef.current += 1;
-        const doc = { components: componentsRef.current, edges: edgesRef.current };
+        const doc = {
+            components: componentsRef.current,
+            relations: relationsRef.current,
+            walkthroughs: walkthroughsRef.current,
+        };
         void buildSubsystemGraph(doc, { maxNodeWidth, showEdgeLabels })
             .then(({ nodes, edges: e }) => {
             if (!alive)
@@ -284,7 +291,7 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
         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]));
         const gen = ++pass2GenRef.current;
-        void buildSubsystemGraph({ components, edges }, { maxNodeWidth, showEdgeLabels, measuredWidths, measuredHeights })
+        void buildSubsystemGraph({ components, relations, walkthroughs }, { maxNodeWidth, showEdgeLabels, measuredWidths, measuredHeights })
             .then(({ nodes, edges: e }) => {
             if (gen !== pass2GenRef.current)
                 return;
@@ -298,7 +305,7 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
             // Reveal Pass 1 layout rather than leaving the cover up forever.
             setLayoutReady(true);
         });
-    }, [built.nodes, components, edges, maxNodeWidth, showEdgeLabels]);
+    }, [built.nodes, components, relations, walkthroughs, maxNodeWidth, showEdgeLabels]);
     // After Pass 1 commits, try Pass 2 immediately with retained measurements.
     // Same-id live updates often get no new React Flow `dimensions` events, so
     // waiting only on onNodesChange leaves the cover stuck.
@@ -329,7 +336,7 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
     // Node components call SUBSYSTEM_CALLBACKS.onSelect on click (their inner
     // onClick stops React Flow propagation), so wire selection + width through it.
     // Lookup from edge id → the authored SubsystemComponentEdge (for onEdgeSelect).
-    const edgeById = useMemo(() => new Map(edges.map((e) => [e.id, e])), [edges]);
+    const edgeById = useMemo(() => new Map(graphEdges.map((e) => [e.id, e])), [graphEdges]);
     // Shared edge-selection logic used by both React Flow's onEdgeClick and the
     // clickable edge label (SUBSYSTEM_CALLBACKS.onEdgeSelect).
     const selectEdge = useCallback((edgeId) => {
@@ -339,8 +346,8 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
         }
         const src = edgeById.get(edgeId);
         setSelectedEdgeId(edgeId);
-        // A direct edge selection on the canvas supersedes any throughline focus.
-        setFocusedThroughlineId(null);
+        // A direct edge selection on the canvas supersedes any walkthrough focus.
+        setFocusedWalkthroughId(null);
         setFocusedStepIndex(null);
         if (src)
             onEdgeSelect?.(src);
@@ -358,7 +365,7 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
                 }
                 setSelected(comp);
                 setSelectedEdgeId(null);
-                setFocusedThroughlineId(null);
+                setFocusedWalkthroughId(null);
                 setFocusedStepIndex(null);
                 onSelect?.(id);
             }
@@ -382,50 +389,50 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
     // 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.
+    // Edge ids in walkthrough focus (an active flow's edge set, or a single
+    // step's edge). Used to frame the camera. `null` = no walkthrough focus.
     const focusEdgeIds = useMemo(() => {
-        if (focusedThroughlineId == null || !throughlines)
+        if (focusedWalkthroughId == null || !walkthroughs)
             return null;
-        const tl = throughlines.find((t) => t.id === focusedThroughlineId);
+        const tl = walkthroughs.find((t) => t.id === focusedWalkthroughId);
         if (!tl)
             return null;
         if (focusedStepIndex != null) {
             const step = tl.steps[focusedStepIndex];
-            return step ? new Set([step.edgeId]) : null;
+            return step ? new Set([walkthroughStepGraphEdgeId(step)]) : null;
         }
-        return new Set(tl.steps.map((s) => s.edgeId));
-    }, [throughlines, focusedThroughlineId, focusedStepIndex]);
+        return new Set(tl.steps.map((s) => walkthroughStepGraphEdgeId(s)));
+    }, [walkthroughs, focusedWalkthroughId, focusedStepIndex]);
     // 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(() => {
-        const activeId = focusedThroughlineId ?? hoveredThroughlineStep?.throughlineId;
-        if (activeId == null || !throughlines)
+        const activeId = focusedWalkthroughId ?? hoveredWalkthroughStep?.walkthroughId;
+        if (activeId == null || !walkthroughs)
             return null;
-        const tl = throughlines.find((t) => t.id === activeId);
+        const tl = walkthroughs.find((t) => t.id === activeId);
         if (!tl)
             return null;
         const map = new Map();
         tl.steps.forEach((s, i) => {
-            const list = map.get(s.edgeId) ?? [];
+            const list = map.get(walkthroughStepGraphEdgeId(s)) ?? [];
             list.push(i + 1);
-            map.set(s.edgeId, list);
+            map.set(walkthroughStepGraphEdgeId(s), list);
         });
         return map;
-    }, [throughlines, focusedThroughlineId, hoveredThroughlineStep]);
-    // Union of every expanded (opened) throughline's edges — the visible set.
+    }, [walkthroughs, focusedWalkthroughId, hoveredWalkthroughStep]);
+    // Union of every expanded (opened) walkthrough's edges — the visible set.
     const openedEdgeIds = useMemo(() => {
-        if (!throughlines || expandedThroughlines.size === 0)
+        if (!walkthroughs || expandedWalkthroughs.size === 0)
             return null;
         const ids = new Set();
-        for (const tl of throughlines) {
-            if (!expandedThroughlines.has(tl.id))
+        for (const tl of walkthroughs) {
+            if (!expandedWalkthroughs.has(tl.id))
                 continue;
             for (const s of tl.steps)
-                ids.add(s.edgeId);
+                ids.add(walkthroughStepGraphEdgeId(s));
         }
         return ids.size > 0 ? ids : null;
-    }, [throughlines, expandedThroughlines]);
+    }, [walkthroughs, expandedWalkthroughs]);
     const endpointsOf = (edgeIds) => {
         if (!edgeIds)
             return null;
@@ -440,17 +447,17 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
     };
     // Edge/nodes involved in the hovered step or whole flow.
     const hoverEdgeIds = useMemo(() => {
-        if (!hoveredThroughlineStep || !throughlines)
+        if (!hoveredWalkthroughStep || !walkthroughs)
             return null;
-        const tl = throughlines.find((t) => t.id === hoveredThroughlineStep.throughlineId);
+        const tl = walkthroughs.find((t) => t.id === hoveredWalkthroughStep.walkthroughId);
         if (!tl)
             return null;
-        if (hoveredThroughlineStep.stepIndex == null) {
-            return new Set(tl.steps.map((s) => s.edgeId));
+        if (hoveredWalkthroughStep.stepIndex == null) {
+            return new Set(tl.steps.map((s) => walkthroughStepGraphEdgeId(s)));
         }
-        const step = tl.steps[hoveredThroughlineStep.stepIndex];
-        return step ? new Set([step.edgeId]) : null;
-    }, [throughlines, hoveredThroughlineStep]);
+        const step = tl.steps[hoveredWalkthroughStep.stepIndex];
+        return step ? new Set([walkthroughStepGraphEdgeId(step)]) : null;
+    }, [walkthroughs, hoveredWalkthroughStep]);
     // While hovering with a *step* already selected, brighten the union of
     // selected + hovered participants. Whole-flow focus (or no focus) keeps
     // the old hover-replace preview so a step hover still dims the rest.
@@ -497,8 +504,8 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
     // React Flow's own selection state from updating.
     const dispNodes = useMemo(() => {
         // While a step/flow is hovered, selected + hovered participants stay
-        // bright; everything else among the currently-visible (opened-throughline)
-        // nodes is dimmed. Nodes outside the opened-throughline set stay hidden.
+        // bright; everything else among the currently-visible (opened-walkthrough)
+        // nodes is dimmed. Nodes outside the opened-walkthrough set stay hidden.
         return xyflowNodesBase.map((n) => {
             // Boundary frames follow their members: hidden when no member is
             // visible, dimmed when members are dimmed. Never selectable.
@@ -613,7 +620,7 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
     const onNodeClick = useCallback((_e, node) => {
         const comp = node.data?.component;
         setSelectedEdgeId(null);
-        setFocusedThroughlineId(null);
+        setFocusedWalkthroughId(null);
         setFocusedStepIndex(null);
         if (node.type === 'subsystem-component' && comp) {
             // Clicking the already-selected node unselects it (toggle off).
@@ -634,13 +641,13 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
     const onPaneClick = useCallback(() => {
         setSelected(null);
         setSelectedEdgeId(null);
-        setFocusedThroughlineId(null);
+        setFocusedWalkthroughId(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 hasWalkthroughs = useMemo(() => (walkthroughs?.length ?? 0) > 0, [walkthroughs]);
     const [collapsedRepos, setCollapsedRepos] = useState(new Set());
     const toggleRepoCollapsed = useCallback((key) => {
         setCollapsedRepos((prev) => {
@@ -671,12 +678,12 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
         setDrawerTarget({ kind: 'file', file, startLine });
         onFileSelect?.(file);
     }, [onFileSelect]);
-    // Camera helper shared by the throughline interactions: frames the focused
+    // Camera helper shared by the walkthrough 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) => {
-        if (!zoomOnThroughlineFocus)
+        if (!zoomOnWalkthroughFocus)
             return;
         const nodeIds = new Set();
         for (const e of baseEdges) {
@@ -692,11 +699,11 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
             padding: 0.25,
             duration: 300,
         });
-    }, [baseEdges, fitView, zoomOnThroughlineFocus]);
-    // Zoom back out to the full diagram after the last expanded throughline
+    }, [baseEdges, fitView, zoomOnWalkthroughFocus]);
+    // Zoom back out to the full diagram after the last expanded walkthrough
     // closes (visibility restores non-flow nodes that were hidden).
     const fitOverview = useCallback(() => {
-        if (!zoomOnThroughlineFocus)
+        if (!zoomOnWalkthroughFocus)
             return;
         fitView({
             padding: 0.1,
@@ -705,62 +712,77 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
             maxZoom: 2,
             duration: 300,
         });
-    }, [fitView, zoomOnThroughlineFocus]);
+    }, [fitView, zoomOnWalkthroughFocus]);
     // 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)
+    // click. A stale walkthrough 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) => {
+    const focusWalkthroughEdges = useCallback((tl) => {
         setSelected(null);
         setSelectedEdgeId(null);
-        setHoveredThroughlineStep(null);
-        if (throughlineStepMode === 'dim') {
+        setHoveredWalkthroughStep(null);
+        if (walkthroughStepMode === 'dim') {
             setFocusedStepIndex(null);
-            setFocusedThroughlineId(null);
-            setDrawerTarget((prev) => (prev?.kind === 'throughline' ? null : prev));
+            setFocusedWalkthroughId(null);
+            setDrawerTarget((prev) => (prev?.kind === 'walkthrough' ? 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, throughlineStepMode]);
-    const clearThroughlineFocus = useCallback(() => {
-        setFocusedThroughlineId(null);
+        setFocusedWalkthroughId(tl.id);
+        fitFocusBounds(new Set(tl.steps.map((s) => walkthroughStepGraphEdgeId(s))));
+        setDrawerTarget((prev) => (prev?.kind === 'walkthrough' ? null : prev));
+    }, [fitFocusBounds, walkthroughStepMode]);
+    const clearWalkthroughFocus = useCallback(() => {
+        setFocusedWalkthroughId(null);
         setFocusedStepIndex(null);
-        setHoveredThroughlineStep(null);
-        setDrawerTarget((prev) => (prev?.kind === 'throughline' ? null : prev));
+        setHoveredWalkthroughStep(null);
+        setDrawerTarget((prev) => (prev?.kind === 'walkthrough' ? null : prev));
     }, []);
-    // Focus a single step's edge on the canvas and open/scroll the throughline
-    // drawer to that step's snippet.
+    // Focus a single step's edge on the canvas and open/scroll the walkthrough
+    // drawer to that step's snippet. Clicking the already-focused step clears
+    // step focus and returns to whole-flow (high-level) framing.
     // 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 focusWalkthroughStep = useCallback((tl, stepIndex) => {
         const step = tl.steps[stepIndex];
         if (!step)
             return;
         setSelected(null);
         setSelectedEdgeId(null);
-        if (throughlineStepMode === 'dim') {
+        if (walkthroughStepMode === 'dim') {
+            setFocusedStepIndex(null);
+            setFocusedWalkthroughId(null);
+            setHoveredWalkthroughStep({ walkthroughId: tl.id, stepIndex });
+            setDrawerTarget((prev) => (prev?.kind === 'walkthrough' ? null : prev));
+            return;
+        }
+        // Toggle: clicking the selected step unselects it (back to whole flow).
+        if (focusedWalkthroughId === tl.id && focusedStepIndex === stepIndex) {
             setFocusedStepIndex(null);
-            setFocusedThroughlineId(null);
-            setHoveredThroughlineStep({ throughlineId: tl.id, stepIndex });
-            setDrawerTarget((prev) => (prev?.kind === 'throughline' ? null : prev));
+            // Pointer is still over the row — keep hover preview so dimming doesn't
+            // flash off until mouseleave.
+            setHoveredWalkthroughStep({ walkthroughId: tl.id, stepIndex });
+            setDrawerTarget((prev) => (prev?.kind === 'walkthrough' ? null : prev));
+            if (pendingFocusFitRef.current != null) {
+                window.clearTimeout(pendingFocusFitRef.current);
+                pendingFocusFitRef.current = null;
+            }
+            fitFocusBounds(new Set(tl.steps.map((s) => walkthroughStepGraphEdgeId(s))));
             return;
         }
         setFocusedStepIndex(stepIndex);
-        setFocusedThroughlineId(tl.id);
-        setHoveredThroughlineStep(null);
+        setFocusedWalkthroughId(tl.id);
+        setHoveredWalkthroughStep(null);
         // Open the drawer before fitting. If it was closed, wait for its height
         // transition so fitView uses the reduced canvas — not full height.
         const drawerWasOpen = drawerOpenRef.current;
-        if (renderThroughlineViewer) {
+        if (renderWalkthroughViewer) {
             setDrawerTarget({
-                kind: 'throughline',
-                throughlineId: tl.id,
+                kind: 'walkthrough',
+                walkthroughId: tl.id,
                 stepIndex,
             });
         }
@@ -771,7 +793,7 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
                 startLine: step.line,
             });
         }
-        const edgeIds = new Set([step.edgeId]);
+        const edgeIds = new Set([walkthroughStepGraphEdgeId(step)]);
         if (pendingFocusFitRef.current != null) {
             window.clearTimeout(pendingFocusFitRef.current);
             pendingFocusFitRef.current = null;
@@ -785,7 +807,13 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
                 requestAnimationFrame(() => fitFocusBounds(edgeIds));
             }, FILE_DRAWER_HEIGHT_MS + 20);
         }
-    }, [fitFocusBounds, renderThroughlineViewer, throughlineStepMode]);
+    }, [
+        fitFocusBounds,
+        focusedStepIndex,
+        focusedWalkthroughId,
+        renderWalkthroughViewer,
+        walkthroughStepMode,
+    ]);
     useEffect(() => {
         return () => {
             if (pendingFocusFitRef.current != null) {
@@ -802,10 +830,10 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
     useEffect(() => {
         const prev = prevPreviewEdgeIdsRef.current;
         prevPreviewEdgeIdsRef.current = previewEdgeIds;
-        if (!zoomOnThroughlineFocus || throughlineStepMode === 'dim')
+        if (!zoomOnWalkthroughFocus || walkthroughStepMode === 'dim')
             return;
         // Camera follows hover only when a specific step is already focused.
-        if (focusedThroughlineId == null || focusedStepIndex == null)
+        if (focusedWalkthroughId == null || focusedStepIndex == null)
             return;
         if (previewEdgeIds) {
             fitFocusBounds(previewEdgeIds);
@@ -817,33 +845,33 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
     }, [
         previewEdgeIds,
         focusEdgeIds,
-        focusedThroughlineId,
+        focusedWalkthroughId,
         focusedStepIndex,
         fitFocusBounds,
-        zoomOnThroughlineFocus,
-        throughlineStepMode,
+        zoomOnWalkthroughFocus,
+        walkthroughStepMode,
     ]);
-    // Graph-only embeds: cycle throughline steps with hover-style dimming.
+    // Graph-only embeds: cycle walkthrough steps with hover-style dimming.
     useEffect(() => {
-        if (!autoPlayThroughlines || !throughlines?.length || !layoutReady)
+        if (!autoPlayWalkthroughs || !walkthroughs?.length || !layoutReady)
             return;
-        const playable = throughlines.filter((tl) => tl.steps.length > 0);
+        const playable = walkthroughs.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 interval = Math.max(400, walkthroughAutoPlayIntervalMs);
         const tick = () => {
             if (cancelled)
                 return;
             const tl = playable[tlIdx];
             setSelected(null);
             setSelectedEdgeId(null);
-            setFocusedThroughlineId(null);
+            setFocusedWalkthroughId(null);
             setFocusedStepIndex(null);
-            setHoveredThroughlineStep({ throughlineId: tl.id, stepIndex: stepIdx });
+            setHoveredWalkthroughStep({ walkthroughId: tl.id, stepIndex: stepIdx });
             stepIdx += 1;
             if (stepIdx >= tl.steps.length) {
                 stepIdx = 0;
@@ -856,16 +884,16 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
             cancelled = true;
             if (timer != null)
                 window.clearTimeout(timer);
-            setHoveredThroughlineStep(null);
+            setHoveredWalkthroughStep(null);
         };
-    }, [autoPlayThroughlines, throughlines, throughlineAutoPlayIntervalMs, layoutReady]);
-    // Arrow keys step through the focused throughline once a step is active
+    }, [autoPlayWalkthroughs, walkthroughs, walkthroughAutoPlayIntervalMs, layoutReady]);
+    // Arrow keys step through the focused walkthrough once a step is active
     // (sidebar click or drawer open). Ignores typing targets and chords.
     useEffect(() => {
-        if (focusedThroughlineId == null || focusedStepIndex == null || !throughlines) {
+        if (focusedWalkthroughId == null || focusedStepIndex == null || !walkthroughs) {
             return;
         }
-        const tl = throughlines.find((t) => t.id === focusedThroughlineId);
+        const tl = walkthroughs.find((t) => t.id === focusedWalkthroughId);
         if (!tl || tl.steps.length === 0)
             return;
         const onKeyDown = (e) => {
@@ -892,19 +920,19 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
             if (next === focusedStepIndex)
                 return;
             e.preventDefault();
-            focusThroughlineStep(tl, next);
+            focusWalkthroughStep(tl, next);
         };
         window.addEventListener('keydown', onKeyDown);
         return () => window.removeEventListener('keydown', onKeyDown);
     }, [
-        focusedThroughlineId,
+        focusedWalkthroughId,
         focusedStepIndex,
-        throughlines,
-        focusThroughlineStep,
+        walkthroughs,
+        focusWalkthroughStep,
     ]);
-    const toggleThroughlineCollapsed = useCallback((tlId) => {
-        const collapsingLast = expandedThroughlines.has(tlId) && expandedThroughlines.size === 1;
-        setExpandedThroughlines((prev) => {
+    const toggleWalkthroughCollapsed = useCallback((tlId) => {
+        const collapsingLast = expandedWalkthroughs.has(tlId) && expandedWalkthroughs.size === 1;
+        setExpandedWalkthroughs((prev) => {
             const next = new Set(prev);
             if (next.has(tlId))
                 next.delete(tlId);
@@ -912,7 +940,7 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
                 next.add(tlId);
             return next;
         });
-        if (!collapsingLast || !zoomOnThroughlineFocus)
+        if (!collapsingLast || !zoomOnWalkthroughFocus)
             return;
         // Cancel any pending focus fit so it doesn't fight the overview zoom.
         if (pendingFocusFitRef.current != null) {
@@ -927,7 +955,7 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
             pendingFocusFitRef.current = null;
             requestAnimationFrame(() => fitOverview());
         }, drawerWasOpen ? FILE_DRAWER_HEIGHT_MS + 20 : 20);
-    }, [expandedThroughlines, fitOverview, zoomOnThroughlineFocus]);
+    }, [expandedWalkthroughs, fitOverview, zoomOnWalkthroughFocus]);
     // 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(() => {
@@ -952,7 +980,7 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
             return;
         setSelected(comp);
         setSelectedEdgeId(null);
-        setFocusedThroughlineId(null);
+        setFocusedWalkthroughId(null);
         setFocusedStepIndex(null);
         onSelect?.(comp.id);
     }, [components, onSelect]);
@@ -1000,10 +1028,10 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
     const fileViewerRef = useRef(fileViewer);
     fileViewerRef.current = fileViewer;
     const renderDrawerContent = useCallback((file, opts) => fileViewerRef.current?.(file, opts) ?? null, []);
-    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', userSelect: sidebarDrag ? 'none' : undefined }, children: [!hideSidebar && (title || description || sidebarExtra || sidebarAfterDescription || treeFilePaths.length > 0 || hasThroughlines) && (_jsxs("div", { style: {
+    const walkthroughViewerRef = useRef(renderWalkthroughViewer);
+    walkthroughViewerRef.current = renderWalkthroughViewer;
+    const renderWalkthroughDrawerContent = useCallback((ctx) => walkthroughViewerRef.current?.(ctx) ?? null, []);
+    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 || hasWalkthroughs) && (_jsxs("div", { style: {
                     width: sidebarWidth,
                     minWidth: sidebarWidth,
                     borderRight: `1px solid ${theme.colors.border}`,
@@ -1041,7 +1069,7 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
                                             color: descToggleHover ? theme.colors.text : (theme.colors.textMuted ?? theme.colors.textSecondary),
                                             cursor: 'pointer',
                                             transition: 'background 120ms ease, color 120ms ease',
-                                        }, children: descriptionVisible ? _jsx(ChevronUp, { size: 14 }) : _jsx(ChevronDown, { size: 14 }) }))] })), description && descriptionVisible && (_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, disableBasePadding: true, fontSizeScale: 0.9, enableKeyboardScrolling: false, autoFocusOnVisible: false }) })), sidebarAfterDescription] }), (treeFilePaths.length > 0 || hasThroughlines) && (_jsxs("div", { style: {
+                                        }, children: descriptionVisible ? _jsx(ChevronUp, { size: 14 }) : _jsx(ChevronDown, { size: 14 }) }))] })), description && descriptionVisible && (_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, disableBasePadding: true, fontSizeScale: 0.9, enableKeyboardScrolling: false, autoFocusOnVisible: false }) })), sidebarAfterDescription] }), (treeFilePaths.length > 0 || hasWalkthroughs) && (_jsxs("div", { style: {
                             ...(showDesc ? { height: '50%' } : { flex: 1, minHeight: 0 }),
                             minHeight: 160,
                             flexShrink: 0,
@@ -1049,13 +1077,13 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
                             display: 'flex',
                             flexDirection: 'column',
                             overflow: 'hidden',
-                        }, children: [hasThroughlines && (_jsx("div", { role: "tablist", "aria-label": "Sidebar view", style: {
+                        }, children: [hasWalkthroughs && (_jsx("div", { role: "tablist", "aria-label": "Sidebar view", style: {
                                     display: 'flex',
                                     width: '100%',
                                     flexShrink: 0,
                                     borderBottom: `1px solid ${theme.colors.border}`,
                                     background: theme.colors.backgroundSecondary ?? theme.colors.background,
-                                }, children: ['flows', 'files'].map((view) => (_jsx("button", { type: "button", role: "tab", "aria-selected": sidebarView === view, onClick: () => setSidebarView(view), style: {
+                                }, children: ['walkthroughs', 'files'].map((view) => (_jsx("button", { type: "button", role: "tab", "aria-selected": sidebarView === view, onClick: () => setSidebarView(view), style: {
                                         flex: 1,
                                         minWidth: 0,
                                         padding: '8px 8px',
@@ -1069,16 +1097,16 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
                                         fontFamily: theme.fonts.monospace,
                                         textTransform: 'capitalize',
                                         cursor: 'pointer',
-                                    }, children: view }, view))) })), sidebarView === 'flows' && throughlines && throughlines.length > 0 ? (_jsx("div", { style: {
+                                    }, children: view === 'walkthroughs' ? 'Walkthroughs' : 'Files' }, view))) })), sidebarView === 'walkthroughs' && walkthroughs && walkthroughs.length > 0 ? (_jsx("div", { style: {
                                     flex: 1,
                                     minHeight: 0,
                                     overflowY: 'auto',
                                     padding: '0 0 12px',
-                                }, children: throughlines.map((tl) => (_jsx(ThroughlineFlow, { throughline: tl, edges: edges, collapsed: !expandedThroughlines.has(tl.id), active: focusedThroughlineId === tl.id
+                                }, children: walkthroughs.map((tl) => (_jsx(WalkthroughFlow, { walkthrough: tl, collapsed: !expandedWalkthroughs.has(tl.id), active: focusedWalkthroughId === 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 }), onHoverFlow: (tl) => setHoveredThroughlineStep({ throughlineId: tl.id, stepIndex: null }), onLeaveStep: () => setHoveredThroughlineStep(null) }, tl.id))) })) : treeFilePaths.length > 0 ? (_jsx(_Fragment, { children: repoGroups.groups.map((group, i) => {
+                                        : hoveredWalkthroughStep?.walkthroughId === tl.id
+                                            ? { stepIndex: hoveredWalkthroughStep.stepIndex }
+                                            : null, onToggleCollapsed: toggleWalkthroughCollapsed, onFocusFlow: focusWalkthroughEdges, onClearFocus: clearWalkthroughFocus, onFocusStep: focusWalkthroughStep, onHoverStep: (tl, i) => setHoveredWalkthroughStep({ walkthroughId: tl.id, stepIndex: i }), onHoverFlow: (tl) => setHoveredWalkthroughStep({ walkthroughId: tl.id, stepIndex: null }), onLeaveStep: () => setHoveredWalkthroughStep(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: {
@@ -1088,7 +1116,7 @@ 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] }))] })), !hideSidebar && (title || description || sidebarExtra || sidebarAfterDescription || treeFilePaths.length > 0 || hasThroughlines) && (_jsx("div", { onMouseDown: onSidebarResizeStart, "aria-label": "Resize sidebar", title: "Drag to resize", style: {
+                                }) })) : null] }))] })), !hideSidebar && (title || description || sidebarExtra || sidebarAfterDescription || treeFilePaths.length > 0 || hasWalkthroughs) && (_jsx("div", { onMouseDown: onSidebarResizeStart, "aria-label": "Resize sidebar", title: "Drag to resize", style: {
                     width: 3,
                     flexShrink: 0,
                     cursor: 'col-resize',
@@ -1151,7 +1179,7 @@ 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 || overlayThroughlineTitle || overlayThroughlineStep) && (_jsxs("div", { style: {
+                                }, children: [_jsx(Background, { variant: BackgroundVariant.Dots, gap: 16, size: 1 }), _jsx(Controls, { showZoom: true, showFitView: true, showInteractive: true })] }, `${baseNodesKey}-${baseEdgesKey}`), (graphTitle || overlayWalkthroughTitle || overlayWalkthroughStep) && (_jsxs("div", { style: {
                                     position: 'absolute',
                                     top: 10,
                                     left: '50%',
@@ -1177,9 +1205,9 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
                                             border: `1px solid ${theme.colors.border}`,
                                             borderRadius: 6,
                                             boxShadow: '0 1px 4px rgba(0,0,0,0.25)',
-                                        }, children: graphTitle })), overlayThroughlineTitle && (_jsxs("div", { style: {
+                                        }, children: graphTitle })), overlayWalkthroughTitle && (_jsxs("div", { style: {
                                             maxWidth: '100%',
-                                            minWidth: overlayThroughlineStep ? 160 : undefined,
+                                            minWidth: overlayWalkthroughStep ? 160 : undefined,
                                             display: 'flex',
                                             flexDirection: 'column',
                                             background: theme.colors.backgroundSecondary ?? theme.colors.background,
@@ -1188,9 +1216,9 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
                                             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: {
+                                        }, "aria-label": overlayWalkthroughStep
+                                            ? `${overlayWalkthroughTitle}, step ${overlayWalkthroughStep.index} of ${overlayWalkthroughStep.total}`
+                                            : overlayWalkthroughTitle, children: [_jsx("div", { style: {
                                                     padding: '5px 14px',
                                                     fontSize: theme.fontSizes[2] ?? theme.fontSizes[1],
                                                     fontWeight: 600,
@@ -1200,14 +1228,14 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
                                                     textOverflow: 'ellipsis',
                                                     whiteSpace: 'nowrap',
                                                     textAlign: 'center',
-                                                }, children: overlayThroughlineTitle }), overlayThroughlineStep && overlayThroughlineStep.total > 0 && (_jsx("div", { style: {
+                                                }, children: overlayWalkthroughTitle }), overlayWalkthroughStep && overlayWalkthroughStep.total > 0 && (_jsx("div", { style: {
                                                     display: 'flex',
                                                     gap: 3,
                                                     padding: '0 6px 5px',
-                                                }, "aria-hidden": "true", children: Array.from({ length: overlayThroughlineStep.total }, (_, i) => {
+                                                }, "aria-hidden": "true", children: Array.from({ length: overlayWalkthroughStep.total }, (_, i) => {
                                                     const n = i + 1;
-                                                    const active = n === overlayThroughlineStep.index;
-                                                    const done = n < overlayThroughlineStep.index;
+                                                    const active = n === overlayWalkthroughStep.index;
+                                                    const done = n < overlayWalkthroughStep.index;
                                                     return (_jsx("span", { style: {
                                                             flex: 1,
                                                             height: 2,
@@ -1220,7 +1248,7 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
                                                             opacity: active ? 1 : done ? 0.75 : 0.4,
                                                             transition: 'opacity 120ms ease, background 120ms ease',
                                                         } }, n));
-                                                }) }))] })), overlayThroughlineStep?.annotation && (_jsx("div", { style: {
+                                                }) }))] })), overlayWalkthroughStep?.annotation && (_jsx("div", { style: {
                                             maxWidth: '100%',
                                             padding: '6px 14px',
                                             background: theme.colors.backgroundSecondary ?? theme.colors.background,
@@ -1232,7 +1260,7 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
                                             fontFamily: theme.fonts.body,
                                             color: theme.colors.textMuted ?? theme.colors.textSecondary,
                                             lineHeight: 1.35,
-                                        }, children: overlayThroughlineStep.annotation }))] })), selected && (_jsx("div", { style: {
+                                        }, children: overlayWalkthroughStep.annotation }))] })), selected && (_jsx("div", { style: {
                                     position: 'absolute',
                                     top: 10,
                                     right: 10,
@@ -1244,9 +1272,9 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
                                     border: `1px solid ${theme.colors.border}`,
                                     borderRadius: 8,
                                     boxShadow: '0 8px 24px rgba(0,0,0,0.35)',
-                                }, children: _jsx(ComponentDeclaration, { component: selected, onOpenFile: onOpenDeclarationFile, onRelatedSelect: resolveRelatedComponent, onVerify: onVerifyComponent, verification: componentVerification }) }))] }), _jsx(FileDrawer, { title: drawerTitle, onClose: () => setDrawerTarget(null), children: drawerTarget?.kind === 'throughline' &&
-                            focusedThroughline &&
-                            renderThroughlineViewer ? (_jsx(ThroughlineDrawerContent, { render: renderThroughlineDrawerContent, throughline: focusedThroughline, stepIndex: drawerTarget.stepIndex })) : drawerTarget?.kind === 'file' ? (_jsx(FileDrawerContent, { render: renderDrawerContent, file: drawerTarget.file, startLine: drawerTarget.startLine })) : null }), _jsx(GraphLayoutCover, { revealed: layoutReady }), canvasOverlay] })] }));
+                                }, children: _jsx(ComponentDeclaration, { component: selected, onOpenFile: onOpenDeclarationFile, onRelatedSelect: resolveRelatedComponent, onVerify: onVerifyComponent, verification: componentVerification }) }))] }), _jsx(FileDrawer, { title: drawerTitle, onClose: () => setDrawerTarget(null), children: drawerTarget?.kind === 'walkthrough' &&
+                            focusedWalkthrough &&
+                            renderWalkthroughViewer ? (_jsx(WalkthroughDrawerContent, { render: renderWalkthroughDrawerContent, walkthrough: focusedWalkthrough, stepIndex: drawerTarget.stepIndex })) : drawerTarget?.kind === 'file' ? (_jsx(FileDrawerContent, { render: renderDrawerContent, file: drawerTarget.file, startLine: drawerTarget.startLine })) : null }), _jsx(GraphLayoutCover, { revealed: layoutReady }), canvasOverlay] })] }));
 }
 /** Sidebar header for one repo's tree: owner avatar + repo name + file count.
  *  Clicking toggles the tree's visibility. */
@@ -1288,15 +1316,14 @@ function RepoGroupHeader({ group, collapsed, onToggle, }) {
                     whiteSpace: 'nowrap',
                 }, children: label })] }));
 }
-/** One collapsible throughline in the sidebar's flows panel. Clicking the
+/** One collapsible walkthrough 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, onHoverStep, onHoverFlow, onLeaveStep, }) {
+function WalkthroughFlow({ walkthrough, collapsed, active, onToggleCollapsed, onFocusFlow, onClearFocus, onFocusStep, onHoverStep, onHoverFlow, onLeaveStep, }) {
     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);
@@ -1318,10 +1345,10 @@ function ThroughlineFlow({ throughline, edges, collapsed, active, onToggleCollap
     useEffect(() => () => stopPlaying(), []);
     const startPlaying = useCallback(() => {
         if (collapsed)
-            onToggleCollapsed(throughline.id);
+            onToggleCollapsed(walkthrough.id);
         if (active === null || active.stepIndex !== null)
-            onFocusFlow(throughline);
-        const stepCount = throughline.steps.length;
+            onFocusFlow(walkthrough);
+        const stepCount = walkthrough.steps.length;
         if (stepCount === 0)
             return;
         setPlaying(true);
@@ -1332,12 +1359,12 @@ function ThroughlineFlow({ throughline, edges, collapsed, active, onToggleCollap
                 setPlaying(false);
                 return;
             }
-            onFocusStep(throughline, i);
+            onFocusStep(walkthrough, i);
             i += 1;
-            playTimerRef.current = window.setTimeout(tick, THROUGHLINE_PLAY_PAUSE_MS);
+            playTimerRef.current = window.setTimeout(tick, WALKTHROUGH_PLAY_PAUSE_MS);
         };
         tick();
-    }, [collapsed, active, onToggleCollapsed, onFocusFlow, throughline, onFocusStep]);
+    }, [collapsed, active, onToggleCollapsed, onFocusFlow, walkthrough, onFocusStep]);
     const togglePlay = useCallback(() => {
         if (playing) {
             stopPlaying();
@@ -1357,7 +1384,7 @@ function ThroughlineFlow({ throughline, edges, collapsed, active, onToggleCollap
     return (_jsxs("div", { children: [_jsxs("div", { onMouseEnter: () => {
                     setHeaderHover(true);
                     if (collapsed)
-                        onHoverFlow(throughline);
+                        onHoverFlow(walkthrough);
                 }, onMouseLeave: () => {
                     setHeaderHover(false);
                     if (collapsed)
@@ -1371,14 +1398,14 @@ function ThroughlineFlow({ throughline, edges, collapsed, active, onToggleCollap
                     transition: 'background 120ms ease',
                 }, children: [_jsx("button", { type: "button", onClick: () => {
                             if (collapsed) {
-                                onToggleCollapsed(throughline.id);
-                                onFocusFlow(throughline);
+                                onToggleCollapsed(walkthrough.id);
+                                onFocusFlow(walkthrough);
                             }
                             else if (active === null) {
-                                onFocusFlow(throughline);
+                                onFocusFlow(walkthrough);
                             }
                             else {
-                                onToggleCollapsed(throughline.id);
+                                onToggleCollapsed(walkthrough.id);
                                 onClearFocus();
                             }
                         }, style: {
@@ -1399,7 +1426,7 @@ function ThroughlineFlow({ throughline, edges, collapsed, active, onToggleCollap
                                 fontFamily: theme.fonts.monospace,
                                 fontWeight: 600,
                                 color: theme.colors.text,
-                            }, 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) => {
+                            }, children: walkthrough.title }) }), !collapsed && (_jsxs(_Fragment, { children: [_jsx("button", { type: "button", "aria-label": playing ? `Pause ${walkthrough.title} autoplay` : `Play ${walkthrough.title}`, title: playing ? 'Pause' : 'Play through steps', onMouseEnter: () => setPlayHover(true), onMouseLeave: () => setPlayHover(false), onClick: (e) => {
                                     e.stopPropagation();
                                     togglePlay();
                                 }, style: {
@@ -1416,9 +1443,9 @@ function ThroughlineFlow({ throughline, edges, collapsed, active, onToggleCollap
                                     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) => {
+                                }, children: playing ? _jsx(Pause, { size: 12, strokeWidth: 2 }) : _jsx(Play, { size: 12, strokeWidth: 2 }) }), _jsx("button", { type: "button", "aria-label": `Close ${walkthrough.title}`, onMouseEnter: () => setCloseHover(true), onMouseLeave: () => setCloseHover(false), onClick: (e) => {
                                     e.stopPropagation();
-                                    onToggleCollapsed(throughline.id);
+                                    onToggleCollapsed(walkthrough.id);
                                     if (active !== null)
                                         onClearFocus();
                                 }, style: {
@@ -1438,17 +1465,16 @@ function ThroughlineFlow({ throughline, edges, collapsed, active, onToggleCollap
                                 }, children: _jsx(X, { size: 12, strokeWidth: 2 }) })] }))] }), !collapsed && (_jsx("div", { style: { display: 'flex', flexDirection: 'column' }, onMouseLeave: () => {
                     setHoveredStep(null);
                     onLeaveStep();
-                }, children: throughline.steps.map((step, i) => {
-                    const edge = edgeById.get(step.edgeId);
-                    const mech = edge?.mechanism;
+                }, children: walkthrough.steps.map((step, i) => {
+                    const mech = step.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);
-                            onHoverStep(throughline, i);
-                        }, onClick: () => onFocusStep(throughline, i), style: {
+                            onHoverStep(walkthrough, i);
+                        }, onClick: () => onFocusStep(walkthrough, i), style: {
                             display: 'flex',
                             alignItems: 'center',
                             gap: 8,
@@ -1485,7 +1511,7 @@ function ThroughlineFlow({ throughline, edges, collapsed, active, onToggleCollap
                                             fontSize: theme.fontSizes[0],
                                             fontFamily: theme.fonts.monospace,
                                             color,
-                                        }, children: mech ?? step.edgeId }), _jsxs("span", { style: {
+                                        }, children: mech ?? step.mechanism }), _jsxs("span", { style: {
                                             flex: 1,
                                             minWidth: 0,
                                             overflow: 'hidden',
@@ -1494,7 +1520,7 @@ function ThroughlineFlow({ throughline, edges, collapsed, active, onToggleCollap
                                             fontSize: theme.fontSizes[0],
                                             fontFamily: theme.fonts.monospace,
                                             color: theme.colors.text,
-                                        }, children: [step.file.split('/').pop(), _jsxs("span", { style: { opacity: 0.7 }, children: [":", step.line] })] })] }))] }, `${step.edgeId}-${i}`));
+                                        }, children: [step.file.split('/').pop(), _jsxs("span", { style: { opacity: 0.7 }, children: [":", step.line] })] })] }))] }, `${walkthroughStepGraphEdgeId(step)}-${i}`));
                 }) }))] }));
 }
 export function SubsystemComponentGraph(props) {