feat(tui): scroll the transcript and overlay through ScrollBox

Author: TheGreatAxios

src/tui/allow-once-reprompt.test.ts

@@ -484,7 +484,7 @@ describe("CL-8792 overlay host: suspend preserves the surface instead of dismiss
       openSlash(shell);
       const list = defined(shell.overlayList, "slash list");
       expect(list.select.isDestroyed).toBe(false);
-      expect(list.select.parent).toBe(shell.overlayView.body);
+      expect(list.select.parent).toBe(shell.overlayView.body.content);
 
       let resolved: unknown;
       emitter.emit("permission.gate", {
@@ -501,7 +501,7 @@ describe("CL-8792 overlay host: suspend preserves the surface instead of dismiss
       expect(shell.overlayKind).toBe("help");
       expect(shell.overlayList).toBe(list);
       expect(list.select.isDestroyed).toBe(false);
-      expect(list.select.parent).toBe(shell.overlayView.body);
+      expect(list.select.parent).toBe(shell.overlayView.body.content);
       expect(shell.overlayView.body.getChildren()).toContain(list.select);
     });
   });

src/tui/overlay-view.ts

@@ -1,5 +1,6 @@
 import {
   BoxRenderable,
+  ScrollBoxRenderable,
   TextRenderable,
   type RenderContext,
 } from "@opentui/core";
@@ -316,13 +317,24 @@ export function createOverlayView(ctx: RenderContext) {
     content: " overlay",
     fg: UI.textDim,
   });
-  const body = new BoxRenderable(ctx, {
+  const body = new ScrollBoxRenderable(ctx, {
     id: "shell-overlay-body",
     width: "100%",
     flexGrow: 1,
-    flexDirection: "column",
-    backgroundColor: UI.ground,
+    flexShrink: 1,
+    // The host scrolls as one surface. Arrow keys stay on the list selection;
+    // the scrollbox must not take focus and page itself.
+    focusable: false,
+    viewportCulling: true,
+    scrollY: true,
+    stickyScroll: false,
+    rootOptions: { backgroundColor: UI.ground },
+    contentOptions: { backgroundColor: UI.ground },
+    viewportOptions: { backgroundColor: UI.ground },
   });
+  body.horizontalScrollBar.visible = false;
+  body.horizontalScrollBar.focusable = false;
+  body.verticalScrollBar.focusable = false;
   host.add(title);
   host.add(body);
 
@@ -374,6 +386,7 @@ export function createOverlayView(ctx: RenderContext) {
       description: "",
     }));
     body.add(list.select);
+    revealList(list);
   }
 
   /** Rule + two-line description zone, painted when `describe` is set. */
@@ -415,10 +428,17 @@ export function createOverlayView(ctx: RenderContext) {
 
   /**
    * Detach the select before `clearBody` destroys the body's children — the
-   * list owns it across paints.
+   * list owns it across paints. ScrollBox.add parents into content, so the
+   * select's parent is not the scrollbox itself.
    */
   function detachList(list: OverlayList): void {
-    if (list.select.parent === body) body.remove(list.select);
+    if (list.select.parent) body.remove(list.select);
+  }
+
+  /** Keep the live choice inside the host viewport after a paint or move. */
+  function revealList(list: OverlayList): void {
+    if (list.select.parent === null || list.select.height <= 0) return;
+    body.scrollChildIntoView(list.select.id);
   }
 
   function paintList(
@@ -459,6 +479,7 @@ export function createOverlayView(ctx: RenderContext) {
     else addOverlayRow(` ${OVERLAY_EMPTY_STATE}`, UI.textDim);
     paintAnswerRow(presentation.answer, contentWidth);
     paintDescriptionZone(presentation.describe, contentWidth);
+    revealList(list);
   }
 
   function paintTitle(

src/tui/shell/chrome.ts

@@ -1047,23 +1047,35 @@ export function syncPromptRows(shell: AppShell): void {
 }
 
 /**
- * Resize the leading filler to soak leftover viewport space (`scrollHeight`
- * minus filler). Not at row-mutation time: mid-layout rows read short for a
- * frame, so a filler grown then would bury one. The render-frame hook calls
- * it after that pass.
+ * Pin a short transcript to the prompt. ScrollBox content is already at least
+ * the viewport tall (`minHeight: "100%"`); justify-end packs the rows against
+ * the bottom. The landing positions its own mark, so flex-end there would
+ * shove it twice. The index-0 spacer stays at height 0 — growing it was the
+ * old anchor.
  */
+const transcriptJustify = new WeakMap<AppShell, "flex-start" | "flex-end">();
+
 export function syncTranscriptSpacer(shell: AppShell): void {
   const spacer = transcriptSpacers.get(shell);
   if (spacer === undefined) return;
-  // The landing already bottom-anchors its mark via the above/below split; a
-  // filler would double-count and squeeze it.
-  if (isLanding(shell)) {
-    if (spacer.height !== 0) spacer.height = 0;
-    return;
-  }
-  const rowsHeight = Math.max(0, shell.transcript.scrollHeight - spacer.height);
-  const nextHeight = Math.max(0, shell.transcript.height - rowsHeight);
-  if (spacer.height !== nextHeight) spacer.height = nextHeight;
+  if (spacer.height !== 0) spacer.height = 0;
+  const justify = isLanding(shell) ? "flex-start" : "flex-end";
+  if (transcriptJustify.get(shell) === justify) return;
+  shell.transcript.contentOptions = { justifyContent: justify };
+  transcriptJustify.set(shell, justify);
+}
+
+/** Keep the newest row in view while the tail is followed. A child that has
+ * not been laid out reports `y === 0`; scrolling that into view yanks the
+ * viewport off the tail. */
+export function followTranscriptTail(shell: AppShell): void {
+  if (isLanding(shell) || !isTranscriptFollowing(shell)) return;
+  const last = shell.transcript.getChildren().at(-1);
+  if (last === undefined || last.id === "shell-transcript-spacer") return;
+  if (last.height <= 0) return;
+  const viewportY = shell.transcript.viewport.y;
+  if (last.y === 0 && viewportY !== 0) return;
+  shell.transcript.scrollChildIntoView(last.id);
 }
 
 export function relayout(shell: AppShell, opts?: RelayoutOpts): GeometryLayout {

src/tui/shell/index.ts

@@ -66,6 +66,7 @@ import {
   syncNoticeAfterLayout,
   syncPromptRows,
   syncTranscriptSpacer,
+  followTranscriptTail,
 } from "./chrome.js";
 import {
   clearPendingAttachments,
@@ -202,6 +203,7 @@ export function createAppShell(
     stickyScroll: true,
     stickyStart: "bottom",
     scrollY: true,
+    viewportCulling: true,
     focusable: true,
     rootOptions: { backgroundColor: UI.ground },
     contentOptions: { backgroundColor: UI.ground },
@@ -215,8 +217,9 @@ export function createAppShell(
   // them (armed rows stop propagation, so a click opens exactly once).
   armMarkdownLinks(transcript, ctx);
 
-  // Leading filler that bottom-anchors a short transcript; see
-  // `syncTranscriptSpacer`. Zero height until the first sync call.
+  // Index 0 stays a zero-height spacer so row offsets do not move. Short
+  // transcripts bottom-align through the scroll content (see
+  // `syncTranscriptSpacer`), not by growing this filler.
   const transcriptSpacer = new BoxRenderable(ctx, {
     id: "shell-transcript-spacer",
     width: "100%",
@@ -388,6 +391,7 @@ export function createAppShell(
     // After a natural render, not at mutation time: the row's box needs a
     // layout pass to size itself, and claiming the padding first starves it.
     syncTranscriptSpacer(shell);
+    followTranscriptTail(shell);
     syncNoticeAfterLayout(shell);
   };
 

src/tui/shell/internals.ts

@@ -356,7 +356,7 @@ export interface AppShell {
   readonly overlayView: ReturnType<typeof createOverlayView>;
   readonly overlayHost: BoxRenderable;
   readonly overlayTitle: TextRenderable;
-  readonly overlayBody: BoxRenderable;
+  readonly overlayBody: ScrollBoxRenderable;
   readonly prompt: PromptInput;
   readonly promptBox: BoxRenderable;
   /** The input's own row, bordered left and right only. */
@@ -723,11 +723,9 @@ interface ShellInternals {
 
 export const internals = new WeakMap<AppShell, ShellInternals>();
 
-/** Filler row sized to leftover viewport space so a short transcript
- * bottom-anchors against the prompt box; settles at zero once rows fill it.
- * A real child, not padding: `minHeight: "100%"` counts padding as viewport
- * height, so `scrollHeight - spacer.height` isolates the rows.
- * Index 0 is always the spacer. */
+/** Index-0 child of the transcript. Height stays 0: short logs bottom-align
+ * via the scroll content's justify-end, not a filler resized every frame.
+ * The node remains so row children keep a stable offset. */
 export const transcriptSpacers = new WeakMap<AppShell, BoxRenderable>();
 
 /** True while the landing composition is still mounted. */

src/tui/shell/overlay-list.ts

@@ -133,22 +133,25 @@ function placeholderOptions(count: number): SelectOption[] {
 }
 
 /**
- * SelectRenderable keeps scroll offset and visible-item capacity private
- * (@opentui/core 0.5.10 exposes no accessors), so read them reflectively
- * and narrow instead of asserting a shape.
+ * SelectRenderable keeps its scroll offset private. The painted window is the
+ * same centered slice Select computes from its public height and selection,
+ * so callers can read it without reflecting into private fields.
  */
-function selectScrollState(select: SelectRenderable): {
-  offset: number;
-  visible: number;
-} {
-  const numberProp = (name: string): number => {
-    const value = Object.getOwnPropertyDescriptor(select, name)?.value;
-    return typeof value === "number" ? value : 1;
-  };
-  return {
-    offset: numberProp("scrollOffset"),
-    visible: Math.max(1, numberProp("maxVisibleItems")),
-  };
+function selectWindow(
+  select: SelectRenderable,
+  count: number,
+  rowsPerItem: number,
+): { offset: number; visible: number } {
+  if (count === 0) return { offset: 0, visible: 0 };
+  const linesPerItem = Math.max(1, rowsPerItem);
+  const visible = Math.max(1, Math.floor(select.height / linesPerItem));
+  const half = Math.floor(visible / 2);
+  const index = select.getSelectedIndex();
+  const offset = Math.max(
+    0,
+    Math.min(index - half, Math.max(0, count - visible)),
+  );
+  return { offset, visible };
 }
 
 export function createOverlayList(
@@ -165,6 +168,7 @@ export function createOverlayList(
 
   const build = (): SelectRenderable =>
     new SelectRenderable(ctx, {
+      id: "shell-overlay-select",
       options,
       selectedIndex: activeIndex,
       height: shape.items * shape.rowsPerItem,
@@ -221,7 +225,7 @@ export function createOverlayList(
       return shape.rowsPerItem;
     },
     get offset() {
-      return selectScrollState(select).offset;
+      return selectWindow(select, count, shape.rowsPerItem).offset;
     },
     get count() {
       return count;
@@ -251,7 +255,7 @@ export function createOverlayList(
       });
     },
     visibleRange() {
-      const { offset, visible } = selectScrollState(select);
+      const { offset, visible } = selectWindow(select, count, shape.rowsPerItem);
       return { start: offset, end: Math.min(count, offset + visible) };
     },
   };