@principal-ai/subsystems-react 0.44.3 → 0.45.0

package/dist/subsystem/SubsystemComponentGraph.js

@@ -8,7 +8,7 @@ import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-run
  * inside one labeled boundary frame; nodes without one sit outside every
  * boundary. Clicking a component invokes `onSelect`.
  *
- * When the model has components but no topology or walkthrough edges, the
+ * When the model has components but no topology or trail edges, the
  * canvas is a constructs catalog (list + signature) instead of a graph.
  *
  * This is a focused fork of the package's `GraphRenderer` pipeline (same ELK
@@ -20,11 +20,11 @@ import { ReactFlow, ReactFlowProvider, useReactFlow, useViewport, applyNodeChang
 import { useTheme } from '@principal-ade/industry-theme';
 import { FileText, X } from 'lucide-react';
 import { IndustryMarkdownSlide } from 'themed-markdown';
-import { buildSubsystemGraph, deriveGraphEdges, isConstructsOnlyModel, moduleGroupNodeId, isWalkthroughMechanism, edgeColor, MECHANISM_DESCRIPTIONS, subsystemGraphLayoutKey, walkthroughStepGraphEdgeId, } from './model';
+import { buildSubsystemGraph, deriveGraphEdges, isConstructsOnlyModel, moduleGroupNodeId, isTrailMechanism, edgeColor, MECHANISM_DESCRIPTIONS, subsystemGraphLayoutKey, trailStepGraphEdgeId, } from './model';
 import { ConstructsCatalog } from './ConstructsCatalog';
 import { SubsystemAgentsPanel, } from './AgentsPanel';
 import { MaintainLivePanel, } from '../components/maintain-events/MaintainLivePanel';
-import { SubsystemComponentNode, SubsystemGroupNode, SubsystemEdge, SUBSYSTEM_CALLBACKS, hexWithAlpha, EDGE_DIM_ALPHA, fileMatchForNode, flowElementVisibility } from './nodes';
+import { SubsystemComponentNode, SubsystemGroupNode, SubsystemEdge, SUBSYSTEM_CALLBACKS, hexWithAlpha, EDGE_DIM_ALPHA, fileMatchForNode, flowElementVisibility, flowNodeVisibility } from './nodes';
 import { SubsystemDiagnosticToggle } from './DiagnosticToggle';
 import { SubsystemIssueList, issueCategory, issueKindOrder, issueRung, ISSUE_KIND_ICON, ISSUE_RUNG_ORDER, } from './IssueList';
 import { SubsystemFileTree } from './SubsystemFileTree';
@@ -33,7 +33,7 @@ import { GRAPH_CANVAS_CLASS, GRAPH_NAV_PROPS, GraphChrome, GraphLayerStyle } fro
 import { ComponentDeclaration } from './ComponentDeclaration';
 import { FileDrawer, FILE_DRAWER_HEIGHT_MS } from './FileDrawer';
 import { buildRepoGroups, repoAvatarUrl } from './paths';
-import { WalkthroughsPanel, WALKTHROUGH_PLAY_PAUSE_MS } from './WalkthroughsPanel';
+import { TrailsPanel, TRAIL_PLAY_PAUSE_MS } from './TrailsPanel';
 import { EDGE_LABEL_WIDTH, EDGE_LABEL_HEIGHT, EDGE_LABEL_FONT_SIZE, EDGE_LABEL_CLOUD_PATH, EDGE_LABEL_CLOUD_EXTRA_TOP, } from '../utils/edgeLabel';
 /** Identifiers a token could match to name this component as a construct. */
 function constructIdentifiers(comp) {
@@ -112,9 +112,9 @@ function FileOverlayCloseButton({ onClose }) {
             transition: 'background 120ms ease, color 120ms ease',
         }, children: _jsx(X, { size: 14 }) }));
 }
-const WalkthroughDrawerContent = memo(function WalkthroughDrawerContent({ render, walkthrough, stepIndex, onOpenFile, proposedAliases, resolveSymbol, onSymbolClick, }) {
+const TrailDrawerContent = memo(function TrailDrawerContent({ render, trail, stepIndex, onOpenFile, proposedAliases, resolveSymbol, onSymbolClick, }) {
     return (_jsx(_Fragment, { children: render({
-            walkthrough,
+            trail,
             stepIndex,
             onOpenFile,
             proposedAliases,
@@ -122,14 +122,14 @@ const WalkthroughDrawerContent = memo(function WalkthroughDrawerContent({ render
             onSymbolClick,
         }) }));
 });
-function Inner({ components, walkthroughs, graphifyRelations, orderByLine, initialWalkthroughId, onReorderWalkthroughs, onSelect, onEdgeSelect, measured: _measured, maxNodeWidth, showEdgeLabels, showSingletonFrames = true, moduleNesting, edgeView, title, hideSidebar, walkthroughStepMode = 'focus', autoPlayWalkthroughs = false, walkthroughAutoPlayIntervalMs = WALKTHROUGH_PLAY_PAUSE_MS, zoomOnWalkthroughFocus = true, walkthroughFocusDurationMs = 300, graphTitle, showWalkthroughTitle = false, description, canvasOverlay, sidebarExtra, sidebarAfterDescription, diagnostic, issues, showIssues, focusIssueCategory, onSelectIssue, onApplyIssueFix, onHoverIssue, renderFileView, renderFileViewer, renderWalkthroughViewer, onFileSelect, componentVerification, onInspectSymbol, boundaryColors, hideDrawer = false, persistKey, liveEvents, agentsPanel }) {
+function Inner({ components, trails, graphifyRelations, orderByLine, initialTrailId, onReorderTrails, onSelect, onEdgeSelect, measured: _measured, maxNodeWidth, showEdgeLabels, showSingletonFrames = true, moduleNesting, edgeView, title, hideSidebar, trailStepMode = 'focus', autoPlayTrails = false, trailAutoPlayIntervalMs = TRAIL_PLAY_PAUSE_MS, zoomOnTrailFocus = true, trailFocusDurationMs = 300, graphTitle, showTrailTitle = false, description, canvasOverlay, sidebarExtra, sidebarAfterDescription, diagnostic, issues, showIssues, focusIssueCategory, onSelectIssue, onApplyIssueFix, onHoverIssue, renderFileView, renderFileViewer, renderTrailViewer, onFileSelect, componentVerification, onInspectSymbol, boundaryColors, hideDrawer = false, persistKey, liveEvents, agentsPanel }) {
     const { theme } = useTheme();
     const { fitView, fitBounds, screenToFlowPosition } = useReactFlow();
     const viewport = useViewport();
     // Restored once per mount from `localStorage` (see `readViewState`). Each
     // graph is its own tab/mount, so `persistKey` is stable for a mount.
     const persisted = useMemo(() => readViewState(persistKey), [persistKey]);
-    const graphEdges = useMemo(() => deriveGraphEdges({ walkthroughs }), [walkthroughs]);
+    const graphEdges = useMemo(() => deriveGraphEdges({ trails }), [trails]);
     const [built, setBuilt] = useState({
         nodes: [],
         edges: [],
@@ -137,9 +137,9 @@ function Inner({ components, walkthroughs, graphifyRelations, orderByLine, initi
     });
     const [layoutReady, setLayoutReady] = useState(false);
     const [selected, setSelected] = useState(null);
-    /** Bottom drawer: single file or walkthrough multi-snippet mode. */
+    /** Bottom drawer: single file or trail multi-snippet mode. */
     const [drawerTarget, setDrawerTarget] = useState(null);
-    /** Full-file layer over an open walkthrough drawer — walkthrough stays mounted. */
+    /** Full-file layer over an open trail drawer — trail stays mounted. */
     const [fileOverlay, setFileOverlay] = useState(null);
     // Mirror so step-focus can decide whether to wait for the drawer open
     // transition before fitView (avoids framing against full-height canvas).
@@ -214,39 +214,46 @@ function Inner({ components, walkthroughs, graphifyRelations, orderByLine, initi
                 cancelAnimationFrame(raf);
         };
     }, [pathFrameRects, screenToFlowPosition]);
-    // Walkthrough focus — selected flow (or step) is full strength; other
+    // Trail focus — selected flow (or step) is full strength; other
     // opened-flow members stay visible but dimmed; everything else is hidden.
     // Restored from the persisted view state when a `persistKey` is set.
-    const [focusedWalkthroughId, setFocusedWalkthroughId] = useState(persisted.focusedWalkthroughId ?? null);
+    const [focusedTrailId, setFocusedTrailId] = useState(persisted.focusedTrailId ?? null);
     // `null` = whole flow focused; a number = that single step's edge focused.
     const [focusedStepIndex, setFocusedStepIndex] = useState(persisted.focusedStepIndex ?? null);
-    // Hovered walkthrough in the flows panel: dims every canvas node/edge not
+    // Hovered trail 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 [hoveredWalkthroughStep, setHoveredWalkthroughStep] = useState(null);
-    // Sidebar bottom half: which panel is shown when walkthroughs exist.
-    const [sidebarView, setSidebarView] = useState(() => persisted.sidebarView ?? (walkthroughs?.length ? 'walkthroughs' : 'files'));
+    const [hoveredTrailStep, setHoveredTrailStep] = useState(null);
+    // Sidebar bottom half: which panel is shown when trails exist.
+    // The persisted value is membership-checked rather than trusted: a stale
+    // localStorage entry from before the walkthrough->trail rename would match
+    // neither panel and render a blank sidebar with no selected tab.
+    const [sidebarView, setSidebarView] = useState(() => {
+        const stored = persisted.sidebarView;
+        const restored = stored === 'files' || stored === 'trails' ? stored : 'trails';
+        return trails?.length ? restored : 'files';
+    });
     // Diagnostics area tab: issues list vs the Maintain agent pipeline.
     const [diagnosticsTab, setDiagnosticsTab] = useState(() => persisted.diagnosticsTab ?? 'issues');
     // One edge source at a time. When the caller doesn't pick, the sidebar's
-    // Files / Walkthroughs tab picks: Files draws graphify static edges,
-    // Walkthroughs draws runtime hop edges. Without visible tabs (no walkthroughs,
-    // or a sidebar-less embed) fall back to walkthrough edges.
-    const sidebarTabsVisible = !hideSidebar && (walkthroughs?.length ?? 0) > 0;
+    // Files / Trails tab picks: Files draws graphify static edges,
+    // Trails draws runtime step edges. Without visible tabs (no trails,
+    // or a sidebar-less embed) fall back to trail edges.
+    const sidebarTabsVisible = !hideSidebar && (trails?.length ?? 0) > 0;
     const resolvedEdgeView = edgeView ??
         (sidebarTabsVisible
-            ? (sidebarView === 'walkthroughs' ? 'walkthroughs' : 'graphify')
-            : (walkthroughs?.length ?? 0) > 0
-                ? 'walkthroughs'
+            ? (sidebarView === 'trails' ? 'trails' : 'graphify')
+            : (trails?.length ?? 0) > 0
+                ? 'trails'
                 : (graphifyRelations?.length ?? 0) > 0
                     ? 'graphify'
-                    : 'walkthroughs');
-    // Walkthrough flows the user has expanded (via the title row). Closed by
+                    : 'trails');
+    // Trail 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.
     // Restored from the persisted view state when a `persistKey` is set.
-    const [expandedWalkthroughs, setExpandedWalkthroughs] = useState(() => new Set(persisted.expandedWalkthroughs ?? []));
+    const [expandedTrails, setExpandedTrails] = useState(() => new Set(persisted.expandedTrails ?? []));
     // 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);
@@ -296,20 +303,20 @@ function Inner({ components, walkthroughs, graphifyRelations, orderByLine, initi
             document.removeEventListener('mouseup', onUp);
         };
     }, [sidebarDrag, sidebarMaxWidth, fitView, persistKey]);
-    // Persist the walkthrough working set per model. Each write merges into the
+    // Persist the trail working set per model. Each write merges into the
     // stored blob, so the three fields never clobber one another.
     useEffect(() => {
         if (!persistKey)
             return;
         writeViewState(persistKey, {
-            expandedWalkthroughs: Array.from(expandedWalkthroughs),
+            expandedTrails: Array.from(expandedTrails),
         });
-    }, [persistKey, expandedWalkthroughs]);
+    }, [persistKey, expandedTrails]);
     useEffect(() => {
         if (!persistKey)
             return;
-        writeViewState(persistKey, { focusedWalkthroughId });
-    }, [persistKey, focusedWalkthroughId]);
+        writeViewState(persistKey, { focusedTrailId });
+    }, [persistKey, focusedTrailId]);
     useEffect(() => {
         if (!persistKey)
             return;
@@ -343,60 +350,60 @@ function Inner({ components, walkthroughs, graphifyRelations, orderByLine, initi
         : drawerTarget?.kind === 'file'
             ? { file: drawerTarget.file, startLine: drawerTarget.startLine }
             : null;
-    const focusedWalkthrough = useMemo(() => {
-        if (drawerTarget?.kind !== 'walkthrough' || !walkthroughs)
+    const focusedTrail = useMemo(() => {
+        if (drawerTarget?.kind !== 'trail' || !trails)
             return null;
-        return walkthroughs.find((t) => t.id === drawerTarget.walkthroughId) ?? null;
-    }, [drawerTarget, walkthroughs]);
+        return trails.find((t) => t.id === drawerTarget.trailId) ?? null;
+    }, [drawerTarget, trails]);
     // Autoplay focus: a sidebar-less embed has no expanded flow to "open", so
     // branding every step as a selection would hide all other nodes. Instead the
-    // autoplay sets this (flow id + step) to frame the hop and dim the rest —
+    // autoplay sets this (flow id + step) to frame the step and dim the rest —
     // same treatment as hover — without hiding anything. Declared before the
     // overlay memos, which read it to title the canvas chip + step bar.
     const [autoPlayFocus, setAutoPlayFocus] = useState(null);
-    // Ref mirror of the drawer's walkthrough id so the symbol resolver stays
+    // Ref mirror of the drawer's trail id so the symbol resolver stays
     // stable across graph re-renders (the drawer is memoized on callback identity).
-    const drawerWalkthroughIdRef = useRef(null);
-    drawerWalkthroughIdRef.current = focusedWalkthrough?.id ?? null;
-    // Walkthrough shown on the canvas title chip (focus, hover highlight, or
+    const drawerTrailIdRef = useRef(null);
+    drawerTrailIdRef.current = focusedTrail?.id ?? null;
+    // Trail shown on the canvas title chip (focus, hover highlight, or
     // autoplay focus).
-    const overlayWalkthroughTitle = useMemo(() => {
-        if (!showWalkthroughTitle || !walkthroughs?.length)
+    const overlayTrailTitle = useMemo(() => {
+        if (!showTrailTitle || !trails?.length)
             return null;
-        const id = focusedWalkthroughId ??
-            autoPlayFocus?.walkthroughId ??
-            hoveredWalkthroughStep?.walkthroughId;
+        const id = focusedTrailId ??
+            autoPlayFocus?.trailId ??
+            hoveredTrailStep?.trailId;
         if (!id)
             return null;
-        return walkthroughs.find((t) => t.id === id)?.title ?? null;
+        return trails.find((t) => t.id === id)?.title ?? null;
     }, [
-        showWalkthroughTitle,
-        walkthroughs,
-        focusedWalkthroughId,
+        showTrailTitle,
+        trails,
+        focusedTrailId,
         autoPlayFocus,
-        hoveredWalkthroughStep,
+        hoveredTrailStep,
     ]);
     // Active step for the bottom-of-title progress + annotation chip.
-    const overlayWalkthroughStep = useMemo(() => {
-        if (!showWalkthroughTitle || !walkthroughs?.length)
+    const overlayTrailStep = useMemo(() => {
+        if (!showTrailTitle || !trails?.length)
             return null;
-        const tlId = focusedWalkthroughId ??
-            autoPlayFocus?.walkthroughId ??
-            hoveredWalkthroughStep?.walkthroughId ??
+        const tlId = focusedTrailId ??
+            autoPlayFocus?.trailId ??
+            hoveredTrailStep?.trailId ??
             null;
         let stepIndex = null;
-        if (focusedWalkthroughId != null) {
+        if (focusedTrailId != null) {
             stepIndex = focusedStepIndex;
         }
         else if (autoPlayFocus != null) {
             stepIndex = autoPlayFocus.stepIndex;
         }
-        else if (hoveredWalkthroughStep != null) {
-            stepIndex = hoveredWalkthroughStep.stepIndex;
+        else if (hoveredTrailStep != null) {
+            stepIndex = hoveredTrailStep.stepIndex;
         }
         if (tlId == null || stepIndex == null)
             return null;
-        const tl = walkthroughs.find((t) => t.id === tlId);
+        const tl = trails.find((t) => t.id === tlId);
         const step = tl?.steps[stepIndex];
         if (!step || !tl)
             return null;
@@ -406,19 +413,19 @@ function Inner({ components, walkthroughs, graphifyRelations, orderByLine, initi
             annotation: step.annotation,
         };
     }, [
-        showWalkthroughTitle,
-        walkthroughs,
-        focusedWalkthroughId,
+        showTrailTitle,
+        trails,
+        focusedTrailId,
         focusedStepIndex,
         autoPlayFocus,
-        hoveredWalkthroughStep,
+        hoveredTrailStep,
     ]);
     const drawerTitle = useMemo(() => {
         if (!drawerTarget)
             return null;
         if (drawerTarget.kind === 'file')
             return drawerTarget.file;
-        const tl = focusedWalkthrough;
+        const tl = focusedTrail;
         if (!tl)
             return null;
         if (drawerTarget.stepIndex == null)
@@ -428,7 +435,7 @@ function Inner({ components, walkthroughs, graphifyRelations, orderByLine, initi
             return tl.title;
         const site = `${step.file.split('/').pop() ?? step.file}:${step.line}`;
         return `${tl.title} · ${site}`;
-    }, [drawerTarget, focusedWalkthrough]);
+    }, [drawerTarget, focusedTrail]);
     // Refresh selected component when the components list updates (e.g. verify
     // writes back declarationRef).
     useEffect(() => {
@@ -441,12 +448,12 @@ function Inner({ components, walkthroughs, graphifyRelations, orderByLine, initi
     // 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, walkthroughs, graphifyRelations }), [components, walkthroughs, graphifyRelations]);
+    const layoutKey = useMemo(() => subsystemGraphLayoutKey({ components, trails, graphifyRelations }), [components, trails, graphifyRelations]);
     const componentsRef = useRef(components);
-    const walkthroughsRef = useRef(walkthroughs);
+    const trailsRef = useRef(trails);
     const graphifyRelationsRef = useRef(graphifyRelations);
     componentsRef.current = components;
-    walkthroughsRef.current = walkthroughs;
+    trailsRef.current = trails;
     graphifyRelationsRef.current = graphifyRelations;
     // Track measured dimensions from React Flow's dimension changes.
     // These arrive as { type: 'dimensions', id, dimensions } in onNodesChange.
@@ -464,7 +471,7 @@ function Inner({ components, walkthroughs, graphifyRelations, orderByLine, initi
         pass2GenRef.current += 1;
         const doc = {
             components: componentsRef.current,
-            walkthroughs: walkthroughsRef.current,
+            trails: trailsRef.current,
         };
         void buildSubsystemGraph(doc, {
             maxNodeWidth,
@@ -523,7 +530,7 @@ function Inner({ components, walkthroughs, graphifyRelations, orderByLine, initi
         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, walkthroughs }, { maxNodeWidth, showEdgeLabels, measuredWidths, measuredHeights, showSingletonFrames, moduleNesting, graphifyRelations, orderByLine })
+        void buildSubsystemGraph({ components, trails }, { maxNodeWidth, showEdgeLabels, measuredWidths, measuredHeights, showSingletonFrames, moduleNesting, graphifyRelations, orderByLine })
             .then(({ nodes, edges: e, absoluteRects }) => {
             if (gen !== pass2GenRef.current)
                 return;
@@ -537,7 +544,7 @@ function Inner({ components, walkthroughs, graphifyRelations, orderByLine, initi
             // Reveal Pass 1 layout rather than leaving the cover up forever.
             setLayoutReady(true);
         });
-    }, [built.nodes, components, walkthroughs, graphifyRelations, orderByLine, maxNodeWidth, showEdgeLabels, moduleNesting]);
+    }, [built.nodes, components, trails, graphifyRelations, orderByLine, maxNodeWidth, showEdgeLabels, moduleNesting]);
     // 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.
@@ -578,8 +585,8 @@ function Inner({ components, walkthroughs, graphifyRelations, orderByLine, initi
         }
         const src = edgeById.get(edgeId);
         setSelectedEdgeId(edgeId);
-        // A direct edge selection on the canvas supersedes any walkthrough focus.
-        setFocusedWalkthroughId(null);
+        // A direct edge selection on the canvas supersedes any trail focus.
+        setFocusedTrailId(null);
         setFocusedStepIndex(null);
         if (src)
             onEdgeSelect?.(src);
@@ -597,7 +604,7 @@ function Inner({ components, walkthroughs, graphifyRelations, orderByLine, initi
                 }
                 setSelected(comp);
                 setSelectedEdgeId(null);
-                setFocusedWalkthroughId(null);
+                setFocusedTrailId(null);
                 setFocusedStepIndex(null);
                 onSelect?.(alias);
             }
@@ -639,9 +646,9 @@ function Inner({ components, walkthroughs, graphifyRelations, orderByLine, initi
             return null;
         return moduleGroupNodeId(key);
     }, [components]);
-    // A `step` issue target names ONE step of a walkthrough — the walkthrough id in
+    // A `step` issue target names ONE step of a trail — the trail id in
     // `id`, the 0-based step position in `stepIndex`. Validated against the loaded
-    // walkthroughs so a finding left over from an edited flow resolves to null
+    // trails so a finding left over from an edited flow resolves to null
     // rather than framing whatever now happens to sit at that index.
     const issueStep = useCallback((issue) => {
         const target = issue.target;
@@ -649,11 +656,11 @@ function Inner({ components, walkthroughs, graphifyRelations, orderByLine, initi
             return null;
         if (target.id == null || target.stepIndex == null)
             return null;
-        const walkthrough = walkthroughs?.find((t) => t.id === target.id);
-        if (!walkthrough?.steps[target.stepIndex])
+        const trail = trails?.find((t) => t.id === target.id);
+        if (!trail?.steps[target.stepIndex])
             return null;
-        return { walkthrough, stepIndex: target.stepIndex };
-    }, [walkthroughs]);
+        return { trail, stepIndex: target.stepIndex };
+    }, [trails]);
     // Per-node diagnostics badge: fold each component-targeted finding that maps
     // to a verification rung into one badge per node — worst severity wins, the
     // chip shows the earliest failing rung, and the count tallies the findings.
@@ -731,7 +738,7 @@ function Inner({ components, walkthroughs, graphifyRelations, orderByLine, initi
     // target:
     //   component   → that node
     //   module      → every component in that module
-    //   walkthrough → the flow's nodes + its hop edges
+    //   trail → the flow's nodes + its step edges
     //   repo        → every component of that repo
     //   graph       → whole-graph finding; implicates nothing specific
     // Returns null when nothing is expanded, no expanded layer has findings, or
@@ -766,13 +773,13 @@ function Inner({ components, walkthroughs, graphifyRelations, orderByLine, initi
                     }
                 }
             }
-            else if (t.kind === 'walkthrough') {
-                const wt = (walkthroughs ?? []).find((w) => w.id === t.id || w.title === t.label);
+            else if (t.kind === 'trail') {
+                const wt = (trails ?? []).find((w) => w.id === t.id || w.title === t.label);
                 if (wt) {
                     for (const s of wt.steps) {
                         nodeIds.add(s.from);
                         nodeIds.add(s.to);
-                        edgeIds.add(walkthroughStepGraphEdgeId(s));
+                        edgeIds.add(trailStepGraphEdgeId(s));
                     }
                 }
             }
@@ -793,7 +800,7 @@ function Inner({ components, walkthroughs, graphifyRelations, orderByLine, initi
                 edgeIds.add(e.id);
         }
         return { nodeIds, edgeIds };
-    }, [issues, expandedIssueCategories, components, walkthroughs, resolveAlias]);
+    }, [issues, expandedIssueCategories, components, trails, resolveAlias]);
     const issueFocusNodeIds = issueFocus?.nodeIds ?? null;
     const issueFocusEdgeIds = issueFocus?.edgeIds ?? null;
     // When an edge is selected, dim every other edge + its label to focus it.
@@ -804,61 +811,61 @@ function Inner({ components, walkthroughs, graphifyRelations, orderByLine, initi
     selectedEdgeIdRef.current = selectedEdgeId;
     // Ref mirrors of the focused step, so `unfocusIssueTarget` (a useCallback
     // over early deps) can tell a step focus it still owns from one the user has
-    // since moved elsewhere in the walkthrough panel.
+    // since moved elsewhere in the trail panel.
     const focusedStepRef = useRef(null);
     focusedStepRef.current =
-        focusedWalkthroughId != null && focusedStepIndex != null
-            ? { walkthroughId: focusedWalkthroughId, stepIndex: focusedStepIndex }
+        focusedTrailId != null && focusedStepIndex != null
+            ? { trailId: focusedTrailId, stepIndex: focusedStepIndex }
             : null;
-    // 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.
+    // Edge ids in trail focus (an active flow's edge set, or a single
+    // step's edge). Used to frame the camera. `null` = no trail focus.
     const focusEdgeIds = useMemo(() => {
         if (autoPlayFocus) {
-            const tl = walkthroughs?.find((t) => t.id === autoPlayFocus.walkthroughId);
+            const tl = trails?.find((t) => t.id === autoPlayFocus.trailId);
             const step = tl?.steps[autoPlayFocus.stepIndex];
-            return step ? new Set([walkthroughStepGraphEdgeId(step)]) : null;
+            return step ? new Set([trailStepGraphEdgeId(step)]) : null;
         }
-        if (focusedWalkthroughId == null || !walkthroughs)
+        if (focusedTrailId == null || !trails)
             return null;
-        const tl = walkthroughs.find((t) => t.id === focusedWalkthroughId);
+        const tl = trails.find((t) => t.id === focusedTrailId);
         if (!tl)
             return null;
         if (focusedStepIndex != null) {
             const step = tl.steps[focusedStepIndex];
-            return step ? new Set([walkthroughStepGraphEdgeId(step)]) : null;
+            return step ? new Set([trailStepGraphEdgeId(step)]) : null;
         }
-        return new Set(tl.steps.map((s) => walkthroughStepGraphEdgeId(s)));
-    }, [walkthroughs, focusedWalkthroughId, focusedStepIndex, autoPlayFocus]);
+        return new Set(tl.steps.map((s) => trailStepGraphEdgeId(s)));
+    }, [trails, focusedTrailId, focusedStepIndex, autoPlayFocus]);
     // 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 = focusedWalkthroughId ?? hoveredWalkthroughStep?.walkthroughId;
-        if (activeId == null || !walkthroughs)
+        const activeId = focusedTrailId ?? hoveredTrailStep?.trailId;
+        if (activeId == null || !trails)
             return null;
-        const tl = walkthroughs.find((t) => t.id === activeId);
+        const tl = trails.find((t) => t.id === activeId);
         if (!tl)
             return null;
         const map = new Map();
         tl.steps.forEach((s, i) => {
-            const list = map.get(walkthroughStepGraphEdgeId(s)) ?? [];
+            const list = map.get(trailStepGraphEdgeId(s)) ?? [];
             list.push(i + 1);
-            map.set(walkthroughStepGraphEdgeId(s), list);
+            map.set(trailStepGraphEdgeId(s), list);
         });
         return map;
-    }, [walkthroughs, focusedWalkthroughId, hoveredWalkthroughStep]);
-    // Union of every expanded (opened) walkthrough's edges — the visible set.
+    }, [trails, focusedTrailId, hoveredTrailStep]);
+    // Union of every expanded (opened) trail's edges — the visible set.
     const openedEdgeIds = useMemo(() => {
-        if (!walkthroughs || expandedWalkthroughs.size === 0)
+        if (!trails || expandedTrails.size === 0)
             return null;
         const ids = new Set();
-        for (const tl of walkthroughs) {
-            if (!expandedWalkthroughs.has(tl.id))
+        for (const tl of trails) {
+            if (!expandedTrails.has(tl.id))
                 continue;
             for (const s of tl.steps)
-                ids.add(walkthroughStepGraphEdgeId(s));
+                ids.add(trailStepGraphEdgeId(s));
         }
         return ids.size > 0 ? ids : null;
-    }, [walkthroughs, expandedWalkthroughs]);
+    }, [trails, expandedTrails]);
     const endpointsOf = (edgeIds) => {
         if (!edgeIds)
             return null;
@@ -873,22 +880,22 @@ function Inner({ components, walkthroughs, graphifyRelations, orderByLine, initi
     };
     // Edge/nodes involved in the hovered step or whole flow.
     const hoverEdgeIds = useMemo(() => {
-        if (!hoveredWalkthroughStep || !walkthroughs)
+        if (!hoveredTrailStep || !trails)
             return null;
-        const tl = walkthroughs.find((t) => t.id === hoveredWalkthroughStep.walkthroughId);
+        const tl = trails.find((t) => t.id === hoveredTrailStep.trailId);
         if (!tl)
             return null;
-        if (hoveredWalkthroughStep.stepIndex == null) {
-            return new Set(tl.steps.map((s) => walkthroughStepGraphEdgeId(s)));
+        if (hoveredTrailStep.stepIndex == null) {
+            return new Set(tl.steps.map((s) => trailStepGraphEdgeId(s)));
         }
-        const step = tl.steps[hoveredWalkthroughStep.stepIndex];
-        return step ? new Set([walkthroughStepGraphEdgeId(step)]) : null;
-    }, [walkthroughs, hoveredWalkthroughStep]);
+        const step = tl.steps[hoveredTrailStep.stepIndex];
+        return step ? new Set([trailStepGraphEdgeId(step)]) : null;
+    }, [trails, hoveredTrailStep]);
     // 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.
     const previewEdgeIds = useMemo(() => {
-        // Autoplay drives focus without a hover, so its hop is the preview set.
+        // Autoplay drives focus without a hover, so its step is the preview set.
         if (autoPlayFocus)
             return focusEdgeIds;
         if (!hoverEdgeIds)
@@ -935,36 +942,29 @@ function Inner({ components, walkthroughs, graphifyRelations, orderByLine, initi
     // `isSelected` rides in data because the node's stopPropagation() keeps
     // 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-walkthrough)
-        // nodes is dimmed. Nodes outside the opened-walkthrough set stay hidden.
-        // Exception: with no expanded flow at all (a sidebar-less embed), there is
-        // nothing to hide toward — everything shows, and focus/hover only dims.
-        const noOpenedFlow = openedEdgeIds == null;
+        // While a step/flow is hovered, hovered participants stay bright; every
+        // other node is dimmed (and, when a flow is expanded, hidden). Exception:
+        // with no expanded flow at all (a sidebar-less embed) there is nothing to
+        // hide toward — everything shows, and focus/hover only dims.
         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 region = n.data?.region;
                 const memberAliases = region?.memberAliases ?? [];
-                // Hover/autoplay dim-only: never hide a frame (see the node branch).
-                const vis = flowElementVisibility({
+                // `brightNodeIds` is the focused step's endpoints. It has to be a
+                // spotlight member as well as a bright set: without an expanded flow
+                // there is no opened set, so dimming has to be driven from the
+                // participants or nothing outside the focused step would dim.
+                const dimSource = previewNodeIds ?? brightNodeIds ?? issueFocusNodeIds;
+                const { hidden, dimmed } = flowNodeVisibility({
                     inOpened: memberAliases.some((alias) => openedNodeIds?.has(alias) === true),
                     inSelected: memberAliases.some((alias) => brightNodeIds?.has(alias) === true),
+                    inSpotlight: memberAliases.some((alias) => dimSource?.has(alias) === true),
                     anyOpened: openedNodeIds != null,
-                    anySelected: brightNodeIds != null || previewNodeIds != null,
+                    anySelected: brightNodeIds != null,
+                    anySpotlight: dimSource != null,
                 });
-                // `brightNodeIds` is the focused step's endpoints. It has to be a dim
-                // source, not just a bright set: without an expanded flow,
-                // `flowElementVisibility` reports non-participants as *hidden*, and the
-                // noOpenedFlow escape below discards that — leaving them neither hidden
-                // nor dimmed. Naming the participants as the dim source dims everything
-                // outside the focused step however the flow got focused.
-                const dimSource = previewNodeIds ?? brightNodeIds ?? issueFocusNodeIds;
-                const dimmed = dimSource
-                    ? vis.hidden || !memberAliases.some((alias) => dimSource.has(alias))
-                    : vis.dimmed;
-                const hidden = noOpenedFlow ? false : vis.hidden;
                 // Host override wins over the library's derived frame color.
                 const color = region?.key != null ? boundaryColors?.[region.key] : undefined;
                 // Boundary findings badge the FRAME, not a member — a region's shape is
@@ -984,22 +984,20 @@ function Inner({ components, walkthroughs, graphifyRelations, orderByLine, initi
             }
             const comp = n.data?.component;
             const fileMatch = fileMatchForNode(comp?.file, openFile, focusNodeIds?.has(n.id) === true);
-            // Hover/autoplay is a dim-only signal: never hide non-participants (there
-            // may be no "opened" flow to reveal them, e.g. a sidebar-less autoplay
-            // embed), only dim them. Bases selection on the focused step, not the
-            // hover preview, so hovering doesn't strip the frame's `isSelected`.
+            // Bases selection on the focused step, not the hover preview, so
+            // hovering doesn't strip the frame's `isSelected`.
             const isSelected = selected?.alias !== undefined && comp?.alias === selected.alias;
-            const vis = flowElementVisibility({
+            // `brightNodeIds` (the focused step's endpoints) is a spotlight member as
+            // well as a bright set — see the group branch above.
+            const dimSource = previewNodeIds ?? brightNodeIds ?? issueFocusNodeIds;
+            const { hidden, dimmed } = flowNodeVisibility({
                 inOpened: openedNodeIds?.has(n.id) === true,
                 inSelected: brightNodeIds?.has(n.id) === true,
+                inSpotlight: dimSource?.has(n.id) === true,
                 anyOpened: openedNodeIds != null,
-                anySelected: brightNodeIds != null || previewNodeIds != null,
+                anySelected: brightNodeIds != null,
+                anySpotlight: dimSource != null,
             });
-            // `brightNodeIds` (the focused step's endpoints) is a dim source as well
-            // as a bright set — see the group branch above.
-            const dimSource = previewNodeIds ?? brightNodeIds ?? issueFocusNodeIds;
-            const dimmed = dimSource ? (vis.hidden || !dimSource.has(n.id)) : vis.dimmed;
-            const hidden = noOpenedFlow ? false : vis.hidden;
             // Component findings key by alias, boundary findings by region node id.
             // The two id spaces are disjoint (`module:` / `process:` are prefixed), so
             // one lookup covers both node kinds.
@@ -1037,14 +1035,14 @@ function Inner({ components, walkthroughs, graphifyRelations, orderByLine, initi
         };
         // Edges outside the selected view are hidden entirely (labels included).
         // graphify-native edges belong to the graphify view (they are static
-        // topology, not runtime hops) regardless of their verb.
+        // topology, not runtime steps) regardless of their verb.
         const edgeInView = (e) => {
             const d = e.data;
             const mechanism = d?.mechanism ?? 'uses';
             if (resolvedEdgeView === 'graphify') {
                 return d?.provenance === 'graphify';
             }
-            return isWalkthroughMechanism(mechanism);
+            return isTrailMechanism(mechanism);
         };
         if (openedEdgeIds || focusEdgeIds || previewEdgeIds || issueFocusEdgeIds) {
             return baseEdges.map((e) => {
@@ -1099,7 +1097,7 @@ function Inner({ components, walkthroughs, graphifyRelations, orderByLine, initi
     const onNodeClick = useCallback((_e, node) => {
         const comp = node.data?.component;
         setSelectedEdgeId(null);
-        setFocusedWalkthroughId(null);
+        setFocusedTrailId(null);
         setFocusedStepIndex(null);
         if (node.type === 'subsystem-component' && comp) {
             // Clicking the already-selected node unselects it (toggle off).
@@ -1121,15 +1119,15 @@ function Inner({ components, walkthroughs, graphifyRelations, orderByLine, initi
     const onPaneClick = useCallback(() => {
         setSelected(null);
         setSelectedEdgeId(null);
-        setFocusedWalkthroughId(null);
+        setFocusedTrailId(null);
         setFocusedStepIndex(null);
         issueModuleFocusRef.current = 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 hasWalkthroughs = useMemo(() => (walkthroughs?.length ?? 0) > 0, [walkthroughs]);
-    // Aliases of proposed components — the flows panel tints walkthrough titles
+    const hasTrails = useMemo(() => (trails?.length ?? 0) > 0, [trails]);
+    // Aliases of proposed components — the flows panel tints trail titles
     // (and steps) that touch one.
     const proposedAliases = useMemo(() => new Set(components.filter((c) => c.proposed).map((c) => c.alias)), [components]);
     // Diagnostics view in the sidebar. Uncontrolled unless the host pins
@@ -1190,7 +1188,7 @@ function Inner({ components, walkthroughs, graphifyRelations, orderByLine, initi
     const [focusedBoundaryKey, setFocusedBoundaryKey] = useState(null);
     const onNodeDoubleClick = useCallback((_e, node) => {
         // Boundary frame → frame its members on the canvas; double-click again to
-        // zoom back out. User-initiated, so it ignores the walkthrough zoom gate.
+        // zoom back out. User-initiated, so it ignores the trail zoom gate.
         if (node.type === 'subsystem-group') {
             const key = node.data?.region?.key;
             if (!key)
@@ -1225,7 +1223,7 @@ function Inner({ components, walkthroughs, graphifyRelations, orderByLine, initi
         const startLine = comp.declarationRef?.startLine;
         onOpenDeclarationFile(comp.file, startLine != null ? { startLine } : undefined);
     }, [onOpenDeclarationFile, fitView, focusedBoundaryKey]);
-    const onOpenFileFromWalkthrough = useCallback((file, opts) => {
+    const onOpenFileFromTrail = useCallback((file, opts) => {
         setFileOverlay({ file, startLine: opts?.startLine });
         onFileSelect?.(file);
     }, [onFileSelect]);
@@ -1239,14 +1237,14 @@ function Inner({ components, walkthroughs, graphifyRelations, orderByLine, initi
     const drawerFillHeight = drawerTarget?.kind === 'file' && drawerTarget.startLine == null;
     const fileOverlayOpen = fileOverlay != null;
     const collapseCanvas = drawerFillHeight || fileOverlayOpen;
-    // Drop the full-file overlay when the underlying walkthrough drawer changes
+    // Drop the full-file overlay when the underlying trail drawer changes
     // or closes — open-file keeps the same drawerTarget so the snippets stay mounted.
-    const walkthroughDrawerKey = drawerTarget?.kind === 'walkthrough'
-        ? `${drawerTarget.walkthroughId}:${drawerTarget.stepIndex}`
+    const trailDrawerKey = drawerTarget?.kind === 'trail'
+        ? `${drawerTarget.trailId}:${drawerTarget.stepIndex}`
         : null;
     useEffect(() => {
         setFileOverlay(null);
-    }, [walkthroughDrawerKey]);
+    }, [trailDrawerKey]);
     useEffect(() => {
         if (!fileOverlayOpen)
             return;
@@ -1257,15 +1255,15 @@ function Inner({ components, walkthroughs, graphifyRelations, orderByLine, initi
         window.addEventListener('keydown', onKey);
         return () => window.removeEventListener('keydown', onKey);
     }, [fileOverlayOpen, closeFileOverlay]);
-    // Camera helper shared by the walkthrough interactions. Fits the union of
+    // Camera helper shared by the trail interactions. Fits the union of
     // the focused edges' endpoint rects AND their routed waypoints — the edge
     // carries its full polyline (`elkPathPoints`, absolute flow coords), so the
-    // frame is the line the hop actually traces. That keeps a hop whose route
+    // frame is the line the step actually traces. That keeps a step whose route
     // bulges out around intervening nodes from being clipped at the viewport
     // edge, and it is the edge's own geometry doing the guiding, not fudge
     // padding.
     const fitFocusBounds = useCallback((ids) => {
-        if (!zoomOnWalkthroughFocus)
+        if (!zoomOnTrailFocus)
             return;
         const nodeIds = new Set();
         const points = [];
@@ -1315,14 +1313,14 @@ function Inner({ components, walkthroughs, graphifyRelations, orderByLine, initi
         };
         fitBounds(bounds, {
             padding: 0.15,
-            duration: walkthroughFocusDurationMs,
+            duration: trailFocusDurationMs,
         });
     }, [
         baseEdges,
         built.absoluteRects,
         fitBounds,
-        zoomOnWalkthroughFocus,
-        walkthroughFocusDurationMs,
+        zoomOnTrailFocus,
+        trailFocusDurationMs,
     ]);
     // A node's laid-out rect in absolute flow coords. `absoluteRects` is the
     // authority; the fallback covers an unparented group node, whose `position` is
@@ -1368,12 +1366,12 @@ function Inner({ components, walkthroughs, graphifyRelations, orderByLine, initi
             y: minY,
             width: Math.max(1, maxX - minX),
             height: Math.max(1, maxY - minY),
-        }, { padding, duration: walkthroughFocusDurationMs });
-    }, [rectForNode, fitBounds, walkthroughFocusDurationMs]);
-    // Zoom back out to the full diagram after the last expanded walkthrough
+        }, { padding, duration: trailFocusDurationMs });
+    }, [rectForNode, fitBounds, trailFocusDurationMs]);
+    // Zoom back out to the full diagram after the last expanded trail
     // closes (visibility restores non-flow nodes that were hidden).
     const fitOverview = useCallback(() => {
-        if (!zoomOnWalkthroughFocus)
+        if (!zoomOnTrailFocus)
             return;
         fitView({
             padding: 0.1,
@@ -1382,109 +1380,109 @@ function Inner({ components, walkthroughs, graphifyRelations, orderByLine, initi
             maxZoom: 2,
             duration: 300,
         });
-    }, [fitView, zoomOnWalkthroughFocus]);
+    }, [fitView, zoomOnTrailFocus]);
     // 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 walkthrough drawer (from a previously focused flow's step)
+    // click. A stale trail 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 focusWalkthroughEdges = useCallback((tl) => {
+    const focusTrailEdges = useCallback((tl) => {
         setSelected(null);
         setSelectedEdgeId(null);
-        setHoveredWalkthroughStep(null);
-        if (walkthroughStepMode === 'dim') {
+        setHoveredTrailStep(null);
+        if (trailStepMode === 'dim') {
             setFocusedStepIndex(null);
-            setFocusedWalkthroughId(null);
-            setDrawerTarget((prev) => (prev?.kind === 'walkthrough' ? null : prev));
+            setFocusedTrailId(null);
+            setDrawerTarget((prev) => (prev?.kind === 'trail' ? null : prev));
             return;
         }
         setFocusedStepIndex(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);
+        setFocusedTrailId(tl.id);
+        fitFocusBounds(new Set(tl.steps.map((s) => trailStepGraphEdgeId(s))));
+        setDrawerTarget((prev) => (prev?.kind === 'trail' ? null : prev));
+    }, [fitFocusBounds, trailStepMode]);
+    const clearTrailFocus = useCallback(() => {
+        setFocusedTrailId(null);
         setFocusedStepIndex(null);
-        setHoveredWalkthroughStep(null);
-        setDrawerTarget((prev) => (prev?.kind === 'walkthrough' ? null : prev));
+        setHoveredTrailStep(null);
+        setDrawerTarget((prev) => (prev?.kind === 'trail' ? null : prev));
     }, []);
-    // Host deep-link: opening the graph from a walkthrough row selects that
+    // Host deep-link: opening the graph from a trail row selects that
     // flow — expand its steps, focus its edges, and switch the sidebar to
-    // Walkthroughs. Guarded by a ref so a later in-tab selection isn't yanked
+    // Trails. Guarded by a ref so a later in-tab selection isn't yanked
     // back; a remount (or a new id) re-applies it.
-    const appliedInitialWalkthroughRef = useRef(null);
+    const appliedInitialTrailRef = useRef(null);
     useEffect(() => {
-        if (!initialWalkthroughId)
+        if (!initialTrailId)
             return;
-        if (appliedInitialWalkthroughRef.current === initialWalkthroughId)
+        if (appliedInitialTrailRef.current === initialTrailId)
             return;
-        if (!layoutReady || !walkthroughs?.length)
+        if (!layoutReady || !trails?.length)
             return;
-        const tl = walkthroughs.find((t) => t.id === initialWalkthroughId);
+        const tl = trails.find((t) => t.id === initialTrailId);
         if (!tl)
             return;
-        appliedInitialWalkthroughRef.current = initialWalkthroughId;
-        setSidebarView('walkthroughs');
-        setExpandedWalkthroughs((prev) => new Set(prev).add(tl.id));
-        focusWalkthroughEdges(tl);
-    }, [initialWalkthroughId, layoutReady, walkthroughs, focusWalkthroughEdges]);
+        appliedInitialTrailRef.current = initialTrailId;
+        setSidebarView('trails');
+        setExpandedTrails((prev) => new Set(prev).add(tl.id));
+        focusTrailEdges(tl);
+    }, [initialTrailId, layoutReady, trails, focusTrailEdges]);
     // Switching sidebar panels also switches the edge vocabulary. Leaving the
-    // Walkthroughs panel drops its canvas state (focus, expanded flows, selected
+    // Trails panel drops its canvas state (focus, expanded flows, selected
     // edge) so the Files view's topology edges aren't gated by a flow the user
     // can no longer see or un-dim.
     const changeSidebarView = useCallback((view) => {
         setSidebarView(view);
-        if (view === 'walkthroughs')
+        if (view === 'trails')
             return;
-        clearWalkthroughFocus();
-        setExpandedWalkthroughs(new Set());
+        clearTrailFocus();
+        setExpandedTrails(new Set());
         setSelectedEdgeId(null);
-    }, [clearWalkthroughFocus]);
-    // Focus a single step's edge on the canvas and open/scroll the walkthrough
+    }, [clearTrailFocus]);
+    // Focus a single step's edge on the canvas and open/scroll the trail
     // 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 focusWalkthroughStep = useCallback((tl, stepIndex) => {
+    const focusTrailStep = useCallback((tl, stepIndex) => {
         const step = tl.steps[stepIndex];
         if (!step)
             return;
         setSelected(null);
         setSelectedEdgeId(null);
-        if (walkthroughStepMode === 'dim') {
+        if (trailStepMode === 'dim') {
             setFocusedStepIndex(null);
-            setFocusedWalkthroughId(null);
-            setHoveredWalkthroughStep({ walkthroughId: tl.id, stepIndex });
-            setDrawerTarget((prev) => (prev?.kind === 'walkthrough' ? null : prev));
+            setFocusedTrailId(null);
+            setHoveredTrailStep({ trailId: tl.id, stepIndex });
+            setDrawerTarget((prev) => (prev?.kind === 'trail' ? null : prev));
             return;
         }
         // Toggle: clicking the selected step unselects it (back to whole flow).
-        if (focusedWalkthroughId === tl.id && focusedStepIndex === stepIndex) {
+        if (focusedTrailId === tl.id && focusedStepIndex === stepIndex) {
             setFocusedStepIndex(null);
             // 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));
+            setHoveredTrailStep({ trailId: tl.id, stepIndex });
+            setDrawerTarget((prev) => (prev?.kind === 'trail' ? null : prev));
             if (pendingFocusFitRef.current != null) {
                 window.clearTimeout(pendingFocusFitRef.current);
                 pendingFocusFitRef.current = null;
             }
-            fitFocusBounds(new Set(tl.steps.map((s) => walkthroughStepGraphEdgeId(s))));
+            fitFocusBounds(new Set(tl.steps.map((s) => trailStepGraphEdgeId(s))));
             return;
         }
         setFocusedStepIndex(stepIndex);
-        setFocusedWalkthroughId(tl.id);
-        setHoveredWalkthroughStep(null);
+        setFocusedTrailId(tl.id);
+        setHoveredTrailStep(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 (renderWalkthroughViewer) {
+        if (renderTrailViewer) {
             setDrawerTarget({
-                kind: 'walkthrough',
-                walkthroughId: tl.id,
+                kind: 'trail',
+                trailId: tl.id,
                 stepIndex,
             });
         }
@@ -1495,7 +1493,7 @@ function Inner({ components, walkthroughs, graphifyRelations, orderByLine, initi
                 startLine: step.line,
             });
         }
-        const edgeIds = new Set([walkthroughStepGraphEdgeId(step)]);
+        const edgeIds = new Set([trailStepGraphEdgeId(step)]);
         if (pendingFocusFitRef.current != null) {
             window.clearTimeout(pendingFocusFitRef.current);
             pendingFocusFitRef.current = null;
@@ -1512,9 +1510,9 @@ function Inner({ components, walkthroughs, graphifyRelations, orderByLine, initi
     }, [
         fitFocusBounds,
         focusedStepIndex,
-        focusedWalkthroughId,
-        renderWalkthroughViewer,
-        walkthroughStepMode,
+        focusedTrailId,
+        renderTrailViewer,
+        trailStepMode,
     ]);
     useEffect(() => {
         return () => {
@@ -1532,11 +1530,11 @@ function Inner({ components, walkthroughs, graphifyRelations, orderByLine, initi
     useEffect(() => {
         const prev = prevPreviewEdgeIdsRef.current;
         prevPreviewEdgeIdsRef.current = previewEdgeIds;
-        if (!zoomOnWalkthroughFocus || walkthroughStepMode === 'dim')
+        if (!zoomOnTrailFocus || trailStepMode === 'dim')
             return;
         // Camera follows hover only when a specific step is already focused (or
         // autoplay is driving an auto-focus).
-        if (!autoPlayFocus && (focusedWalkthroughId == null || focusedStepIndex == null)) {
+        if (!autoPlayFocus && (focusedTrailId == null || focusedStepIndex == null)) {
             return;
         }
         if (previewEdgeIds) {
@@ -1549,27 +1547,27 @@ function Inner({ components, walkthroughs, graphifyRelations, orderByLine, initi
     }, [
         previewEdgeIds,
         focusEdgeIds,
-        focusedWalkthroughId,
+        focusedTrailId,
         focusedStepIndex,
         autoPlayFocus,
         fitFocusBounds,
-        zoomOnWalkthroughFocus,
-        walkthroughStepMode,
+        zoomOnTrailFocus,
+        trailStepMode,
     ]);
-    // Graph-only embeds: cycle walkthrough steps. In `focus` mode each step is
-    // selected (camera frames it via fitFocusBounds) and, when a walkthrough
+    // Graph-only embeds: cycle trail steps. In `focus` mode each step is
+    // selected (camera frames it via fitFocusBounds) and, when a trail
     // viewer is supplied, its snippet drawer opens; in `dim` mode it only
     // dim-highlights the step (hover-style) with no camera move.
     useEffect(() => {
-        if (!autoPlayWalkthroughs || walkthroughs == null || walkthroughs.length === 0)
+        if (!autoPlayTrails || trails == null || trails.length === 0)
             return;
         if (!layoutReady)
             return;
-        const playable = walkthroughs.filter((tl) => tl.steps.length > 0);
+        const playable = trails.filter((tl) => tl.steps.length > 0);
         if (playable.length === 0)
             return;
         // Only run the cycles that can actually be shown in the current edge view.
-        const inView = playable.filter((tl) => tl.steps.some((s) => isWalkthroughMechanism(s.mechanism)));
+        const inView = playable.filter((tl) => tl.steps.some((s) => isTrailMechanism(s.mechanism)));
         if (inView.length === 0)
             return;
         const cyc = inView;
@@ -1577,8 +1575,8 @@ function Inner({ components, walkthroughs, graphifyRelations, orderByLine, initi
         let tlIdx = 0;
         let stepIdx = 0;
         let timer = null;
-        const interval = Math.max(400, walkthroughAutoPlayIntervalMs);
-        const focusMode = walkthroughStepMode !== 'dim';
+        const interval = Math.max(400, trailAutoPlayIntervalMs);
+        const focusMode = trailStepMode !== 'dim';
         let cleanup = () => { };
         const tick = () => {
             if (cancelled)
@@ -1587,15 +1585,15 @@ function Inner({ components, walkthroughs, graphifyRelations, orderByLine, initi
             setSelected(null);
             setSelectedEdgeId(null);
             if (focusMode) {
-                setHoveredWalkthroughStep(null);
-                setFocusedWalkthroughId(null);
+                setHoveredTrailStep(null);
+                setFocusedTrailId(null);
                 setFocusedStepIndex(null);
-                setAutoPlayFocus({ walkthroughId: tl.id, stepIndex: stepIdx });
+                setAutoPlayFocus({ trailId: tl.id, stepIndex: stepIdx });
                 if (!hideDrawer) {
                     const step = tl.steps[stepIdx];
                     if (step) {
-                        if (renderWalkthroughViewer) {
-                            setDrawerTarget({ kind: 'walkthrough', walkthroughId: tl.id, stepIndex: stepIdx });
+                        if (renderTrailViewer) {
+                            setDrawerTarget({ kind: 'trail', trailId: tl.id, stepIndex: stepIdx });
                         }
                         else {
                             setDrawerTarget({ kind: 'file', file: step.file, startLine: step.line });
@@ -1605,9 +1603,9 @@ function Inner({ components, walkthroughs, graphifyRelations, orderByLine, initi
             }
             else {
                 setAutoPlayFocus(null);
-                setFocusedWalkthroughId(null);
+                setFocusedTrailId(null);
                 setFocusedStepIndex(null);
-                setHoveredWalkthroughStep({ walkthroughId: tl.id, stepIndex: stepIdx });
+                setHoveredTrailStep({ trailId: tl.id, stepIndex: stepIdx });
             }
             stepIdx += 1;
             if (stepIdx >= tl.steps.length) {
@@ -1621,28 +1619,28 @@ function Inner({ components, walkthroughs, graphifyRelations, orderByLine, initi
             cancelled = true;
             if (timer != null)
                 window.clearTimeout(timer);
-            setHoveredWalkthroughStep(null);
-            setFocusedWalkthroughId(null);
+            setHoveredTrailStep(null);
+            setFocusedTrailId(null);
             setFocusedStepIndex(null);
             setAutoPlayFocus(null);
         };
         return cleanup;
     }, [
-        autoPlayWalkthroughs,
-        walkthroughs,
-        walkthroughAutoPlayIntervalMs,
+        autoPlayTrails,
+        trails,
+        trailAutoPlayIntervalMs,
         layoutReady,
-        walkthroughStepMode,
-        renderWalkthroughViewer,
+        trailStepMode,
+        renderTrailViewer,
         hideDrawer,
     ]);
-    // Arrow keys step through the focused walkthrough once a step is active
+    // Arrow keys step through the focused trail once a step is active
     // (sidebar click or drawer open). Ignores typing targets and chords.
     useEffect(() => {
-        if (focusedWalkthroughId == null || focusedStepIndex == null || !walkthroughs) {
+        if (focusedTrailId == null || focusedStepIndex == null || !trails) {
             return;
         }
-        const tl = walkthroughs.find((t) => t.id === focusedWalkthroughId);
+        const tl = trails.find((t) => t.id === focusedTrailId);
         if (!tl || tl.steps.length === 0)
             return;
         const onKeyDown = (e) => {
@@ -1669,19 +1667,19 @@ function Inner({ components, walkthroughs, graphifyRelations, orderByLine, initi
             if (next === focusedStepIndex)
                 return;
             e.preventDefault();
-            focusWalkthroughStep(tl, next);
+            focusTrailStep(tl, next);
         };
         window.addEventListener('keydown', onKeyDown);
         return () => window.removeEventListener('keydown', onKeyDown);
     }, [
-        focusedWalkthroughId,
+        focusedTrailId,
         focusedStepIndex,
-        walkthroughs,
-        focusWalkthroughStep,
+        trails,
+        focusTrailStep,
     ]);
-    const toggleWalkthroughCollapsed = useCallback((tlId) => {
-        const collapsingLast = expandedWalkthroughs.has(tlId) && expandedWalkthroughs.size === 1;
-        setExpandedWalkthroughs((prev) => {
+    const toggleTrailCollapsed = useCallback((tlId) => {
+        const collapsingLast = expandedTrails.has(tlId) && expandedTrails.size === 1;
+        setExpandedTrails((prev) => {
             const next = new Set(prev);
             if (next.has(tlId))
                 next.delete(tlId);
@@ -1689,7 +1687,7 @@ function Inner({ components, walkthroughs, graphifyRelations, orderByLine, initi
                 next.add(tlId);
             return next;
         });
-        if (!collapsingLast || !zoomOnWalkthroughFocus)
+        if (!collapsingLast || !zoomOnTrailFocus)
             return;
         // Cancel any pending focus fit so it doesn't fight the overview zoom.
         if (pendingFocusFitRef.current != null) {
@@ -1704,7 +1702,7 @@ function Inner({ components, walkthroughs, graphifyRelations, orderByLine, initi
             pendingFocusFitRef.current = null;
             requestAnimationFrame(() => fitOverview());
         }, drawerWasOpen ? FILE_DRAWER_HEIGHT_MS + 20 : 20);
-    }, [expandedWalkthroughs, fitOverview, zoomOnWalkthroughFocus]);
+    }, [expandedTrails, fitOverview, zoomOnTrailFocus]);
     // Detail-panel links: related-name clicks select the matching component —
     // resolved by alias, name, or symbol (call labels may carry a trailing `()`).
     const resolveRelatedComponent = useCallback((ref) => {
@@ -1717,7 +1715,7 @@ function Inner({ components, walkthroughs, graphifyRelations, orderByLine, initi
             return;
         setSelected(comp);
         setSelectedEdgeId(null);
-        setFocusedWalkthroughId(null);
+        setFocusedTrailId(null);
         setFocusedStepIndex(null);
         onSelect?.(comp.alias);
     }, [components, onSelect]);
@@ -1732,9 +1730,9 @@ function Inner({ components, walkthroughs, graphifyRelations, orderByLine, initi
         if (comp) {
             setSelected(comp);
             setSelectedEdgeId(null);
-            setFocusedWalkthroughId(null);
+            setFocusedTrailId(null);
             setFocusedStepIndex(null);
-            setHoveredWalkthroughStep(null);
+            setHoveredTrailStep(null);
             issueModuleFocusRef.current = null;
             onSelect?.(comp.alias);
             requestAnimationFrame(() => {
@@ -1749,11 +1747,11 @@ function Inner({ components, walkthroughs, graphifyRelations, orderByLine, initi
         }
         else if (step) {
             // A step finding focuses the step itself, through the same entry point
-            // the walkthrough panel uses — so the drawer, the step numbering, the
+            // the trail panel uses — so the drawer, the step numbering, the
             // dim-mode hover preview, and the camera all behave identically whether
             // the step was reached from the panel or from a diagnostics card.
             issueModuleFocusRef.current = null;
-            focusWalkthroughStep(step.walkthrough, step.stepIndex);
+            focusTrailStep(step.trail, step.stepIndex);
         }
         else {
             // Nothing selectable — but a module target names a boundary frame, so
@@ -1762,9 +1760,9 @@ function Inner({ components, walkthroughs, graphifyRelations, orderByLine, initi
             if (moduleNodeId) {
                 setSelected(null);
                 setSelectedEdgeId(null);
-                setFocusedWalkthroughId(null);
+                setFocusedTrailId(null);
                 setFocusedStepIndex(null);
-                setHoveredWalkthroughStep(null);
+                setHoveredTrailStep(null);
                 issueModuleFocusRef.current = moduleNodeId;
                 requestAnimationFrame(() => {
                     fitNodeRects(new Set([moduleNodeId]), 0.4);
@@ -1776,7 +1774,7 @@ function Inner({ components, walkthroughs, graphifyRelations, orderByLine, initi
         issueComponent,
         issueStep,
         issueModuleNodeId,
-        focusWalkthroughStep,
+        focusTrailStep,
         onSelect,
         onSelectIssue,
         fitView,
@@ -1804,13 +1802,13 @@ function Inner({ components, walkthroughs, graphifyRelations, orderByLine, initi
                 // keeps its step focus in hover state instead (owned by the pointer,
                 // not the card), and correctly leaves that alone here.
                 const owned = focusedStepRef.current;
-                if (owned?.walkthroughId !== step.walkthrough.id ||
+                if (owned?.trailId !== step.trail.id ||
                     owned?.stepIndex !== step.stepIndex) {
                     return;
                 }
-                setFocusedWalkthroughId(null);
+                setFocusedTrailId(null);
                 setFocusedStepIndex(null);
-                setDrawerTarget((prev) => (prev?.kind === 'walkthrough' ? null : prev));
+                setDrawerTarget((prev) => (prev?.kind === 'trail' ? null : prev));
             }
             else if (moduleNodeId) {
                 // Only unwind framing this card still owns.
@@ -1826,14 +1824,14 @@ function Inner({ components, walkthroughs, graphifyRelations, orderByLine, initi
             fitView({ padding: 0.1, duration: 300, minZoom: 0.05, maxZoom: 2 });
         });
     }, [issueComponent, issueStep, issueModuleNodeId, fitView]);
-    // Construct tokens inside a walkthrough snippet. A step's line is an edge
+    // Construct tokens inside a trail snippet. A step's line is an edge
     // between its `from`/`to` components, so a token naming either of those
     // constructs should navigate to that construct's declaration. Index the
-    // matchable identifiers per step (`walkthroughId:index`).
-    const walkthroughSymbolIndex = useMemo(() => {
+    // matchable identifiers per step (`trailId:index`).
+    const trailSymbolIndex = useMemo(() => {
         const byAlias = new Map(components.map((c) => [c.alias, c]));
         const index = new Map();
-        for (const wt of walkthroughs ?? []) {
+        for (const wt of trails ?? []) {
             wt.steps.forEach((step, i) => {
                 const tokens = new Map();
                 for (const alias of [step.from, step.to]) {
@@ -1847,17 +1845,17 @@ function Inner({ components, walkthroughs, graphifyRelations, orderByLine, initi
             });
         }
         return index;
-    }, [components, walkthroughs]);
-    const walkthroughSymbolIndexRef = useRef(walkthroughSymbolIndex);
-    walkthroughSymbolIndexRef.current = walkthroughSymbolIndex;
-    // Stable resolver: reads the live index + focused walkthrough from refs so
-    // the memoized walkthrough drawer isn't rebuilt on every graph render.
-    const resolveWalkthroughSymbol = useCallback((query) => {
-        const walkthroughId = drawerWalkthroughIdRef.current;
-        if (walkthroughId == null)
+    }, [components, trails]);
+    const trailSymbolIndexRef = useRef(trailSymbolIndex);
+    trailSymbolIndexRef.current = trailSymbolIndex;
+    // Stable resolver: reads the live index + focused trail from refs so
+    // the memoized trail drawer isn't rebuilt on every graph render.
+    const resolveTrailSymbol = useCallback((query) => {
+        const trailId = drawerTrailIdRef.current;
+        if (trailId == null)
             return null;
-        return (walkthroughSymbolIndexRef.current
-            .get(`${walkthroughId}:${query.stepIndex}`)
+        return (trailSymbolIndexRef.current
+            .get(`${trailId}:${query.stepIndex}`)
             ?.get(query.tokenText) ?? null);
     }, []);
     // A construct token click navigates to that construct's declaration: open
@@ -1920,10 +1918,10 @@ function Inner({ components, walkthroughs, graphifyRelations, orderByLine, initi
     const fileViewerRef = useRef(fileViewer);
     fileViewerRef.current = fileViewer;
     const renderDrawerContent = useCallback((file, opts) => fileViewerRef.current?.(file, opts) ?? null, []);
-    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 || diagnostic || issuesActive || sidebarExtra || sidebarAfterDescription || treeFilePaths.length > 0 || hasWalkthroughs) && (_jsxs("div", { style: {
+    const trailViewerRef = useRef(renderTrailViewer);
+    trailViewerRef.current = renderTrailViewer;
+    const renderTrailDrawerContent = useCallback((ctx) => trailViewerRef.current?.(ctx) ?? null, []);
+    return (_jsxs("div", { style: { width: '100%', height: '100%', display: 'flex', flexDirection: 'row', userSelect: sidebarDrag ? 'none' : undefined }, children: [!hideSidebar && (title || description || diagnostic || issuesActive || sidebarExtra || sidebarAfterDescription || treeFilePaths.length > 0 || hasTrails) && (_jsxs("div", { style: {
                     width: sidebarWidth,
                     minWidth: sidebarWidth,
                     borderRight: `1px solid ${theme.colors.border}`,
@@ -1969,7 +1967,7 @@ function Inner({ components, walkthroughs, graphifyRelations, orderByLine, initi
                                                     color: descriptionVisible || descToggleHover ? theme.colors.text : (theme.colors.textMuted ?? theme.colors.textSecondary),
                                                     cursor: 'pointer',
                                                     transition: 'background 120ms ease, color 120ms ease',
-                                                }, children: _jsx(FileText, { 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, enableKeyboardScrolling: false, autoFocusOnVisible: false }) })), sidebarAfterDescription] }), (treeFilePaths.length > 0 || hasWalkthroughs || issuesActive) && (_jsx("div", { style: {
+                                                }, children: _jsx(FileText, { 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, enableKeyboardScrolling: false, autoFocusOnVisible: false }) })), sidebarAfterDescription] }), (treeFilePaths.length > 0 || hasTrails || issuesActive) && (_jsx("div", { style: {
                             ...(showDesc ? { height: '50%' } : { flex: 1, minHeight: 0 }),
                             minHeight: 160,
                             flexShrink: 0,
@@ -1995,13 +1993,13 @@ function Inner({ components, walkthroughs, graphifyRelations, orderByLine, initi
                                             fontFamily: theme.fonts.monospace,
                                             textTransform: 'capitalize',
                                             cursor: 'pointer',
-                                        }, children: tab === 'issues' ? 'Issues' : 'Agents' }, tab))) }), diagnosticsTab === 'agents' ? (_jsx(SubsystemAgentsPanel, { ...agentsPanel })) : (_jsx(SubsystemIssueList, { issues: issues ?? [], focusCategory: focusIssueCategory, onSelectIssue: focusIssueTarget, onDeselectIssue: unfocusIssueTarget, onApplyFix: onApplyIssueFix, onHoverIssue: onHoverIssue, onExpandedCategoriesChange: handleExpandedCategoriesChange }))] })) : (_jsx(SubsystemIssueList, { issues: issues ?? [], focusCategory: focusIssueCategory, onSelectIssue: focusIssueTarget, onDeselectIssue: unfocusIssueTarget, onApplyFix: onApplyIssueFix, onHoverIssue: onHoverIssue, onExpandedCategoriesChange: handleExpandedCategoriesChange }))) : (_jsxs(_Fragment, { children: [hasWalkthroughs && (_jsx("div", { role: "tablist", "aria-label": "Sidebar view", style: {
+                                        }, children: tab === 'issues' ? 'Issues' : 'Agents' }, tab))) }), diagnosticsTab === 'agents' ? (_jsx(SubsystemAgentsPanel, { ...agentsPanel })) : (_jsx(SubsystemIssueList, { issues: issues ?? [], focusCategory: focusIssueCategory, onSelectIssue: focusIssueTarget, onDeselectIssue: unfocusIssueTarget, onApplyFix: onApplyIssueFix, onHoverIssue: onHoverIssue, onExpandedCategoriesChange: handleExpandedCategoriesChange }))] })) : (_jsx(SubsystemIssueList, { issues: issues ?? [], focusCategory: focusIssueCategory, onSelectIssue: focusIssueTarget, onDeselectIssue: unfocusIssueTarget, onApplyFix: onApplyIssueFix, onHoverIssue: onHoverIssue, onExpandedCategoriesChange: handleExpandedCategoriesChange }))) : (_jsxs(_Fragment, { children: [hasTrails && (_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: ['walkthroughs', 'files'].map((view) => (_jsx("button", { type: "button", role: "tab", "aria-selected": sidebarView === view, onClick: () => changeSidebarView(view), style: {
+                                    }, children: ['trails', 'files'].map((view) => (_jsx("button", { type: "button", role: "tab", "aria-selected": sidebarView === view, onClick: () => changeSidebarView(view), style: {
                                             flex: 1,
                                             minWidth: 0,
                                             padding: '8px 8px',
@@ -2015,7 +2013,7 @@ function Inner({ components, walkthroughs, graphifyRelations, orderByLine, initi
                                             fontFamily: theme.fonts.monospace,
                                             textTransform: 'capitalize',
                                             cursor: 'pointer',
-                                        }, children: view === 'walkthroughs' ? 'Walkthroughs' : 'Files' }, view))) })), sidebarView === 'walkthroughs' && walkthroughs && walkthroughs.length > 0 ? (_jsx(WalkthroughsPanel, { walkthroughs: walkthroughs, expandedWalkthroughs: expandedWalkthroughs, focusedWalkthroughId: focusedWalkthroughId, focusedStepIndex: focusedStepIndex, hoveredWalkthroughStep: hoveredWalkthroughStep, 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), onReorder: onReorderWalkthroughs, proposedAliases: proposedAliases })) : treeFilePaths.length > 0 ? (_jsx(_Fragment, { children: repoGroups.groups.map((group, i) => {
+                                        }, children: view === 'trails' ? 'Trails' : 'Files' }, view))) })), sidebarView === 'trails' && trails && trails.length > 0 ? (_jsx(TrailsPanel, { trails: trails, expandedTrails: expandedTrails, focusedTrailId: focusedTrailId, focusedStepIndex: focusedStepIndex, hoveredTrailStep: hoveredTrailStep, onToggleCollapsed: toggleTrailCollapsed, onFocusFlow: focusTrailEdges, onClearFocus: clearTrailFocus, onFocusStep: focusTrailStep, onHoverStep: (tl, i) => setHoveredTrailStep({ trailId: tl.id, stepIndex: i }), onHoverFlow: (tl) => setHoveredTrailStep({ trailId: tl.id, stepIndex: null }), onLeaveStep: () => setHoveredTrailStep(null), onReorder: onReorderTrails, proposedAliases: proposedAliases })) : 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: {
@@ -2025,7 +2023,7 @@ function Inner({ components, walkthroughs, graphifyRelations, orderByLine, initi
                                                 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, hoveredFolder: hoveredBoundaryPath, headerless: repoGroups.multiRepo }))] }, groupKey));
-                                    }) })) : null] })) }))] })), !hideSidebar && (title || description || diagnostic || issuesActive || sidebarExtra || sidebarAfterDescription || treeFilePaths.length > 0 || hasWalkthroughs) && (_jsx("div", { onMouseDown: onSidebarResizeStart, "aria-label": "Resize sidebar", title: "Drag to resize", style: {
+                                    }) })) : null] })) }))] })), !hideSidebar && (title || description || diagnostic || issuesActive || sidebarExtra || sidebarAfterDescription || treeFilePaths.length > 0 || hasTrails) && (_jsx("div", { onMouseDown: onSidebarResizeStart, "aria-label": "Resize sidebar", title: "Drag to resize", style: {
                     width: 3,
                     flexShrink: 0,
                     cursor: 'col-resize',
@@ -2118,7 +2116,7 @@ function Inner({ components, walkthroughs, graphifyRelations, orderByLine, initi
                                     flex: 1,
                                     minHeight: 0,
                                     background: theme.colors.background,
-                                }, children: _jsx(GraphChrome, {}) }, `${baseNodesKey}-${baseEdgesKey}`), (graphTitle || overlayWalkthroughTitle || overlayWalkthroughStep) && (_jsxs("div", { style: {
+                                }, children: _jsx(GraphChrome, {}) }, `${baseNodesKey}-${baseEdgesKey}`), (graphTitle || overlayTrailTitle || overlayTrailStep) && (_jsxs("div", { style: {
                                     position: 'absolute',
                                     top: 10,
                                     left: '50%',
@@ -2144,9 +2142,9 @@ function Inner({ components, walkthroughs, graphifyRelations, orderByLine, initi
                                             border: `1px solid ${theme.colors.border}`,
                                             borderRadius: 6,
                                             boxShadow: '0 1px 4px rgba(0,0,0,0.25)',
-                                        }, children: graphTitle })), overlayWalkthroughTitle && (_jsxs("div", { style: {
+                                        }, children: graphTitle })), overlayTrailTitle && (_jsxs("div", { style: {
                                             maxWidth: '100%',
-                                            minWidth: overlayWalkthroughStep ? 160 : undefined,
+                                            minWidth: overlayTrailStep ? 160 : undefined,
                                             display: 'flex',
                                             flexDirection: 'column',
                                             background: theme.colors.backgroundSecondary ?? theme.colors.background,
@@ -2155,9 +2153,9 @@ function Inner({ components, walkthroughs, graphifyRelations, orderByLine, initi
                                             boxShadow: '0 1px 4px rgba(0,0,0,0.25)',
                                             overflow: 'hidden',
                                             opacity: 0.95,
-                                        }, "aria-label": overlayWalkthroughStep
-                                            ? `${overlayWalkthroughTitle}, step ${overlayWalkthroughStep.index} of ${overlayWalkthroughStep.total}`
-                                            : overlayWalkthroughTitle, children: [_jsx("div", { style: {
+                                        }, "aria-label": overlayTrailStep
+                                            ? `${overlayTrailTitle}, step ${overlayTrailStep.index} of ${overlayTrailStep.total}`
+                                            : overlayTrailTitle, children: [_jsx("div", { style: {
                                                     padding: '5px 14px',
                                                     fontSize: theme.fontSizes[2] ?? theme.fontSizes[1],
                                                     fontWeight: 600,
@@ -2167,14 +2165,14 @@ function Inner({ components, walkthroughs, graphifyRelations, orderByLine, initi
                                                     textOverflow: 'ellipsis',
                                                     whiteSpace: 'nowrap',
                                                     textAlign: 'center',
-                                                }, children: overlayWalkthroughTitle }), overlayWalkthroughStep && overlayWalkthroughStep.total > 0 && (_jsx("div", { style: {
+                                                }, children: overlayTrailTitle }), overlayTrailStep && overlayTrailStep.total > 0 && (_jsx("div", { style: {
                                                     display: 'flex',
                                                     gap: 3,
                                                     padding: '0 6px 5px',
-                                                }, "aria-hidden": "true", children: Array.from({ length: overlayWalkthroughStep.total }, (_, i) => {
+                                                }, "aria-hidden": "true", children: Array.from({ length: overlayTrailStep.total }, (_, i) => {
                                                     const n = i + 1;
-                                                    const active = n === overlayWalkthroughStep.index;
-                                                    const done = n < overlayWalkthroughStep.index;
+                                                    const active = n === overlayTrailStep.index;
+                                                    const done = n < overlayTrailStep.index;
                                                     return (_jsx("span", { style: {
                                                             flex: 1,
                                                             height: 2,
@@ -2187,7 +2185,7 @@ function Inner({ components, walkthroughs, graphifyRelations, orderByLine, initi
                                                             opacity: active ? 1 : done ? 0.75 : 0.4,
                                                             transition: 'opacity 120ms ease, background 120ms ease',
                                                         } }, n));
-                                                }) }))] })), overlayWalkthroughStep?.annotation && (_jsx("div", { style: {
+                                                }) }))] })), overlayTrailStep?.annotation && (_jsx("div", { style: {
                                             maxWidth: '100%',
                                             padding: '6px 14px',
                                             background: theme.colors.backgroundSecondary ?? theme.colors.background,
@@ -2199,7 +2197,7 @@ function Inner({ components, walkthroughs, graphifyRelations, orderByLine, initi
                                             fontFamily: theme.fonts.body,
                                             color: theme.colors.textMuted ?? theme.colors.textSecondary,
                                             lineHeight: 1.35,
-                                        }, children: overlayWalkthroughStep.annotation }))] })), selected && (_jsx("div", { style: {
+                                        }, children: overlayTrailStep.annotation }))] })), selected && (_jsx("div", { style: {
                                     position: 'absolute',
                                     top: 10,
                                     right: 10,
@@ -2224,9 +2222,9 @@ function Inner({ components, walkthroughs, graphifyRelations, orderByLine, initi
                                         drawerTarget.startLine != null &&
                                         !!selected.file &&
                                         selected.file === drawerTarget.file &&
-                                        selected.declarationRef?.startLine === drawerTarget.startLine }) }))] }), _jsx(FileDrawer, { title: drawerTitle, onClose: closeDrawer, fillHeight: drawerFillHeight, suppressEscape: fileOverlayOpen, hidden: hideDrawer, children: drawerTarget?.kind === 'walkthrough' &&
-                            focusedWalkthrough &&
-                            renderWalkthroughViewer ? (_jsx(WalkthroughDrawerContent, { render: renderWalkthroughDrawerContent, walkthrough: focusedWalkthrough, stepIndex: drawerTarget.stepIndex, onOpenFile: onOpenFileFromWalkthrough, proposedAliases: proposedAliases, resolveSymbol: resolveWalkthroughSymbol, onSymbolClick: openConstructDeclaration })) : drawerTarget?.kind === 'file' ? (_jsx(FileDrawerContent, { render: renderDrawerContent, file: drawerTarget.file, startLine: drawerTarget.startLine })) : null }), fileOverlay && (_jsxs("div", { style: {
+                                        selected.declarationRef?.startLine === drawerTarget.startLine }) }))] }), _jsx(FileDrawer, { title: drawerTitle, onClose: closeDrawer, fillHeight: drawerFillHeight, suppressEscape: fileOverlayOpen, hidden: hideDrawer, children: drawerTarget?.kind === 'trail' &&
+                            focusedTrail &&
+                            renderTrailViewer ? (_jsx(TrailDrawerContent, { render: renderTrailDrawerContent, trail: focusedTrail, stepIndex: drawerTarget.stepIndex, onOpenFile: onOpenFileFromTrail, proposedAliases: proposedAliases, resolveSymbol: resolveTrailSymbol, onSymbolClick: openConstructDeclaration })) : drawerTarget?.kind === 'file' ? (_jsx(FileDrawerContent, { render: renderDrawerContent, file: drawerTarget.file, startLine: drawerTarget.startLine })) : null }), fileOverlay && (_jsxs("div", { style: {
                             position: 'absolute',
                             inset: 0,
                             zIndex: 8,
@@ -2313,7 +2311,7 @@ export function SubsystemComponentGraph(props) {
     }, []);
     const constructsOnly = isConstructsOnlyModel({
         components: props.components,
-        walkthroughs: props.walkthroughs,
+        trails: props.trails,
         graphifyRelations: props.graphifyRelations,
     });
     return (_jsx("div", { ref: wrapRef, style: {