@principal-ai/subsystems-react 0.21.1 → 0.23.0

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

@@ -0,0 +1,287 @@
+import '@xyflow/react/dist/style.css';
+import type { Meta, StoryObj } from '@storybook/react';
+import { ThemeProvider, defaultEditorTheme } from '@principal-ade/industry-theme';
+import { SubsystemComponentGraph } from '../../../subsystem/SubsystemComponentGraph';
+import type { SubsystemComponent } from '../../../subsystem/model';
+import { graphSpecFromEdges } from './fixtures';
+
+const meta = {
+  title: 'Subsystem/ComponentGraph/Modules',
+  component: SubsystemComponentGraph,
+  parameters: { layout: 'fullscreen' },
+  tags: ['autodocs'],
+  decorators: [
+    (Story) => (
+      <ThemeProvider theme={defaultEditorTheme}>
+        <Story />
+      </ThemeProvider>
+    ),
+  ],
+} satisfies Meta<typeof SubsystemComponentGraph>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const PURL = 'pkg:github/principal-ai/agent-monitoring';
+
+/**
+ * Module frames replace `construct: module`. Each export keeps its real
+ * construct; shared `module` (the source path) draws the file as a boundary.
+ */
+const moduleComponents: SubsystemComponent[] = [
+  {
+    id: 'record',
+    name: 'CodexRolloutRecord',
+    construct: 'type_alias',
+    symbol: 'CodexRolloutRecord',
+    file: 'src/session/transcript.ts',
+    module: 'src/session/transcript.ts',
+    purl: PURL,
+    purpose: 'parsed rollout record shape',
+    layer: 1,
+  },
+  {
+    id: 'is-rollout',
+    name: 'isCodexRollout',
+    construct: 'function',
+    symbol: 'isCodexRollout',
+    file: 'src/session/transcript.ts',
+    module: 'src/session/transcript.ts',
+    purl: PURL,
+    purpose: 'type guard for rollout records',
+    layer: 1,
+  },
+  {
+    id: 'parse',
+    name: 'parseTranscript',
+    construct: 'function',
+    symbol: 'parseTranscript',
+    file: 'src/session/transcript.ts',
+    module: 'src/session/transcript.ts',
+    purl: PURL,
+    purpose: 'parses session transcript lines',
+    layer: 1,
+  },
+  {
+    id: 'tool-name',
+    name: 'extractToolName',
+    construct: 'function',
+    symbol: 'extractToolName',
+    file: 'src/session/paths.ts',
+    module: 'src/session/paths.ts',
+    purl: PURL,
+    purpose: 'pulls tool names from path-like strings',
+    layer: 2,
+  },
+  {
+    id: 'file-path',
+    name: 'extractFilePath',
+    construct: 'function',
+    symbol: 'extractFilePath',
+    file: 'src/session/paths.ts',
+    module: 'src/session/paths.ts',
+    purl: PURL,
+    purpose: 'pulls file paths from tool args',
+    layer: 2,
+  },
+  {
+    id: 'reader',
+    name: 'SessionReader',
+    construct: 'class',
+    symbol: 'SessionReader',
+    file: 'src/session/SessionReader.ts',
+    module: 'src/session/SessionReader.ts',
+    purl: PURL,
+    purpose: 'normalizes a session into universal events',
+    layer: 3,
+  },
+  {
+    id: 'normalize',
+    name: 'normalize',
+    construct: 'method',
+    symbol: 'SessionReader.normalize',
+    file: 'src/session/SessionReader.ts',
+    module: 'src/session/SessionReader.ts',
+    purl: PURL,
+    purpose: 'maps a session into universal events',
+    layer: 3,
+  },
+  {
+    id: 'registry',
+    name: 'registerAgent',
+    construct: 'function',
+    symbol: 'registerAgent',
+    file: 'src/supported-agents.ts',
+    // Singleton module — no frame (same rule as process: need 2+ members).
+    module: 'src/supported-agents.ts',
+    purl: PURL,
+    purpose: 'registers a supported agent (singleton file — no module frame)',
+    layer: 4,
+  },
+];
+
+const moduleEdges = graphSpecFromEdges([
+  ['parse', 'record', 'references'],
+  ['is-rollout', 'record', 'references'],
+  ['reader', 'normalize', 'method'],
+  ['normalize', 'parse', 'calls'],
+  ['normalize', 'tool-name', 'calls'],
+  ['normalize', 'file-path', 'calls'],
+  ['reader', 'registry', 'registers-into'],
+]);
+
+export const ModuleBoundaries: Story = {
+  render: () => (
+    <div style={{ width: '100%', height: '100vh' }}>
+      <SubsystemComponentGraph
+        title="Module boundaries"
+        description="Concrete exports keep their real construct. Shared `module` (the source path) draws the file as a dashed frame — not `construct: module`. Singleton modules (registerAgent) stay unframed."
+        components={moduleComponents}
+        relations={moduleEdges.relations}
+        walkthroughs={moduleEdges.walkthroughs}
+      />
+    </div>
+  ),
+};
+
+/** Process → module → export nesting (host / renderer). */
+const nestedComponents: SubsystemComponent[] = [
+  {
+    id: 'boot',
+    name: 'boot',
+    construct: 'function',
+    symbol: 'boot',
+    role: 'entry',
+    file: 'src/host/main.ts',
+    module: 'src/host/main.ts',
+    process: 'principal-studio/host',
+    purl: 'pkg:github/principal-ai/principal-studio',
+    purpose: 'Boots the host process',
+    layer: 1,
+  },
+  {
+    id: 'create-host',
+    name: 'createHost',
+    construct: 'function',
+    symbol: 'createHost',
+    file: 'src/host/main.ts',
+    module: 'src/host/main.ts',
+    process: 'principal-studio/host',
+    purl: 'pkg:github/principal-ai/principal-studio',
+    purpose: 'Constructs the host runtime',
+    layer: 1,
+  },
+  {
+    id: 'session-store',
+    name: 'SessionStore',
+    construct: 'store',
+    symbol: 'SessionStore',
+    file: 'src/host/store.ts',
+    module: 'src/host/store.ts',
+    process: 'principal-studio/host',
+    purl: 'pkg:github/principal-ai/principal-studio',
+    purpose: 'Retained host session state',
+    layer: 2,
+  },
+  {
+    id: 'write-session',
+    name: 'writeSession',
+    construct: 'function',
+    symbol: 'writeSession',
+    file: 'src/host/store.ts',
+    module: 'src/host/store.ts',
+    process: 'principal-studio/host',
+    purl: 'pkg:github/principal-ai/principal-studio',
+    purpose: 'Mutates SessionStore',
+    layer: 2,
+  },
+  {
+    id: 'bridge',
+    name: 'bridge',
+    construct: 'function',
+    symbol: 'bridge',
+    role: 'entry',
+    file: 'src/renderer/bridge.ts',
+    module: 'src/renderer/bridge.ts',
+    process: 'principal-studio/renderer',
+    purl: 'pkg:github/principal-ai/principal-studio',
+    purpose: 'Renderer IPC entry',
+    layer: 3,
+  },
+  {
+    id: 'post-to-host',
+    name: 'postToHost',
+    construct: 'function',
+    symbol: 'postToHost',
+    file: 'src/renderer/bridge.ts',
+    module: 'src/renderer/bridge.ts',
+    process: 'principal-studio/renderer',
+    purl: 'pkg:github/principal-ai/principal-studio',
+    purpose: 'Sends a message to the host',
+    layer: 3,
+  },
+  {
+    id: 'trail-view',
+    name: 'TrailView',
+    construct: 'function',
+    symbol: 'TrailView',
+    framework: 'react',
+    stereotype: 'component',
+    file: 'src/renderer/view.tsx',
+    module: 'src/renderer/view.tsx',
+    process: 'principal-studio/renderer',
+    purl: 'pkg:github/principal-ai/principal-studio',
+    purpose: 'Renders the trail',
+    layer: 4,
+  },
+  {
+    id: 'use-trail',
+    name: 'useTrail',
+    construct: 'function',
+    symbol: 'useTrail',
+    framework: 'react',
+    stereotype: 'hook',
+    file: 'src/renderer/view.tsx',
+    module: 'src/renderer/view.tsx',
+    process: 'principal-studio/renderer',
+    purl: 'pkg:github/principal-ai/principal-studio',
+    purpose: 'Subscribes the view to trail updates',
+    layer: 4,
+  },
+  {
+    id: 'telemetry',
+    name: 'telemetry',
+    construct: 'external',
+    role: 'service',
+    file: '',
+    purl: 'external',
+    purpose: 'External sink — outside every frame',
+    layer: 5,
+  },
+];
+
+const nestedEdges = graphSpecFromEdges([
+  ['boot', 'write-session', 'imports'],
+  ['trail-view', 'bridge', 'imports'],
+  ['trail-view', 'use-trail', 'references'],
+  ['boot', 'create-host', 'calls'],
+  ['create-host', 'write-session', 'calls'],
+  ['write-session', 'session-store', 'writes'],
+  ['bridge', 'boot', 'calls'],
+  ['trail-view', 'post-to-host', 'calls'],
+  ['boot', 'telemetry', 'uses'],
+]);
+
+export const ProcessAndModuleNesting: Story = {
+  render: () => (
+    <div style={{ width: '100%', height: '100vh' }}>
+      <SubsystemComponentGraph
+        title="Process × module nesting"
+        description="process frames wrap module frames wrap exports. Leaves parent to module:; module groups parent to process: when every member shares that process."
+        components={nestedComponents}
+        relations={nestedEdges.relations}
+        walkthroughs={nestedEdges.walkthroughs}
+      />
+    </div>
+  ),
+};

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

@@ -28,7 +28,7 @@ const processComponents = [
     ['main', 'main', 'function', 'src/host/main.ts', 'pkg:github/principal-ai/principal-studio', 'boots the host process', 'main'],
     ['store', 'SessionStore', 'store', 'src/host/store.ts', 'pkg:github/principal-ai/principal-studio', 'retained host state', 'SessionStore'],
     ['view', 'TrailView', 'function', 'src/renderer/view.tsx', 'pkg:github/principal-ai/principal-studio', 'renders the trail', 'TrailView'],
-    ['bridge', 'bridge', 'module', 'src/renderer/bridge.ts', 'pkg:github/principal-ai/principal-studio', 'IPC bridge to the host', 'bridge'],
+    ['bridge', 'bridge', 'function', 'src/renderer/bridge.ts', 'pkg:github/principal-ai/principal-studio', 'IPC bridge to the host', 'bridge'],
   ]),
   {
     id: 'svc',

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

@@ -84,7 +84,7 @@ const mermaidComponents: SubsystemComponent[] = [
   {
     id: 'helpers',
     name: 'beautifulMermaid',
-    construct: 'module',
+    construct: 'function',
     file: 'industryMarkdown/utils/beautifulMermaid.ts',
     purl: mermaidPurl,
     purpose: 'engine detection, theme\u2192options mapping, SVG post-processing',
@@ -130,11 +130,11 @@ const coreLibPurl = 'pkg:github/principal-ai/principal-view-core-library';
 const graphifyPurl = 'pkg:github/Graphify-Labs/graphify';
 
 const multiRepoComponents = components([
-  ['resolver', 'resolve.ts', 'module', 'packages/subsystems-react/src/graphify/resolve.ts', coreLibPurl, 'consumer-side resolution mirroring graphify rewire tiers', 'createGraphifyTypeResolver'],
-  ['reftypes', 'consolidated.ts', 'module', 'packages/subsystems-react/src/graphify/consolidated.ts', coreLibPurl, 'drill-down payload types carrying ref.nodeId', 'GraphifyParamInfo'],
-  ['detail', 'ComponentDeclaration.tsx', 'module', 'packages/subsystems-react/src/subsystem/ComponentDeclaration.tsx', coreLibPurl, 'declaration panel rendering the selected component as code, with clickable type tokens', 'ComponentDeclaration'],
-  ['engine', 'engine.py', 'module', 'graphify/extractors/engine.py', graphifyPurl, 'tree-sitter walk emitting references[parameter_type] edges + sourceless stubs', 'ensure_named_node'],
-  ['rewire', 'extract.py', 'module', 'graphify/extract.py', graphifyPurl, 'corpus pass folding unique-label stubs onto definitions', '_rewire_unique_stub_nodes'],
+  ['resolver', 'resolve.ts', 'function', 'packages/subsystems-react/src/graphify/resolve.ts', coreLibPurl, 'consumer-side resolution mirroring graphify rewire tiers', 'createGraphifyTypeResolver'],
+  ['reftypes', 'consolidated.ts', 'function', 'packages/subsystems-react/src/graphify/consolidated.ts', coreLibPurl, 'drill-down payload types carrying ref.nodeId', 'GraphifyParamInfo'],
+  ['detail', 'ComponentDeclaration.tsx', 'function', 'packages/subsystems-react/src/subsystem/ComponentDeclaration.tsx', coreLibPurl, 'declaration panel rendering the selected component as code, with clickable type tokens', 'ComponentDeclaration'],
+  ['engine', 'engine.py', 'function', 'graphify/extractors/engine.py', graphifyPurl, 'tree-sitter walk emitting references[parameter_type] edges + sourceless stubs', 'ensure_named_node'],
+  ['rewire', 'extract.py', 'function', 'graphify/extract.py', graphifyPurl, 'corpus pass folding unique-label stubs onto definitions', '_rewire_unique_stub_nodes'],
 ]);
 
 const multiRepoEdges = graphSpecFromEdges([

package/src/stories/Subsystem/ComponentGraph/fixtures.ts

@@ -29,16 +29,12 @@ export function components(
 
 const RELATION_TYPES = new Set<string>([
   'imports',
-  'imports_from',
-  're_exports',
-  'defines',
   'extends',
   'inherits',
   'implements',
   'mixes_in',
   'method',
   'references',
-  'contains',
 ]);
 
 export function relations(

package/src/subsystem/FileDrawer.tsx

@@ -5,7 +5,7 @@
  * children by the graph component.
  */
 
-import { useEffect } from 'react';
+import { useEffect, useState } from 'react';
 import type { ReactNode } from 'react';
 import { useTheme } from '@principal-ade/industry-theme';
 import { X } from 'lucide-react';
@@ -16,29 +16,37 @@ export const FILE_DRAWER_HEIGHT_MS = 200;
 
 /** Bottom panel that slides up from the bottom of the graph area.
  *  Sits in normal flow (canvas shrinks while open, nothing covered)
- *  and animates via height; stays mounted so open/close animates. */
+ *  and animates via height; stays mounted so open/close animates.
+ *  `fillHeight` expands to the full graph column (for whole-file reading). */
 export function FileDrawer({
   title,
   onClose,
+  fillHeight = false,
+  suppressEscape = false,
   children,
 }: {
   /** Drawer chrome title; `null` closes the drawer. */
   title: string | null;
   onClose: () => void;
+  /** When true and open, fill the graph column instead of ~45% height. */
+  fillHeight?: boolean;
+  /** Skip Escape handling (e.g. while a full-file overlay is on top). */
+  suppressEscape?: boolean;
   children?: ReactNode;
 }) {
   const { theme } = useTheme();
   const muted = theme.colors.textMuted ?? theme.colors.textSecondary;
   const open = title !== null;
+  const [closeHover, setCloseHover] = useState(false);
 
   useEffect(() => {
-    if (!open) return;
+    if (!open || suppressEscape) return;
     const onKey = (e: KeyboardEvent) => {
       if (e.key === 'Escape') onClose();
     };
     window.addEventListener('keydown', onKey);
     return () => window.removeEventListener('keydown', onKey);
-  }, [open, onClose]);
+  }, [open, onClose, suppressEscape]);
 
   return (
     <div
@@ -48,7 +56,8 @@ export function FileDrawer({
         // whole graph-area container including this panel's slice.
         zIndex: 6,
         flexShrink: 0,
-        height: open ? '45%' : 0,
+        flex: open && fillHeight ? 1 : undefined,
+        height: open ? (fillHeight ? undefined : '45%') : 0,
         minHeight: 0,
         overflow: 'hidden',
         display: 'flex',
@@ -86,6 +95,8 @@ export function FileDrawer({
         <button
           type="button"
           onClick={onClose}
+          onMouseEnter={() => setCloseHover(true)}
+          onMouseLeave={() => setCloseHover(false)}
           aria-label="Close file"
           style={{
             display: 'inline-flex',
@@ -96,9 +107,10 @@ export function FileDrawer({
             padding: 0,
             border: 'none',
             borderRadius: 4,
-            background: 'transparent',
-            color: theme.colors.text,
+            background: closeHover ? theme.colors.border : 'transparent',
+            color: closeHover ? theme.colors.text : muted,
             cursor: 'pointer',
+            transition: 'background 120ms ease, color 120ms ease',
           }}
         >
           <X size={14} />

package/src/subsystem/SubsystemComponentGraph.tsx

@@ -69,6 +69,8 @@ export interface WalkthroughViewerContext {
   walkthrough: SubsystemWalkthrough;
   /** Focused step index; `null` means the whole flow (no specific step). */
   stepIndex: number | null;
+  /** Open a step's full source file over the walkthrough drawer (keeps snippets mounted). */
+  onOpenFile: (path: string) => void;
 }
 
 type DrawerTarget =
@@ -198,16 +200,49 @@ const FileDrawerContent = memo(function FileDrawerContent({
   return <>{render(file, startLine != null ? { startLine } : undefined)}</>;
 });
 
+function FileOverlayCloseButton({ onClose }: { onClose: () => void }) {
+  const { theme } = useTheme();
+  const muted = theme.colors.textMuted ?? theme.colors.textSecondary;
+  const [hover, setHover] = useState(false);
+  return (
+    <button
+      type="button"
+      onClick={onClose}
+      onMouseEnter={() => setHover(true)}
+      onMouseLeave={() => setHover(false)}
+      aria-label="Close file"
+      style={{
+        display: 'inline-flex',
+        alignItems: 'center',
+        justifyContent: 'center',
+        width: 22,
+        height: 22,
+        padding: 0,
+        border: 'none',
+        borderRadius: 4,
+        background: hover ? theme.colors.border : 'transparent',
+        color: hover ? theme.colors.text : muted,
+        cursor: 'pointer',
+        transition: 'background 120ms ease, color 120ms ease',
+      }}
+    >
+      <X size={14} />
+    </button>
+  );
+}
+
 const WalkthroughDrawerContent = memo(function WalkthroughDrawerContent({
   render,
   walkthrough,
   stepIndex,
+  onOpenFile,
 }: {
   render: (ctx: WalkthroughViewerContext) => ReactNode;
   walkthrough: SubsystemWalkthrough;
   stepIndex: number | null;
+  onOpenFile: (path: string) => void;
 }) {
-  return <>{render({ walkthrough, stepIndex })}</>;
+  return <>{render({ walkthrough, stepIndex, onOpenFile })}</>;
 });
 
 interface InnerProps extends SubsystemComponentGraphProps {
@@ -230,6 +265,8 @@ function Inner({ components, relations, walkthroughs, onSelect, onEdgeSelect, me
   const [selected, setSelected] = useState<SubsystemComponent | null>(null);
   /** Bottom drawer: single file or walkthrough multi-snippet mode. */
   const [drawerTarget, setDrawerTarget] = useState<DrawerTarget | null>(null);
+  /** Full-file layer over an open walkthrough drawer — walkthrough stays mounted. */
+  const [fileOverlay, setFileOverlay] = useState<{ file: string } | null>(null);
   // Mirror so step-focus can decide whether to wait for the drawer open
   // transition before fitView (avoids framing against full-height canvas).
   const drawerOpenRef = useRef(false);
@@ -316,9 +353,11 @@ function Inner({ components, relations, walkthroughs, onSelect, onEdgeSelect, me
   // Ref mirror of the open file drawer target for tree-click toggle.
   const openFileRef = useRef<{ file: string; startLine?: number } | null>(null);
   const openFile =
-    drawerTarget?.kind === 'file' ? drawerTarget.file : null;
-  openFileRef.current =
-    drawerTarget?.kind === 'file'
+    fileOverlay?.file ??
+    (drawerTarget?.kind === 'file' ? drawerTarget.file : null);
+  openFileRef.current = fileOverlay
+    ? { file: fileOverlay.file }
+    : drawerTarget?.kind === 'file'
       ? { file: drawerTarget.file, startLine: drawerTarget.startLine }
       : null;
 
@@ -864,6 +903,7 @@ function Inner({ components, relations, walkthroughs, onSelect, onEdgeSelect, me
   );
   const onTreeSelectFile = useCallback(
     (file: string) => {
+      setFileOverlay(null);
       if (openFileRef.current?.file === file && openFileRef.current.startLine == null) {
         setDrawerTarget(null);
         return;
@@ -876,6 +916,7 @@ function Inner({ components, relations, walkthroughs, onSelect, onEdgeSelect, me
 
   const onOpenDeclarationFile = useCallback(
     (file: string, opts?: SubsystemOpenFileOptions) => {
+      setFileOverlay(null);
       const startLine = opts?.startLine;
       if (
         openFileRef.current?.file === file &&
@@ -890,6 +931,47 @@ function Inner({ components, relations, walkthroughs, onSelect, onEdgeSelect, me
     [onFileSelect],
   );
 
+  const onOpenFileFromWalkthrough = useCallback(
+    (file: string) => {
+      setFileOverlay({ file });
+      onFileSelect?.(file);
+    },
+    [onFileSelect],
+  );
+
+  const closeFileOverlay = useCallback(() => {
+    setFileOverlay(null);
+  }, []);
+
+  const closeDrawer = useCallback(() => {
+    setFileOverlay(null);
+    setDrawerTarget(null);
+  }, []);
+
+  const drawerFillHeight =
+    drawerTarget?.kind === 'file' && drawerTarget.startLine == null;
+  const fileOverlayOpen = fileOverlay != null;
+  const collapseCanvas = drawerFillHeight || fileOverlayOpen;
+
+  // Drop the full-file overlay when the underlying walkthrough drawer changes
+  // or closes — open-file keeps the same drawerTarget so the snippets stay mounted.
+  const walkthroughDrawerKey =
+    drawerTarget?.kind === 'walkthrough'
+      ? `${drawerTarget.walkthroughId}:${drawerTarget.stepIndex}`
+      : null;
+  useEffect(() => {
+    setFileOverlay(null);
+  }, [walkthroughDrawerKey]);
+
+  useEffect(() => {
+    if (!fileOverlayOpen) return;
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') closeFileOverlay();
+    };
+    window.addEventListener('keydown', onKey);
+    return () => window.removeEventListener('keydown', onKey);
+  }, [fileOverlayOpen, closeFileOverlay]);
+
   // Camera helper shared by the walkthrough interactions: frames the focused
   // edges' endpoint nodes via `fitView({ nodes })`, which uses the store's
   // live positions + measured dims — so the frame always includes BOTH
@@ -1532,8 +1614,19 @@ function Inner({ components, relations, walkthroughs, onSelect, onEdgeSelect, me
       {/* Graph area */}
       <div style={{ flex: 1, position: 'relative', display: 'flex', flexDirection: 'column', minHeight: 0 }}>
         {/* Canvas box — the edge-label overlay and legend anchor here, so
-            overlays shift with the canvas, not the labels. */}
-        <div style={{ position: 'relative', flex: 1, minHeight: 0, display: 'flex', flexDirection: 'column' }}>
+            overlays shift with the canvas, not the labels. Collapses when the
+            file drawer fills the column (whole-file reading). */}
+        <div
+          style={{
+            position: 'relative',
+            flex: collapseCanvas ? 0 : 1,
+            minHeight: 0,
+            height: collapseCanvas ? 0 : undefined,
+            overflow: 'hidden',
+            display: 'flex',
+            flexDirection: 'column',
+          }}
+        >
         {/* Edge-label overlay — sits above the ReactFlow pane so clicks land. */}
         {showEdgeLabels !== false && (
         <div
@@ -1796,7 +1889,12 @@ function Inner({ components, relations, walkthroughs, onSelect, onEdgeSelect, me
           </div>
         )}
         </div>
-      <FileDrawer title={drawerTitle} onClose={() => setDrawerTarget(null)}>
+      <FileDrawer
+        title={drawerTitle}
+        onClose={closeDrawer}
+        fillHeight={drawerFillHeight}
+        suppressEscape={fileOverlayOpen}
+      >
         {drawerTarget?.kind === 'walkthrough' &&
         focusedWalkthrough &&
         renderWalkthroughViewer ? (
@@ -1804,6 +1902,7 @@ function Inner({ components, relations, walkthroughs, onSelect, onEdgeSelect, me
             render={renderWalkthroughDrawerContent}
             walkthrough={focusedWalkthrough}
             stepIndex={drawerTarget.stepIndex}
+            onOpenFile={onOpenFileFromWalkthrough}
           />
         ) : drawerTarget?.kind === 'file' ? (
           <FileDrawerContent
@@ -1813,6 +1912,53 @@ function Inner({ components, relations, walkthroughs, onSelect, onEdgeSelect, me
           />
         ) : null}
       </FileDrawer>
+      {fileOverlay && (
+        <div
+          style={{
+            position: 'absolute',
+            inset: 0,
+            zIndex: 8,
+            display: 'flex',
+            flexDirection: 'column',
+            background: theme.colors.background,
+            borderLeft: `1px solid ${theme.colors.border}`,
+          }}
+        >
+          <div
+            style={{
+              display: 'flex',
+              alignItems: 'center',
+              gap: 8,
+              padding: '6px 10px',
+              borderBottom: `1px solid ${theme.colors.border}`,
+              flexShrink: 0,
+            }}
+          >
+            <span
+              title={fileOverlay.file}
+              style={{
+                flex: 1,
+                minWidth: 0,
+                overflow: 'hidden',
+                textOverflow: 'ellipsis',
+                whiteSpace: 'nowrap',
+                fontFamily: theme.fonts.monospace,
+                fontSize: theme.fontSizes[0],
+                color: theme.colors.textMuted ?? theme.colors.textSecondary,
+              }}
+            >
+              {fileOverlay.file}
+            </span>
+            <FileOverlayCloseButton onClose={closeFileOverlay} />
+          </div>
+          <div style={{ flex: 1, minHeight: 0, overflow: 'auto' }}>
+            <FileDrawerContent
+              render={renderDrawerContent}
+              file={fileOverlay.file}
+            />
+          </div>
+        </div>
+      )}
       {/* Startup cover — hides measurement, layout swap, and camera settle. */}
       <GraphLayoutCover revealed={layoutReady} />
       {canvasOverlay}

package/src/subsystem/declarationRef.ts

@@ -58,6 +58,11 @@ export function extractDeclarationLine(content: string, lineNumber: number): str
 
 /** Options when opening a file in the subsystem graph drawer. */
 export interface SubsystemOpenFileOptions {
-  /** Scroll/highlight this 1-based line (declaration start). */
+  /** Scroll/highlight this 1-based line (declaration start or walkthrough site). */
   startLine?: number;
+  /**
+   * When true with `startLine`, show the whole file scrolled to that line
+   * instead of a focused snippet window.
+   */
+  fullFile?: boolean;
 }