@principal-ai/subsystems-react 0.56.11 → 0.56.13

package/src/stories/Canvases/C4/C4Draft.stories.tsx

@@ -0,0 +1,238 @@
+import React, { useMemo, useState } from 'react';
+import '@xyflow/react/dist/style.css';
+import type { Meta, StoryObj } from '@storybook/react';
+import { ThemeProvider, defaultEditorTheme } from '@principal-ade/industry-theme';
+import { C4Graph } from '../../../subsystem/C4Graph';
+import type { C4ConstructGraph } from '../../../subsystem/C4Graph';
+import type { C4Edge, C4Element, C4Model } from '../../../subsystem/c4';
+import {
+  DRILLDOWN_COMPONENTS,
+  DRILLDOWN_PURL,
+  DRILLDOWN_TRAILS,
+} from '../../../subsystem/__fixtures__/c4Drilldown';
+
+const meta = {
+  title: 'Canvases/C4/C4Draft',
+  component: C4Graph,
+  parameters: { layout: 'fullscreen' },
+  tags: ['autodocs'],
+  decorators: [
+    (Story) => (
+      <ThemeProvider theme={defaultEditorTheme}>
+        <Story />
+      </ThemeProvider>
+    ),
+  ],
+} satisfies Meta<typeof C4Graph>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// ---------------------------------------------------------------------------
+// The minimal C4: no accepted containers, no authored components.
+//
+// Every box is derived from the model itself:
+//
+//   - one *draft* container per runtime `process` key (members resolve by
+//     exact process match, the rule accepted containers use);
+//   - a file-less / external process becomes an external system, so lines
+//     leaving the boundary have somewhere to land;
+//   - lines are the fold of cross-boundary trail steps, labelled by
+//     mechanism;
+//   - each opened container hosts its member constructs directly, because no
+//     C4 component layer exists to group them.
+//
+// Nothing here claims verification. This is what the API's `source=draft`
+// projection looks like: a reading of the model, not a stored decision.
+// ---------------------------------------------------------------------------
+
+const SYSTEM = {
+  id: 'system:draft',
+  label: 'Gist share from Studio',
+  repoKey: DRILLDOWN_PURL,
+};
+
+const byAlias = new Map(DRILLDOWN_COMPONENTS.map((c) => [c.alias, c]));
+
+/** `local/disk` → `local-disk`; keeps ids readable in the story. */
+function slug(value: string): string {
+  return value.replace(/[^a-zA-Z0-9]+/g, '-').replace(/^-|-$/g, '');
+}
+
+interface DraftElement {
+  element: C4Element;
+  members: string[];
+}
+
+const elements: C4Element[] = [];
+const membersByElement = new Map<string, string[]>();
+const elementOfAlias = new Map<string, string>();
+
+const byProcess = new Map<string, string[]>();
+for (const component of DRILLDOWN_COMPONENTS) {
+  const process = component.process?.trim();
+  if (!process) continue;
+  const list = byProcess.get(process) ?? [];
+  list.push(component.alias);
+  byProcess.set(process, list);
+}
+
+const drafts: DraftElement[] = [];
+for (const [process, members] of byProcess) {
+  // A process with no grounded code behind it is not a deployable unit: it is
+  // the model's way of naming something outside the boundary.
+  const fileless = members.every((alias) => !byAlias.get(alias)?.file);
+  const external =
+    fileless || process.startsWith('external/') || process.startsWith('local/');
+
+  if (external) {
+    const element: C4Element = {
+      kind: 'external-system',
+      id: `external:${slug(process)}`,
+      label: process,
+      members,
+      technology: byAlias.get(members[0] ?? '')?.framework ?? 'external',
+      state: 'accepted',
+      description: `${members.length} member${members.length === 1 ? '' : 's'} outside the boundary.`,
+    };
+    elements.push(element);
+    drafts.push({ element, members });
+    membersByElement.set(element.id, members);
+  } else {
+    const element: C4Element = {
+      kind: 'container',
+      id: `container:${slug(process)}`,
+      label: process,
+      containerKind: members.some((alias) => byAlias.get(alias)?.construct === 'store')
+        ? 'data-store'
+        : 'application',
+      technology: byAlias.get(members[0] ?? '')?.framework ?? '',
+      process,
+      parentId: SYSTEM.id,
+      state: 'accepted',
+      description: `${members.length} component${members.length === 1 ? '' : 's'} derived from process ${process}.`,
+    };
+    elements.push(element);
+    drafts.push({ element, members });
+    membersByElement.set(element.id, members);
+  }
+  for (const alias of members) elementOfAlias.set(alias, elements[elements.length - 1]!.id);
+}
+
+const containers = drafts.filter((d) => d.element.kind === 'container');
+const externals = drafts.filter((d) => d.element.kind === 'external-system');
+
+// Fold cross-boundary trail steps into lines. Same rule the accepted-store
+// projection uses; only the membership source differs.
+const edges: C4Edge[] = (() => {
+  const byKey = new Map<
+    string,
+    { source: string; target: string; mechanism: string; refs: Map<string, number[]> }
+  >();
+  for (const trail of DRILLDOWN_TRAILS) {
+    trail.steps.forEach((step, index) => {
+      const source = elementOfAlias.get(step.from);
+      const target = elementOfAlias.get(step.to);
+      if (!source || !target || source === target) return;
+      const key = [source, target, step.mechanism].join('\0');
+      let acc = byKey.get(key);
+      if (!acc) {
+        acc = { source, target, mechanism: step.mechanism, refs: new Map() };
+        byKey.set(key, acc);
+      }
+      const steps = acc.refs.get(trail.id) ?? [];
+      steps.push(index);
+      acc.refs.set(trail.id, steps);
+    });
+  }
+  return [...byKey.values()].map((acc) => ({
+    id: `e:${slug(acc.source)}-${slug(acc.target)}-${acc.mechanism}`,
+    source: acc.source,
+    target: acc.target,
+    label: acc.mechanism,
+    protocol: acc.mechanism,
+    mechanisms: [acc.mechanism],
+    count: [...acc.refs.values()].reduce((n, steps) => n + steps.length, 0),
+    trailRefs: [...acc.refs.entries()].map(([trailId, stepIndices]) => ({
+      trailId,
+      stepIndices,
+    })),
+  }));
+})();
+
+// No `componentOf`: the constructs nest directly under their container.
+const constructGraphByContainer = new Map<string, C4ConstructGraph>();
+for (const draft of containers) {
+  const members = membersByElement.get(draft.element.id) ?? [];
+  constructGraphByContainer.set(draft.element.id, {
+    components: members
+      .map((alias) => byAlias.get(alias))
+      .filter((c): c is NonNullable<typeof c> => Boolean(c)),
+    trails: DRILLDOWN_TRAILS,
+  });
+}
+
+const allContainerIds = containers.map((d) => d.element.id);
+
+function Demo() {
+  const [openIds, setOpenIds] = useState<string[]>(allContainerIds);
+
+  const model = useMemo<C4Model>(
+    () => ({
+      view: 'container',
+      system: SYSTEM,
+      nodes: elements,
+      edges,
+      openContainerIds: openIds,
+    }),
+    [openIds],
+  );
+
+  const toggle = (id: string) =>
+    setOpenIds((prev) =>
+      prev.includes(id) ? prev.filter((x) => x !== id) : [...prev, id].sort(),
+    );
+
+  return (
+    <div style={{ width: '100%', height: '100vh', display: 'flex', flexDirection: 'column' }}>
+      <div
+        style={{
+          display: 'flex',
+          alignItems: 'center',
+          gap: 16,
+          padding: '7px 12px',
+          borderBottom: '1px solid #333',
+          background: '#1b1b1b',
+          color: '#aaa',
+          fontFamily: 'ui-monospace, monospace',
+          fontSize: 12,
+        }}
+      >
+        <strong style={{ color: '#e3b341' }}>DRAFT</strong>
+        <span>
+          no accepted containers — {containers.length} derived from process keys,{' '}
+          {externals.length} externals, {edges.length} lines
+        </span>
+        <span style={{ marginLeft: 'auto', display: 'flex', gap: 6 }}>
+          <button type="button" onClick={() => setOpenIds(allContainerIds)}>
+            Open all
+          </button>
+          <button type="button" onClick={() => setOpenIds([])}>
+            Collapse all
+          </button>
+        </span>
+      </div>
+      <div style={{ flex: 1, minHeight: 0, position: 'relative' }}>
+        <C4Graph
+          model={model}
+          onToggleContainer={toggle}
+          constructGraphByContainer={constructGraphByContainer}
+        />
+      </div>
+    </div>
+  );
+}
+
+export const DraftFromProcessKeys: Story = {
+  render: () => <Demo />,
+};

package/src/stories/Canvases/Subsystem/TrailSidebarViews.stories.tsx

@@ -13,11 +13,11 @@ const components: SubsystemComponent[] = [
   { alias: 'mail', name: 'Mail', construct: 'function', file: 'src/mail.ts', purl: 'pkg:github/acme/app' },
 ];
 const trails: SubsystemTrail[] = [
-  { id: 'checkout', title: 'Save checkout', steps: [
+  { id: 'checkout', title: 'Validate the checkout and persist the customer’s order with all selected items', steps: [
     { from: 'checkout', to: 'store', mechanism: 'calls', file: 'src/checkout.ts',
       purl: 'pkg:github/acme/app', symbol: 'saveCheckout', annotation: 'Persist the checkout.' },
   ] },
-  { id: 'report', title: 'Send report', steps: [
+  { id: 'report', title: 'Generate the monthly account activity report and deliver it to every subscribed recipient', steps: [
     { from: 'report', to: 'mail', mechanism: 'calls', file: 'src/report.ts',
       purl: 'pkg:github/acme/app', symbol: 'sendReport' },
   ] },

package/src/subsystem/C4Graph.tsx

@@ -1383,10 +1383,16 @@ function Inner({ model, onSelectNode, onSelectEdge, onTrailClick, onToggleContai
           element: n,
           selected: false,
           componentCount: childComponentCount.get(n.id) ?? 0,
-          // A container with components opens; the same affordance closes it
-          // again, so the toggle lives in one place.
-          ...(n.kind === 'container' && (childComponentCount.get(n.id) ?? 0) > 0 && canToggle
-            ? { onExpand: () => toggle(n.id), open: opened.has(n.id) }
+          // A container with components — or with constructs hosted from the
+          // model, when no C4 component layer exists — opens; the same
+          // affordance closes it again, so the toggle lives in one place.
+          ...(n.kind === 'container' &&
+          ((childComponentCount.get(n.id) ?? 0) > 0 ||
+            (constructGraphByContainer?.get(n.id)?.components.length ?? 0) > 0)
+            ? {
+                ...(canToggle ? { onExpand: () => toggle(n.id) } : {}),
+                open: opened.has(n.id),
+              }
             : {}),
           // A component grown to hold its constructs is a drawn-as-card group:
           // no description, absolute box, sized by ELK.

package/src/subsystem/DescriptionOverlay.test.tsx

@@ -0,0 +1,76 @@
+import { afterEach, describe, expect, test } from 'bun:test';
+import { createElement } from 'react';
+import { Window } from 'happy-dom';
+import { cleanup, fireEvent, render } from '@testing-library/react/pure';
+import { ThemeProvider, defaultEditorTheme } from '@principal-ade/industry-theme';
+import { SubsystemComponentGraph } from './SubsystemComponentGraph';
+
+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.SVGElement = dom.SVGElement;
+globals.Node = dom.Node;
+globals.Element = dom.Element;
+globals.Event = dom.Event;
+globals.localStorage = dom.localStorage;
+globals.ResizeObserver = dom.ResizeObserver;
+globals.getComputedStyle = dom.getComputedStyle.bind(dom);
+globals.requestAnimationFrame = dom.requestAnimationFrame.bind(dom);
+globals.cancelAnimationFrame = dom.cancelAnimationFrame.bind(dom);
+globals.matchMedia = dom.matchMedia.bind(dom);
+
+afterEach(cleanup);
+
+function renderGraph(description: string | undefined) {
+  return render(createElement(
+    ThemeProvider,
+    { theme: defaultEditorTheme },
+    createElement(SubsystemComponentGraph, {
+      components: [
+        { alias: 'entry', name: 'Entry', construct: 'function', file: 'entry.ts' },
+        { alias: 'store', name: 'Store', construct: 'function', file: 'store.ts' },
+      ],
+      trails: [{
+        id: 'request',
+        title: 'Request flow',
+        steps: [{ from: 'entry', to: 'store', mechanism: 'calls' }],
+      }],
+      description,
+    }),
+  ));
+}
+
+describe('subsystem description overlay', () => {
+  for (const closeWithEscape of [false, true]) {
+    test(`More opens the full markdown over the graph and closes with ${closeWithEscape ? 'Escape' : 'the close button'}`, () => {
+      const description = `${'A long description. '.repeat(50)}\n\n**Final detail**`;
+      const view = renderGraph(description);
+      const more = view.getByRole('button', { name: 'Read full description' });
+      more.focus();
+      fireEvent.click(more);
+      const overlay = view.getByRole('dialog', { name: 'Subsystem description' });
+      expect(overlay.textContent).toContain('A long description. '.repeat(50).trim());
+      expect(overlay.querySelector('strong')?.textContent).toBe('Final detail');
+      expect(overlay.style.position).toBe('absolute');
+      expect(overlay.parentElement?.contains(view.getByLabelText('Resize sidebar'))).toBe(false);
+      expect(more.getAttribute('aria-expanded')).toBe('true');
+      const close = view.getByRole('button', { name: 'Close description' });
+      expect(document.activeElement).toBe(close);
+      if (closeWithEscape) fireEvent.keyDown(close, { key: 'Escape' });
+      else fireEvent.click(close);
+      expect(view.queryByRole('dialog')).toBeNull();
+      expect(more.getAttribute('aria-expanded')).toBe('false');
+      expect(document.activeElement).toBe(more);
+      expect(view.getByText('Request flow')).toBeTruthy();
+    });
+  }
+
+  test('does not offer More when there is no description', () => {
+    const view = renderGraph(undefined);
+    expect(view.queryByRole('button', { name: 'Read full description' })).toBeNull();
+    expect(view.queryByRole('dialog')).toBeNull();
+  });
+});

package/src/subsystem/DescriptionOverlay.tsx

@@ -0,0 +1,101 @@
+import { useEffect, useRef } from 'react';
+import { useTheme } from '@principal-ade/industry-theme';
+import { X } from 'lucide-react';
+import { IndustryMarkdownSlide } from 'themed-markdown';
+
+export function DescriptionOverlay({ description, onClose }: {
+  description: string;
+  onClose: () => void;
+}) {
+  const { theme } = useTheme();
+  const closeRef = useRef<HTMLButtonElement>(null);
+
+  useEffect(() => {
+    const previousFocus = document.activeElement;
+    closeRef.current?.focus();
+    return () => {
+      if (previousFocus instanceof HTMLElement && previousFocus.isConnected) previousFocus.focus();
+    };
+  }, []);
+
+  return (
+    <div
+      role="dialog"
+      aria-label="Subsystem description"
+      onKeyDown={(event) => {
+        if (event.key === 'Escape') {
+          event.stopPropagation();
+          onClose();
+        }
+      }}
+      style={{
+        position: 'absolute',
+        inset: 0,
+        zIndex: 10,
+        display: 'flex',
+        flexDirection: 'column',
+        background: theme.colors.background,
+        color: theme.colors.text,
+      }}
+    >
+      <div style={{
+        display: 'flex',
+        alignItems: 'center',
+        gap: 8,
+        flexShrink: 0,
+        padding: '12px 16px',
+        borderBottom: `1px solid ${theme.colors.border}`,
+      }}>
+        <h3 style={{
+          flex: 1,
+          margin: 0,
+          fontSize: theme.fontSizes[1],
+          fontFamily: theme.fonts.monospace,
+          textTransform: 'uppercase',
+          color: theme.colors.textSecondary,
+        }}>
+          Overview
+        </h3>
+        <button
+          ref={closeRef}
+          type="button"
+          aria-label="Close description"
+          onClick={onClose}
+          style={{
+            display: 'inline-flex',
+            alignItems: 'center',
+            justifyContent: 'center',
+            width: 24,
+            height: 24,
+            padding: 0,
+            border: 'none',
+            borderRadius: 4,
+            background: 'transparent',
+            color: theme.colors.textSecondary,
+            cursor: 'pointer',
+          }}
+        >
+          <X size={14} />
+        </button>
+      </div>
+      <div style={{ flex: 1, minHeight: 0, overflow: 'auto', padding: '20px 0 32px' }}>
+        <div style={{ lineHeight: 1.7 }}>
+          <IndustryMarkdownSlide
+            content={description}
+            slideIdPrefix="subsystem-desc-overlay"
+            slideIndex={0}
+            isVisible
+            theme={theme}
+            disableScroll
+            disableBasePadding
+            transparentBackground
+            additionalPadding={{ left: '24px', right: '24px' }}
+            fontSizeScale={1.05}
+            enableKeyboardScrolling={false}
+            autoFocusOnVisible={false}
+          />
+        </div>
+      </div>
+    </div>
+  );
+}

package/src/subsystem/DiagnosticToggle.tsx

@@ -155,7 +155,7 @@ export function SubsystemDiagnosticToggle({
           justifyContent: bordered || segmented ? 'center' : undefined,
           gap: 4,
           height: bordered || segmented ? 28 : 22,
-          padding: bordered || segmented ? '4px 7px' : showCount ? '0 7px 0 6px' : '0 5px',
+          padding: segmented ? '4px 16px' : bordered ? '4px 7px' : showCount ? '0 7px 0 6px' : '0 5px',
           border: bordered ? `1px solid ${theme.colors.border}` : 'none',
           borderRadius: 4,
           background,
@@ -227,6 +227,7 @@ export function SubsystemDiagnosticToggle({
               fontFamily: theme.fonts.monospace,
               fontSize: theme.fontSizes[0],
               fontWeight: 600,
+              marginLeft: segmented && labelText ? 4 : undefined,
               lineHeight: 1,
             }}
           >

package/src/subsystem/SubsystemComponentGraph.sidebar.test.tsx

@@ -50,12 +50,19 @@ describe('subsystem graph sidebar', () => {
     expect(content?.textContent).not.toContain('Request subsystem');
   });
 
-  test('caps the scrollable description at 30% above the trails', () => {
+  test('truncates the description without scrolling and offers the full description', () => {
     const body = renderGraph();
-    const description = body.querySelector('[style*="max-height:30%"]') as HTMLElement;
+    const description = body.querySelector('[style*="-webkit-line-clamp:6"]') as HTMLElement;
     expect(description).not.toBeNull();
     expect(description.textContent).toContain('Always visible description.');
-    expect(description.style.overflowY).toBe('auto');
+    expect(description.style.overflow).toBe('hidden');
+    expect(description.style.maxHeight).toBe('9em');
+    const more = body.querySelector('button[aria-label="Read full description"]');
+    expect(more?.textContent).toBe('More');
+    expect(more?.getAttribute('aria-haspopup')).toBe('dialog');
+    expect(more?.getAttribute('aria-expanded')).toBe('false');
+    expect(body.querySelector('[role="dialog"]')).toBeNull();
+    expect(body.querySelector('[style*="max-height:30%"]')).toBeNull();
   });
 
   test('keeps the Files button in the header when no name is provided', () => {
@@ -73,16 +80,51 @@ describe('subsystem graph sidebar', () => {
   });
 
   test('groups Trails, Files, and Issues into one switch with Trails selected by default', () => {
-    const body = renderGraph();
+    const body = renderGraph({ diagnostic: { status: 'issues', issueCount: 1 } });
     const group = body.querySelector('header [role="group"][aria-label="Sidebar view"]');
     expect(group?.querySelectorAll('button').length).toBe(3);
     expect(group?.querySelectorAll('button[aria-pressed="true"]').length).toBe(1);
-    expect(group?.querySelector('button[aria-label="Trails"]')?.getAttribute('aria-pressed')).toBe('true');
-    expect(group?.querySelector('button[aria-label="Trails"]')?.textContent).toBe('Trails');
-    expect(group?.querySelector('button[aria-label^="Issues:"]')?.textContent).toBe('Issues');
+    expect(group?.querySelector('button[aria-label^="Trails"]')?.getAttribute('aria-pressed')).toBe('true');
+    expect(group?.querySelector('button[aria-label^="Trails"]')?.textContent).toBe('Trails1');
+    expect(group?.querySelector('button[aria-label^="Issues:"]')?.textContent).toBe('Issues1');
     expect((group as HTMLElement).style.borderStyle).toBe('solid');
+    expect((group as HTMLElement).style.gridAutoColumns).toBe('1fr');
+    for (const button of group!.querySelectorAll('button')) {
+      expect((button as HTMLElement).style.paddingLeft).toBe('16px');
+      expect((button as HTMLElement).style.paddingRight).toBe('16px');
+      expect((button.lastElementChild as HTMLElement).style.marginLeft).toBe('4px');
+    }
   });
 
+  for (const count of [0, 1, 3]) {
+    test(`shows ${count} in the plural Trails option`, () => {
+      const body = renderGraph({
+        trails: Array.from({ length: count }, (_, index) => ({ ...trails![0], id: `trail-${index}` })),
+        graphifyRelations,
+      });
+      const button = body.querySelector('header button[aria-label^="Trails"]');
+      expect(button?.textContent).toBe(`Trails${count}`);
+      expect(button?.getAttribute('aria-label')).toBe(`Trails (${count} ${count === 1 ? 'trail' : 'trails'})`);
+    });
+  }
+
+  for (const props of [
+    {},
+    { diagnostic: { status: 'ok' as const, issueCount: 0 } },
+    { issues: [], diagnostic: { status: 'issues' as const, issueCount: 3 } },
+    { issues: [], showIssues: true },
+  ]) {
+    test(`hides Issues and keeps Trails active for an empty scope: ${JSON.stringify(props)}`, () => {
+      const body = renderGraph(props);
+      const group = body.querySelector('header [aria-label="Sidebar view"]');
+      expect(group?.querySelectorAll('button').length).toBe(2);
+      expect(group?.querySelector('button[aria-label^="Issues:"]')).toBeNull();
+      expect(group?.querySelector('button[aria-label^="Trails"]')?.getAttribute('aria-pressed')).toBe('true');
+      expect(body.textContent).toContain('Request flow');
+      expect((group as HTMLElement).style.gridAutoColumns).toBe('1fr');
+    });
+  }
+
   test('omits the Files button when no components have files', () => {
     const body = renderGraph({
       components: components.map((component) => ({ ...component, file: '' })),
@@ -111,7 +153,7 @@ describe('subsystem graph sidebar', () => {
       expect(toggle?.getAttribute('aria-pressed')).toBe(String(active));
       expect(header?.querySelectorAll('button').length).toBe(3);
       expect(header?.querySelectorAll('button[aria-pressed="true"]').length).toBe(1);
-      expect(header?.querySelector('button[aria-label="Trails"]')?.getAttribute('aria-pressed')).toBe(String(!active));
+      expect(header?.querySelector('button[aria-label^="Trails"]')?.getAttribute('aria-pressed')).toBe(String(!active));
       expect(body.querySelectorAll('button[aria-label^="Issues:"]').length).toBe(1);
       expect(header?.nextElementSibling?.querySelector('button[aria-label^="Issues:"]')).toBeNull();
       expect(body.textContent).toContain('Always visible description.');
@@ -190,7 +232,7 @@ describe('subsystem graph sidebar', () => {
     try {
       const body = renderGraph({ persistKey: 'trail-nav-test' });
       expect(body.querySelector('header button[aria-label="Trail"]')?.textContent).toBe('Trail');
-      expect(body.querySelector('header button[aria-label="Trails"]')).toBeNull();
+      expect(body.querySelector('header button[aria-label^="Trails"]')).toBeNull();
       expect(body.querySelector('[aria-hidden="false"] button[aria-label="Back to trails"]')).not.toBeNull();
       expect(body.querySelector('button[aria-label^="Play "]')).toBeNull();
       expect(body.querySelector('button[aria-label^="Focus layout"]')).toBeNull();
@@ -234,6 +276,32 @@ describe('subsystem graph sidebar', () => {
     }
   });
 
+  test('hides Issues for a selected trail with no findings even when other trails have issues', () => {
+    const previousWindow = globalThis.window;
+    const dom = new Window();
+    dom.localStorage.setItem('principal.subsystems.viewState.empty-trail-issues-test', JSON.stringify({
+      sidebarTrailId: 'request',
+    }));
+    globalThis.window = dom as unknown as typeof window;
+    try {
+      const body = renderGraph({
+        persistKey: 'empty-trail-issues-test',
+        showIssues: true,
+        issues: [{
+          id: 'unrelated', severity: 'error', kind: 'missing_file', message: 'Unrelated finding',
+          target: { kind: 'component', id: 'other', label: 'Other' },
+        }],
+        diagnostic: { status: 'issues', issueCount: 1 },
+      });
+      expect(body.querySelector('header button[aria-label^="Issues:"]')).toBeNull();
+      expect(body.querySelector('header button[aria-label="Trail"]')?.getAttribute('aria-pressed')).toBe('true');
+      expect(body.querySelector('[aria-hidden="false"] button[aria-label="Back to trails"]')).not.toBeNull();
+      expect(body.querySelector('[aria-hidden="false"]')?.textContent).toContain('Entry');
+    } finally {
+      globalThis.window = previousWindow;
+    }
+  });
+
   test('static graphs keep their description but do not show a file panel', () => {
     const body = renderGraph({ trails: undefined, graphifyRelations });
     expect(body.textContent).toContain('Always visible description.');
@@ -254,7 +322,10 @@ describe('subsystem graph sidebar', () => {
   });
 
   test('the description stays visible while diagnostics replace the trails', () => {
-    const body = renderGraph({ showIssues: true, issues: [] });
+    const body = renderGraph({ showIssues: true, issues: [{
+      id: 'related', severity: 'error', kind: 'missing_file', message: 'Related finding',
+      target: { kind: 'component', id: 'entry', label: 'Entry' },
+    }] });
     expect(body.textContent).toContain('Always visible description.');
     expect(body.textContent).not.toContain('Request flow');
     expect(body.querySelector('[aria-label="Resize sidebar"]')).not.toBeNull();