fix(tui): stop a size pass from snapping one detent to the tail

OpenTUI re-engages bottom sticky at one row above the tail. Sticky
now stays armed only while scrollTop is on the tail, so a same-height
size pass leaves that detent pinned. Growth while the tail is followed
still sticks.

CL-10642

Author: TheGreatAxios

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

@@ -485,7 +485,6 @@ describe("CL-8792 overlay host: suspend preserves the surface instead of dismiss
       const list = defined(shell.overlayList, "slash list");
       expect(list.select.isDestroyed).toBe(false);
       expect(list.viewport.parent).toBe(shell.overlayView.body);
-      expect(list.select.isDestroyed).toBe(false);
 
       let resolved: unknown;
       emitter.emit("permission.gate", {

src/tui/shell.test.ts

@@ -125,6 +125,37 @@ describe("createAppShell", () => {
     );
   });
 
+  test("one wheel detent survives a same-height content size pass", async () => {
+    await withTestRenderer(
+      async (h) => {
+        const shell = createAppShell(h.renderer, {
+          terminal: { columns: 80, rows: 24 },
+          wireKeys: false,
+        });
+        try {
+          for (let i = 0; i < 50; i++) {
+            appendTranscript(shell, `seed-${i}`);
+          }
+          await h.renderOnce();
+          const max = Math.max(
+            0,
+            shell.transcript.scrollHeight - shell.transcript.height,
+          );
+          expect(max).toBeGreaterThan(1);
+          const scrollHeight = shell.transcript.scrollHeight;
+          shell.transcript.scrollTop = max - 1;
+          shell.transcript.content.onSizeChange?.();
+          expect(shell.transcript.scrollHeight).toBe(scrollHeight);
+          expect(shell.transcript.scrollTop).toBe(max - 1);
+          expect(isTranscriptFollowing(shell)).toBe(false);
+        } finally {
+          shell.dispose();
+        }
+      },
+      { width: 80, height: 24 },
+    );
+  });
+
   test("one wheel detent up from a followed tail stays off the bottom", async () => {
     await withTestRenderer(
       async (h) => {

src/tui/shell/chrome.ts

@@ -1065,9 +1065,7 @@ export function syncTranscriptSpacer(shell: AppShell): void {
   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. */
+/** Keep the newest row in view while the tail is followed. */
 export function followTranscriptTail(shell: AppShell): void {
   if (isLanding(shell) || !isTranscriptFollowing(shell)) return;
   const last = shell.transcript.getChildren().at(-1);
@@ -1393,7 +1391,7 @@ export function replaceStreamRowAt(
 export function repaintTranscriptWindow(shell: AppShell): void {
   clearLandingMark(shell);
   shell.agentVoices = new Set(agentVoicesIn(shell.streamLog));
-  // The bottom-anchor spacer (index 0) stays; the eviction notice (if any)
+  // Index 0 is the zero-height spacer and stays; the eviction notice (if any)
   // and every row get torn down and rebuilt from the log.
   for (const child of shell.transcript.getChildren().slice(1)) {
     shell.transcript.remove(child);

src/tui/shell/index.ts

@@ -34,6 +34,7 @@ import { flushStreamRowUpdates } from "../runtime-bridge.js";
 import {
   type AppShell,
   type AppShellOptions,
+  bindTranscriptTailSticky,
   EMPTY_PRIMARY_BINDINGS,
   flashTimers,
   initShellInternals,
@@ -213,6 +214,7 @@ export function createAppShell(
   // row restating it.
   transcript.verticalScrollBar.visible = false;
   transcript.horizontalScrollBar.visible = false;
+  bindTranscriptTailSticky(transcript);
   // Markdown links live on nodes we do not own; this bubbling handler arms
   // them (armed rows stop propagation, so a click opens exactly once).
   armMarkdownLinks(transcript, ctx);

src/tui/shell/internals.ts

@@ -498,16 +498,41 @@ export type PrimaryOverlayKind =
   | "mcp"
   | "plugin_credentials";
 
-/** Whether the transcript viewport is stuck to the bottom (FOLLOW vs PINNED).
- * The bottom is `scrollTop >= max` only. `max - 1` is one wheel detent up;
- * treating it as followed makes the next frame's `scrollChildIntoView` yank
- * the tail back. */
+/** True when the viewport is on the tail (`scrollTop >= max`). */
 export function isTranscriptFollowing(shell: AppShell): boolean {
   const { transcript } = shell;
   const max = Math.max(0, transcript.scrollHeight - transcript.height);
   return transcript.scrollTop >= max;
 }
 
+/** Bottom sticky stays armed only on the tail, so one detent up stays pinned. */
+export function bindTranscriptTailSticky(
+  transcript: ScrollBoxRenderable,
+): void {
+  const desc = Object.getOwnPropertyDescriptor(
+    Object.getPrototypeOf(transcript),
+    "scrollTop",
+  );
+  const get = desc?.get;
+  const set = desc?.set;
+  if (get === undefined || set === undefined) {
+    throw new Error("ScrollBox scrollTop accessor is missing");
+  }
+  const sync = (): void => {
+    const max = Math.max(0, transcript.scrollHeight - transcript.height);
+    transcript.stickyScroll = transcript.scrollTop >= max;
+  };
+  Object.defineProperty(transcript, "scrollTop", {
+    configurable: true,
+    enumerable: true,
+    get: () => get.call(transcript),
+    set: (value: number) => {
+      set.call(transcript, value);
+      sync();
+    },
+  });
+}
+
 /** Sticky-scroll mode label (surfaced on the notice row only when PINNED). */
 export function stickyMode(shell: AppShell): "FOLLOW" | "PINNED" {
   return isTranscriptFollowing(shell) ? "FOLLOW" : "PINNED";

src/tui/shell/overlay-list.ts

@@ -223,8 +223,6 @@ export function createOverlayList(
   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",
@@ -253,8 +251,6 @@ export function createOverlayList(
       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;