@principal-ai/subsystems-react 0.22.0 → 0.23.1

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, opts?: SubsystemOpenFileOptions) => void;
 }
 
 type DrawerTarget =
@@ -190,24 +192,68 @@ const FileDrawerContent = memo(function FileDrawerContent({
   render,
   file,
   startLine,
+  fullFile,
 }: {
   render: (file: string, opts?: SubsystemOpenFileOptions) => ReactNode;
   file: string;
   startLine?: number;
+  fullFile?: boolean;
 }) {
-  return <>{render(file, startLine != null ? { startLine } : undefined)}</>;
+  return (
+    <>
+      {render(
+        file,
+        startLine != null
+          ? { startLine, ...(fullFile ? { fullFile: true } : {}) }
+          : 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, opts?: SubsystemOpenFileOptions) => void;
 }) {
-  return <>{render({ walkthrough, stepIndex })}</>;
+  return <>{render({ walkthrough, stepIndex, onOpenFile })}</>;
 });
 
 interface InnerProps extends SubsystemComponentGraphProps {
@@ -230,6 +276,11 @@ 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;
+    startLine?: number;
+  } | 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 +367,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, startLine: fileOverlay.startLine }
+    : drawerTarget?.kind === 'file'
       ? { file: drawerTarget.file, startLine: drawerTarget.startLine }
       : null;
 
@@ -864,6 +917,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 +930,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 +945,47 @@ function Inner({ components, relations, walkthroughs, onSelect, onEdgeSelect, me
     [onFileSelect],
   );
 
+  const onOpenFileFromWalkthrough = useCallback(
+    (file: string, opts?: SubsystemOpenFileOptions) => {
+      setFileOverlay({ file, startLine: opts?.startLine });
+      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 +1628,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 +1903,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 +1916,7 @@ function Inner({ components, relations, walkthroughs, onSelect, onEdgeSelect, me
             render={renderWalkthroughDrawerContent}
             walkthrough={focusedWalkthrough}
             stepIndex={drawerTarget.stepIndex}
+            onOpenFile={onOpenFileFromWalkthrough}
           />
         ) : drawerTarget?.kind === 'file' ? (
           <FileDrawerContent
@@ -1813,6 +1926,55 @@ 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}
+              startLine={fileOverlay.startLine}
+              fullFile
+            />
+          </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;
 }

package/src/subsystem/model.ts

@@ -96,8 +96,7 @@ export type SubsystemRelationType =
   | 'implements'
   | 'mixes_in'
   | 'method'
-  | 'references'
-  | 'contains';
+  | 'references';
 
 /**
  * Walkthrough hop mechanism — runtime seams with a `file:line` site.
@@ -619,7 +618,6 @@ export const MECHANISM_COLOR: Record<SubsystemEdgeMechanism, string> = {
   uses: '#e3b341', // gold
   method: '#c586c0', // magenta
   references: '#e07a5f', // terracotta
-  contains: '#6c5ce7', // indigo
   feeds: '#22c55e', // green — data-flow into a processor
   produces: '#e07a5f', // terracotta — emits an output type
   writes: '#2f9e44', // deep green — mutates retained state
@@ -638,7 +636,6 @@ export const MECHANISM_STYLE: Record<SubsystemEdgeMechanism, 'solid' | 'dashed'
   uses: 'solid',
   method: 'solid',
   references: 'dotted',
-  contains: 'solid',
   feeds: 'solid',
   produces: 'solid',
   writes: 'solid',
@@ -659,7 +656,6 @@ export const MECHANISM_DESCRIPTIONS: [SubsystemEdgeMechanism, string, boolean][]
   ['uses', 'general dependency (import, call, or reference)', false],
   ['method', 'structural: has method / member', true],
   ['references', 'type / symbol reference (not a call)', true],
-  ['contains', 'UI composition: shell/view owns a child surface', false],
   ['feeds', 'data flow: output feeds into input', false],
   ['produces', 'data flow: produces / outputs', false],
   ['writes', 'state access: mutates retained state', true],