@principal-ai/subsystems-react 0.28.4 → 0.28.6

package/src/pierre/PierreWalkthroughCodeView.tsx

@@ -33,11 +33,15 @@ type CodeViewLineSelection = {
 /** Metadata carried on a walkthrough step's line annotation. */
 type WalkthroughStepAnnotation = { text: string };
 import { useTheme } from '@principal-ade/industry-theme';
-import type { SubsystemWalkthrough } from '../subsystem/model';
+import type {
+  SubsystemWalkthrough,
+  SubsystemWalkthroughStep,
+} from '../subsystem/model';
 import type { SubsystemOpenFileOptions } from '../subsystem/declarationRef';
 import { buildPierreOptions, PIERRE_FILE_STYLE } from './pierreBackground';
 import { pierreLangForPath } from './pierreFileLang';
 import { resolvePierreSyntaxThemeName } from './pierreSyntaxTheme';
+import { fileUnavailableNotice, isFileUnavailableError } from './fileAvailability';
 import {
   remapSnippetLineNumbers,
   sliceSnippetWindow,
@@ -56,17 +60,52 @@ export interface PierreWalkthroughCodeViewProps {
   background?: string;
   /** Open the step's full source file (header button or double-click snippet body). */
   onOpenFile?: (path: string, opts?: SubsystemOpenFileOptions) => void;
+  /**
+   * Aliases of components marked `proposed`. A step whose file can't be read
+   * but whose endpoint is proposed reads as "planned" rather than "missing".
+   */
+  proposedAliases?: ReadonlySet<string>;
 }
 
 type FileLoadState =
   | { status: 'loading' }
-  | { status: 'error'; message: string }
-  | { status: 'ready'; byPath: Map<string, string> };
+  | {
+      status: 'ready';
+      byPath: Map<string, string>;
+      /** Paths the host couldn't serve, keyed like `byPath`, with the reason. */
+      unavailable: Map<string, string>;
+    };
 
 function stepItemId(walkthroughId: string, index: number): string {
   return `${walkthroughId}:${index}`;
 }
 
+/** Stable key for a step's file within a repo (mirrors `pathsKey`). */
+function siteKey(step: Pick<SubsystemWalkthroughStep, 'purl' | 'file'>): string {
+  return `${step.purl}\0${step.file}`;
+}
+
+/** Notice shown in place of a snippet whose file the host couldn't read. */
+function unavailableNotice(
+  step: SubsystemWalkthroughStep,
+  error: string,
+  proposed: boolean,
+): string {
+  return isFileUnavailableError(error)
+    ? fileUnavailableNotice(step.file, proposed)
+    : `Couldn't load ${step.file}: ${error}`;
+}
+
+/** A single-line placeholder snippet standing in for an unreadable file. */
+function unavailableSlice(notice: string): SnippetSlice {
+  return {
+    contents: `// ${notice}`,
+    sliceStart: 1,
+    sliceEnd: 1,
+    focusOffset: 1,
+  };
+}
+
 function OpenFileHeaderButton({
   file,
   line,
@@ -117,38 +156,58 @@ export function PierreWalkthroughCodeView({
   contextLines = 8,
   background,
   onOpenFile,
+  proposedAliases,
 }: PierreWalkthroughCodeViewProps) {
   const { theme, mode } = useTheme();
   const viewRef = useRef<CodeViewHandle<undefined>>(null);
   const [load, setLoad] = useState<FileLoadState>({ status: 'loading' });
 
+  // A hop onto a proposed component is planned work; label its missing file
+  // accordingly instead of showing a bare "not found".
+  const isProposedStep = useCallback(
+    (step: SubsystemWalkthroughStep): boolean =>
+      proposedAliases != null &&
+      (proposedAliases.has(step.from) || proposedAliases.has(step.to)),
+    [proposedAliases],
+  );
+
   const pathsKey = useMemo(() => {
-    const keys = [...new Set(walkthrough.steps.map((s) => `${s.purl}\0${s.file}`))];
+    const keys = [...new Set(walkthrough.steps.map((s) => siteKey(s)))];
     keys.sort();
     return keys.join('\0');
   }, [walkthrough.steps]);
 
+  // Load each site independently: one unreadable step (a proposed seam whose
+  // file isn't implemented yet) must not blank the whole walkthrough. Failures
+  // are kept per-path and rendered as inline placeholders below.
   useEffect(() => {
     let cancelled = false;
     setLoad({ status: 'loading' });
-    const sites = [...new Map(walkthrough.steps.map((s) => [`${s.purl}\0${s.file}`, s])).values()];
+    const sites = [...new Map(walkthrough.steps.map((s) => [siteKey(s), s])).values()];
     void Promise.all(
       sites.map(async (step) => {
-        const contents = await readFile(step.file, step.purl);
-        return [`${step.purl}\0${step.file}`, contents] as const;
+        const key = siteKey(step);
+        try {
+          const contents = await readFile(step.file, step.purl);
+          return { key, contents, error: null as string | null };
+        } catch (err) {
+          return {
+            key,
+            contents: null,
+            error: err instanceof Error ? err.message : 'Failed to read file',
+          };
+        }
       }),
-    )
-      .then((entries) => {
-        if (cancelled) return;
-        setLoad({ status: 'ready', byPath: new Map(entries) });
-      })
-      .catch((err) => {
-        if (cancelled) return;
-        setLoad({
-          status: 'error',
-          message: err instanceof Error ? err.message : 'Failed to read files',
-        });
-      });
+    ).then((results) => {
+      if (cancelled) return;
+      const byPath = new Map<string, string>();
+      const unavailable = new Map<string, string>();
+      for (const row of results) {
+        if (row.contents != null) byPath.set(row.key, row.contents);
+        else unavailable.set(row.key, row.error ?? 'Failed to read file');
+      }
+      setLoad({ status: 'ready', byPath, unavailable });
+    });
     return () => {
       cancelled = true;
     };
@@ -157,7 +216,14 @@ export function PierreWalkthroughCodeView({
   const slices = useMemo((): SnippetSlice[] => {
     if (load.status !== 'ready') return [];
     return walkthrough.steps.map((step) => {
-      const contents = load.byPath.get(`${step.purl}\0${step.file}`) ?? '';
+      const key = siteKey(step);
+      const failure = load.unavailable.get(key);
+      if (failure != null) {
+        return unavailableSlice(
+          unavailableNotice(step, failure, isProposedStep(step)),
+        );
+      }
+      const contents = load.byPath.get(key) ?? '';
       return sliceSnippetWindow(
         contents,
         step.line,
@@ -166,17 +232,24 @@ export function PierreWalkthroughCodeView({
         step.line,
       );
     });
-  }, [load, walkthrough.steps, contextLines]);
+  }, [load, walkthrough.steps, contextLines, isProposedStep]);
 
-const items = useMemo((): CodeViewItem<WalkthroughStepAnnotation>[] => {
+  const items = useMemo((): CodeViewItem<WalkthroughStepAnnotation>[] => {
     if (load.status !== 'ready' || slices.length === 0) return [];
     return walkthrough.steps.map((step, index) => {
       const slice = slices[index]!;
       const focus = slice.focusOffset;
+      const key = siteKey(step);
+      const failure = load.unavailable.get(key);
+      // The placeholder line already carries the reason, so it replaces any
+      // authored annotation rather than stacking with it.
       const annotations:
         | LineAnnotation<WalkthroughStepAnnotation>[]
         | undefined =
-        step.annotation != null && step.annotation.length > 0 && focus != null
+        failure == null &&
+        step.annotation != null &&
+        step.annotation.length > 0 &&
+        focus != null
           ? [
               {
                 lineNumber: focus,
@@ -193,11 +266,11 @@ const items = useMemo((): CodeViewItem<WalkthroughStepAnnotation>[] => {
           name: step.file,
           contents: slice.contents,
           lang: pierreLangForPath(step.file),
-          cacheKey: `${walkthrough.id}:${index}:${step.file}:${step.line}:${slice.sliceStart}-${slice.sliceEnd}`,
+          cacheKey: `${walkthrough.id}:${index}:${step.file}:${step.line}:${slice.sliceStart}-${slice.sliceEnd}${failure != null ? ':unavailable' : ''}`,
         },
       };
     });
-  }, [load, slices, walkthrough.id, walkthrough.steps]);
+  }, [load, slices, walkthrough.id, walkthrough.steps, isProposedStep]);
 
   const selectedLines = useMemo((): CodeViewLineSelection | null => {
     if (stepIndex == null || stepIndex < 0 || stepIndex >= slices.length) {
@@ -259,6 +332,10 @@ const items = useMemo((): CodeViewItem<WalkthroughStepAnnotation>[] => {
       const index = Number.parseInt(item.id.split(':').pop() ?? '', 10);
       const step = walkthrough.steps[index];
       if (!step) return null;
+      // Unreadable sites have nothing to open — say so instead of offering a
+      // button that would only fail again in the full-file overlay.
+      const unavailable =
+        load.status === 'ready' && load.unavailable.has(siteKey(step));
       return (
         <span
           style={{
@@ -271,18 +348,26 @@ const items = useMemo((): CodeViewItem<WalkthroughStepAnnotation>[] => {
             color: theme.colors.textSecondary,
           }}
         >
-          L{step.line}
-          {onOpenFile && (
-            <OpenFileHeaderButton
-              file={step.file}
-              line={step.line}
-              onOpenFile={onOpenFile}
-            />
+          {unavailable ? (
+            <span title="This file isn't in the local checkout">
+              not in checkout
+            </span>
+          ) : (
+            <>
+              L{step.line}
+              {onOpenFile && (
+                <OpenFileHeaderButton
+                  file={step.file}
+                  line={step.line}
+                  onOpenFile={onOpenFile}
+                />
+              )}
+            </>
           )}
         </span>
       );
     };
-  }, [walkthrough.steps, theme, onOpenFile]);
+  }, [walkthrough.steps, theme, onOpenFile, load]);
 
   const renderAnnotation = useMemo(() => {
     return (
@@ -324,9 +409,10 @@ const items = useMemo((): CodeViewItem<WalkthroughStepAnnotation>[] => {
       const index = Number.parseInt(id.split(':').pop() ?? '', 10);
       const step = walkthrough.steps[index];
       if (!step) return;
+      if (load.status === 'ready' && load.unavailable.has(siteKey(step))) return;
       onOpenFile(step.file, { startLine: step.line, fullFile: true });
     },
-    [onOpenFile, walkthrough.steps],
+    [onOpenFile, walkthrough.steps, load],
   );
 
   const options = useMemo((): CodeViewReactOptions => {
@@ -369,17 +455,17 @@ const items = useMemo((): CodeViewItem<WalkthroughStepAnnotation>[] => {
     items.length,
   ]);
 
-  if (load.status === 'error') {
+  if (load.status === 'loading') {
     return (
-      <div style={{ padding: 16, color: theme.colors.error ?? '#e5534b' }}>
-        {load.message}
+      <div style={{ padding: 16, color: theme.colors.textSecondary }}>
+        Loading…
       </div>
     );
   }
-  if (load.status === 'loading' || items.length === 0) {
+  if (items.length === 0) {
     return (
       <div style={{ padding: 16, color: theme.colors.textSecondary }}>
-        Loading…
+        No steps in this walkthrough.
       </div>
     );
   }

package/src/pierre/fileAvailability.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, test } from 'bun:test';
+import { fileUnavailableNotice, isFileUnavailableError } from './fileAvailability';
+
+describe('isFileUnavailableError', () => {
+  test('matches the host "no local checkout" family', () => {
+    expect(
+      isFileUnavailableError(
+        'file not found in graph repos: packages/subsystems-studio/src/bun/subsystem-model-runs.ts',
+      ),
+    ).toBe(true);
+    expect(isFileUnavailableError('graph has no local root for this file')).toBe(
+      true,
+    );
+    expect(isFileUnavailableError('no local checkout for this repo')).toBe(true);
+  });
+
+  test('leaves genuine I/O errors alone', () => {
+    expect(isFileUnavailableError('EACCES: permission denied')).toBe(false);
+    expect(isFileUnavailableError('')).toBe(false);
+    expect(isFileUnavailableError(null)).toBe(false);
+    expect(isFileUnavailableError(undefined)).toBe(false);
+  });
+});
+
+describe('fileUnavailableNotice', () => {
+  test('names proposed work as planned, not missing', () => {
+    expect(
+      fileUnavailableNotice('src/a.ts', true),
+    ).toBe("Proposed — src/a.ts isn't in the local checkout yet.");
+  });
+
+  test('falls back to a plain not-in-checkout notice', () => {
+    expect(fileUnavailableNotice('src/a.ts')).toBe(
+      'Not in the local checkout: src/a.ts',
+    );
+    expect(fileUnavailableNotice('src/a.ts', false)).toBe(
+      'Not in the local checkout: src/a.ts',
+    );
+  });
+});

package/src/pierre/fileAvailability.ts

@@ -0,0 +1,37 @@
+/**
+ * Host file reads fail with a small, stable set of messages when a path can't
+ * be served from any local checkout — most often a *proposed* seam whose file
+ * isn't implemented yet. These helpers detect that class of failure so the
+ * Pierre views can show a proposed / not-yet-available notice instead of a raw
+ * host error.
+ */
+
+/** Substrings the host uses when a read can't resolve to a local file. */
+const UNAVAILABLE_FRAGMENTS = [
+  'not found in graph repos',
+  'graph has no local root',
+  'no local checkout',
+] as const;
+
+/** True when a read failed because the file has no local checkout, not because
+ *  of an I/O or permission error. */
+export function isFileUnavailableError(
+  message: string | null | undefined,
+): boolean {
+  if (!message) return false;
+  return UNAVAILABLE_FRAGMENTS.some((fragment) => message.includes(fragment));
+}
+
+/**
+ * One-line notice shown in place of a snippet whose file can't be read. When
+ * the step touches a proposed component the wording names that, so a proposed
+ * seam reads as "planned" rather than "missing".
+ */
+export function fileUnavailableNotice(
+  path: string,
+  proposed?: boolean,
+): string {
+  return proposed
+    ? `Proposed — ${path} isn't in the local checkout yet.`
+    : `Not in the local checkout: ${path}`;
+}

package/src/stories/Subsystem/ComponentGraph/Flows.stories.tsx

@@ -54,7 +54,11 @@ const storyFiles: Record<string, string> = {
 function readStoryFile(path: string): Promise<string> {
   const content = storyFiles[path];
   if (content == null) {
-    return Promise.reject(new Error(`No story fixture for ${path}`));
+    // Mirror the host's wording so the Pierre views exercise their
+    // "not in the local checkout" handling, not just any rejection.
+    return Promise.reject(
+      new Error(`file not found in graph repos: ${path}`),
+    );
   }
   return Promise.resolve(content);
 }
@@ -122,50 +126,59 @@ const drawingComponents: SubsystemComponent[] = [
   },
 ];
 
+const STORY_PURL = 'pkg:github/principal-ai/desktop-app';
+const stepPurl = (file: string) => `${STORY_PURL}#${file}`;
+
 const drawingWalkthroughs: SubsystemWalkthrough[] = [
   {
     id: 'tl-open-drawing',
     title: 'Open drawing',
     steps: [
-      { from: 'panel', to: 'storage', mechanism: 'calls', file: 'src/panels/DrawingsLeftPanel.tsx', line: 56, symbol: 'DrawingsLeftPanel.scan', annotation: 'Lists the drawings directory; each row feeds an open intent.' },
-      { from: 'panel', to: 'host', mechanism: 'produces', file: 'src/panels/DrawingsLeftPanel.tsx', line: 85, symbol: 'DrawingsLeftPanel.openDrawing', annotation: 'Emits the open intent up to the host.' },
-      { from: 'host', to: 'storage', mechanism: 'calls', file: 'src/hooks/useDrawingsHost.ts', line: 45, symbol: 'useDrawingsHost.openDrawing', annotation: 'Host resolves the path and delegates to storage.' },
-      { from: 'host', to: 'shell', mechanism: 'produces', file: 'src/workspace/WorkspaceShell.tsx', line: 369, symbol: 'WorkspaceShell.openTab', annotation: 'Asks the shell to surface the drawing as a tab.' },
-      { from: 'shell', to: 'tab', mechanism: 'feeds', file: 'src/workspace/WorkspaceShell.tsx', line: 372, symbol: 'WorkspaceShell.mountTab' },
-      { from: 'storage', to: 'fs', mechanism: 'calls', file: 'src/storage/drawingsStorage.ts', line: 90, symbol: 'DrawingsStorage.read', annotation: 'Reads the file through the sandboxed fs service.' },
-      { from: 'tab', to: 'fs', mechanism: 'calls', file: 'src/components/DrawingTabContent.tsx', line: 83, symbol: 'DrawingTabContent.load' },
+      { from: 'panel', to: 'storage', mechanism: 'calls', file: 'src/panels/DrawingsLeftPanel.tsx', line: 56, purl: stepPurl('src/panels/DrawingsLeftPanel.tsx'), symbol: 'DrawingsLeftPanel.scan', annotation: 'Lists the drawings directory; each row feeds an open intent.' },
+      { from: 'panel', to: 'host', mechanism: 'produces', file: 'src/panels/DrawingsLeftPanel.tsx', line: 85, purl: stepPurl('src/panels/DrawingsLeftPanel.tsx'), symbol: 'DrawingsLeftPanel.openDrawing', annotation: 'Emits the open intent up to the host.' },
+      { from: 'host', to: 'storage', mechanism: 'calls', file: 'src/hooks/useDrawingsHost.ts', line: 45, purl: stepPurl('src/hooks/useDrawingsHost.ts'), symbol: 'useDrawingsHost.openDrawing', annotation: 'Host resolves the path and delegates to storage.' },
+      { from: 'host', to: 'shell', mechanism: 'produces', file: 'src/workspace/WorkspaceShell.tsx', line: 369, purl: stepPurl('src/workspace/WorkspaceShell.tsx'), symbol: 'WorkspaceShell.openTab', annotation: 'Asks the shell to surface the drawing as a tab.' },
+      { from: 'shell', to: 'tab', mechanism: 'feeds', file: 'src/workspace/WorkspaceShell.tsx', line: 372, purl: stepPurl('src/workspace/WorkspaceShell.tsx'), symbol: 'WorkspaceShell.mountTab' },
+      { from: 'storage', to: 'fs', mechanism: 'calls', file: 'src/storage/drawingsStorage.ts', line: 90, purl: stepPurl('src/storage/drawingsStorage.ts'), symbol: 'DrawingsStorage.read', annotation: 'Reads the file through the sandboxed fs service.' },
+      { from: 'tab', to: 'fs', mechanism: 'calls', file: 'src/components/DrawingTabContent.tsx', line: 83, purl: stepPurl('src/components/DrawingTabContent.tsx'), symbol: 'DrawingTabContent.load' },
     ],
   },
   {
     id: 'tl-save-drawing',
     title: 'Save drawing',
     steps: [
-      { from: 'tab', to: 'fs', mechanism: 'calls', file: 'src/components/DrawingTabContent.tsx', line: 112, symbol: 'DrawingTabContent.save' },
-      { from: 'tab', to: 'host', mechanism: 'produces', file: 'src/components/DrawingTabContent.tsx', line: 121, symbol: 'DrawingTabContent.emitSaved' },
-      { from: 'host', to: 'panel', mechanism: 'produces', file: 'src/hooks/useDrawingsHost.ts', line: 64, symbol: 'useDrawingsHost.onSaved' },
-      { from: 'panel', to: 'storage', mechanism: 'calls', file: 'src/panels/DrawingsLeftPanel.tsx', line: 56, symbol: 'DrawingsLeftPanel.scan' },
+      { from: 'tab', to: 'fs', mechanism: 'calls', file: 'src/components/DrawingTabContent.tsx', line: 112, purl: stepPurl('src/components/DrawingTabContent.tsx'), symbol: 'DrawingTabContent.save' },
+      { from: 'tab', to: 'host', mechanism: 'produces', file: 'src/components/DrawingTabContent.tsx', line: 121, purl: stepPurl('src/components/DrawingTabContent.tsx'), symbol: 'DrawingTabContent.emitSaved' },
+      { from: 'host', to: 'panel', mechanism: 'produces', file: 'src/hooks/useDrawingsHost.ts', line: 64, purl: stepPurl('src/hooks/useDrawingsHost.ts'), symbol: 'useDrawingsHost.onSaved' },
+      { from: 'panel', to: 'storage', mechanism: 'calls', file: 'src/panels/DrawingsLeftPanel.tsx', line: 56, purl: stepPurl('src/panels/DrawingsLeftPanel.tsx'), symbol: 'DrawingsLeftPanel.scan' },
     ],
   },
   {
     id: 'tl-delete-drawing',
     title: 'Delete drawing',
     steps: [
-      { from: 'host', to: 'fs', mechanism: 'calls', file: 'src/hooks/useDrawingsHost.ts', line: 64, symbol: 'useDrawingsHost.deleteDrawing' },
-      { from: 'host', to: 'panel', mechanism: 'produces', file: 'src/hooks/useDrawingsHost.ts', line: 66, symbol: 'useDrawingsHost.refreshList' },
-      { from: 'panel', to: 'storage', mechanism: 'calls', file: 'src/panels/DrawingsLeftPanel.tsx', line: 56, symbol: 'DrawingsLeftPanel.scan' },
+      { from: 'host', to: 'fs', mechanism: 'calls', file: 'src/hooks/useDrawingsHost.ts', line: 64, purl: stepPurl('src/hooks/useDrawingsHost.ts'), symbol: 'useDrawingsHost.deleteDrawing' },
+      { from: 'host', to: 'panel', mechanism: 'produces', file: 'src/hooks/useDrawingsHost.ts', line: 66, purl: stepPurl('src/hooks/useDrawingsHost.ts'), symbol: 'useDrawingsHost.refreshList' },
+      { from: 'panel', to: 'storage', mechanism: 'calls', file: 'src/panels/DrawingsLeftPanel.tsx', line: 56, purl: stepPurl('src/panels/DrawingsLeftPanel.tsx'), symbol: 'DrawingsLeftPanel.scan' },
     ],
   },
 ];
 
 function FlowsDemo() {
   const renderWalkthroughViewer = useCallback(
-    ({ walkthrough, stepIndex, onOpenFile }: WalkthroughViewerContext) => (
+    ({
+      walkthrough,
+      stepIndex,
+      onOpenFile,
+      proposedAliases,
+    }: WalkthroughViewerContext) => (
       <PierreWalkthroughCodeView
         walkthrough={walkthrough}
         stepIndex={stepIndex}
         readFile={readStoryFile}
         contextLines={4}
         onOpenFile={onOpenFile}
+        proposedAliases={proposedAliases}
       />
     ),
     [],
@@ -204,3 +217,105 @@ function FlowsDemo() {
 export const ThreeFlows: Story = {
   render: () => <FlowsDemo />,
 };
+
+/**
+ * The proposed-seam failure mode: a walkthrough hop whose component is
+ * `proposed` points at a file that isn't in the checkout yet (no story
+ * fixture). The hop must render an inline "Proposed — … isn't in the local
+ * checkout yet." placeholder with no Open-file affordance, while the live hops
+ * around it still render their snippets — one bad step must not blank the flow.
+ */
+const proposedComponents: SubsystemComponent[] = [
+  ...drawingComponents,
+  {
+    alias: 'runs',
+    name: 'SubsystemModelRunStore',
+    construct: 'store',
+    file: 'src/runs/subsystemModelRuns.ts',
+    purl: 'pkg:github/principal-ai/desktop-app',
+    symbol: 'SubsystemModelRunStore',
+    purpose: 'proposed store associating maintain runs with a model',
+    proposed: true,
+    process: 'draw-host',
+  },
+];
+
+const proposedWalkthroughs: SubsystemWalkthrough[] = [
+  {
+    id: 'tl-associate-run',
+    title: 'Associate a finished run with its model (proposed)',
+    steps: [
+      {
+        from: 'host',
+        to: 'storage',
+        mechanism: 'calls',
+        file: 'src/hooks/useDrawingsHost.ts',
+        line: 45,
+        purl: stepPurl('src/hooks/useDrawingsHost.ts'),
+        symbol: 'useDrawingsHost.openDrawing',
+        annotation: 'Live hop — its snippet still renders.',
+      },
+      {
+        from: 'storage',
+        to: 'runs',
+        mechanism: 'writes',
+        file: 'src/runs/subsystemModelRuns.ts',
+        line: 1,
+        purl: stepPurl('src/runs/subsystemModelRuns.ts'),
+        symbol: 'SubsystemModelRunStore.write',
+        annotation: 'Proposed seam — the file is not in the checkout yet.',
+      },
+    ],
+  },
+];
+
+function ProposedMissingStepDemo() {
+  const renderWalkthroughViewer = useCallback(
+    ({
+      walkthrough,
+      stepIndex,
+      onOpenFile,
+      proposedAliases,
+    }: WalkthroughViewerContext) => (
+      <PierreWalkthroughCodeView
+        walkthrough={walkthrough}
+        stepIndex={stepIndex}
+        readFile={readStoryFile}
+        contextLines={4}
+        onOpenFile={onOpenFile}
+        proposedAliases={proposedAliases}
+      />
+    ),
+    [],
+  );
+
+  return (
+    <div style={{ width: '100%', height: '100vh', display: 'flex', flexDirection: 'column' }}>
+      <SubsystemComponentGraph
+        components={proposedComponents}
+        relations={[]}
+        walkthroughs={proposedWalkthroughs}
+        title="proposed seam with a missing file"
+        description="Expand **Associate a finished run with its model** and click either step. The proposed hop has no file in the checkout, so its snippet shows an inline *Proposed — … isn't in the local checkout yet.* placeholder instead of failing the whole flow."
+        renderWalkthroughViewer={renderWalkthroughViewer}
+        renderFileViewer={(file) => (
+          <div
+            style={{
+              padding: 12,
+              fontFamily: 'monospace',
+              fontSize: 12,
+              color: '#bbb',
+              whiteSpace: 'pre',
+            }}
+          >
+            {`// ${file}\n  …`}
+          </div>
+        )}
+      />
+    </div>
+  );
+}
+
+export const ProposedMissingStep: Story = {
+  render: () => <ProposedMissingStepDemo />,
+};

package/src/subsystem/IssueList.tsx

@@ -12,10 +12,16 @@
  */
 
 import { useState } from 'react';
+import type { LucideIcon } from 'lucide-react';
 import {
   ChevronDown,
   ChevronRight,
   CircleCheck,
+  Component,
+  FolderGit2,
+  Network,
+  Route,
+  Server,
   Wrench,
 } from 'lucide-react';
 import { useTheme } from '@principal-ade/industry-theme';
@@ -50,6 +56,18 @@ export const SUBSYSTEM_ISSUE_CATEGORIES: SubsystemIssueCategory[] = [
   'walkthrough',
 ];
 
+/** Per-category header icon — mirrors the Maintainer tab's lane icons. */
+export const SUBSYSTEM_ISSUE_CATEGORY_ICON: Record<
+  SubsystemIssueCategory,
+  LucideIcon
+> = {
+  repo: FolderGit2,
+  construct: Component,
+  'static-topology': Network,
+  'runtime-topology': Server,
+  walkthrough: Route,
+};
+
 export const SUBSYSTEM_ISSUE_CATEGORY_LABEL: Record<
   SubsystemIssueCategory,
   string
@@ -306,11 +324,11 @@ export function groupIssuesByCategory(
 
 function severityColor(
   severity: SubsystemIssueSeverity,
-  colors: { error: string; info: string },
-  muted: string,
+  colors: { error: string; info: string; warning: string },
 ): string {
   if (severity === 'error') return colors.error ?? '#e5534b';
-  return colors.info ?? muted;
+  // `info` severity = unconfirmed findings; amber, matching the lane icons.
+  return colors.warning ?? '#d4a017';
 }
 
 const TARGET_KIND_LABEL: Record<SubsystemIssueTargetKind, string> = {
@@ -342,7 +360,7 @@ export function SubsystemIssueCard({
   const [expanded, setExpanded] = useState(false);
   const showDetail = expanded;
   const muted = theme.colors.textMuted ?? theme.colors.textSecondary;
-  const color = severityColor(issue.severity, theme.colors, muted);
+  const color = severityColor(issue.severity, theme.colors);
   const activate = () => {
     setExpanded((v) => !v);
     onSelect?.(issue);
@@ -513,7 +531,7 @@ export function SubsystemIssueList({
         // the header, no count, no cards.
         const clean = category.count === 0;
         const accent = category.severity
-          ? severityColor(category.severity, theme.colors, muted)
+          ? severityColor(category.severity, theme.colors)
           : theme.colors.success;
         const isCollapsed = collapsed.has(category.category);
         const isHovered = hovered === category.category;
@@ -550,6 +568,20 @@ export function SubsystemIssueList({
                 fontFamily: theme.fonts.body,
               }}
             >
+              {(() => {
+                const Icon = SUBSYSTEM_ISSUE_CATEGORY_ICON[category.category];
+                if (Icon) {
+                  return (
+                    <Icon
+                      size={13}
+                      color={accent}
+                      style={{ flexShrink: 0 }}
+                      aria-hidden="true"
+                    />
+                  );
+                }
+                return null;
+              })()}
               <span
                 style={{
                   flex: 1,
@@ -573,7 +605,7 @@ export function SubsystemIssueList({
                     fontFamily: theme.fonts.monospace,
                     fontSize: theme.fontSizes[0],
                     fontWeight: 600,
-                    color: accent,
+                    color: muted,
                     flexShrink: 0,
                   }}
                 >