@principal-ai/subsystems-react 0.55.3 → 0.56.1

package/src/subsystem/IssueList.tsx

@@ -123,6 +123,12 @@ const KIND_CATEGORY: Record<string, SubsystemIssueCategory> = {
   trail: 'trail',
   step_span_unconfirmed: 'trail',
   step_span_stale: 'trail',
+  step_site_outside_from: 'trail',
+  step_site_unconfirmed: 'trail',
+  step_site_mismatch: 'trail',
+  step_site_stale: 'trail',
+  step_target_mismatch: 'trail',
+  step_target_stale: 'trail',
 };
 
 /**
@@ -198,6 +204,14 @@ export const ISSUE_KIND_ICON: Record<string, LucideIcon> = {
   construct_span_stale: FileCodeCorner,
   step_span_unconfirmed: FileCodeCorner,
   step_span_stale: FileCodeCorner,
+  // A `calls` edge whose site does not live in the source component — the
+  // mechanism and the code are disagreeing, so a broken-link glyph.
+  step_site_outside_from: Link2Off,
+  step_site_unconfirmed: FileCodeCorner,
+  step_site_mismatch: Link2Off,
+  step_site_stale: FileCodeCorner,
+  step_target_mismatch: Link2Off,
+  step_target_stale: FileCodeCorner,
 };
 
 /**
@@ -288,6 +302,12 @@ const KIND_LABEL: Record<string, string> = {
   trail: 'Step issue',
   step_span_unconfirmed: 'Step span not captured',
   step_span_stale: 'Step span changed',
+  step_site_outside_from: 'Calls site outside source',
+  step_site_unconfirmed: 'Site construct not captured',
+  step_site_mismatch: 'Site construct mismatch',
+  step_site_stale: 'Site construct changed',
+  step_target_mismatch: 'Target construct mismatch',
+  step_target_stale: 'Target construct changed',
 };
 
 /** Label for an issue's kind. Explicit `kindLabel` wins; unknown kinds humanize. */
@@ -329,6 +349,12 @@ const KIND_ORDER: Record<string, number> = {
   trail: 40,
   step_span_unconfirmed: 41,
   step_span_stale: 42,
+  step_site_outside_from: 43,
+  step_site_unconfirmed: 44,
+  step_site_mismatch: 45,
+  step_site_stale: 46,
+  step_target_mismatch: 47,
+  step_target_stale: 48,
 };
 
 const KIND_ORDER_FALLBACK = 100;

package/src/subsystem/SubsystemComponentGraph.tsx

@@ -91,6 +91,8 @@ import { GraphWithSidebar } from './GraphWithSidebar';
 import type { GraphSidebarTab } from './GraphSidebar';
 import { buildRepoGroups, repoAvatarUrl, type RepoGroup } from './paths';
 import { TrailsPanel, TRAIL_PLAY_PAUSE_MS } from './TrailsPanel';
+import { TrailStackBreadcrumb } from './TrailStackBreadcrumb';
+import type { StepEmphasisMap } from './stepEmphasis';
 import {
   EDGE_LABEL_WIDTH,
   EDGE_LABEL_HEIGHT,
@@ -106,11 +108,6 @@ export interface TrailViewerContext {
   stepIndex: number | null;
   /** Open a step's full source file over the trail drawer (keeps snippets mounted). */
   onOpenFile: (path: string, opts?: SubsystemOpenFileOptions) => void;
-  /**
-   * Aliases of components marked `proposed`. A step whose file can't be read
-   * but whose endpoint is proposed can be labelled as planned, not missing.
-   */
-  proposedAliases: ReadonlySet<string>;
   /**
    * Resolve a token in a step's snippet to a construct the step touches (its
    * `from`/`to` component), returning that component's alias. `null` when the
@@ -287,6 +284,14 @@ export interface SubsystemComponentGraphProps {
    * and never reorders its own prop).
    */
   onReorderTrails?: (next: SubsystemTrail[]) => void;
+  /**
+   * PROTOTYPE: host-owned step emphasis augmentations, keyed by trail + claim
+   * fingerprint. Kept out of the model document; the host reads a separate
+   * augmentation store. A mark is a star plus optional markdown guidance.
+   */
+  stepEmphasis?: StepEmphasisMap;
+  /** Toggle a step's guidance off. Omit to hide the remove action. */
+  onRemoveStepEmphasis?: (trail: SubsystemTrail, stepIndex: number) => void;
   onSelect?: (componentAlias: string) => void;
   /** Called when an edge is clicked (relationship / mechanism + refs seam). */
   onEdgeSelect?: (edge: SubsystemComponentEdge) => void;
@@ -579,7 +584,6 @@ const TrailDrawerContent = memo(function TrailDrawerContent({
   trail,
   stepIndex,
   onOpenFile,
-  proposedAliases,
   resolveSymbol,
   onSymbolClick,
   onVisibleStepChange,
@@ -588,7 +592,6 @@ const TrailDrawerContent = memo(function TrailDrawerContent({
   trail: SubsystemTrail;
   stepIndex: number | null;
   onOpenFile: (path: string, opts?: SubsystemOpenFileOptions) => void;
-  proposedAliases: ReadonlySet<string>;
   resolveSymbol?: (query: TrailSymbolQuery) => string | null;
   onSymbolClick?: (symbol: string, query: TrailSymbolQuery) => void;
   onVisibleStepChange?: (index: number) => void;
@@ -599,7 +602,6 @@ const TrailDrawerContent = memo(function TrailDrawerContent({
         trail,
         stepIndex,
         onOpenFile,
-        proposedAliases,
         resolveSymbol,
         onSymbolClick,
         onVisibleStepChange,
@@ -612,7 +614,7 @@ interface InnerProps extends SubsystemComponentGraphProps {
   measured: { w: number; h: number } | null;
 }
 
-function Inner({ components, trails, graphifyRelations, orderByLine, layoutDirection: layoutDirectionProp, defaultLayoutDirection = 'horizontal', onLayoutDirectionChange, hideLayoutToggle = false, refocusOnLayoutFlip = true, initialTrailId, onTrailSelect, onTrailStepHover, 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, 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, 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, laneStatus, onSelectIssue, onApplyIssueFix, onHoverIssue, renderFileViewer, renderTrailViewer, onFileSelect, componentVerification, onInspectSymbol, boundaryColors, codeProcessKeys, hideDrawer = false, persistKey, liveEvents, agentsPanel }: InnerProps) {
   const { theme } = useTheme();
   const { fitView, fitBounds, screenToFlowPosition } = useReactFlow();
   const viewport = useViewport();
@@ -1431,24 +1433,42 @@ function Inner({ components, trails, graphifyRelations, orderByLine, layoutDirec
 
   // 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
-  // multiple steps with issues; we show the worst status (stale > unconfirmed).
+  // multiple steps with issues; we show the worst status.
   const stepIssueBadgeByEdgeId = useMemo(() => {
-    const map = new Map<string, { kind: 'step_span_unconfirmed' | 'step_span_stale'; severity: 'info' | 'error'; count: number }>();
+    type StepIssueKind =
+      | 'step_span_unconfirmed'
+      | 'step_span_stale'
+      | 'step_site_outside_from';
+    // Unconfirmed is the hard failure; a miscategorized `calls` edge is the
+    // next most actionable (it changes what the edge means); drift is last.
+    const rank: Record<StepIssueKind, number> = {
+      step_span_unconfirmed: 3,
+      step_site_outside_from: 2,
+      step_span_stale: 1,
+    };
+    const map = new Map<string, { kind: StepIssueKind; severity: 'info' | 'error'; count: number }>();
     if (!issues?.length || !trails?.length) {
       return map;
     }
     for (const issue of issues) {
-      if (issue.kind !== 'step_span_unconfirmed' && issue.kind !== 'step_span_stale') continue;
+      if (
+        issue.kind !== 'step_span_unconfirmed' &&
+        issue.kind !== 'step_span_stale' &&
+        issue.kind !== 'step_site_outside_from'
+      ) {
+        continue;
+      }
       const stepInfo = issueStep(issue);
       if (!stepInfo) continue;
       const step = stepInfo.trail.steps[stepInfo.stepIndex];
       if (!step) continue;
       const edgeId = trailStepGraphEdgeId(step);
+      const kind = issue.kind as StepIssueKind;
       const prev = map.get(edgeId);
-      // step_span_stale is worse than step_span_unconfirmed
-      const isWorse = issue.kind === 'step_span_stale' && prev?.kind !== 'step_span_stale';
+      const isWorse = !prev || rank[kind] > rank[prev.kind];
+      const nextKind = isWorse ? kind : prev!.kind;
       map.set(edgeId, {
-        kind: isWorse || !prev ? issue.kind as 'step_span_unconfirmed' | 'step_span_stale' : prev.kind,
+        kind: nextKind,
         severity: prev?.severity === 'error' || issue.severity === 'error' ? 'error' : 'info',
         count: (prev?.count ?? 0) + 1,
       });
@@ -1456,22 +1476,6 @@ function Inner({ components, trails, graphifyRelations, orderByLine, layoutDirec
     return map;
   }, [issues, trails, issueStep]);
 
-  // Edges backed by a step that ITSELF declares `proposed` — a planned seam
-  // between otherwise-real components. Distinct from a proposed ENDPOINT
-  // (the node is the placeholder there, and draws its own dashed border):
-  // here the seam is the claim that is not real yet, so the edge label draws
-  // dashed. Proposed steps are never verified, so this never competes with
-  // the step-issue badge.
-  const proposedEdgeIds = useMemo(() => {
-    const set = new Set<string>();
-    for (const trail of trails ?? []) {
-      for (const step of trail.steps) {
-        if (step.proposed) set.add(trailStepGraphEdgeId(step));
-      }
-    }
-    return set;
-  }, [trails]);
-
   // Expanded verification layers in the diagnostics list. When any layer with
   // findings is expanded, the canvas dims everything that layer does not
   // implicate (see `issueFocus`). The list publishes this through
@@ -1798,17 +1802,6 @@ function Inner({ components, trails, graphifyRelations, orderByLine, layoutDirec
     () => convertedEdges.map((e) => e.id).sort().join(','),
     [convertedEdges],
   );
-  // Stamp `proposedStep` onto edge data so the SVG edge itself (not just its
-  // label) draws dashed when a backing trail step declares itself proposed.
-  const proposedStampedEdges = useMemo(
-    () =>
-      baseEdges.map((e) =>
-        proposedEdgeIds.has(e.id)
-          ? { ...e, data: { ...(e.data as object), proposedStep: true } }
-          : e,
-      ),
-    [baseEdges, proposedEdgeIds],
-  );
 
   const dispEdges = useMemo(() => {
     const paint = (e: Edge, dimmed: boolean): Edge => {
@@ -1837,7 +1830,7 @@ function Inner({ components, trails, graphifyRelations, orderByLine, layoutDirec
       return isTrailMechanism(mechanism);
     };
     if (openedEdgeIds || focusEdgeIds || previewEdgeIds || issueFocusEdgeIds) {
-      return proposedStampedEdges.map((e) => {
+      return baseEdges.map((e) => {
         const vis = flowElementVisibility({
           inOpened: openedEdgeIds?.has(e.id) === true,
           inSelected: focusEdgeIds?.has(e.id) === true,
@@ -1851,13 +1844,13 @@ function Inner({ components, trails, graphifyRelations, orderByLine, layoutDirec
       });
     }
     if (selectedEdgeId) {
-      return proposedStampedEdges.map((e) => ({
+      return baseEdges.map((e) => ({
         ...paint(e, e.id !== selectedEdgeId),
         hidden: !edgeInView(e),
       }));
     }
-    return proposedStampedEdges.map((e) => ({ ...e, hidden: !edgeInView(e) }));
-  }, [proposedStampedEdges, selectedEdgeId, openedEdgeIds, focusEdgeIds, previewEdgeIds, issueFocusEdgeIds, resolvedEdgeView]);
+    return baseEdges.map((e) => ({ ...e, hidden: !edgeInView(e) }));
+  }, [baseEdges, selectedEdgeId, openedEdgeIds, focusEdgeIds, previewEdgeIds, issueFocusEdgeIds, resolvedEdgeView]);
 
   // Gated on layoutReady so the pre-reveal Pass 1 swap never flashes a count.
   const unroutedIds = useMemo(
@@ -1947,10 +1940,10 @@ function Inner({ components, trails, graphifyRelations, orderByLine, layoutDirec
   // own owner-avatar header. Clicking a header collapses that repo's tree.
   const repoGroups = useMemo(() => buildRepoGroups(components), [components]);
   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)),
+  // 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(
+    () => new Map(components.map((c) => [c.alias, c])),
     [components],
   );
   // Diagnostics view in the sidebar. Uncontrolled unless the host pins
@@ -2800,7 +2793,6 @@ function Inner({ components, trails, graphifyRelations, orderByLine, layoutDirec
           pathLength?: number;
         } | undefined;
         const stepIssue = stepIssueBadgeByEdgeId.get(e.id);
-        const proposed = proposedEdgeIds.has(e.id);
         return {
           id: e.id,
           mechanism: d?.mechanism ?? 'uses',
@@ -2811,11 +2803,10 @@ function Inner({ components, trails, graphifyRelations, orderByLine, layoutDirec
           pathLength: d?.pathLength ?? 0,
           stepNos: selectedFlowStepNos?.get(e.id),
           stepIssue,
-          proposed,
         };
       });
     return labels;
-  }, [dispEdges, selectedFlowStepNos, stepIssueBadgeByEdgeId, proposedEdgeIds]);
+  }, [dispEdges, selectedFlowStepNos, stepIssueBadgeByEdgeId]);
 
   // Unique source files across components → sidebar file trees.
   const treeFilePaths = treeFiles;
@@ -3006,7 +2997,9 @@ function Inner({ components, trails, graphifyRelations, orderByLine, layoutDirec
         onTrailStepHover?.(null);
       }}
       onReorder={onReorderTrails}
-      proposedAliases={proposedAliases}
+      componentByAlias={componentByAlias}
+      stepEmphasis={stepEmphasis}
+      onRemoveStepEmphasis={onRemoveStepEmphasis}
       layoutFocusedTrailId={layoutTrailId}
       onFocusLayout={toggleLayoutFocus}
     />
@@ -3153,9 +3146,7 @@ function Inner({ components, trails, graphifyRelations, orderByLine, layoutDirec
                   crisp rounded box; soft / ambiguous ones (uses, feeds,
                   watches …) get a real lobed cloud silhouette — ambiguous, not
                   a dashed proposal (or a pill, which border-radius can only
-                  ever make). A step that ITSELF declares `proposed` dashes the
-                  silhouette — the seam is planned, distinct from a proposed
-                  ENDPOINT, which dashes the node instead. */}
+                  ever make). */}
               {verifiable ? (
                 <span
                   aria-hidden
@@ -3163,9 +3154,7 @@ function Inner({ components, trails, graphifyRelations, orderByLine, layoutDirec
                     position: 'absolute',
                     inset: 0,
                     borderRadius: 4,
-                    border: lbl.proposed
-                      ? `1.5px dashed ${color}`
-                      : `0.5px solid ${color}`,
+                    border: `0.5px solid ${color}`,
                     background:
                       theme.colors.backgroundSecondary ?? theme.colors.background,
                     pointerEvents: 'none',
@@ -3190,7 +3179,6 @@ function Inner({ components, trails, graphifyRelations, orderByLine, layoutDirec
                     stroke={hexWithAlpha(color, 0.75)}
                     strokeWidth={1.2}
                     strokeLinejoin="round"
-                    strokeDasharray={lbl.proposed ? '4 3' : undefined}
                   />
                 </svg>
               )}
@@ -3221,9 +3209,13 @@ function Inner({ components, trails, graphifyRelations, orderByLine, layoutDirec
                 return (
                   <span
                     aria-hidden
-                    title={lbl.stepIssue.kind === 'step_span_stale'
-                      ? 'Call site changed since verification'
-                      : 'Call site not yet verified'}
+                    title={
+                      lbl.stepIssue.kind === 'step_span_stale'
+                        ? 'Call site changed since verification'
+                        : lbl.stepIssue.kind === 'step_site_outside_from'
+                          ? 'Calls site is outside its source component'
+                          : 'Call site not yet verified'
+                    }
                     style={{
                       position: 'absolute',
                       right: -7,
@@ -3553,6 +3545,18 @@ function Inner({ components, trails, graphifyRelations, orderByLine, layoutDirec
         suppressEscape={fileOverlayOpen}
         hidden={hideDrawer}
         progress={drawerProgress}
+        subheader={
+          drawerTarget?.kind === 'trail' &&
+          focusedTrail &&
+          drawerTarget.stepIndex != null ? (
+            <TrailStackBreadcrumb
+              trail={focusedTrail}
+              stepIndex={drawerTarget.stepIndex}
+              componentByAlias={componentByAlias}
+              onFocusStep={(index) => focusTrailStep(focusedTrail, index)}
+            />
+          ) : null
+        }
       >
         {drawerTarget?.kind === 'trail' &&
         focusedTrail &&
@@ -3562,7 +3566,6 @@ function Inner({ components, trails, graphifyRelations, orderByLine, layoutDirec
             trail={focusedTrail}
             stepIndex={drawerTarget.stepIndex}
             onOpenFile={onOpenFileFromTrail}
-            proposedAliases={proposedAliases}
             resolveSymbol={resolveTrailSymbol}
             onSymbolClick={openConstructDeclaration}
             onVisibleStepChange={setVisibleStepIndex}

package/src/subsystem/TrailStackBreadcrumb.test.tsx

@@ -0,0 +1,109 @@
+import { afterEach, describe, expect, test } from 'bun:test';
+import { Window } from 'happy-dom';
+import { cleanup, fireEvent, render } from '@testing-library/react/pure';
+import { ThemeProvider, defaultEditorTheme } from '@principal-ade/industry-theme';
+import type { SubsystemTrail } from './model';
+import { TrailStackBreadcrumb } from './TrailStackBreadcrumb';
+
+const dom = new Window();
+const globals = globalThis as unknown as Record<string, unknown>;
+globals.window = dom;
+globals.document = dom.document;
+globals.navigator = dom.navigator;
+globals.HTMLElement = dom.HTMLElement;
+globals.Node = dom.Node;
+globals.Element = dom.Element;
+globals.Event = dom.Event;
+globals.MouseEvent = dom.MouseEvent;
+globals.getComputedStyle = dom.getComputedStyle.bind(dom);
+globals.requestAnimationFrame = dom.requestAnimationFrame.bind(dom);
+globals.cancelAnimationFrame = dom.cancelAnimationFrame.bind(dom);
+globals.localStorage = dom.localStorage;
+globals.sessionStorage = dom.sessionStorage;
+globals.matchMedia = dom.matchMedia.bind(dom);
+globals.ResizeObserver = class {
+  observe() {}
+  unobserve() {}
+  disconnect() {}
+};
+
+afterEach(cleanup);
+
+const trail: SubsystemTrail = {
+  id: 't',
+  title: 'T',
+  steps: [
+    {
+      from: 'panel',
+      to: 'rpc',
+      mechanism: 'calls',
+      file: 'src/panel.ts',
+      purl: 'pkg:github/acme/app#src/panel.ts',
+      symbol: 'MaintenancePanel',
+      target: {
+        purl: 'pkg:github/acme/app#src/rpc.ts',
+        file: 'src/rpc.ts',
+        symbol: 'getRpc',
+      },
+    },
+    {
+      from: 'rpc',
+      to: 'detail',
+      mechanism: 'calls',
+      file: 'src/rpc.ts',
+      purl: 'pkg:github/acme/app#src/rpc.ts',
+      symbol: 'getRpc',
+      target: {
+        purl: 'pkg:github/acme/app#src/detail.ts',
+        file: 'src/detail.ts',
+        symbol: 'modelDetail',
+      },
+    },
+    {
+      from: 'panel',
+      to: 'merge',
+      mechanism: 'uses',
+      file: 'src/list.tsx',
+      purl: 'pkg:github/acme/app#src/list.tsx',
+      symbol: 'ModelList',
+    },
+  ],
+};
+
+function renderBreadcrumb(stepIndex: number, onFocusStep?: (i: number) => void) {
+  return render(
+    <ThemeProvider theme={defaultEditorTheme}>
+      <TrailStackBreadcrumb
+        trail={trail}
+        stepIndex={stepIndex}
+        onFocusStep={onFocusStep}
+      />
+    </ThemeProvider>,
+  );
+}
+
+describe('TrailStackBreadcrumb', () => {
+  test('renders the call chain and the callee', () => {
+    const { getByText } = renderBreadcrumb(1);
+    expect(getByText('MaintenancePanel')).toBeTruthy();
+    expect(getByText('getRpc')).toBeTruthy();
+    expect(getByText('modelDetail')).toBeTruthy();
+  });
+
+  test('clicking a frame focuses that step', () => {
+    let focused: number | null = null;
+    const { getByText } = renderBreadcrumb(1, (i) => {
+      focused = i;
+    });
+    fireEvent.click(getByText('MaintenancePanel'));
+    expect(focused).toBe(0);
+  });
+
+  test('a uses step is an annotation, not a fourth frame', () => {
+    const { getByText, queryByText } = renderBreadcrumb(2);
+    expect(getByText('Context')).toBeTruthy();
+    expect(getByText('uses merge')).toBeTruthy();
+    // The uses step's site symbol is not rendered as a frame.
+    expect(queryByText('ModelList')).toBeNull();
+  });
+});

package/src/subsystem/TrailStackBreadcrumb.tsx

@@ -0,0 +1,172 @@
+/**
+ * TrailStackBreadcrumb — the call stack at one trail step.
+ *
+ * Rendered above the trail code view. `calls` steps form the chain; `uses` and
+ * data/event seams are annotations on the nearest frame, never frames of their
+ * own. Clicking a frame focuses the step that created it.
+ */
+
+import type { CSSProperties } from 'react';
+import { ArrowRight, CornerDownRight } from 'lucide-react';
+import { useTheme } from '@principal-ade/industry-theme';
+import type { SubsystemTrail } from './model';
+import { buildTrailStack } from './trailStack';
+import type { TrailComponentLabels } from './trailStepDisplay';
+
+export interface TrailStackBreadcrumbProps {
+  trail: SubsystemTrail;
+  /** Selected step; the stack is the chain into its caller frame. */
+  stepIndex: number;
+  /** Alias → component, for human frame/callee labels when no symbol resolves. */
+  componentByAlias?: TrailComponentLabels;
+  /** Focus a frame's step (usually the trail panel's onFocusStep). */
+  onFocusStep?: (stepIndex: number) => void;
+}
+
+const chipBase: CSSProperties = {
+  display: 'inline-flex',
+  alignItems: 'center',
+  minWidth: 0,
+  maxWidth: 260,
+  padding: '2px 7px',
+  borderRadius: 4,
+  lineHeight: 1.4,
+  whiteSpace: 'nowrap',
+  overflow: 'hidden',
+  textOverflow: 'ellipsis',
+};
+
+export function TrailStackBreadcrumb({
+  trail,
+  stepIndex,
+  componentByAlias,
+  onFocusStep,
+}: TrailStackBreadcrumbProps) {
+  const { theme } = useTheme();
+  const muted = theme.colors.textMuted ?? theme.colors.textSecondary;
+  const stack = buildTrailStack(trail, stepIndex, componentByAlias);
+  if (stack.frames.length === 0) return null;
+
+  return (
+    <div
+      aria-label={`${
+        stack.isCall ? 'Call stack' : 'Trail context'
+      } at step ${stepIndex + 1}`}
+      style={{
+        display: 'flex',
+        alignItems: 'center',
+        gap: 6,
+        flexShrink: 0,
+        minHeight: 28,
+        padding: '4px 10px',
+        overflowX: 'auto',
+        borderBottom: `1px solid ${theme.colors.border}`,
+        background:
+          theme.colors.backgroundSecondary ?? theme.colors.background,
+      }}
+    >
+      <span
+        style={{
+          flexShrink: 0,
+          paddingRight: 2,
+          fontSize: 9,
+          fontFamily: theme.fonts.body,
+          fontWeight: 600,
+          letterSpacing: 0.5,
+          textTransform: 'uppercase',
+          color: muted,
+        }}
+      >
+        {stack.isCall ? 'Stack' : 'Context'}
+      </span>
+
+      {stack.frames.map((frame, index) => {
+        const chipStyle: CSSProperties = {
+          ...chipBase,
+          fontFamily: theme.fonts.monospace,
+          fontSize: theme.fontSizes[0],
+          border: `1px solid ${
+            frame.current ? theme.colors.primary : theme.colors.border
+          }`,
+          background: frame.current ? theme.colors.background : 'transparent',
+          color: frame.current ? theme.colors.text : theme.colors.textSecondary,
+          fontWeight: frame.current ? 600 : 400,
+          cursor: onFocusStep ? 'pointer' : 'default',
+          flexShrink: 0,
+        };
+        const label = (
+          <span
+            style={{
+              overflow: 'hidden',
+              textOverflow: 'ellipsis',
+            }}
+          >
+            {frame.label}
+          </span>
+        );
+        return (
+          <span
+            key={`${frame.stepIndex}:${index}`}
+            style={{ display: 'inline-flex', alignItems: 'center', gap: 6 }}
+          >
+            {index > 0 && (
+              <span aria-hidden style={{ color: muted, fontSize: 11 }}>
+                ›
+              </span>
+            )}
+            {onFocusStep ? (
+              <button
+                type="button"
+                onClick={() => onFocusStep(frame.stepIndex)}
+                style={chipStyle}
+              >
+                {label}
+              </button>
+            ) : (
+              <span style={chipStyle}>{label}</span>
+            )}
+          </span>
+        );
+      })}
+
+      {stack.callee && (
+        <span
+          style={{ display: 'inline-flex', alignItems: 'center', gap: 4 }}
+        >
+          <ArrowRight size={11} style={{ color: muted, flexShrink: 0 }} />
+          <span
+            style={{
+              ...chipBase,
+              fontFamily: theme.fonts.monospace,
+              fontSize: theme.fontSizes[0],
+              border: `1px dashed ${theme.colors.border}`,
+              color: muted,
+              flexShrink: 0,
+            }}
+          >
+            {stack.callee}
+          </span>
+        </span>
+      )}
+
+      {stack.annotations.map((annotation) => (
+        <span
+          key={`annotation:${annotation.stepIndex}`}
+          style={{
+            display: 'inline-flex',
+            alignItems: 'center',
+            gap: 3,
+            flexShrink: 0,
+            fontSize: 10,
+            fontFamily: theme.fonts.monospace,
+            color: muted,
+            whiteSpace: 'nowrap',
+          }}
+        >
+          <CornerDownRight size={10} style={{ flexShrink: 0 }} />
+          {annotation.label}
+        </span>
+      ))}
+    </div>
+  );
+}

package/src/subsystem/TrailStepsNav.test.tsx

@@ -155,6 +155,41 @@ describe('TrailStepsNav', () => {
     expect(cleared).toBe(true);
   });
 
+  test('uses rows show the logical hop and the via site', () => {
+    const usesTrail: SubsystemTrail = {
+      id: 'uses',
+      title: 'Uses flow',
+      steps: [
+        {
+          from: 'panel',
+          to: 'merge',
+          mechanism: 'uses',
+          file: 'src/list.tsx',
+          span: { startLine: 10, endLine: 12, contentHash: 'h' },
+          purl: 'pkg:github/x#src/list.tsx',
+          symbol: 'ModelList',
+        },
+      ],
+    };
+    const { getByText } = renderNav({
+      trails: [usesTrail],
+      focusedTrailId: 'uses',
+      focusedStepIndex: null,
+      hoveredTrailStep: null,
+      componentByAlias: new Map([
+        ['panel', { alias: 'panel', name: 'MaintenancePanel' }],
+        ['merge', { alias: 'merge', name: 'mergeProvenance' }],
+      ]),
+      onFocusFlow: () => {},
+      onClearFocus: () => {},
+      onFocusStep: () => {},
+      onHoverStep: () => {},
+      onHoverFlow: () => {},
+      onLeaveStep: () => {},
+    });
+    expect(getByText('MaintenancePanel uses mergeProvenance')).toBeTruthy();
+  });
+
   test('clicking the step-pane header title also goes back', () => {
     let cleared = false;
     const { getByRole } = renderNav({