@principal-ai/subsystems-react 0.28.3 → 0.28.5

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/SubsystemComponentGraph.tsx

@@ -78,12 +78,59 @@ export interface WalkthroughViewerContext {
   stepIndex: number | null;
   /** Open a step's full source file over the walkthrough 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>;
 }
 
 type DrawerTarget =
   | { kind: 'file'; file: string; startLine?: number }
   | { kind: 'walkthrough'; walkthroughId: string; stepIndex: number | null };
 
+/**
+ * Per-model UI state persisted to `localStorage`, keyed by `persistKey`.
+ * Only the walkthrough working set is stored — which flows are expanded and
+ * which flow/step is selected — so tabbing away from a model and back lands
+ * you where you left off. Transient things (hover, drag, camera) are not saved.
+ */
+interface PersistedViewState {
+  expandedWalkthroughs?: string[];
+  focusedWalkthroughId?: string | null;
+  focusedStepIndex?: number | null;
+  sidebarWidth?: number;
+}
+
+const VIEW_STATE_PREFIX = 'principal.subsystems.viewState.';
+
+function readViewState(key: string | undefined): PersistedViewState {
+  if (!key || typeof window === 'undefined') return {};
+  try {
+    const raw = window.localStorage.getItem(VIEW_STATE_PREFIX + key);
+    if (!raw) return {};
+    const parsed: unknown = JSON.parse(raw);
+    return parsed && typeof parsed === 'object'
+      ? (parsed as PersistedViewState)
+      : {};
+  } catch {
+    return {};
+  }
+}
+
+function writeViewState(
+  key: string | undefined,
+  patch: PersistedViewState,
+): void {
+  if (!key || typeof window === 'undefined') return;
+  try {
+    const merged = { ...readViewState(key), ...patch };
+    window.localStorage.setItem(VIEW_STATE_PREFIX + key, JSON.stringify(merged));
+  } catch {
+    // Best-effort: private mode / quota — view state is non-critical.
+  }
+}
+
 export interface SubsystemComponentGraphProps {
   components: SubsystemComponent[];
   /** Topology relations (structural / module / type). Display edges are derived with walkthrough hops. */
@@ -232,6 +279,13 @@ export interface SubsystemComponentGraphProps {
   onVerifyComponent?: (componentAlias: string) => void;
   /** Live verification status for the selected component. */
   componentVerification?: ComponentVerificationState | null;
+  /**
+   * When set, the graph's walkthrough working set — expanded flows and the
+   * selected flow/step — is persisted to `localStorage` under this key and
+   * restored on mount. Hosts key it by the model id so each model remembers
+   * where the user left off. Omit to keep the state purely in-memory.
+   */
+  persistKey?: string;
 }
 
 const nodeTypes: NodeTypes = {
@@ -306,23 +360,28 @@ const WalkthroughDrawerContent = memo(function WalkthroughDrawerContent({
   walkthrough,
   stepIndex,
   onOpenFile,
+  proposedAliases,
 }: {
   render: (ctx: WalkthroughViewerContext) => ReactNode;
   walkthrough: SubsystemWalkthrough;
   stepIndex: number | null;
   onOpenFile: (path: string, opts?: SubsystemOpenFileOptions) => void;
+  proposedAliases: ReadonlySet<string>;
 }) {
-  return <>{render({ walkthrough, stepIndex, onOpenFile })}</>;
+  return <>{render({ walkthrough, stepIndex, onOpenFile, proposedAliases })}</>;
 });
 
 interface InnerProps extends SubsystemComponentGraphProps {
   measured: { w: number; h: number } | null;
 }
 
-function Inner({ components, relations, walkthroughs, initialWalkthroughId, onReorderWalkthroughs, onSelect, onEdgeSelect, measured: _measured, maxNodeWidth, showEdgeLabels, edgeView, title, hideSidebar, walkthroughStepMode = 'focus', autoPlayWalkthroughs = false, walkthroughAutoPlayIntervalMs = WALKTHROUGH_PLAY_PAUSE_MS, zoomOnWalkthroughFocus = true, graphTitle, showWalkthroughTitle = false, description, canvasOverlay, sidebarExtra, sidebarAfterDescription, diagnostic, issues, showIssues, onSelectIssue, onApplyIssueFix, onHoverIssue, renderFileView, renderFileViewer, renderWalkthroughViewer, onFileSelect, onVerifyComponent, componentVerification }: InnerProps) {
+function Inner({ components, relations, walkthroughs, initialWalkthroughId, onReorderWalkthroughs, onSelect, onEdgeSelect, measured: _measured, maxNodeWidth, showEdgeLabels, edgeView, title, hideSidebar, walkthroughStepMode = 'focus', autoPlayWalkthroughs = false, walkthroughAutoPlayIntervalMs = WALKTHROUGH_PLAY_PAUSE_MS, zoomOnWalkthroughFocus = true, graphTitle, showWalkthroughTitle = false, description, canvasOverlay, sidebarExtra, sidebarAfterDescription, diagnostic, issues, showIssues, onSelectIssue, onApplyIssueFix, onHoverIssue, renderFileView, renderFileViewer, renderWalkthroughViewer, onFileSelect, onVerifyComponent, componentVerification, persistKey }: InnerProps) {
   const { theme } = useTheme();
   const { fitView } = useReactFlow();
   const viewport = useViewport();
+  // Restored once per mount from `localStorage` (see `readViewState`). Each
+  // graph is its own tab/mount, so `persistKey` is stable for a mount.
+  const persisted = useMemo(() => readViewState(persistKey), [persistKey]);
   const graphEdges = useMemo(
     () => deriveGraphEdges({ relations, walkthroughs }),
     [relations, walkthroughs],
@@ -350,9 +409,14 @@ function Inner({ components, relations, walkthroughs, initialWalkthroughId, onRe
   const [hoveredComponentAlias, setHoveredComponentId] = useState<string | null>(null);
   // Walkthrough focus — selected flow (or step) is full strength; other
   // opened-flow members stay visible but dimmed; everything else is hidden.
-  const [focusedWalkthroughId, setFocusedWalkthroughId] = useState<string | null>(null);
+  // Restored from the persisted view state when a `persistKey` is set.
+  const [focusedWalkthroughId, setFocusedWalkthroughId] = useState<string | null>(
+    persisted.focusedWalkthroughId ?? null,
+  );
   // `null` = whole flow focused; a number = that single step's edge focused.
-  const [focusedStepIndex, setFocusedStepIndex] = useState<number | null>(null);
+  const [focusedStepIndex, setFocusedStepIndex] = useState<number | null>(
+    persisted.focusedStepIndex ?? null,
+  );
   // Hovered walkthrough in the flows panel: dims every canvas node/edge not
   // involved in the hover preview (or selected ∪ hovered when a step is
   // focused). `stepIndex: null` = whole flow (collapsed title hover);
@@ -381,7 +445,10 @@ function Inner({ components, relations, walkthroughs, initialWalkthroughId, onRe
         : 'relations');
   // Walkthrough flows the user has expanded (via the title row). Closed by
   // default so a graph with several flows doesn't dump every step list at once.
-  const [expandedWalkthroughs, setExpandedWalkthroughs] = useState<Set<string>>(new Set());
+  // Restored from the persisted view state when a `persistKey` is set.
+  const [expandedWalkthroughs, setExpandedWalkthroughs] = useState<Set<string>>(
+    () => new Set(persisted.expandedWalkthroughs ?? []),
+  );
   // Sidebar description visibility. Hidden by default so the files/flows
   // panel gets the vertical room; the title-row toggle reveals it.
   const [descriptionVisible, setDescriptionVisible] = useState(false);
@@ -389,11 +456,16 @@ function Inner({ components, relations, walkthroughs, initialWalkthroughId, onRe
   // `true` only when a description exists AND the user opened it.
   const showDesc = !!description && descriptionVisible;
   // Sidebar width (px). Draggable via the resize handle between the sidebar
-  // and the graph canvas; clamps to sensible bounds while dragging.
-  const [sidebarWidth, setSidebarWidth] = useState(340);
+  // and the graph canvas; clamps to sensible bounds while dragging. Restored
+  // from the persisted view state when a `persistKey` is set.
+  const [sidebarWidth, setSidebarWidth] = useState(persisted.sidebarWidth ?? 450);
   const [sidebarDrag, setSidebarDrag] = useState(false);
   const sidebarDragStartX = useRef(0);
-  const sidebarDragStartWidth = useRef(340);
+  const sidebarDragStartWidth = useRef(450);
+  // Mirror of `sidebarWidth` for the drag-end persist (the mouseup listener
+  // closes over the drag-start render).
+  const sidebarWidthRef = useRef(sidebarWidth);
+  sidebarWidthRef.current = sidebarWidth;
   const sidebarMinWidth = 240;
   const sidebarMaxWidth = useMemo(
     () => Math.max(Math.min((_measured?.w ?? 680) * 0.5, 600), sidebarMinWidth),
@@ -422,6 +494,8 @@ function Inner({ components, relations, walkthroughs, initialWalkthroughId, onRe
     };
     const onUp = () => {
       setSidebarDrag(false);
+      // Persist only on drag end — not on every mousemove.
+      writeViewState(persistKey, { sidebarWidth: sidebarWidthRef.current });
       // Re-fit the canvas so the graph re-centers in the new available space.
       requestAnimationFrame(() => fitView());
     };
@@ -431,7 +505,23 @@ function Inner({ components, relations, walkthroughs, initialWalkthroughId, onRe
       document.removeEventListener('mousemove', onMove);
       document.removeEventListener('mouseup', onUp);
     };
-  }, [sidebarDrag, sidebarMaxWidth, fitView]);
+  }, [sidebarDrag, sidebarMaxWidth, fitView, persistKey]);
+  // Persist the walkthrough working set per model. Each write merges into the
+  // stored blob, so the three fields never clobber one another.
+  useEffect(() => {
+    if (!persistKey) return;
+    writeViewState(persistKey, {
+      expandedWalkthroughs: Array.from(expandedWalkthroughs),
+    });
+  }, [persistKey, expandedWalkthroughs]);
+  useEffect(() => {
+    if (!persistKey) return;
+    writeViewState(persistKey, { focusedWalkthroughId });
+  }, [persistKey, focusedWalkthroughId]);
+  useEffect(() => {
+    if (!persistKey) return;
+    writeViewState(persistKey, { focusedStepIndex });
+  }, [persistKey, focusedStepIndex]);
   // Ref mirror of `selected` so the SUBSYSTEM_CALLBACKS click handler (a
   // closure over the effect deps) can toggle without a stale value.
   const selectedRef = useRef<SubsystemComponent | null>(null);
@@ -2069,6 +2159,7 @@ function Inner({ components, relations, walkthroughs, initialWalkthroughId, onRe
             walkthrough={focusedWalkthrough}
             stepIndex={drawerTarget.stepIndex}
             onOpenFile={onOpenFileFromWalkthrough}
+            proposedAliases={proposedAliases}
           />
         ) : drawerTarget?.kind === 'file' ? (
           <FileDrawerContent