@principal-ai/subsystems-react 0.56.10 → 0.56.12

package/src/subsystem/TrailsPanel.test.tsx

@@ -115,8 +115,6 @@ function renderPanel(overrides: Partial<TrailsPanelProps> = {}) {
   );
 }
 
-const COPY_LABEL = 'Copy step 1 of Auth flow for an agent';
-
 describe('TrailsPanel drilldown navigation', () => {
   test('clicking a trail opens its steps, and Back restores the list without playback', () => {
     const onFocusFlow = mock(() => {});
@@ -165,14 +163,17 @@ describe('TrailsPanel drilldown navigation', () => {
     expect(queryByRole('button', { name: /Login.submit/ })).toBeNull();
   });
 
-  test('keeps step-copy controls in the focused pane without playback controls', async () => {
-    const { getByText, getByLabelText, queryByLabelText } = renderPanel({
+  test('supports Command-click copy in the focused pane without extra controls', async () => {
+    const onFocusStep = mock(() => {});
+    const { getByText, getByLabelText, queryByLabelText, queryByRole } = renderPanel({
       drilldown: true,
       focusedTrailId: 'auth-flow',
+      onFocusStep,
     });
-    fireEvent.mouseEnter(getByText('Login.submit').closest('button')!);
-    fireEvent.click(getByLabelText(COPY_LABEL));
+    fireEvent.click(getByText('Login.submit').closest('button')!, { metaKey: true });
     await waitFor(() => expect(writeText).toHaveBeenCalledWith(buildStepBrief(trails[0]!, 0)));
+    expect(onFocusStep).not.toHaveBeenCalled();
+    expect(queryByRole('button', { name: /Copy step/ })).toBeNull();
     expect(queryByLabelText('Play Auth flow')).toBeNull();
     expect(queryByLabelText('Collapse Auth flow')).toBeNull();
     expect(getByLabelText('Back to trails')).toBeTruthy();
@@ -188,6 +189,35 @@ describe('TrailsPanel drilldown navigation', () => {
 });
 
 describe('TrailsPanel trail titles', () => {
+  for (const title of ['Short flow', 'Validate every selected checkout item and persist the complete customer order']) {
+    for (const collapsed of [true, false]) {
+      test(`keeps explicit title spacing for ${collapsed ? 'collapsed' : 'expanded'} ${title}`, () => {
+        const { getByRole } = renderPanel({
+          trails: [{ ...trails[0]!, title }],
+          expandedTrails: collapsed ? new Set() : new Set(['auth-flow']),
+          onReorder: () => {},
+        });
+        const button = getByRole('button', { name: title, exact: true });
+        const row = button.parentElement!;
+        expect(row.style.paddingTop).toBe('14px');
+        expect(row.style.paddingBottom).toBe('14px');
+        expect(row.style.paddingLeft).toBe('16px');
+        expect(row.style.paddingRight).toBe(row.style.paddingLeft);
+        expect(row.style.minHeight).toBe('');
+        expect(row.style.alignItems).toBe('flex-start');
+        expect(button.style.padding).toBe('0px');
+        expect((button.lastElementChild as HTMLElement).style.lineHeight).toBe('20px');
+        expect((button.firstElementChild as SVGElement).style.marginTop).toBe('3px');
+        if (collapsed) {
+          expect(getByRole('button', { name: `Reorder ${title}` }).style.height).toBe('20px');
+          expect(getByRole('button', { name: `Reorder ${title}` }).style.marginRight).toBe('');
+        } else {
+          expect(getByRole('button', { name: `Play ${title}` }).style.height).toBe('20px');
+        }
+      });
+    }
+  }
+
   test('highlights immediately without a CSS fade while graph preview waits', async () => {
     const onHoverFlow = mock(() => {});
     const onLeaveStep = mock(() => {});
@@ -253,30 +283,28 @@ describe('TrailsPanel trail titles', () => {
 });
 
 describe('TrailsPanel step copy', () => {
-  test('copy icon is hidden until the step row is hovered', () => {
-    const { getByText, queryByLabelText } = renderPanel();
-    expect(queryByLabelText(COPY_LABEL)).toBeNull();
+  test('does not show a copy button on hover or keyboard focus', () => {
+    const { getByText, queryByRole, container } = renderPanel();
     const row = getByText('Login.submit').closest('button')!;
     fireEvent.mouseEnter(row);
-    expect(queryByLabelText(COPY_LABEL)).not.toBeNull();
-  });
-
-  test('copy icon is revealed on keyboard focus', () => {
-    const { getByText, queryByLabelText } = renderPanel();
-    const row = getByText('Login.submit').closest('button')!;
     fireEvent.focus(row);
-    expect(queryByLabelText(COPY_LABEL)).not.toBeNull();
+    expect(queryByRole('button', { name: /Copy step/ })).toBeNull();
+    expect(container.querySelector('.lucide-copy')).toBeNull();
+    expect(row.hasAttribute('title')).toBe(false);
+    expect(row.firstElementChild?.textContent).toBe('1');
   });
 
-  test('clicking copies the step brief and flashes a copied state', async () => {
-    const { getByText, getByLabelText } = renderPanel();
-    fireEvent.mouseEnter(getByText('Login.submit').closest('button')!);
-    const copy = getByLabelText(COPY_LABEL);
-    fireEvent.mouseDown(copy);
-    fireEvent.click(copy);
-    await waitFor(() => expect(writeText).toHaveBeenCalledTimes(1));
+  test('Command-click copies the brief without focusing and replaces the number with a checkmark', async () => {
+    const onFocusStep = mock(() => {});
+    const { getByText, getByRole } = renderPanel({ onFocusStep });
+    const row = getByText('Login.submit').closest('button')!;
+    fireEvent.click(row, { metaKey: true });
+    await waitFor(() => expect(getByRole('status', { name: 'Copied' })).toBeTruthy());
+    expect(writeText).toHaveBeenCalledTimes(1);
     expect(writeText).toHaveBeenCalledWith(buildStepBrief(trails[0]!, 0));
-    expect(copy.getAttribute('title')).toBe('Copied');
+    expect(onFocusStep).not.toHaveBeenCalled();
+    expect(row.hasAttribute('title')).toBe(false);
+    expect(row.firstElementChild?.querySelector('.lucide-check')).not.toBeNull();
   });
 
   test('hovering the row still focuses the step on click', () => {
@@ -286,26 +314,40 @@ describe('TrailsPanel step copy', () => {
     fireEvent.mouseEnter(row);
     fireEvent.click(row);
     expect(onFocusStep).toHaveBeenCalledWith(trails[0]!, 0);
+    expect(writeText).not.toHaveBeenCalled();
   });
 
   test('the copied checkmark clears after the feedback window', async () => {
-    const { getByText, getByLabelText } = renderPanel();
-    fireEvent.mouseEnter(getByText('Login.submit').closest('button')!);
-    const copy = getByLabelText(COPY_LABEL);
-    fireEvent.click(copy);
-    await waitFor(() => expect(copy.getAttribute('title')).toBe('Copied'));
+    const { getByText, getByRole, queryByRole } = renderPanel();
+    const row = getByText('Login.submit').closest('button')!;
+    fireEvent.click(row, { metaKey: true });
+    await waitFor(() => expect(getByRole('status', { name: 'Copied' })).toBeTruthy());
     await new Promise((r) => setTimeout(r, STEP_COPY_FEEDBACK_MS + 20));
-    await waitFor(() => expect(copy.getAttribute('title')).not.toBe('Copied'));
+    await waitFor(() => expect(queryByRole('status', { name: 'Copied' })).toBeNull());
+    expect(row.firstElementChild?.textContent).toBe('1');
   });
 
   test('a failed copy shows no copied state', async () => {
     writeText.mockImplementationOnce(() => Promise.reject(new Error('denied')));
-    const { getByText, getByLabelText } = renderPanel();
-    fireEvent.mouseEnter(getByText('Login.submit').closest('button')!);
-    const copy = getByLabelText(COPY_LABEL);
-    fireEvent.click(copy);
+    const { getByText, queryByRole } = renderPanel();
+    const row = getByText('Login.submit').closest('button')!;
+    fireEvent.click(row, { metaKey: true });
     await new Promise((r) => setTimeout(r, 10));
-    expect(copy.getAttribute('title')).toBe('Copy this step for an agent');
+    expect(writeText).toHaveBeenCalledTimes(1);
+    expect(queryByRole('status', { name: 'Copied' })).toBeNull();
+    expect(row.firstElementChild?.textContent).toBe('1');
+  });
+
+  test('an unavailable clipboard leaves the number and does not focus the step', () => {
+    Object.defineProperty(navigator, 'clipboard', { value: undefined, configurable: true });
+    const onFocusStep = mock(() => {});
+    const { getByText, queryByRole } = renderPanel({ onFocusStep });
+    const row = getByText('Login.submit').closest('button')!;
+    fireEvent.click(row, { metaKey: true });
+    expect(writeText).not.toHaveBeenCalled();
+    expect(onFocusStep).not.toHaveBeenCalled();
+    expect(queryByRole('status', { name: 'Copied' })).toBeNull();
+    expect(row.firstElementChild?.textContent).toBe('1');
   });
 });
 
@@ -334,9 +376,31 @@ describe('TrailsPanel step semantics', () => {
       expect(symbol.style.color).toBe(normal.style.color);
       expect(symbol.style.fontFamily).toBe(defaultEditorTheme.fonts.body);
       expect(symbol.previousElementSibling).toBe(annotation);
+      const row = symbol.closest('button')!;
+      expect(row.style.paddingTop).toBe('14px');
+      expect(row.style.paddingBottom).toBe('14px');
+      expect(row.style.paddingLeft).toBe(drilldown ? '12px' : '16px');
+      expect((row.firstElementChild as HTMLElement).style.width).toBe('14px');
+      expect((row.firstElementChild as HTMLElement).style.textAlign).toBe('center');
       fireEvent.click(getByRole('button', { name: /Submit the login request.*Login.submit/ }));
       expect(onFocusStep).toHaveBeenCalledWith(trail, 0);
     });
+
+    test(`keeps nested steps offset from the ${drilldown ? 'selected' : 'inline'} header column`, () => {
+      const trail: SubsystemTrail = {
+        ...trails[0]!,
+        steps: [
+          { ...trails[0]!.steps[0]!, from: 'a', to: 'b', symbol: 'A.go' },
+          { ...trails[0]!.steps[0]!, from: 'b', to: 'c', symbol: 'B.go' },
+          { ...trails[0]!.steps[0]!, from: 'a', to: 'd', symbol: 'A.next' },
+        ],
+      };
+      const { getByText } = renderPanel({ trails: [trail], drilldown, focusedTrailId: trail.id });
+      const inset = drilldown ? 12 : 16;
+      expect(getByText('A.go').closest('button')!.style.paddingLeft).toBe(`${inset}px`);
+      expect(getByText('B.go').closest('button')!.style.paddingLeft).toBe(`${inset + 10}px`);
+      expect(getByText('A.next').closest('button')!.style.paddingLeft).toBe(`${inset}px`);
+    });
   }
 
   test('calls leads with the caller frame', () => {

package/src/subsystem/TrailsPanel.tsx

@@ -11,9 +11,9 @@
  */
 
 import { useCallback, useEffect, useRef, useState } from 'react';
-import type { DragEvent as ReactDragEvent } from 'react';
+import type { DragEvent as ReactDragEvent, ReactNode } from 'react';
 import { useTheme } from '@principal-ade/industry-theme';
-import { Check, ChevronDown, Copy, Focus, GripVertical, Minimize2, Pause, Play, Route, Star } from 'lucide-react';
+import { Check, ChevronDown, Focus, GripVertical, Minimize2, Pause, Play, Route, Star } from 'lucide-react';
 import { IndustryMarkdownSlide } from 'themed-markdown';
 import {
   reorderTargetIndex,
@@ -45,10 +45,10 @@ const EMPHASIS_COLOR = '#f5a524';
  */
 export const TRAIL_HOVER_PREVIEW_MS = 150;
 
-/** How long a step's copy button flashes its "copied" checkmark (ms). */
+/** How long a step's number shows its "copied" checkmark (ms). */
 export const STEP_COPY_FEEDBACK_MS = 2000;
 
-/** Square size (px) of a trail header's Play/Collapse control. */
+/** Width (px) of a trail header's Play/Collapse control. */
 const TRAIL_CONTROL_SIZE = 34;
 
 /** Drag state handed to a row's grip while a reorder is in flight. */
@@ -166,11 +166,6 @@ function TrailFlow({
   // A pending preview must not fire after the row unmounts or collapses.
   useEffect(() => () => cancelHoverPreview(), [cancelHoverPreview]);
   const stepButtonRefs = useRef<(HTMLButtonElement | null)[]>([]);
-  // Per-step copy affordance: revealed while a row is hovered or holds focus.
-  // `focusedStep` tracks focus-within (button or its copy control) so the icon
-  // stays put while the pointer or focus moves between them.
-  const [focusedStep, setFocusedStep] = useState<number | null>(null);
-  const [copyHoverStep, setCopyHoverStep] = useState<number | null>(null);
   const [copiedStep, setCopiedStep] = useState<number | null>(null);
   const copyTimerRef = useRef<number | null>(null);
   // Autoplay: stepping through the flow's steps with a pause between each.
@@ -291,10 +286,9 @@ function TrailFlow({
         }}
         style={{
           display: 'flex',
-          alignItems: 'center',
+          alignItems: 'flex-start',
           gap: 4,
-          minHeight: TRAIL_CONTROL_SIZE,
-          padding: '0 0 0 16px',
+          padding: '14px 16px',
           // A collapsed row follows the pointer, not the delayed graph preview.
           background: headerHover || (!collapsed && wholeFlowActive) ? hoverBg : 'transparent',
         }}
@@ -318,16 +312,10 @@ function TrailFlow({
           style={{
             flex: 1,
             display: 'flex',
-            alignItems: 'center',
+            alignItems: 'flex-start',
             minWidth: 0,
             gap: 8,
-            // Vertical padding, not just the row's min-height: a title that
-            // wraps to two+ lines must grow the header past `minHeight`, and
-            // without this the text sits flush against the row's top and bottom
-            // edges (the controls stretch to the text height). 6px keeps a
-            // one-line title under `TRAIL_CONTROL_SIZE`, so single-line rows
-            // stay 34px.
-            padding: '6px 0',
+            padding: 0,
             border: 'none',
             background: 'transparent',
             textAlign: 'left',
@@ -340,6 +328,7 @@ function TrailFlow({
             aria-hidden
             style={{
               flexShrink: 0,
+              marginTop: 3,
               color: headerHover || (!collapsed && wholeFlowActive) ? theme.colors.primary : muted,
             }}
           />
@@ -350,6 +339,7 @@ function TrailFlow({
               fontSize: theme.fontSizes[1],
               fontFamily: theme.fonts.monospace,
               fontWeight: 600,
+              lineHeight: '20px',
               color: theme.colors.text,
             }}
           >
@@ -365,6 +355,7 @@ function TrailFlow({
               gap: 2,
               flexShrink: 0,
               marginRight: 4,
+              height: 20,
               fontSize: theme.fontSizes[0],
               fontFamily: theme.fonts.monospace,
               color: theme.colors.accent ?? theme.colors.primary ?? muted,
@@ -401,7 +392,7 @@ function TrailFlow({
                 alignItems: 'center',
                 justifyContent: 'center',
                 flexShrink: 0,
-                alignSelf: 'stretch',
+                height: 20,
                 width: TRAIL_CONTROL_SIZE,
                 padding: 0,
                 border: 'none',
@@ -434,7 +425,7 @@ function TrailFlow({
               alignItems: 'center',
               justifyContent: 'center',
               flexShrink: 0,
-              alignSelf: 'stretch',
+              height: 20,
               width: TRAIL_CONTROL_SIZE,
               padding: 0,
               border: 'none',
@@ -463,7 +454,7 @@ function TrailFlow({
               alignItems: 'center',
               justifyContent: 'center',
               flexShrink: 0,
-              alignSelf: 'stretch',
+              height: 20,
               width: TRAIL_CONTROL_SIZE,
               padding: 0,
               border: 'none',
@@ -496,8 +487,8 @@ function TrailFlow({
               display: 'inline-flex',
               alignItems: 'center',
               flexShrink: 0,
-              marginRight: 8,
-              padding: '2px 0',
+              height: 20,
+              padding: 0,
               color: gripHover || reorder.isDragging ? theme.colors.text : muted,
               cursor: reorder.isDragging ? 'grabbing' : 'grab',
               transition: 'color 120ms ease',
@@ -518,10 +509,7 @@ function TrailFlow({
         >
           {trail.steps.map((step, i) => {
             const stepActive = active !== null && active.stepIndex === i;
-            const revealed =
-              stepActive || hoveredStep === i || focusedStep === i || copiedStep === i;
             const copied = copiedStep === i;
-            const copyHovered = copyHoverStep === i;
             const record = stepEmphasis?.get(emphasisKey(trail.id, step));
             const display = trailStepDisplay(step, componentByAlias);
             // Calls nest; uses/data steps sit at their anchor frame's depth.
@@ -530,6 +518,7 @@ function TrailFlow({
               i,
               componentByAlias,
             ).frames.length;
+            const stepInset = (hideHeader ? 12 : 16) + Math.max(0, stackDepth - 1) * 10;
             // The guidance body follows step focus: clicking a step opens it,
             // clicking the focused step again returns to the flow. Hover is
             // deliberately not enough — the list would flutter on sweep.
@@ -538,14 +527,8 @@ function TrailFlow({
               <div
                 key={`${trailStepGraphEdgeId(step)}-${i}`}
                 style={{ position: 'relative' }}
-                onFocus={() => setFocusedStep(i)}
-                onBlur={(e) => {
-                  if (!e.currentTarget.contains(e.relatedTarget as Node | null)) {
-                    setFocusedStep((cur) => (cur === i ? null : cur));
-                  }
-                }}
               >
-                {/* The row's absolute affordances (star, copy) are scoped to
+                {/* The row's absolute star is scoped to
                     this wrapper so the guidance body below cannot stretch
                     them — `top:0;bottom:0` on the outer row would grow their
                     hit area with the markdown block. */}
@@ -559,16 +542,23 @@ function TrailFlow({
                     setHoveredStep(i);
                     scheduleHoverPreview(() => onHoverStep(trail, i));
                   }}
-                  onClick={() => onFocusStep(trail, i)}
+                  onClick={(e) => {
+                    if (e.metaKey) {
+                      e.preventDefault();
+                      e.stopPropagation();
+                      cancelHoverPreview();
+                      copyStep(i);
+                      return;
+                    }
+                    onFocusStep(trail, i);
+                  }}
                   style={{
                     display: 'flex',
                     alignItems: 'flex-start',
                     gap: 8,
                     minWidth: 0,
                     width: '100%',
-                    padding: `8px 70px 8px ${
-                      17 + Math.max(0, stackDepth - 1) * 10
-                    }px`,
+                    padding: `14px 36px 14px ${stepInset}px`,
                     textAlign: 'left',
                     borderRadius: 0,
                     border: 'none',
@@ -579,21 +569,26 @@ function TrailFlow({
                   }}
                 >
                   <span
+                    role={copied ? 'status' : undefined}
+                    aria-label={copied ? 'Copied' : undefined}
                     style={{
                       flexShrink: 0,
                       width: 14,
+                      textAlign: 'center',
                       paddingTop: 1,
                       fontSize: theme.fontSizes[0],
                       fontFamily: theme.fonts.monospace,
                       fontWeight: record ? 700 : undefined,
-                      color: record
+                      color: copied
+                        ? theme.colors.primary
+                        : record
                         ? EMPHASIS_COLOR
                         : stepActive
                           ? theme.colors.text
                           : muted,
                     }}
                   >
-                    {i + 1}
+                    {copied ? <Check size={12} strokeWidth={2} aria-hidden /> : i + 1}
                   </span>
                   <span
                     style={{
@@ -639,7 +634,7 @@ function TrailFlow({
                     title="Key step"
                     style={{
                       position: 'absolute',
-                      right: 34,
+                      right: 12,
                       top: 0,
                       bottom: 0,
                       display: 'inline-flex',
@@ -654,54 +649,12 @@ function TrailFlow({
                     <Star size={12} strokeWidth={2} fill={EMPHASIS_COLOR} />
                   </span>
                 )}
-                {revealed && (
-                  <button
-                    type="button"
-                    aria-label={`Copy step ${i + 1} of ${trail.title} for an agent`}
-                    title={copied ? 'Copied' : 'Copy this step for an agent'}
-                    onMouseDown={(e) => e.preventDefault()}
-                    onMouseEnter={() => setCopyHoverStep(i)}
-                    onMouseLeave={() =>
-                      setCopyHoverStep((cur) => (cur === i ? null : cur))
-                    }
-                    onClick={() => copyStep(i)}
-                    style={{
-                      position: 'absolute',
-                      right: 0,
-                      top: 0,
-                      bottom: 0,
-                      display: 'inline-flex',
-                      alignItems: 'center',
-                      justifyContent: 'center',
-                      width: 'auto',
-                      aspectRatio: '1 / 1',
-                      padding: 0,
-                      border: 'none',
-                      borderRadius: 0,
-                      background: copied
-                        ? 'rgba(16,185,129,0.12)'
-                        : copyHovered
-                          ? theme.colors.border
-                          : 'transparent',
-                      color: copied ? '#10b981' : copyHovered ? theme.colors.text : muted,
-                      cursor: 'pointer',
-                      transition: 'background 120ms ease, color 120ms ease',
-                    }}
-                  >
-                    {copied ? (
-                      <Check size={12} strokeWidth={2} />
-                    ) : (
-                      <Copy size={12} strokeWidth={2} />
-                    )}
-                  </button>
-                )}
                 </div>
                 {guidanceVisible && record?.guidance && (
                   <div
                     style={{
-                      // Align with the step text: 17px row inset + 14px number
-                      // column + 8px gap.
-                      padding: '2px 12px 10px 39px',
+                      // Follow the row inset, number column, and text gap.
+                      padding: `2px 12px 10px ${stepInset + 14 + 8}px`,
                       fontSize: theme.fontSizes[0],
                       lineHeight: 1.5,
                     }}
@@ -786,6 +739,8 @@ export interface TrailsPanelProps {
   componentByAlias?: TrailComponentLabels;
   /** Slide from the trail list into its steps, without playback controls. */
   drilldown?: boolean;
+  /** Files or issues for the selected trail, beneath its shared header. */
+  detailContent?: ReactNode;
 }
 
 /**
@@ -813,6 +768,7 @@ export function TrailsPanel({
   onRemoveStepEmphasis,
   componentByAlias,
   drilldown = false,
+  detailContent,
 }: TrailsPanelProps) {
   const { theme } = useTheme();
   // Reordering is offered only while every row is collapsed: the compact list
@@ -1023,6 +979,7 @@ export function TrailsPanel({
       onLeaveStep={onLeaveStep}
       componentByAlias={componentByAlias}
       listContent={list}
+      detailContent={detailContent}
       renderSteps={(trail) => (
         <TrailFlow
           key={trail.id}

package/src/subsystem/trailSidebarScope.test.ts

@@ -0,0 +1,89 @@
+import { describe, expect, test } from 'bun:test';
+import type { SubsystemComponent, SubsystemTrail } from './model';
+import type { SubsystemIssue, SubsystemIssueTarget } from './IssueList';
+import { buildTrailSidebarScope } from './trailSidebarScope';
+
+const components: SubsystemComponent[] = [
+  { alias: 'entry', name: 'Entry', construct: 'function', file: 'src/entry.ts', purl: 'pkg:github/acme/app', module: 'src', process: 'web' },
+  { alias: 'store', name: 'Store', construct: 'function', file: 'src/store.ts', purl: 'pkg:github/acme/app', module: 'src', process: 'host' },
+  { alias: 'other', name: 'Other', construct: 'function', file: 'src/other.ts', purl: 'pkg:github/acme/other', module: 'other', process: 'worker' },
+];
+const trail: SubsystemTrail = {
+  id: 'save', title: 'Save record',
+  steps: [{
+    from: 'entry', to: 'store', mechanism: 'calls', file: 'src/seam.ts', purl: 'pkg:github/acme/app',
+    target: { file: 'src/target.ts', purl: 'pkg:github/acme/shared#src/target.ts', symbol: 'persist' },
+  }],
+};
+const finding = (id: string, target?: SubsystemIssueTarget): SubsystemIssue => ({
+  id, kind: 'trail', severity: 'error', message: id, target,
+});
+
+describe('trail sidebar scope', () => {
+  test('without a selected trail, keeps the model-wide files and findings', () => {
+    const issues = [finding('global')];
+    const scope = buildTrailSidebarScope(components, [trail], issues, null);
+    expect(scope.trail).toBeNull();
+    expect(scope.treePaths.entries.map((entry) => entry.file)).toEqual(components.map((component) => component.file));
+    expect(scope.issues).toBe(issues);
+  });
+
+  test('includes endpoint declarations, seam sites, and target files, excluding unrelated files', () => {
+    const scope = buildTrailSidebarScope(components, [trail], [], trail.id);
+    expect(scope.trail).toBe(trail);
+    expect(scope.treePaths.entries.map((entry) => entry.file)).toEqual([
+      'src/entry.ts', 'src/store.ts', 'src/seam.ts', 'src/target.ts',
+    ]);
+    expect(scope.treePaths.multiRepo).toBe(true);
+  });
+
+  test('includes only findings for this trail and its participating constructs, boundaries, and repos', () => {
+    const relevant = [
+      finding('component', { kind: 'component', id: 'entry', label: 'Entry' }),
+      finding('legacy-label', { kind: 'component', label: 'Store' }),
+      finding('trail', { kind: 'trail', id: 'save', label: 'Save record' }),
+      finding('step', { kind: 'step', id: 'save', stepIndex: 0, label: 'Entry → Store' }),
+      finding('module', { kind: 'module', id: 'src', label: 'src' }),
+      finding('process', { kind: 'process', id: 'host', label: 'Host' }),
+      finding('repo', { kind: 'repo', id: 'pkg:github/acme/app#src/entry.ts', label: 'app' }),
+      finding('target-repo', { kind: 'repo', id: 'pkg:github/acme/shared', label: 'shared' }),
+    ];
+    const unrelated = [
+      finding('other-component', { kind: 'component', id: 'other', label: 'Other' }),
+      finding('other-trail', { kind: 'trail', id: 'other', label: 'Other' }),
+      finding('other-step', { kind: 'step', id: 'other', stepIndex: 0, label: 'Other step' }),
+      finding('invalid-step', { kind: 'step', id: 'save', stepIndex: 10, label: 'Old step' }),
+      finding('other-module', { kind: 'module', id: 'other', label: 'other' }),
+      finding('other-process', { kind: 'process', id: 'worker', label: 'Worker' }),
+      finding('other-repo', { kind: 'repo', id: 'pkg:github/acme/other', label: 'other' }),
+      finding('graph', { kind: 'graph', label: 'Whole graph' }),
+      finding('untargeted'),
+    ];
+    expect(buildTrailSidebarScope(components, [trail], [...relevant, ...unrelated], trail.id).issues).toEqual(relevant);
+  });
+
+  test('deduplicates repeated sites without merging identical paths from different repos', () => {
+    const repeated: SubsystemTrail = {
+      ...trail, steps: [trail.steps[0]!, trail.steps[0]!, {
+        ...trail.steps[0]!, purl: 'pkg:github/acme/shared',
+      }],
+    };
+    const paths = buildTrailSidebarScope(components, [repeated], [], trail.id).treePaths;
+    expect(paths.entries.filter((entry) => entry.file === 'src/seam.ts')).toHaveLength(2);
+    expect(paths.toFile.get('acme/shared/src/seam.ts')).toBe('src/seam.ts');
+  });
+
+  test('a removed trail restores model-wide content', () => {
+    const scope = buildTrailSidebarScope(components, [], [], trail.id);
+    expect(scope.trail).toBeNull();
+    expect(scope.treePaths.entries).toHaveLength(3);
+  });
+
+  test('an empty trail has empty files and issues rather than falling back to the full model', () => {
+    const empty: SubsystemTrail = { id: 'empty', title: 'Empty', steps: [] };
+    const scope = buildTrailSidebarScope(components, [empty], [finding('global')], empty.id);
+    expect(scope.trail).toBe(empty);
+    expect(scope.treePaths.entries).toHaveLength(0);
+    expect(scope.issues).toHaveLength(0);
+  });
+});

package/src/subsystem/trailSidebarScope.ts

@@ -0,0 +1,62 @@
+import type { SubsystemComponent, SubsystemTrail } from './model';
+import type { SubsystemIssue } from './IssueList';
+import { buildTreePathMapping, purlOwnerName, purlRepoKey, type TreePathMapping } from './paths';
+
+export interface TrailSidebarScope {
+  trail: SubsystemTrail | null;
+  treePaths: TreePathMapping;
+  issues: SubsystemIssue[];
+}
+
+/** Scope sidebar content to a trail's endpoints and authored source sites. */
+export function buildTrailSidebarScope(
+  components: SubsystemComponent[],
+  trails: SubsystemTrail[] | undefined,
+  issues: SubsystemIssue[] | undefined,
+  trailId: string | null,
+): TrailSidebarScope {
+  const trail = trails?.find((item) => item.id === trailId) ?? null;
+  if (!trail) {
+    return { trail: null, treePaths: buildTreePathMapping(components), issues: issues ?? [] };
+  }
+  const aliases = new Set(trail.steps.flatMap((step) => [step.from, step.to]));
+  const participants = components.filter((component) => aliases.has(component.alias));
+  const files: Array<{ file?: string; purl?: string }> = [...participants];
+  for (const step of trail.steps) {
+    files.push(step);
+    if (step.target) files.push(step.target);
+  }
+  const modules = new Set(participants.map((component) => component.module?.trim()).filter(Boolean));
+  const processes = new Set(participants.map((component) => component.process).filter(Boolean));
+  const repos = new Set(files.flatMap((file) =>
+    [purlRepoKey(file.purl), purlOwnerName(file.purl)].filter((key): key is string => !!key),
+  ));
+  const scopedIssues = (issues ?? []).filter((issue) => {
+    const target = issue.target;
+    if (!target) return false;
+    const key = target.id ?? target.label;
+    switch (target.kind) {
+      case 'component': {
+        const component = components.find((candidate) =>
+          candidate.alias === target.id || candidate.alias === target.label ||
+          candidate.name === target.label || candidate.symbol === target.label,
+        );
+        return component != null && aliases.has(component.alias);
+      }
+      case 'trail':
+        return target.id != null ? target.id === trail.id : target.label === trail.title;
+      case 'step':
+        return target.id === trail.id && target.stepIndex != null &&
+          Number.isInteger(target.stepIndex) && trail.steps[target.stepIndex] != null;
+      case 'module':
+        return modules.has(key);
+      case 'process':
+        return processes.has(key);
+      case 'repo':
+        return repos.has(purlRepoKey(key) ?? key);
+      default:
+        return false;
+    }
+  });
+  return { trail, treePaths: buildTreePathMapping(files), issues: scopedIssues };
+}