feat(tui): scroll the overlay list with the host scrollbar

Author: TheGreatAxios

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

@@ -484,7 +484,8 @@ 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.content);
+      expect(list.viewport.parent).toBe(shell.overlayView.body);
+      expect(list.select.isDestroyed).toBe(false);
 
       let resolved: unknown;
       emitter.emit("permission.gate", {
@@ -501,8 +502,8 @@ 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.content);
-      expect(shell.overlayView.body.getChildren()).toContain(list.select);
+      expect(list.viewport.parent).toBe(shell.overlayView.body);
+      expect(shell.overlayView.body.getChildren()).toContain(list.viewport);
     });
   });
 

src/tui/overlay-paint.test.ts

@@ -83,15 +83,18 @@ async function paintOverlay(
 /**
  * Every interior row must be blank or exactly one expected overlay row; two
  * renderables sharing cells produces a hybrid string that matches nothing.
+ * A native ScrollBar thumb occupies the last column when the list overflows;
+ * that glyph is not a second copy of the row.
  */
 function expectCleanInterior(
   interior: readonly string[],
   expected: readonly string[],
 ): void {
   const allowed = new Set(expected.map((e) => e.trimEnd()));
   for (const row of interior) {
-    if (row.trim().length === 0) continue;
-    expect(allowed.has(row)).toBe(true);
+    const withoutBar = row.replace(/[▀▄█▌▐░▒▓]+$/u, "").trimEnd();
+    if (withoutBar.length === 0) continue;
+    expect(allowed.has(withoutBar)).toBe(true);
   }
 }
 
@@ -125,7 +128,8 @@ describe("overlay host never shares cells with the prompt border", () => {
       expectCleanInterior(interior.slice(1), expected);
 
       // The selected row must be intact, not overwritten by the model label.
-      expect(interior).toContain(` ${ITEMS[0]}`);
+      // A ScrollBar thumb may sit on the same line, so match the label prefix.
+      expect(interior.some((row) => row.startsWith(` ${ITEMS[0]}`))).toBe(true);
       for (const row of interior) {
         expect(row.includes(MODEL_LABEL)).toBe(false);
         expect(row.includes("alice")).toBe(false);

src/tui/overlay-view.ts

@@ -1,6 +1,5 @@
 import {
   BoxRenderable,
-  ScrollBoxRenderable,
   TextRenderable,
   type RenderContext,
 } from "@opentui/core";
@@ -317,24 +316,13 @@ export function createOverlayView(ctx: RenderContext) {
     content: " overlay",
     fg: UI.textDim,
   });
-  const body = new ScrollBoxRenderable(ctx, {
+  const body = new BoxRenderable(ctx, {
     id: "shell-overlay-body",
     width: "100%",
     flexGrow: 1,
-    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 },
+    flexDirection: "column",
+    backgroundColor: UI.ground,
   });
-  body.horizontalScrollBar.visible = false;
-  body.horizontalScrollBar.focusable = false;
-  body.verticalScrollBar.focusable = false;
   host.add(title);
   host.add(body);
 
@@ -385,8 +373,8 @@ export function createOverlayView(ctx: RenderContext) {
       name: line,
       description: "",
     }));
-    body.add(list.select);
-    revealList(list);
+    body.add(list.viewport);
+    list.scrollActiveIntoView();
   }
 
   /** Rule + two-line description zone, painted when `describe` is set. */
@@ -427,18 +415,11 @@ export function createOverlayView(ctx: RenderContext) {
   }
 
   /**
-   * Detach the select before `clearBody` destroys the body's children — the
-   * list owns it across paints. ScrollBox.add parents into content, so the
-   * select's parent is not the scrollbox itself.
+   * Detach the list viewport before `clearBody` destroys the body's children —
+   * the list owns the select inside that ScrollBox across paints.
    */
   function detachList(list: OverlayList): void {
-    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);
+    if (list.viewport.parent) body.remove(list.viewport);
   }
 
   function paintList(
@@ -475,11 +456,11 @@ export function createOverlayView(ctx: RenderContext) {
     });
     // An empty list renders nothing: the renderable would claim a background
     // row the chooser did not reserve.
-    if (presentation.items.length > 0) body.add(list.select);
+    if (presentation.items.length > 0) body.add(list.viewport);
     else addOverlayRow(` ${OVERLAY_EMPTY_STATE}`, UI.textDim);
     paintAnswerRow(presentation.answer, contentWidth);
     paintDescriptionZone(presentation.describe, contentWidth);
-    revealList(list);
+    list.scrollActiveIntoView();
   }
 
   function paintTitle(

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: ScrollBoxRenderable;
+  readonly overlayBody: BoxRenderable;
   readonly prompt: PromptInput;
   readonly promptBox: BoxRenderable;
   /** The input's own row, bordered left and right only. */
@@ -546,6 +546,8 @@ export interface OverlayListRange {
  * rebuilds on geometry change. */
 export interface OverlayList {
   readonly select: SelectRenderable;
+  /** ScrollBox that clips the select and owns the host ScrollBar. */
+  readonly viewport: ScrollBoxRenderable;
   readonly activeIndex: number;
   /** Item-row capacity reserved by layout (not the renderable's row height). */
   readonly height: number;
@@ -557,6 +559,8 @@ export interface OverlayList {
   jump(index: number): void;
   setCount(count: number): void;
   setHeight(items: number, rowsPerItem?: number): void;
+  /** Move the host ScrollBox so the active row is inside the viewport. */
+  scrollActiveIntoView(): void;
   visibleRange(): OverlayListRange;
 }
 

src/tui/shell/overlay-list.ts

@@ -2,6 +2,8 @@
  * The overlay list wrapper (SelectRenderable) and its selection delegations.
  */
 import {
+  BoxRenderable,
+  ScrollBoxRenderable,
   SelectRenderable,
   type KeyEvent,
   type RenderContext,
@@ -133,20 +135,19 @@ function placeholderOptions(count: number): SelectOption[] {
 }
 
 /**
- * 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.
+ * Select keeps scroll offset private. The window is the same centered slice
+ * it would paint, taken from the reserved slot count rather than a reflective
+ * read. The ScrollBox viewport is what actually scrolls; this only names the
+ * slice.
  */
-function selectWindow(
-  select: SelectRenderable,
+function listWindow(
+  index: number,
   count: number,
-  rowsPerItem: number,
+  slots: 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 visible = Math.max(1, slots);
   const half = Math.floor(visible / 2);
-  const index = select.getSelectedIndex();
   const offset = Math.max(
     0,
     Math.min(index - half, Math.max(0, count - visible)),
@@ -166,12 +167,17 @@ export function createOverlayList(
   const activeIndex = opts.activeIndex ?? 0;
   let options = placeholderOptions(count);
 
+  const rowSpan = (): number => Math.max(1, shape.rowsPerItem);
+
   const build = (): SelectRenderable =>
     new SelectRenderable(ctx, {
       id: "shell-overlay-select",
       options,
       selectedIndex: activeIndex,
-      height: shape.items * shape.rowsPerItem,
+      // Full list, not the visible window. The viewport ScrollBox clips it and
+      // owns the scrollbar; a window-sized select would scroll a second time
+      // inside itself and the bar would never see overflow.
+      height: Math.max(rowSpan(), Math.max(shape.items, count) * rowSpan()),
       width: "100%",
       flexShrink: 0,
       showDescription: shape.rowsPerItem > 1,
@@ -193,6 +199,72 @@ export function createOverlayList(
 
   let select = build();
 
+  const viewport = new ScrollBoxRenderable(ctx, {
+    id: "shell-overlay-list-scroll",
+    width: "100%",
+    height: Math.max(1, shape.items * rowSpan()),
+    flexShrink: 0,
+    // Arrow keys stay on the shell's selection handler. A focusable scrollbox
+    // would page itself and steal the list.
+    focusable: false,
+    viewportCulling: true,
+    scrollY: true,
+    stickyScroll: false,
+    rootOptions: { backgroundColor: UI.ground },
+    contentOptions: { backgroundColor: UI.ground },
+    viewportOptions: { backgroundColor: UI.ground },
+  });
+  viewport.horizontalScrollBar.visible = false;
+  viewport.horizontalScrollBar.focusable = false;
+  viewport.verticalScrollBar.focusable = false;
+  // Vertical bar stays on the native auto rule: visible once the select is
+  // taller than the slot window. Forcing it off is the transcript's choice,
+  // not the overlay host's.
+  const placed = viewport.content.onSizeChange;
+  let revealing = false;
+
+  // Absolute marker at the active row. scrollChildIntoView on the whole select
+  // is a no-op when the select is taller than the viewport (both edges outside).
+  const anchor = new BoxRenderable(ctx, {
+    id: "shell-overlay-active-anchor",
+    position: "absolute",
+    left: 0,
+    width: 1,
+    height: rowSpan(),
+    top: 0,
+  });
+  viewport.add(select);
+  viewport.add(anchor);
+
+  const reveal = (): void => {
+    if (revealing) return;
+    revealing = true;
+    try {
+      const row = rowSpan();
+      const slots = Math.max(1, shape.items);
+      viewport.height = slots * row;
+      select.height = Math.max(row, Math.max(slots, count) * row);
+      const index = select.getSelectedIndex();
+      anchor.height = row;
+      anchor.top = index * row;
+      const { offset } = listWindow(index, count, slots);
+      const y = count === 0 ? 0 : offset * row;
+      viewport.scrollTop = y;
+      if (count > 0 && anchor.y !== 0 && viewport.viewport.y !== 0) {
+        viewport.scrollChildIntoView(anchor.id);
+      }
+      // Applied last: scrollTop clamps until the bar has a content size, and
+      // that clamp rewrites translateY. The viewport paints this translation.
+      viewport.content.translateY = -y;
+    } finally {
+      revealing = false;
+    }
+  };
+  viewport.content.onSizeChange = () => {
+    placed?.call(viewport.content);
+    reveal();
+  };
+
   const reshape = (next: Partial<OverlayListShape>): void => {
     const merged = { ...shape, ...next };
     if (
@@ -205,16 +277,22 @@ export function createOverlayList(
     // (clamped to the new count) so a resize does not snap the cursor back.
     const current = select.getSelectedIndex();
     shape = merged;
+    if (select.parent) viewport.remove(select);
     select = build();
+    viewport.add(select, 0);
     select.setSelectedIndex(
       count === 0 ? 0 : Math.min(count - 1, Math.max(0, current)),
     );
+    reveal();
   };
 
+  reveal();
+
   return {
     get select() {
       return select;
     },
+    viewport,
     get activeIndex() {
       return select.getSelectedIndex();
     },
@@ -225,14 +303,15 @@ export function createOverlayList(
       return shape.rowsPerItem;
     },
     get offset() {
-      return selectWindow(select, count, shape.rowsPerItem).offset;
+      return listWindow(select.getSelectedIndex(), count, shape.items).offset;
     },
     get count() {
       return count;
     },
     move(delta: number) {
       if (delta < 0) select.moveUp(-delta);
       else if (delta > 0) select.moveDown(delta);
+      reveal();
     },
     page(dir: -1 | 1) {
       this.move(dir * (shape.items > 1 ? shape.items - 1 : 1));
@@ -242,20 +321,29 @@ export function createOverlayList(
       select.setSelectedIndex(
         Math.max(0, Math.min(count - 1, Math.floor(index))),
       );
+      reveal();
     },
     setCount(next: number) {
       count = Math.max(0, Math.floor(next));
       options = placeholderOptions(count);
       select.options = options;
+      reveal();
     },
     setHeight(items: number, rowsPerItem?: number) {
       reshape({
         items: Math.max(0, Math.floor(items)),
         ...(rowsPerItem ? { rowsPerItem } : {}),
       });
     },
+    scrollActiveIntoView() {
+      reveal();
+    },
     visibleRange() {
-      const { offset, visible } = selectWindow(select, count, shape.rowsPerItem);
+      const { offset, visible } = listWindow(
+        select.getSelectedIndex(),
+        count,
+        shape.items,
+      );
       return { start: offset, end: Math.min(count, offset + visible) };
     },
   };