@principal-ai/subsystems-react 0.49.0 → 0.50.0

package/src/subsystem/FileDrawer.tsx

@@ -25,6 +25,7 @@ export function FileDrawer({
   fillHeight = false,
   suppressEscape = false,
   hidden = false,
+  progress = null,
   children,
 }: {
   /** Drawer chrome title; `null` closes the drawer. */
@@ -36,11 +37,18 @@ export function FileDrawer({
   suppressEscape?: boolean;
   /** Suppress the drawer entirely — no spacer, no panel (embeds). */
   hidden?: boolean;
+  /**
+   * Segmented progress readout for the drawer content, e.g. trail step 2 of 5.
+   * Rendered as one tick per step, filled through the current one. Omit for
+   * content with no position (a single file).
+   */
+  progress?: { index: number; total: number } | null;
   children?: ReactNode;
 }) {
   const { theme } = useTheme();
   const muted = theme.colors.textMuted ?? theme.colors.textSecondary;
   const open = title !== null && !hidden;
+  const showProgress = progress != null && progress.total > 1;
   const [closeHover, setCloseHover] = useState(false);
   const [maxHover, setMaxHover] = useState(false);
   // Full-height mode: the maximize button or double-clicking the header.
@@ -103,78 +111,119 @@ export function FileDrawer({
           onDoubleClick={() => setMaximized((v) => !v)}
           style={{
             display: "flex",
-            alignItems: "center",
-            gap: 8,
-            padding: "6px 10px",
-            borderBottom: `1px solid ${theme.colors.border}`,
+            flexDirection: "column",
             flexShrink: 0,
             cursor: "default",
             userSelect: "none",
           }}
         >
-          <span
-            title={title ?? undefined}
+          <div
             style={{
-              flex: 1,
-              minWidth: 0,
-              overflow: "hidden",
-              textOverflow: "ellipsis",
-              whiteSpace: "nowrap",
-              fontFamily: theme.fonts.monospace,
-              fontSize: theme.fontSizes[0],
-              color: muted,
-            }}
-          >
-            {title}
-          </span>
-          <button
-            type="button"
-            onClick={() => setMaximized((v) => !v)}
-            onMouseEnter={() => setMaxHover(true)}
-            onMouseLeave={() => setMaxHover(false)}
-            aria-label={maximized ? "Minimize code view" : "Maximize code view"}
-            aria-pressed={maximized}
-            title={maximized ? "Minimize code view" : "Maximize code view"}
-            style={{
-              display: "inline-flex",
-              alignItems: "center",
-              justifyContent: "center",
-              width: 22,
-              height: 22,
-              padding: 0,
-              border: "none",
-              borderRadius: 4,
-              background: maxHover ? theme.colors.border : "transparent",
-              color: maxHover ? theme.colors.text : muted,
-              cursor: "pointer",
-              transition: "background 120ms ease, color 120ms ease",
-            }}
-          >
-            {maximized ? <Minimize2 size={14} /> : <Maximize2 size={14} />}
-          </button>
-          <button
-            type="button"
-            onClick={onClose}
-            onMouseEnter={() => setCloseHover(true)}
-            onMouseLeave={() => setCloseHover(false)}
-            aria-label="Close file"
-            style={{
-              display: "inline-flex",
+              display: "flex",
               alignItems: "center",
-              justifyContent: "center",
-              width: 22,
-              height: 22,
-              padding: 0,
-              border: "none",
-              borderRadius: 4,
-              background: closeHover ? theme.colors.border : "transparent",
-              color: closeHover ? theme.colors.text : muted,
-              cursor: "pointer",
-              transition: "background 120ms ease, color 120ms ease",
+              gap: 8,
+              padding: "6px 10px",
+              // With segments present they form the header's bottom edge, so
+              // only draw the hairline when there is nothing to stand in for it.
+              borderBottom: showProgress
+                ? "none"
+                : `1px solid ${theme.colors.border}`,
             }}
           >
-            <X size={14} />
-          </button>
+            <span
+              title={title ?? undefined}
+              style={{
+                flex: 1,
+                minWidth: 0,
+                overflow: "hidden",
+                textOverflow: "ellipsis",
+                whiteSpace: "nowrap",
+                fontFamily: theme.fonts.monospace,
+                fontSize: theme.fontSizes[1],
+                fontWeight: 600,
+                color: theme.colors.text,
+              }}
+            >
+              {title}
+            </span>
+            <button
+              type="button"
+              onClick={() => setMaximized((v) => !v)}
+              onMouseEnter={() => setMaxHover(true)}
+              onMouseLeave={() => setMaxHover(false)}
+              aria-label={
+                maximized ? "Minimize code view" : "Maximize code view"
+              }
+              aria-pressed={maximized}
+              title={maximized ? "Minimize code view" : "Maximize code view"}
+              style={{
+                display: "inline-flex",
+                alignItems: "center",
+                justifyContent: "center",
+                width: 22,
+                height: 22,
+                padding: 0,
+                border: "none",
+                borderRadius: 4,
+                background: maxHover ? theme.colors.border : "transparent",
+                color: maxHover ? theme.colors.text : muted,
+                cursor: "pointer",
+                transition: "background 120ms ease, color 120ms ease",
+              }}
+            >
+              {maximized ? <Minimize2 size={14} /> : <Maximize2 size={14} />}
+            </button>
+            <button
+              type="button"
+              onClick={onClose}
+              onMouseEnter={() => setCloseHover(true)}
+              onMouseLeave={() => setCloseHover(false)}
+              aria-label="Close file"
+              style={{
+                display: "inline-flex",
+                alignItems: "center",
+                justifyContent: "center",
+                width: 22,
+                height: 22,
+                padding: 0,
+                border: "none",
+                borderRadius: 4,
+                background: closeHover ? theme.colors.border : "transparent",
+                color: closeHover ? theme.colors.text : muted,
+                cursor: "pointer",
+                transition: "background 120ms ease, color 120ms ease",
+              }}
+            >
+              <X size={14} />
+            </button>
+          </div>
+          {showProgress && progress != null && (
+            <div
+              role="img"
+              aria-label={`Step ${progress.index + 1} of ${progress.total}`}
+              style={{
+                display: "flex",
+                gap: 2,
+                flexShrink: 0,
+                padding: "0 10px 6px",
+              }}
+            >
+              {Array.from({ length: progress.total }, (_, i) => (
+                <span
+                  key={i}
+                  style={{
+                    flex: 1,
+                    height: 2,
+                    borderRadius: 1,
+                    background:
+                      i <= progress.index
+                        ? theme.colors.primary
+                        : theme.colors.border,
+                  }}
+                />
+              ))}
+            </div>
+          )}
         </div>
         <div style={{ flex: 1, minHeight: 0, overflow: "auto" }}>
           {children}

package/src/subsystem/SubsystemComponentGraph.tsx

@@ -114,6 +114,12 @@ export interface TrailViewerContext {
   resolveSymbol?: (query: TrailSymbolQuery) => string | null;
   /** A clicked construct token — open that construct's declaration line. */
   onSymbolClick?: (symbol: string, query: TrailSymbolQuery) => void;
+  /**
+   * Report which step scrolling has brought to the top of the code view, so the
+   * drawer can track the viewport instead of only the selected step. Forward
+   * the code view's scroll callback here.
+   */
+  onVisibleStepChange?: (index: number) => void;
 }
 
 /** Identifiers a token could match to name this component as a construct. */
@@ -491,6 +497,7 @@ const TrailDrawerContent = memo(function TrailDrawerContent({
   proposedAliases,
   resolveSymbol,
   onSymbolClick,
+  onVisibleStepChange,
 }: {
   render: (ctx: TrailViewerContext) => ReactNode;
   trail: SubsystemTrail;
@@ -499,6 +506,7 @@ const TrailDrawerContent = memo(function TrailDrawerContent({
   proposedAliases: ReadonlySet<string>;
   resolveSymbol?: (query: TrailSymbolQuery) => string | null;
   onSymbolClick?: (symbol: string, query: TrailSymbolQuery) => void;
+  onVisibleStepChange?: (index: number) => void;
 }) {
   return (
     <>
@@ -509,6 +517,7 @@ const TrailDrawerContent = memo(function TrailDrawerContent({
         proposedAliases,
         resolveSymbol,
         onSymbolClick,
+        onVisibleStepChange,
       })}
     </>
   );
@@ -848,15 +857,28 @@ function Inner({ components, trails, graphifyRelations, orderByLine, initialTrai
   const drawerTitle = useMemo(() => {
     if (!drawerTarget) return null;
     if (drawerTarget.kind === 'file') return drawerTarget.file;
+    // Trail steps already show their own file header per file, so the drawer
+    // title is just the trail name.
     const tl = focusedTrail;
     if (!tl) return null;
-    if (drawerTarget.stepIndex == null) return tl.title;
-    const step = tl.steps[drawerTarget.stepIndex];
-    if (!step) return tl.title;
-    const site = `${step.file.split('/').pop() ?? step.file}:${step.line}`;
-    return `${tl.title} · ${site}`;
+    return tl.title;
   }, [drawerTarget, focusedTrail]);
 
+  // Segmented step readout for trail drawers — a single file has no position.
+  // Follows the viewport once the code view reports a scroll, and falls back to
+  // the selected step until it does.
+  const [visibleStepIndex, setVisibleStepIndex] = useState<number | null>(null);
+  const drawerStepIndex = drawerTarget?.kind === 'trail' ? drawerTarget.stepIndex : null;
+  const drawerProgress = useMemo(() => {
+    if (drawerStepIndex == null || !focusedTrail) return null;
+    return { index: visibleStepIndex ?? drawerStepIndex, total: focusedTrail.steps.length };
+  }, [drawerStepIndex, focusedTrail, visibleStepIndex]);
+
+  // A new trail or step invalidates whatever the last scroll reported.
+  useEffect(() => {
+    setVisibleStepIndex(null);
+  }, [focusedTrail?.id, drawerStepIndex]);
+
   // Refresh selected component when the components list updates (e.g. verify
   // writes back declarationRef).
   useEffect(() => {
@@ -3145,6 +3167,7 @@ function Inner({ components, trails, graphifyRelations, orderByLine, initialTrai
         fillHeight={drawerFillHeight}
         suppressEscape={fileOverlayOpen}
         hidden={hideDrawer}
+        progress={drawerProgress}
       >
         {drawerTarget?.kind === 'trail' &&
         focusedTrail &&
@@ -3157,6 +3180,7 @@ function Inner({ components, trails, graphifyRelations, orderByLine, initialTrai
             proposedAliases={proposedAliases}
             resolveSymbol={resolveTrailSymbol}
             onSymbolClick={openConstructDeclaration}
+            onVisibleStepChange={setVisibleStepIndex}
           />
         ) : drawerTarget?.kind === 'file' ? (
           <FileDrawerContent