@principal-ai/subsystems-react 0.56.10 → 0.56.12

package/src/subsystem/SubsystemComponentGraph.tsx

@@ -82,7 +82,7 @@ import {
 } from './IssueList';
 import { GraphLayoutCover } from './GraphLayoutCover';
 import { SubsystemFileTree } from './SubsystemFileTree';
-import { buildTreePathMapping } from './paths';
+import { buildTrailSidebarScope, type TrailSidebarScope } from './trailSidebarScope';
 import { GRAPH_CANVAS_CLASS, GRAPH_NAV_PROPS, GraphChrome, GraphLayerStyle, LAYOUT_FLIP_CLASS, LAYOUT_FLIP_EDGE_MS, LAYOUT_FLIP_NODE_MS } from './graphChrome';
 import { ComponentDeclaration } from './ComponentDeclaration';
 import type { ComponentVerificationState } from './ComponentDeclaration';
@@ -151,6 +151,7 @@ type DrawerTarget =
 interface PersistedViewState {
   expandedTrails?: string[];
   focusedTrailId?: string | null;
+  sidebarTrailId?: string | null;
   focusedStepIndex?: number | null;
   /** Sidebar width moved to the shared GraphWithSidebar chrome (persisted
    *  under `principal.subsystems.sidebarWidth.<persistKey>`); reading the old
@@ -403,7 +404,8 @@ export interface SubsystemComponentGraphProps {
   /**
    * Verification issues for this graph (audit findings). When diagnostics are
    * active the sidebar's bottom panel becomes the issue list instead of the
-   * file tree / trails.
+   * file tree / trails. Graph issue badges and issue-driven dimming are only
+   * shown in that mode.
    */
   issues?: SubsystemIssue[];
   /**
@@ -609,9 +611,11 @@ const TrailDrawerContent = memo(function TrailDrawerContent({
 interface InnerProps extends SubsystemComponentGraphProps {
   measured: { w: number; h: number } | null;
   filesActive: boolean;
+  sidebarScope: TrailSidebarScope;
+  onSidebarTrailChange: (trailId: string | null) => void;
 }
 
-function Inner({ components, trails, graphifyRelations, orderByLine, layoutDirection: layoutDirectionProp, defaultLayoutDirection = 'horizontal', onLayoutDirectionChange, hideLayoutToggle = false, refocusOnLayoutFlip = true, initialTrailId, onTrailSelect, onTrailStepHover, onReorderTrails, stepEmphasis, onRemoveStepEmphasis, onSelect, onEdgeSelect, measured: _measured, maxNodeWidth, showEdgeLabels, showSingletonFrames = true, moduleNesting, edgeView, hideSidebar, trailStepMode = 'focus', autoPlayTrails = false, trailAutoPlayIntervalMs = TRAIL_PLAY_PAUSE_MS, zoomOnTrailFocus = true, trailFocusDurationMs = 300, graphTitle, showTrailTitle = false, description, canvasOverlay, sidebarExtra, sidebarAfterDescription, issues, showIssues, filesActive, focusIssueCategory, laneStatus, onSelectIssue, onApplyIssueFix, onHoverIssue, renderFileViewer, renderTrailViewer, onFileSelect, componentVerification, onInspectSymbol, boundaryColors, codeProcessKeys, hideDrawer = false, persistKey, liveEvents, agentsPanel }: InnerProps) {
+function Inner({ components, trails, graphifyRelations, orderByLine, layoutDirection: layoutDirectionProp, defaultLayoutDirection = 'horizontal', onLayoutDirectionChange, hideLayoutToggle = false, refocusOnLayoutFlip = true, initialTrailId, onTrailSelect, onTrailStepHover, onReorderTrails, stepEmphasis, onRemoveStepEmphasis, onSelect, onEdgeSelect, measured: _measured, maxNodeWidth, showEdgeLabels, showSingletonFrames = true, moduleNesting, edgeView, hideSidebar, trailStepMode = 'focus', autoPlayTrails = false, trailAutoPlayIntervalMs = TRAIL_PLAY_PAUSE_MS, zoomOnTrailFocus = true, trailFocusDurationMs = 300, graphTitle, showTrailTitle = false, description, canvasOverlay, sidebarExtra, sidebarAfterDescription, issues, showIssues, filesActive, sidebarScope, onSidebarTrailChange, focusIssueCategory, laneStatus, onSelectIssue, onApplyIssueFix, onHoverIssue, renderFileViewer, renderTrailViewer, onFileSelect, componentVerification, onInspectSymbol, boundaryColors, codeProcessKeys, hideDrawer = false, persistKey, liveEvents, agentsPanel }: InnerProps) {
   const { theme } = useTheme();
   const { fitView, fitBounds } = useReactFlow();
   const viewport = useViewport();
@@ -1259,7 +1263,7 @@ function Inner({ components, trails, graphifyRelations, orderByLine, layoutDirec
   // node says "diagnostics here" for every finding the sidebar lists.
   const issueBadgeByAlias = useMemo(() => {
     const map = new Map<string, SubsystemNodeIssue>();
-    if (!issues?.length) return map;
+    if (showIssues !== true || !issues?.length) return map;
     for (const issue of issues) {
       const rung = issueRung(issue.kind);
       if (!rung && !ISSUE_KIND_ICON[issue.kind]) continue;
@@ -1294,7 +1298,7 @@ function Inner({ components, trails, graphifyRelations, orderByLine, layoutDirec
       if (kinded) map.set(alias, { ...badge, kind: kinded.kind });
     }
     return map;
-  }, [issues, issueComponent]);
+  }, [showIssues, issues, issueComponent]);
 
   // Per-frame diagnostics badge: the same fold, but for findings about a
   // BOUNDARY rather than a construct. Keyed by the region's React Flow node
@@ -1305,7 +1309,7 @@ function Inner({ components, trails, graphifyRelations, orderByLine, layoutDirec
   // borrowing its layer's icon would imply the frame is at fault for it.
   const regionIssueByNodeId = useMemo(() => {
     const map = new Map<string, SubsystemRegionIssue>();
-    if (!issues?.length) return map;
+    if (showIssues !== true || !issues?.length) return map;
     for (const issue of issues) {
       const target = issue.target;
       if (!target || !ISSUE_KIND_ICON[issue.kind]) continue;
@@ -1326,7 +1330,7 @@ function Inner({ components, trails, graphifyRelations, orderByLine, layoutDirec
       });
     }
     return map;
-  }, [issues]);
+  }, [showIssues, issues]);
 
   // Per-edge step verification badge: maps edge IDs to step verification status.
   // Keyed by the React Flow edge id (from → mechanism → to). An edge can have
@@ -1344,7 +1348,7 @@ function Inner({ components, trails, graphifyRelations, orderByLine, layoutDirec
       step_span_stale: 1,
     };
     const map = new Map<string, { kind: StepIssueKind; severity: 'info' | 'error'; count: number }>();
-    if (!issues?.length || !trails?.length) {
+    if (showIssues !== true || !issues?.length || !trails?.length) {
       return map;
     }
     for (const issue of issues) {
@@ -1371,7 +1375,7 @@ function Inner({ components, trails, graphifyRelations, orderByLine, layoutDirec
       });
     }
     return map;
-  }, [issues, trails, issueStep]);
+  }, [showIssues, issues, trails, issueStep]);
 
   // Expanded verification layers in the diagnostics list. When any layer with
   // findings is expanded, the canvas dims everything that layer does not
@@ -1420,7 +1424,7 @@ function Inner({ components, trails, graphifyRelations, orderByLine, layoutDirec
   // Returns null when nothing is expanded, no expanded layer has findings, or
   // the findings implicate nothing — so no dimming is applied.
   const issueFocus = useMemo(() => {
-    if (!issues?.length || expandedIssueCategories.length === 0) return null;
+    if (showIssues !== true || !issues?.length || expandedIssueCategories.length === 0) return null;
     const active = new Set(expandedIssueCategories);
     const activeIssues = issues.filter((i) => active.has(issueCategory(i)));
     if (activeIssues.length === 0) return null;
@@ -1475,7 +1479,7 @@ function Inner({ components, trails, graphifyRelations, orderByLine, layoutDirec
       if (nodeIds.has(e.source) && nodeIds.has(e.target)) edgeIds.add(e.id);
     }
     return { nodeIds, edgeIds };
-  }, [issues, expandedIssueCategories, components, trails, resolveAlias]);
+  }, [showIssues, issues, expandedIssueCategories, components, trails, resolveAlias]);
   const issueFocusNodeIds = issueFocus?.nodeIds ?? null;
   const issueFocusEdgeIds = issueFocus?.edgeIds ?? null;
 
@@ -1834,7 +1838,11 @@ function Inner({ components, trails, graphifyRelations, orderByLine, layoutDirec
   }, []);
 
   const hasTrails = useMemo(() => (trails?.length ?? 0) > 0, [trails]);
-  const treePaths = useMemo(() => buildTreePathMapping(components), [components]);
+  const { treePaths, trail: sidebarTrail } = sidebarScope;
+  const treeFilePaths = useMemo(() => treePaths.entries.map((entry) => entry.displayPath), [treePaths]);
+  useEffect(() => {
+    if (persistKey) writeViewState(persistKey, { sidebarTrailId: sidebarTrail?.id ?? null });
+  }, [persistKey, sidebarTrail?.id]);
   // Alias → component, so the Trails panel can show human hop names instead
   // of model-local aliases (and the site/`via` distinction can read).
   const componentByAlias = useMemo(
@@ -2123,13 +2131,14 @@ function Inner({ components, trails, graphifyRelations, orderByLine, layoutDirec
       }
       setExpandedTrails(new Set([tl.id]));
       setLayoutTrailId(tl.id);
+      onSidebarTrailChange(tl.id);
       setFocusedStepIndex(null);
       setFocusedTrailId(tl.id);
       onTrailSelect?.({ trailId: tl.id });
       fitFocusBounds(new Set(tl.steps.map((s) => trailStepGraphEdgeId(s))));
       setDrawerTarget((prev) => (prev?.kind === 'trail' ? null : prev));
     },
-    [fitFocusBounds, trailStepMode, onTrailSelect],
+    [fitFocusBounds, trailStepMode, onTrailSelect, onSidebarTrailChange],
   );
 
   const clearTrailFocus = useCallback(() => {
@@ -2139,25 +2148,25 @@ function Inner({ components, trails, graphifyRelations, orderByLine, layoutDirec
     }
     setExpandedTrails(new Set());
     setLayoutTrailId(null);
+    onSidebarTrailChange(null);
     setFocusedTrailId(null);
     setFocusedStepIndex(null);
     setHoveredTrailStep(null);
     setDrawerTarget((prev) => (prev?.kind === 'trail' ? null : prev));
     onTrailSelect?.(null);
-  }, [onTrailSelect]);
+  }, [onTrailSelect, onSidebarTrailChange]);
 
-  // A hidden trail must not leave the file view filtered to its cast.
+  // Switching panels keeps the selected trail, but drops transient hover previews.
   const filesWereActive = useRef(false);
   useEffect(() => {
     const enteringFiles = filesActive && !filesWereActive.current;
     filesWereActive.current = filesActive;
     if (!enteringFiles) return;
-    clearTrailFocus();
-    setExpandedTrails(new Set());
+    if (!sidebarTrail) clearTrailFocus();
     setSelectedEdgeId(null);
-    setLayoutTrailId(null);
+    setHoveredTrailStep(null);
     onTrailStepHover?.(null);
-  }, [filesActive, clearTrailFocus, onTrailStepHover]);
+  }, [filesActive, clearTrailFocus, onTrailStepHover, sidebarTrail]);
 
   // Host deep-link: opening the graph from a trail row selects that
   // flow — expand its steps and focus its edges.
@@ -2195,6 +2204,7 @@ function Inner({ components, trails, graphifyRelations, orderByLine, layoutDirec
         return;
       }
       // Toggle: clicking the selected step unselects it (back to whole flow).
+      onSidebarTrailChange(tl.id);
       if (focusedTrailId === tl.id && focusedStepIndex === stepIndex) {
         setFocusedStepIndex(null);
         // Pointer is still over the row — keep hover preview so dimming doesn't
@@ -2250,6 +2260,7 @@ function Inner({ components, trails, graphifyRelations, orderByLine, layoutDirec
       renderTrailViewer,
       trailStepMode,
       onTrailSelect,
+      onSidebarTrailChange,
     ],
   );
 
@@ -2705,7 +2716,7 @@ function Inner({ components, trails, graphifyRelations, orderByLine, layoutDirec
     (description || filesActive || issuesActive || sidebarExtra || sidebarAfterDescription ||
       hasTrails);
   const sidebarBodyVisible = hasTrails || filesActive || issuesActive;
-  const sidebarTabs: GraphSidebarTab[] | undefined = issuesActive
+  const sidebarTabs: GraphSidebarTab[] | undefined = issuesActive && !sidebarTrail
     ? agentsPanel
       ? [
           { id: 'issues', label: 'Issues' },
@@ -2736,14 +2747,14 @@ function Inner({ components, trails, graphifyRelations, orderByLine, layoutDirec
     </>
   );
   // Lower panel: diagnostics, the file tree, or the trail flow list.
-  const sidebarBody = issuesActive ? (
-    diagnosticsTab === 'agents' && agentsPanel ? (
+  const sidebarPanel = issuesActive ? (
+    diagnosticsTab === 'agents' && agentsPanel && !sidebarTrail ? (
       <SubsystemAgentsPanel {...agentsPanel} />
     ) : (
       <SubsystemIssueList
-        issues={issues ?? []}
+        issues={sidebarScope.issues}
         focusCategory={focusIssueCategory}
-        laneStatus={laneStatus}
+        laneStatus={sidebarTrail ? undefined : laneStatus}
         onSelectIssue={focusIssueTarget}
         onDeselectIssue={unfocusIssueTarget}
         onApplyFix={onApplyIssueFix}
@@ -2751,22 +2762,27 @@ function Inner({ components, trails, graphifyRelations, orderByLine, layoutDirec
         onExpandedCategoriesChange={handleExpandedCategoriesChange}
       />
     )
-  ) : filesActive ? (
+  ) : filesActive ? treePaths.entries.length === 0 ? (
+    <div style={{ padding: 16, color: theme.colors.textSecondary }}>No files for this trail.</div>
+  ) : (
     <SubsystemFileTree
-      files={treePaths.entries.map((entry) => entry.displayPath)}
+      headerless
+      files={treeFilePaths}
       selectedFile={openFile ? treePaths.toDisplay.get(openFile) : null}
       onSelectFile={(path) => {
         const file = treePaths.toFile.get(path);
         if (file) onOpenDeclarationFile(file);
       }}
     />
-  ) : trails && trails.length > 0 ? (
+  ) : null;
+  const trailNavigation = trails && trails.length > 0 ? (
     <TrailsPanel
       drilldown={trailStepMode !== 'dim'}
       trails={trails}
       expandedTrails={expandedTrails}
-      focusedTrailId={focusedTrailId}
-      focusedStepIndex={focusedStepIndex}
+      focusedTrailId={sidebarTrail?.id ?? focusedTrailId}
+      focusedStepIndex={!sidebarTrail || focusedTrailId === sidebarTrail.id ? focusedStepIndex : null}
+      detailContent={sidebarPanel}
       hoveredTrailStep={hoveredTrailStep}
       onToggleCollapsed={toggleTrailCollapsed}
       onFocusFlow={focusTrailEdges}
@@ -2790,6 +2806,9 @@ function Inner({ components, trails, graphifyRelations, orderByLine, layoutDirec
       onRemoveStepEmphasis={onRemoveStepEmphasis}
     />
   ) : null;
+  const sidebarBody = sidebarTrail && trailStepMode !== 'dim'
+    ? trailNavigation
+    : sidebarPanel ?? trailNavigation;
   const fileOverlayView = fileOverlay && (
     <div
       style={{
@@ -3385,20 +3404,43 @@ export function SubsystemComponentGraph(props: SubsystemComponentGraphProps) {
   const wrapRef = useRef<HTMLDivElement>(null);
   const [size, setSize] = useState<{ w: number; h: number } | null>(null);
   const [filesOpen, setFilesOpen] = useState(false);
-  const fileCount = useMemo(
-    () => buildTreePathMapping(props.components).entries.length,
-    [props.components],
+  // Browsing a trail is independent of selecting one of its files or findings.
+  const [sidebarTrailId, setSidebarTrailId] = useState<string | null>(() => {
+    const saved = readViewState(props.persistKey);
+    return saved.sidebarTrailId !== undefined ? saved.sidebarTrailId : saved.focusedTrailId ?? null;
+  });
+  const sidebarScope = useMemo(
+    () => buildTrailSidebarScope(props.components, props.trails, props.issues, sidebarTrailId),
+    [props.components, props.trails, props.issues, sidebarTrailId],
   );
-  const hasFiles = fileCount > 0;
+  const fileCount = sidebarScope.treePaths.entries.length;
+  const trailViewLabel = sidebarScope.trail ? 'Trail' : 'Trails';
+  const trailCount = props.trails?.length ?? 0;
+  const hasFiles = fileCount > 0 || sidebarScope.trail != null;
+  const sidebarDiagnostic: SubsystemDiagnostic = sidebarScope.trail ? {
+    ...props.diagnostic,
+    status: props.issues == null ? props.diagnostic?.status ?? 'unknown'
+      : sidebarScope.issues.length > 0 ? 'issues' : 'ok',
+    issueCount: sidebarScope.issues.length,
+    fixableCount: sidebarScope.issues.filter((issue) => issue.fix != null).length,
+    title: undefined,
+  } : props.diagnostic ?? { status: 'unknown', issueCount: props.issues?.length };
+  const hasIssues = (props.issues != null
+    ? sidebarScope.issues.length
+    : sidebarDiagnostic.issueCount ?? 0) > 0;
+  useEffect(() => {
+    if (sidebarTrailId != null && !sidebarScope.trail) setSidebarTrailId(null);
+  }, [sidebarTrailId, sidebarScope.trail]);
   const [diagnosticsOpen, setDiagnosticsOpen] = useState<boolean>(
     props.showIssues ?? (props.issues?.length ?? 0) > 0,
   );
-  const issuesActive = props.showIssues ?? diagnosticsOpen;
+  const issuesRequested = props.showIssues ?? diagnosticsOpen;
+  const issuesActive = hasIssues && issuesRequested;
   const filesActive = filesOpen && hasFiles && !issuesActive;
   const selectSidebarView = (view: 'trails' | 'files' | 'issues') => {
     const nextIssuesActive = view === 'issues';
     setFilesOpen(view === 'files');
-    if (nextIssuesActive !== issuesActive) {
+    if (nextIssuesActive !== issuesRequested) {
       if (props.showIssues === undefined) setDiagnosticsOpen(nextIssuesActive);
       props.diagnostic?.onToggle?.();
     }
@@ -3409,7 +3451,7 @@ export function SubsystemComponentGraph(props: SubsystemComponentGraphProps) {
     justifyContent: 'center',
     gap: 4,
     height: 28,
-    padding: '4px 7px',
+    padding: '4px 16px',
     fontFamily: theme.fonts.monospace,
     fontSize: theme.fontSizes[0],
     border: 'none',
@@ -3500,13 +3542,14 @@ export function SubsystemComponentGraph(props: SubsystemComponentGraphProps) {
             >
               <button
                 type="button"
-                aria-label="Trails"
+                aria-label={sidebarScope.trail ? 'Trail' : `Trails (${trailCount} ${trailCount === 1 ? 'trail' : 'trails'})`}
                 aria-pressed={!filesActive && !issuesActive}
                 onClick={() => selectSidebarView('trails')}
                 style={viewButtonStyle(!filesActive && !issuesActive)}
               >
                 <Route size={14} aria-hidden />
-                <span>Trails</span>
+                <span>{trailViewLabel}</span>
+                {!sidebarScope.trail && <span style={{ fontWeight: 600, marginLeft: 4 }}>{trailCount}</span>}
               </button>
               {hasFiles && (
                 <button
@@ -3519,16 +3562,18 @@ export function SubsystemComponentGraph(props: SubsystemComponentGraphProps) {
                 >
                   <Files size={14} aria-hidden />
                   <span>Files</span>
-                  <span style={{ fontWeight: 600 }}>{fileCount}</span>
+                  <span style={{ fontWeight: 600, marginLeft: 4 }}>{fileCount}</span>
                 </button>
               )}
+              {hasIssues && (
                 <SubsystemDiagnosticToggle
-                  {...(props.diagnostic ?? { status: 'unknown', issueCount: props.issues?.length })}
+                  {...sidebarDiagnostic}
                   labelText="Issues"
                   segmented
                   active={issuesActive}
                   onToggle={() => selectSidebarView('issues')}
                 />
+              )}
             </div>
         </header>
       )}
@@ -3552,7 +3597,8 @@ export function SubsystemComponentGraph(props: SubsystemComponentGraphProps) {
           />
         ) : (
           <ReactFlowProvider>
-            <Inner {...props} showIssues={issuesActive} filesActive={filesActive} measured={size} />
+            <Inner {...props} showIssues={issuesActive} filesActive={filesActive} measured={size}
+              sidebarScope={sidebarScope} onSidebarTrailChange={setSidebarTrailId} />
           </ReactFlowProvider>
         )}
       </div>

package/src/subsystem/SubsystemFileTree.tsx

@@ -143,6 +143,7 @@ export function SubsystemFileTree({ files, selectedFile, hoveredFile, hoveredFol
       ref={treeRef}
       onClickCapture={handleContainerClick}
       style={{
+        paddingTop: headerless ? 8 : undefined,
         flex: 1,
         minHeight: 0,
         display: 'flex',
@@ -187,7 +188,7 @@ export function SubsystemFileTree({ files, selectedFile, hoveredFile, hoveredFol
             '--trees-fg-muted-override': muted,
             '--trees-accent-override': theme.colors.primary,
             '--trees-font-family-override': theme.fonts.monospace,
-            '--trees-font-size-override': `${theme.fontSizes[0]}px`,
+            '--trees-font-size-override': `${theme.fontSizes[1]}px`,
             '--trees-theme-list-hover-bg': theme.colors.border,
             '--trees-theme-list-active-selection-bg': theme.colors.border,
           } as CSSProperties

package/src/subsystem/TrailStepsNav.test.tsx

@@ -56,6 +56,61 @@ function renderNav(props: Record<string, unknown>) {
 }
 
 describe('TrailStepsNav', () => {
+  for (const title of ['Short flow', 'Generate the account report and deliver it to every subscribed recipient']) {
+    for (const selected of [false, true]) {
+      test(`keeps explicit title spacing in the ${selected ? 'selected header' : 'list'} for ${title}`, () => {
+        const { getByRole } = renderNav({
+          trails: [{ ...TRAILS[0], title }],
+          focusedTrailId: selected ? 't1' : null,
+          focusedStepIndex: null,
+          hoveredTrailStep: null,
+          onFocusFlow: () => {},
+          onClearFocus: () => {},
+          onFocusStep: () => {},
+          onHoverStep: () => {},
+          onHoverFlow: () => {},
+          onLeaveStep: () => {},
+        });
+        const button = getByRole('button', { name: selected ? title : new RegExp(title), exact: selected });
+        const row = selected ? button.parentElement! : button;
+        const label = selected ? button : button.children[1] as HTMLElement;
+        expect(row.style.paddingTop).toBe('14px');
+        expect(row.style.paddingBottom).toBe('14px');
+        expect(row.style.paddingLeft).toBe('12px');
+        expect(row.style.paddingRight).toBe(row.style.paddingLeft);
+        expect(row.style.alignItems).toBe('flex-start');
+        expect(label.style.lineHeight).toBe('20px');
+        expect((row.firstElementChild as SVGElement).style.marginTop).toBe('3px');
+        if (selected) {
+          expect(row.style.borderBottomStyle).toBe('');
+          expect(getByRole('button', { name: 'Back to trails' }).style.height).toBe('20px');
+        }
+      });
+    }
+  }
+
+  test('keeps the selected trail header when files or issues replace the step body', () => {
+    let cleared = false;
+    const { getByRole, getByText, queryByText } = renderNav({
+      trails: TRAILS,
+      focusedTrailId: 't1',
+      focusedStepIndex: null,
+      hoveredTrailStep: null,
+      onFocusFlow: () => {},
+      onClearFocus: () => { cleared = true; },
+      onFocusStep: () => {},
+      onHoverStep: () => {},
+      onHoverFlow: () => {},
+      onLeaveStep: () => {},
+      detailContent: createElement('div', null, 'Files for this trail'),
+    });
+    expect(getByRole('button', { name: 'First flow', exact: true })).toBeTruthy();
+    expect(getByText('Files for this trail')).toBeTruthy();
+    expect(queryByText('A.go')).toBeNull();
+    fireEvent.click(getByRole('button', { name: 'Back to trails' }));
+    expect(cleared).toBe(true);
+  });
+
   test('lists trails with step counts and focuses on click', () => {
     let focused: string | null = null;
     const { getByText, getByRole } = renderNav({
@@ -161,6 +216,11 @@ describe('TrailStepsNav', () => {
     expect(getByText('B.go').style.fontFamily).toBe(defaultEditorTheme.fonts.body);
     expect(getByRole('button', { name: /A\.go/ }).style.paddingLeft).toBe('12px');
     expect(getByRole('button', { name: /B\.go/ }).style.paddingLeft).toBe('22px');
+    for (const name of [/A\.go/, /B\.go/]) {
+      const row = getByRole('button', { name });
+      expect(row.style.paddingTop).toBe('14px');
+      expect(row.style.paddingBottom).toBe('14px');
+    }
     fireEvent.click(getByRole('button', { name: /B\.go/ }));
     expect(focusedStep).toBe(1);
     fireEvent.click(getByLabelText('Back to trails'));

package/src/subsystem/TrailStepsNav.tsx

@@ -54,6 +54,8 @@ export interface TrailStepsNavProps {
   listContent?: ReactNode;
   /** Optional step content, for hosts with copy and guidance controls. */
   renderSteps?: (trail: SubsystemTrail) => ReactNode;
+  /** Replace the step body without replacing the selected trail's header. */
+  detailContent?: ReactNode;
 }
 
 const PANE: CSSProperties = {
@@ -80,6 +82,7 @@ export function TrailStepsNav({
   transitionMs = 340,
   listContent,
   renderSteps,
+  detailContent,
 }: TrailStepsNavProps) {
   const { theme } = useTheme();
   const muted = theme.colors.textMuted ?? theme.colors.textSecondary;
@@ -149,11 +152,11 @@ export function TrailStepsNav({
                 onClick={() => onFocusFlow(trail)}
                 style={{
                   display: 'flex',
-                  alignItems: 'center',
+                  alignItems: 'flex-start',
                   gap: 8,
                   width: '100%',
                   minWidth: 0,
-                  padding: '10px 8px 10px 12px',
+                  padding: '14px 12px',
                   border: 'none',
                   borderRadius: 0,
                   background: focusedRow || hovered ? hoverBg : 'transparent',
@@ -168,6 +171,7 @@ export function TrailStepsNav({
                   aria-hidden
                   style={{
                     flexShrink: 0,
+                    marginTop: 3,
                     color: focusedRow || hovered ? theme.colors.primary : muted,
                     transition: 'color 120ms ease',
                   }}
@@ -180,6 +184,7 @@ export function TrailStepsNav({
                     fontSize: theme.fontSizes[1],
                     fontFamily: theme.fonts.monospace,
                     fontWeight: 600,
+                    lineHeight: '20px',
                     color: theme.colors.text,
                   }}
                 >
@@ -189,6 +194,7 @@ export function TrailStepsNav({
                   style={{
                     flexShrink: 0,
                     fontSize: theme.fontSizes[0],
+                    lineHeight: '20px',
                     fontFamily: theme.fonts.monospace,
                     color: muted,
                   }}
@@ -217,12 +223,11 @@ export function TrailStepsNav({
               style={{
                 flexShrink: 0,
                 display: 'flex',
-                alignItems: 'center',
+                alignItems: 'flex-start',
                 gap: 8,
                 // Left inset + leading cell + gap match the step rows below, so
                 // the trail icon and the step numbers share one column.
-                padding: '6px 6px 6px 12px',
-                borderBottom: `1px solid ${theme.colors.border}`,
+                padding: '14px 12px',
               }}
             >
               <Route
@@ -231,7 +236,7 @@ export function TrailStepsNav({
                 aria-hidden
                 // The focused trail: the icon stays primary, matching the row's
                 // hover colour in the list it came from.
-                style={{ flexShrink: 0, color: theme.colors.primary }}
+                style={{ flexShrink: 0, marginTop: 3, color: theme.colors.primary }}
               />
               {/* The title is the back affordance too: clicking it goes back to
                   the list, like the trailing close. */}
@@ -254,6 +259,7 @@ export function TrailStepsNav({
                   fontSize: theme.fontSizes[1],
                   fontFamily: theme.fonts.monospace,
                   fontWeight: 600,
+                  lineHeight: '20px',
                   color: theme.colors.text,
                 }}
               >
@@ -272,7 +278,7 @@ export function TrailStepsNav({
                   justifyContent: 'center',
                   flexShrink: 0,
                   width: 24,
-                  height: 24,
+                  height: 20,
                   padding: 0,
                   border: 'none',
                   borderRadius: 4,
@@ -285,7 +291,7 @@ export function TrailStepsNav({
                 <X size={16} strokeWidth={2} />
               </button>
             </div>
-            <div
+            {detailContent ?? <div
               style={{ flex: 1, minHeight: 0, overflowY: 'auto', padding: '0 0 12px' }}
               onMouseLeave={onLeaveStep}
             >
@@ -308,7 +314,7 @@ export function TrailStepsNav({
                       gap: 8,
                       width: '100%',
                       minWidth: 0,
-                      padding: `8px 16px 8px ${12 + Math.max(0, stackDepth - 1) * 10}px`,
+                      padding: `14px 16px 14px ${12 + Math.max(0, stackDepth - 1) * 10}px`,
                       border: 'none',
                       borderRadius: 0,
                       background: active || hovered ? hoverBg : 'transparent',
@@ -370,7 +376,7 @@ export function TrailStepsNav({
                   </button>
                 );
               })}
-            </div>
+            </div>}
           </>
         )}
       </div>