@principal-ai/subsystems-react 0.48.0 → 0.50.0

package/src/pierre/PierreTrailCodeView.tsx

@@ -42,6 +42,7 @@ import type { SubsystemOpenFileOptions } from '../subsystem/declarationRef';
 import { buildPierreOptions, PIERRE_FILE_STYLE } from './pierreBackground';
 import { pierreLangForPath } from './pierreFileLang';
 import { resolvePierreSyntaxThemeName } from './pierreSyntaxTheme';
+import { resolveVisibleStepIndex, type VisibleStepRect } from './visibleStep';
 import { fileUnavailableNotice, isFileUnavailableError } from './fileAvailability';
 import {
   remapSnippetLineNumbers,
@@ -67,6 +68,16 @@ function stepIndexFromItemContext(context: unknown): number | null {
   return Number.isFinite(index) ? index : null;
 }
 
+/**
+ * Assumed height of the compact file header, in px.
+ *
+ * Must track the header chrome passed to `buildPierreOptions` (fontSizes[0] at
+ * line-height 1.15 plus 2px vertical padding) — CodeView sizes its
+ * virtualization window and sticky offset from this, and the library's own
+ * default of 44 is more than double the compact header.
+ */
+const TRAIL_HEADER_HEIGHT = 18;
+
 /** Pointer/dotted-underline affordance for a clickable construct token. */
 function paintSymbolToken(el: HTMLElement | undefined, active: boolean): void {
   if (el == null) return;
@@ -88,6 +99,12 @@ export interface PierreTrailCodeViewProps {
   background?: string;
   /** Open the step's full source file (header button or double-click snippet body). */
   onOpenFile?: (path: string, opts?: SubsystemOpenFileOptions) => void;
+  /**
+   * Fires when scrolling brings a different step to the top of the view, with
+   * that step's index. Drives a progress readout that tracks the viewport
+   * rather than the selected step. Only fires on change, not per scroll event.
+   */
+  onVisibleStepChange?: (index: number) => 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".
@@ -193,12 +210,15 @@ export function PierreTrailCodeView({
   contextLines = 8,
   background,
   onOpenFile,
+  onVisibleStepChange,
   proposedAliases,
   resolveSymbol,
   onSymbolClick,
 }: PierreTrailCodeViewProps) {
   const { theme, mode } = useTheme();
   const viewRef = useRef<CodeViewHandle<undefined>>(null);
+  // CodeView's scroll container — also the box we measure items against.
+  const containerRef = useRef<HTMLDivElement | null>(null);
   const [load, setLoad] = useState<FileLoadState>({ status: 'loading' });
 
   // Keep the newest symbol callbacks in refs so the Pierre options object stays
@@ -207,6 +227,43 @@ export function PierreTrailCodeView({
   resolveSymbolRef.current = resolveSymbol;
   const onSymbolClickRef = useRef(onSymbolClick);
   onSymbolClickRef.current = onSymbolClick;
+  const onVisibleStepChangeRef = useRef(onVisibleStepChange);
+  onVisibleStepChangeRef.current = onVisibleStepChange;
+  const visibleStepRef = useRef<number | null>(null);
+
+  // Report which step the viewport is on. The geometry lives in `visibleStep` so
+  // it can be tested — the answer depends on how tall the final snippet is
+  // relative to the viewport, which is not something to eyeball.
+  const reportVisibleStep = useCallback(() => {
+    const container = containerRef.current;
+    const viewer = viewRef.current?.getInstance();
+    if (container == null || viewer == null) return;
+    const rect = container.getBoundingClientRect();
+    const rects: VisibleStepRect[] = [];
+    for (const rendered of viewer.getRenderedItems()) {
+      const index = Number.parseInt(rendered.id.split(':').pop() ?? '', 10);
+      if (!Number.isFinite(index)) continue;
+      const itemRect = rendered.element.getBoundingClientRect();
+      rects.push({ index, top: itemRect.top, bottom: itemRect.bottom });
+    }
+    const next = resolveVisibleStepIndex(
+      {
+        top: rect.top,
+        bottom: rect.bottom,
+        scrollTop: container.scrollTop,
+        clientHeight: container.clientHeight,
+        scrollHeight: container.scrollHeight,
+      },
+      rects,
+    );
+    if (next == null || next === visibleStepRef.current) return;
+    visibleStepRef.current = next;
+    onVisibleStepChangeRef.current?.(next);
+  }, []);
+
+  const onCodeViewScroll = useCallback(() => {
+    reportVisibleStep();
+  }, [reportVisibleStep]);
 
   // A step onto a proposed component is planned work; label its missing file
   // accordingly instead of showing a bare "not found".
@@ -346,32 +403,19 @@ export function PierreTrailCodeView({
       context?: { item?: { id?: string } },
     ) => {
       const id = context?.item?.id;
+      // Item-level renders don't move the viewport, but the first paint does
+      // decide which step is on screen.
+      reportVisibleStep();
       if (id == null) return;
       const sliceStart = sliceStartByItemId.get(id);
       if (sliceStart == null) return;
       remapSnippetLineNumbers(node, sliceStart);
     },
-    [sliceStartByItemId],
+    [sliceStartByItemId, reportVisibleStep],
   );
 
-  const renderHeaderPrefix = useMemo(() => {
-    return (item: CodeViewItem) => {
-      const index = Number.parseInt(item.id.split(':').pop() ?? '', 10);
-      if (!trail.steps[index]) return null;
-      return (
-        <span
-          style={{
-            fontFamily: theme.fonts.monospace,
-            fontSize: theme.fontSizes[0],
-            color: theme.colors.textSecondary,
-            marginRight: 8,
-          }}
-        >
-          {index + 1}.
-        </span>
-      );
-    };
-  }, [trail.steps, theme]);
+  // No step numbers in the file header: the sidebar already numbers the steps,
+  // and the drawer header carries a segmented progress readout.
 
   const renderHeaderMetadata = useMemo(() => {
     return (item: CodeViewItem) => {
@@ -495,15 +539,29 @@ export function PierreTrailCodeView({
         light: resolvePierreSyntaxThemeName('light'),
       },
       stickyHeaders: true,
+      // CodeView never injects `unsafeCSS` into its own shadow root, but it
+      // forwards the option to each file item (CODE_VIEW_FILE_OPTION_KEYS),
+      // which does — so this retints the file surfaces and headers. It cannot
+      // reach CodeView's host, hence the spread only carries
+      // PIERRE_BASE_OPTIONS and `disableFileHeader` must follow it.
+      ...buildPierreOptions(background, {
+        background: theme.colors.backgroundSecondary,
+        fontSize: `${theme.fontSizes[0]}px`,
+        lineHeight: '1.15',
+        padding: '2px 8px',
+      }),
       disableFileHeader: false,
+      // The library assumes a 44px header (DEFAULT_VIRTUAL_FILE_METRICS); the
+      // compact chrome above is ~18px. CodeView uses this for its
+      // virtualization window and sticky offset, so leaving it at 44 drifts.
+      itemMetrics: { diffHeaderHeight: TRAIL_HEADER_HEIGHT },
       layout: { paddingTop: 0, paddingBottom: 0, gap: 4 },
       onPostRender,
       ...(onOpenFile ? { onLineClick } : {}),
       ...symbolHandlers,
-      ...(background ? buildPierreOptions(background) : {}),
       ...(mode === 'light' || mode === 'dark' ? { themeType: mode } : {}),
     };
-  }, [background, mode, onPostRender, onOpenFile, onLineClick, symbolHandlers]);
+  }, [background, theme.colors.backgroundSecondary, theme.fontSizes, mode, onPostRender, onOpenFile, onLineClick, symbolHandlers]);
 
   useEffect(() => {
     if (load.status !== 'ready' || stepIndex == null) return;
@@ -549,10 +607,11 @@ export function PierreTrailCodeView({
   return (
     <CodeViewLoose
       ref={viewRef}
+      containerRef={containerRef}
       items={items}
       options={options}
+      onScroll={onCodeViewScroll}
       selectedLines={selectedLines}
-      renderHeaderPrefix={renderHeaderPrefix}
       renderHeaderMetadata={renderHeaderMetadata}
       renderAnnotation={renderAnnotation}
       style={{ ...PIERRE_FILE_STYLE, height: '100%', overflow: 'auto' }}

package/src/pierre/pierreBackground.ts

@@ -6,28 +6,78 @@ export const PIERRE_BASE_OPTIONS = {
   disableFileHeader: true,
 } as const;
 
-export function buildBackgroundCSS(background: string): string {
+/** Chrome overrides for the per-file header (`[data-diffs-header]`). */
+export interface PierreHeaderStyle {
+  /** Fill behind the header row. */
+  background?: string;
+  /** Rule under the header row. */
+  borderBottom?: string;
+  /** Explicit size — the library leaves the header to inherit its line box. */
+  fontSize?: string;
+  lineHeight?: string;
+  /** Vertical padding. The library ships none, so this is the only breathing room. */
+  padding?: string;
+}
+
+/**
+ * Retint Pierre's code surface to `background`, optionally restyling the file
+ * header.
+ *
+ * Every background in `@pierre/diffs` resolves to `--diffs-bg`, which is
+ * `light-dark(var(--diffs-light-bg, #fff), var(--diffs-dark-bg, #000))` — so
+ * overriding both inputs re-tints the whole surface from one variable and lets
+ * the diff / selection / hover layers keep recomputing their `color-mix` tints
+ * against it.
+ *
+ * `:host` still needs a direct override: the theme layer writes a literal
+ * `background-color` there from the Shiki theme, which does not go through
+ * `--diffs-bg`.
+ *
+ * Header rules land in each file item's shadow root, which is where
+ * `FileRenderer` puts the header — `CodeView` forwards `unsafeCSS` to its file
+ * items even though it never injects it into its own shadow root.
+ *
+ * Changing header height also invalidates `itemMetrics.diffHeaderHeight`, which
+ * `CodeView` uses for its virtualization window and sticky offset. Keep the two
+ * in step when overriding `fontSize` / `lineHeight` / `padding`.
+ */
+export function buildBackgroundCSS(
+  background: string,
+  header?: PierreHeaderStyle,
+): string {
+  const headerDeclarations = header
+    ? Object.entries(header)
+        .map(([property, value]) => `  ${kebab(property)}: ${value};`)
+        .join("\n")
+    : "";
+
   return `
   :host {
+    --diffs-light-bg: ${background};
+    --diffs-dark-bg: ${background};
     background: ${background} !important;
   }
-  pre, code,
-  [data-gutter], [data-content],
-  [data-line], [data-column-number],
-  [data-gutter-buffer], [data-line-annotation], [data-no-newline],
-  [data-separator], [data-separator-wrapper] {
-    background: ${background} !important;
-  }
-  [data-line] span {
-    background: ${background} !important;
+  ${
+    headerDeclarations
+      ? `[data-diffs-header] {
+${headerDeclarations}
+  }`
+      : ""
   }
 `;
 }
 
-export function buildPierreOptions(background?: string) {
+function kebab(property: string): string {
+  return property.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`);
+}
+
+export function buildPierreOptions(
+  background?: string,
+  header?: PierreHeaderStyle,
+) {
   if (!background) return PIERRE_BASE_OPTIONS;
   return {
     ...PIERRE_BASE_OPTIONS,
-    unsafeCSS: buildBackgroundCSS(background),
+    unsafeCSS: buildBackgroundCSS(background, header),
   };
 }

package/src/pierre/visibleStep.test.ts

@@ -0,0 +1,108 @@
+import { describe, expect, test } from 'bun:test';
+
+import {
+  AT_END_TOLERANCE_PX,
+  resolveVisibleStepIndex,
+  type VisibleStepRect,
+  type VisibleStepViewport,
+} from "./visibleStep";
+
+/**
+ * Four steps in *content* coordinates. Steps 2 and 3 are short tails, which is
+ * the case that matters: neither can fill a 600px viewport, so at full scroll
+ * the topmost thing on screen is step 1 while the true position is step 3.
+ */
+const CONTENT_RECTS = [
+  { index: 0, top: 0, bottom: 200 },
+  { index: 1, top: 200, bottom: 900 },
+  { index: 2, top: 900, bottom: 1100 },
+  { index: 3, top: 1100, bottom: 1200 },
+];
+
+const CONTENT_HEIGHT = 1200;
+const CLIENT_HEIGHT = 600;
+/** Furthest the view can scroll with this content. */
+const MAX_SCROLL = CONTENT_HEIGHT - CLIENT_HEIGHT;
+
+/** Project the content layout into viewport coordinates at `scrollTop`. */
+function rectsAt(scrollTop: number): VisibleStepRect[] {
+  return CONTENT_RECTS.map((rect) => ({
+    index: rect.index,
+    top: rect.top - scrollTop,
+    bottom: rect.bottom - scrollTop,
+  }));
+}
+
+function viewport(
+  scrollTop: number,
+  overrides: Partial<VisibleStepViewport> = {},
+): VisibleStepViewport {
+  return {
+    top: 0,
+    bottom: CLIENT_HEIGHT,
+    scrollTop,
+    clientHeight: CLIENT_HEIGHT,
+    scrollHeight: CONTENT_HEIGHT,
+    ...overrides,
+  };
+}
+
+function at(scrollTop: number, overrides: Partial<VisibleStepViewport> = {}) {
+  return resolveVisibleStepIndex(
+    viewport(scrollTop, overrides),
+    rectsAt(scrollTop),
+  );
+}
+
+describe('resolveVisibleStepIndex', () => {
+  test('reports the topmost step on screen', () => {
+    expect(at(0)).toBe(0);
+    expect(at(250)).toBe(1);
+  });
+
+  test('reports the last step once the end of the content is on screen', () => {
+    // The regression: at full scroll step 1's tail is still the topmost thing
+    // on screen, but the end of the content has been reached.
+    expect(at(MAX_SCROLL)).toBe(3);
+  });
+
+  test('does not report the end while content remains below', () => {
+    expect(at(300)).toBe(1);
+    // Extra scrollable content below must not be mistaken for the end: step 3
+    // is still well below the viewport here.
+    expect(at(400, { scrollHeight: CONTENT_HEIGHT + 4000 })).toBe(1);
+  });
+
+  test('trusts the scroll extent when the container box is not authoritative', () => {
+    // Nested scroller: the container's own box reports a bottom edge far above
+    // the real end, so only scrollTop/clientHeight/scrollHeight say we're done.
+    expect(at(MAX_SCROLL, { bottom: 100 })).toBe(3);
+  });
+
+  test('ignores the scroll extent when the container does not actually scroll', () => {
+    // An ancestor scrolls instead: scrollTop is pinned at 0 and scrollHeight
+    // equals clientHeight, which must not read as 'at the end' on first paint.
+    const notAScroller = { scrollTop: 0, clientHeight: 600, scrollHeight: 600 };
+    expect(at(0, { ...notAScroller, bottom: 100 })).toBe(0);
+  });
+
+  test('tolerates a bottom edge a fraction of a pixel off', () => {
+    expect(
+      at(MAX_SCROLL, { scrollHeight: CONTENT_HEIGHT + AT_END_TOLERANCE_PX }),
+    ).toBe(3);
+  });
+
+  test('returns null when nothing is on screen', () => {
+    expect(resolveVisibleStepIndex(viewport(0), [])).toBeNull();
+    expect(
+      resolveVisibleStepIndex(viewport(0), [
+        { index: 0, top: -800, bottom: -400 },
+      ]),
+    ).toBeNull();
+  });
+
+  test('uses the highest index even when rects arrive out of order', () => {
+    const shuffled = [...rectsAt(MAX_SCROLL)].reverse();
+    expect(resolveVisibleStepIndex(viewport(MAX_SCROLL), shuffled)).toBe(3);
+  });
+});

package/src/pierre/visibleStep.ts

@@ -0,0 +1,76 @@
+/**
+ * visibleStep — pick which step a scroll position should report as current.
+ *
+ * Kept separate from the component so the geometry can be tested directly:
+ * the answer depends on how tall the final snippet is relative to the
+ * viewport, which is not something to eyeball.
+ */
+
+/** A mounted CodeView item reduced to what the choice depends on. */
+export interface VisibleStepRect {
+  /** Step index parsed from the item id. */
+  index: number;
+  /** Viewport-relative top edge, in px. */
+  top: number;
+  /** Viewport-relative bottom edge, in px. */
+  bottom: number;
+}
+
+/** The scroll container's box plus its scroll metrics, in px. */
+export interface VisibleStepViewport {
+  top: number;
+  bottom: number;
+  scrollTop: number;
+  clientHeight: number;
+  scrollHeight: number;
+}
+
+/** Sub-pixel slack so a bottom edge that lands a hair off still counts. */
+export const AT_END_TOLERANCE_PX = 2;
+
+/**
+ * Index of the step to report as current.
+ *
+ * Normally the topmost step still on screen. The exception is the end of the
+ * content: when the final snippet is shorter than the viewport, reaching the
+ * bottom still leaves the previous step's tail on screen, and reporting that
+ * would strand a progress readout one step short of full.
+ *
+ * 'At the end' is accepted two ways, because either can be the authoritative
+ * one depending on how the view is nested:
+ *   - the lowest mounted item's bottom edge has entered the container's box, or
+ *   - the container's own scroll offset has reached its scroll extent.
+ *
+ * The second signal is only consulted when the container actually scrolls. If
+ * an ancestor scrolls instead, `scrollHeight` equals `clientHeight` and
+ * `scrollTop` is pinned at 0, which would otherwise read as 'at the end' from
+ * the very first pixel.
+ *
+ * Returns `null` when nothing measurable is on screen.
+ */
+export function resolveVisibleStepIndex(
+  viewport: VisibleStepViewport,
+  rects: readonly VisibleStepRect[],
+): number | null {
+  let topIndex: number | null = null;
+  let lastIndex: number | null = null;
+  let lowestBottom = Number.NEGATIVE_INFINITY;
+
+  for (const rect of rects) {
+    if (topIndex == null && rect.bottom > viewport.top) topIndex = rect.index;
+    if (lastIndex == null || rect.index > lastIndex) lastIndex = rect.index;
+    if (rect.bottom > lowestBottom) lowestBottom = rect.bottom;
+  }
+  if (topIndex == null) return null;
+
+  const reachedLastItem = lowestBottom <= viewport.bottom + AT_END_TOLERANCE_PX;
+  const containerScrolls = viewport.scrollHeight > viewport.clientHeight;
+  const reachedScrollEnd =
+    containerScrolls &&
+    viewport.scrollTop + viewport.clientHeight >=
+      viewport.scrollHeight - AT_END_TOLERANCE_PX;
+
+  return reachedLastItem || reachedScrollEnd
+    ? (lastIndex ?? topIndex)
+    : topIndex;
+}

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

@@ -173,6 +173,7 @@ function FlowsDemo() {
       proposedAliases,
       resolveSymbol,
       onSymbolClick,
+      onVisibleStepChange,
     }: TrailViewerContext) => (
       <PierreTrailCodeView
         trail={trail}
@@ -183,6 +184,7 @@ function FlowsDemo() {
         proposedAliases={proposedAliases}
         resolveSymbol={resolveSymbol}
         onSymbolClick={onSymbolClick}
+        onVisibleStepChange={onVisibleStepChange}
       />
     ),
     [],
@@ -281,6 +283,7 @@ function ProposedMissingStepDemo() {
       proposedAliases,
       resolveSymbol,
       onSymbolClick,
+      onVisibleStepChange,
     }: TrailViewerContext) => (
       <PierreTrailCodeView
         trail={trail}
@@ -291,6 +294,7 @@ function ProposedMissingStepDemo() {
         proposedAliases={proposedAliases}
         resolveSymbol={resolveSymbol}
         onSymbolClick={onSymbolClick}
+        onVisibleStepChange={onVisibleStepChange}
       />
     ),
     [],
@@ -480,6 +484,7 @@ function ClickableConstructsDemo() {
       proposedAliases,
       resolveSymbol,
       onSymbolClick,
+      onVisibleStepChange,
     }: TrailViewerContext) => (
       <PierreTrailCodeView
         trail={trail}
@@ -490,6 +495,7 @@ function ClickableConstructsDemo() {
         proposedAliases={proposedAliases}
         resolveSymbol={resolveSymbol}
         onSymbolClick={onSymbolClick}
+        onVisibleStepChange={onVisibleStepChange}
       />
     ),
     [],