@cplieger/web-terminal-engine 5.0.3 → 5.0.5

package/README.md

@@ -81,7 +81,7 @@ document.addEventListener("keydown", (ev) => {
 - **`keyboard`** — Translates `KeyboardEvent` to terminal byte sequences. `mapKeyboardEvent`, `bracketTextForPaste`, `prepareTextForTerminal`, `ctrlByteFor`, plus the shared logical-key encodings (`plainCursorKeySeq`, `plainEscapeSeq`) the toolbar module reuses. Honors `applicationCursor`, `applicationKeypad`, `bracketedPaste`.
 - **`toolbar`** — On-screen mobile toolbar widget (moved out of `keyboard` in v3). `bindMobileToolbar({toolbar, send, ids?})` wires `pointerdown` handlers for an on-screen Ctrl/arrows/Tab/Enter/Esc toolbar (with sticky-Ctrl semantics and kitty/DECCKM-aware arrows byte-identical to the physical-key path), returning a `MobileToolbarController` exposing `applyStickyCtrl`, `setCtrlArmed`, `isCtrlArmed`, and `dispose`.
 - **`mouse`** — SGR 1006 mouse + focus reporting encoder. `init`, `encodeSGR`, `MouseInputHandler`. Auto-gates on `mouseMode > 0`.
-- **`scroll`** — Auto-follow tracker for the scroll container. `init`, `stickToBottom`, `scrollToBottom`, `isUserScrolledUp`.
+- **`scroll`** — Auto-follow tracker for the scroll container. `init`, `stickToBottom`, `scrollToBottom`, `isUserScrolledUp`, `currentScrollTop`, `restoreView`, `adjustForContentShift`, plus two renderer seams: `noteContentShrink(scrollTopBefore)` says a row removal rather than a gesture caused the scroll event about to arrive, and `reconcileScrollRange()` moves the offset back inside the container's range when the container did not reconcile the shrink itself. The second exists because clamping an offset the content shrank out from under is an implementation behaviour and not a specified one: Blink and Gecko reconcile during layout, WebKit does not, and without the correction an iOS viewport is left parked past the end of the content after an application clears the screen, showing background with the content above it until the reader scrolls.
 - **`modes`** — DEC private mode state (synced from server's `ModesMessage`). `setModes`, `isBracketedPaste`, `isApplicationCursor`, `getMouseMode`, `isMouseSGR`, `isFocusReporting`, `isApplicationKeypad`, `isReverseVideo`.
 - **`decodeWireBinary(buf)`**: Top-level decoder for the binary WebSocket frames. Returns a `ServerMessage` or `null` for invalid/truncated frames.
 - **Wire compatibility metadata**: `WIRE_PROTOCOL_VERSION`, `MIN_SUPPORTED_SERVER_WIRE_VERSION`, `WIRE_INCOMPATIBLE_CLOSE_CODE`, and `WIRE_COMPATIBILITY` publish this client release's directional contract. The same values ship as a language-neutral JSON artifact for non-TypeScript consumers — see [Wire compatibility manifest](#wire-compatibility-manifest).

package/jsr.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/web-terminal-engine",
-  "version": "5.0.3",
+  "version": "5.0.5",
   "license": "MPL-2.0",
   "exports": {
     ".": "./src/index.ts"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/web-terminal-engine",
-  "version": "5.0.3",
+  "version": "5.0.5",
   "type": "module",
   "scripts": {
     "typecheck": "tsc -p tsconfig.json",

package/src/keyboard.ts

@@ -57,17 +57,6 @@ function modifiersDigit(ev: KeyboardEvent): number {
 /** The cursor-key trailing letters that honor DECCKM (arrows + Home/End). */
 type CursorKeyLetter = "A" | "B" | "C" | "D" | "H" | "F";
 
-function isCursorKeyLetter(letter: string): letter is CursorKeyLetter {
-  return (
-    letter === "A" ||
-    letter === "B" ||
-    letter === "C" ||
-    letter === "D" ||
-    letter === "H" ||
-    letter === "F"
-  );
-}
-
 /**
  * plainCursorKeySeq is THE encoding of an unmodified logical cursor-key press
  * (arrows, Home, End) — the one home for the mode decision, shared by the
@@ -114,21 +103,31 @@ function kittyActiveIn(modes: KeyboardModes): boolean {
   return (modes.getKeyboardFlags() & KITTY_DISAMBIGUATE) !== 0;
 }
 
-// Letter is the xterm trailing letter (ABCDEFGHPQRS for arrows / Home /
-// End / F1-F4 etc.). Without modifiers we send the bare CSI form; with
-// modifiers we send CSI 1;{mod}{letter}. xterm.js Keyboard.ts pattern.
+// Letter is the xterm trailing letter for the keys that honor DECCKM: the four
+// arrows plus Home (H) and End (F). Without modifiers we send the bare CSI form;
+// with modifiers we send CSI 1;{mod}{letter}. xterm.js Keyboard.ts pattern.
+// (F1-F4's SS3/CSI pair is encoded inline at its own call site, not here.)
+//
+// The parameter type is `CursorKeyLetter` rather than `string`, so "every
+// letter reaching here honors DECCKM" is a compiler guarantee instead of a
+// runtime net: all three call sites pass A/B/C/D from ARROW_LETTER, or the H/F
+// literals.
 //
 // Application cursor mode (DECCKM, CSI ?1) is plumbed via modes.ts.
 // When the application has set DECCKM, the modifier-less form switches
 // from CSI to SS3 (ESC O letter) via plainCursorKeySeq; modifier-bearing
 // forms stay on CSI because they have no SS3 equivalent.
-function csiLetter(letter: string, ev: KeyboardEvent, modes: KeyboardModes): string {
+function csiLetter(letter: CursorKeyLetter, ev: KeyboardEvent, modes: KeyboardModes): string {
   const m = modifiersDigit(ev);
   if (m === 1) {
-    if (isCursorKeyLetter(letter)) {
-      return plainCursorKeySeq(letter, kittyActiveIn(modes), modes.isApplicationCursor());
-    }
-    return `${ESC}[${letter}`;
+    // `kittyActiveIn(modes)` is always FALSE as reached from today's only
+    // caller: mapKeyboardEvent returns through encodeKittyDisambiguate before
+    // any cursor key gets here. It is passed anyway rather than hard-coded,
+    // because plainCursorKeySeq is the one home for the mode decision and a
+    // literal `false` would make this function structurally unable to express
+    // the kitty form — a later change to that early return would then
+    // mis-encode silently instead of failing to compile or reading wrong.
+    return plainCursorKeySeq(letter, kittyActiveIn(modes), modes.isApplicationCursor());
   }
   return `${ESC}[1;${m}${letter}`;
 }
@@ -169,7 +168,7 @@ const FN_TILDE: Record<string, number | undefined> = {
   F20: 34,
 };
 
-const ARROW_LETTER: Record<string, string | undefined> = {
+const ARROW_LETTER: Record<string, CursorKeyLetter | undefined> = {
   ArrowUp: "A",
   ArrowDown: "B",
   ArrowRight: "C",

package/src/mouse.ts

@@ -264,10 +264,20 @@ function onWheel(e: WheelEvent): void {
   if (!pos) {
     return;
   }
-  // Wheel up = button 64, wheel down = button 65
-  const btn = e.deltaY < 0 ? 64 : 65;
-  const code = buttonCode(btn, false, e.shiftKey, e.altKey, e.ctrlKey);
-  handler.send(encodeSGR(code, pos.col, pos.row, false));
+  // Wheel up = button 64, wheel down = button 65. A gesture with NO vertical
+  // component — a horizontal trackpad swipe, or shift-wheel where the browser
+  // routes the delta to deltaX — has no wheel button to report: xterm.js's
+  // reference encoder returns before encoding when the vertical delta is zero,
+  // while its wheel handler still calls preventDefault unconditionally. So
+  // parity is "report nothing, still swallow the gesture": a terminal owns the
+  // wheel, and letting a sideways swipe through would scroll the page instead.
+  // Reporting 65 here (the pre-fix behavior, `deltaY < 0 ? 64 : 65` with no
+  // zero case) scrolled the TUI DOWN on a sideways gesture.
+  if (e.deltaY !== 0) {
+    const btn = e.deltaY < 0 ? 64 : 65;
+    const code = buttonCode(btn, false, e.shiftKey, e.altKey, e.ctrlKey);
+    handler.send(encodeSGR(code, pos.col, pos.row, false));
+  }
   e.preventDefault();
 }
 

package/src/render.ts

@@ -1393,6 +1393,12 @@ function flushRender(): void {
   // silently switching auto-follow off (scroll.ts's header; §1.3).
   if (removedRowsThisPass) {
     scroll.noteContentShrink(scrollTopBefore);
+    // And correct the offset when the container left it past the end of the
+    // shrunken content instead of reconciling it (scroll.ts's header: the third
+    // arithmetic state). Before the three invariants below, so they measure a
+    // geometry the container agrees with rather than one it is still holding an
+    // impossible offset into.
+    scroll.reconcileScrollRange();
   }
   // Three position invariants, applied after every DOM mutation and in this
   // order. An armed view restore goes first because it OWNS the position while
@@ -1497,6 +1503,16 @@ function flushRenderInner(): void {
     }
     gapMarkerEls.clear();
     cursorAbs = -1;
+    // The rows are not the only thing in content space, and this wipe is as
+    // total as rebuild()'s. Collapse the four overlays with them HERE rather
+    // than relying on the tail's positionCursorOverlay/onCursorMove, so the
+    // shrink this pass announces is the real one: while an overlay still holds
+    // the container's scrollable overflow at its old offset, both the
+    // announcement and the range correction measure a phantom height and read
+    // "already at the bottom" over zero rows of content. See
+    // collapseContentSpaceOverlays for the measurement, and note that the tail
+    // is exactly what does not run on the three paths listed there.
+    collapseContentSpaceOverlays();
   } else {
     for (const abs of ch.evictedLines) {
       const el = rowEls.get(abs);
@@ -2056,6 +2072,19 @@ function renderAlt(rows: readonly (readonly WireRun[])[]): void {
       div.replaceChildren(...buildRowSpans(runs));
       els.push(div);
     }
+    // This replaceChildren REMOVES rows, and on the first alt frame it removes
+    // the entire main-buffer scrollback in favour of one screen of grid: the
+    // largest shrink in this module after rebuild()'s wipe. The alt branch in
+    // flushRenderInner returns before the shared bookkeeping, so the flag is set
+    // here or not at all, and without it the pass reached neither
+    // noteContentShrink (leaving the clamp to be inferred from its lossy
+    // arithmetic signature, which can silently switch auto-follow off) nor
+    // reconcileScrollRange (leaving the viewport parked past the grid).
+    //
+    // Over-announcing is harmless by mechanism: the resize and desynced-DOM
+    // cases reach this branch too, and both seams are position-gated, so a
+    // rebuild that moves nothing and strands nothing announces nothing.
+    removedRowsThisPass = true;
     output.replaceChildren(...els);
     altPrevRows = rows.slice();
     return;
@@ -2280,19 +2309,48 @@ function rowTopInTermWrap(el: HTMLElement): number {
   return top;
 }
 
+// rowTopFor resolves the top of the row holding absolute line `abs`, in
+// termWrap's coordinate space. Three positioners need that answer — the caret
+// overlay, the predicted-cursor overlay, and `getCursorPx` for the consumer's
+// IME view and hidden textarea — and they must not disagree, because they
+// describe the same row. They did: `getCursorPx` fell back to a bare `padT`
+// while the two that PAINT fell back to grid arithmetic, and `rowEls` is
+// populated only by the main-screen row builder (`renderAlt` clears it), so for
+// an ENTIRE alt-screen session the caret painted on the right row while the
+// consumer was told the top of the terminal every frame.
+//
+// Three cases, in order:
+//   - the map holds a built row: its own DOM offset, walked into termWrap space.
+//   - no row for a real index (an alt-screen grid row, or a main row this flush
+//     has not built yet): uniform-grid arithmetic from the window base.
+//   - `abs < 0`: not a row at all. That is the state
+//     `collapseContentSpaceOverlays` leaves behind, where the cursor genuinely
+//     has no row and the content origin IS the accurate answer; the arithmetic
+//     would put the overlay a cell above it.
+function rowTopFor(abs: number): number {
+  const el = rowEls.get(abs);
+  if (el) {
+    return rowTopInTermWrap(el);
+  }
+  const { padT } = termPadding();
+  if (abs < 0) {
+    return padT;
+  }
+  return padT + (abs - store.getWindow().base) * cellHeight;
+}
+
 /**
  * Returns the cursor's pixel position relative to the scroll container
  * (termWrap) — the coordinate space of the absolutely-positioned overlays
  * (predicted-cursor, IME composition view) — plus the current cell height.
- * Uses the cursor row's actual DOM offset.
+ * Uses the cursor row's actual DOM offset, or the grid position of a row that
+ * has none (see rowTopFor).
  */
 export function getCursorPx(): { left: number; top: number; cellH: number } {
-  const { padL, padT } = termPadding();
-  const el = rowEls.get(cursorAbs);
-  const top = el ? rowTopInTermWrap(el) : padT;
+  const { padL } = termPadding();
   return {
     left: Math.round(padL + cursorCol * cellWidth),
-    top: Math.round(top),
+    top: Math.round(rowTopFor(cursorAbs)),
     cellH: cellHeight,
   };
 }
@@ -2352,15 +2410,13 @@ function positionCursorOverlay(runs: readonly WireRun[] | undefined): void {
     el.className = "term-cursor-overlay";
     return;
   }
-  const win = store.getWindow();
-  const { padL, padT } = termPadding();
-  const rowEl = rowEls.get(cursorAbs);
-  // Alt-screen rows are not registered in rowEls; their grid is uniform, so
-  // the row offset derives from the window-relative row index. Main-screen
-  // rows exist by the time this runs (the flush force-builds the cursor row).
-  // rowTopInTermWrap (not bare offsetTop) so the top is in termWrap space
-  // regardless of which ancestor is the rows' offsetParent.
-  const top = rowEl ? rowTopInTermWrap(rowEl) : padT + (cursorAbs - win.base) * cellHeight;
+  const { padL } = termPadding();
+  // Alt-screen rows are not registered in rowEls; their grid is uniform, so the
+  // row offset derives from the window-relative row index. Main-screen rows
+  // exist by the time this runs (the flush force-builds the cursor row).
+  // rowTopFor is shared with getCursorPx so the consumer's IME view cannot be
+  // told a different row than the one the caret paints on.
+  const top = rowTopFor(cursorAbs);
   const ch = glyphAt(runs, cursorCol);
   // A wide glyph (CJK, emoji) owns two cells; the overlay covers both, like
   // the old inline cursor span did via its continuation-spacer adjustment.
@@ -2404,9 +2460,14 @@ export function setPredictedCursor(row: number, col: number, active: boolean): v
     el.classList.remove("visible");
     return;
   }
-  const { padL, padT } = termPadding();
-  const rowEl = rowEls.get(predAbs);
-  const top = rowEl ? rowTopInTermWrap(rowEl) : padT + row * cellHeight;
+  const { padL } = termPadding();
+  // Same resolver as the caret and getCursorPx. A row the flush has not built
+  // yet answers from grid arithmetic, which for `predAbs >= 0` is exactly the
+  // `padT + row * cellHeight` this used to compute inline. A prediction BELOW
+  // the first line of the session (`predAbs < 0`) now lands on the content
+  // origin instead of a negative top: that row does not exist, and an overlay
+  // at a negative offset paints over the terminal's top padding.
+  const top = rowTopFor(predAbs);
   el.style.left = `${Math.round(padL + col * cellWidth)}px`;
   el.style.top = `${Math.round(top)}px`;
   el.style.width = `${cellWidth}px`;

package/src/scroll.ts

@@ -87,6 +87,44 @@
 // follow and a lingering arm cannot swallow a later real gesture. It is also
 // cleared unconditionally by the first event that arrives, so it cannot outlive
 // one frame even if that guarantee were ever broken.
+
+// A shrink asks TWO independent questions, and for years this module asked only
+// the first.
+//
+//   1. Did the offset MOVE? That identifies the clamp's scroll event, so the
+//      follow state survives it (shrinkArmed, above).
+//   2. Is the offset still OUT OF RANGE? That says the container has not
+//      reconciled it at all, and the viewport is parked past the end of the
+//      content (rangeCorrectionOwed, below).
+//
+// distanceFromBottom() has three arithmetic states and only two were consumed:
+// positive means content below (pin down), zero means the tail (nothing to do),
+// and NEGATIVE means the offset is beyond the content's end. The third was a
+// gap: `stickToBottom`'s `> 0` test is false for it, so the one invariant that
+// could rescue the view declined to act, and nothing else writes the offset.
+// The reader then sees the container's background with the content above the
+// visible region, until either the growing content reaches the parked offset or
+// they scroll and the container reconciles.
+//
+// The negative state is reachable because "the offset is clamped when the
+// content shrinks" is an implementation behaviour, not a specified one. CSSOM
+// View clamps a programmatic scroll at write time; neither it nor CSS Overflow 3
+// says WHEN a UA must reconcile an offset already established when the
+// scrollable overflow rectangle shrinks under it. Blink and Gecko reconcile
+// during layout, so the read that follows a row removal already reports the new
+// maximum. WebKit does not hold the offset inside the range at all: this repo
+// separately records that Safari "updates scrollTop PAST the maximum during an
+// overscroll bounce" (render.ts, the removedRowsThisPass comment), and iOS
+// Safari has been reported leaving an offset outside the valid range until a
+// manual scroll nudges the browser into fixing it
+// (stackoverflow.com/q/79752870, September 2025 — that report is about a
+// programmatic scroll during momentum rather than a shrink, so it corroborates
+// the state rather than proving this path into it).
+//
+// So the arithmetic is treated as authoritative and the browser is not:
+// reconcileScrollRange writes the offset the geometry says is the maximum. The
+// correction is gated on a caller's announced row removal, which is what keeps
+// an overscroll bounce (out of range with no content change) out of it.
 const BOTTOM_TOLERANCE_PX = 24;
 // An upward move only disengages follow when a real gap is left below it.
 // Bigger than 0 to absorb fractional-layout rounding in the shrink-clamp case
@@ -106,6 +144,12 @@ let preserveFollowOnce = false;
 // position: the next event is that clamp, not a gesture. Consumed (and in all
 // cases cleared) by the first event to arrive.
 let shrinkArmed = false;
+// Armed by noteContentShrink when a caller's own row removal left the offset
+// PAST the end of the content, i.e. the container did not reconcile it.
+// Consumed by reconcileScrollRange in the same pass. Independent of shrinkArmed:
+// one says the offset moved, this one says it did not move far enough, and a
+// partial reconciliation sets both.
+let rangeCorrectionOwed = false;
 let onFollowChange: ((scrolledUp: boolean) => void) | null = null;
 let onPosition: (() => void) | null = null;
 let scrollHandler: (() => void) | null = null;
@@ -117,6 +161,27 @@ function distanceFromBottom(): number {
   return scrollEl.scrollHeight - scrollEl.scrollTop - scrollEl.clientHeight;
 }
 
+/**
+ * The largest offset the container can hold: the zero point of
+ * distanceFromBottom, written out. Every write that means "the bottom" targets
+ * this rather than `scrollHeight`.
+ *
+ * The over-scroll write it replaces (`scrollTop = scrollHeight`, an extra
+ * clientHeight past the end) delegated the arithmetic to the container's own
+ * clamp. That is the one thing this module can no longer assume: the container
+ * this UI runs on is reported to leave an offset outside the valid range, and a
+ * write is not obviously exempt from that (the report behind
+ * rangeCorrectionOwed is about a programmatic scroll). Writing the maximum
+ * needs no clamp to be correct, is identical on a conforming container, and
+ * keeps one definition of "the bottom" for the reads and the writes both.
+ */
+function bottomOffset(): number {
+  if (!scrollEl) {
+    return 0;
+  }
+  return Math.max(0, scrollEl.scrollHeight - scrollEl.clientHeight);
+}
+
 function atBottom(): boolean {
   return distanceFromBottom() <= BOTTOM_TOLERANCE_PX;
 }
@@ -157,6 +222,7 @@ export function init(opts: {
   lastScrollTop = scrollEl.scrollTop;
   preserveFollowOnce = false;
   shrinkArmed = false;
+  rangeCorrectionOwed = false;
   scrollHandler = () => {
     if (!scrollEl) {
       return;
@@ -281,6 +347,12 @@ function writePreservingFollow(next: number): void {
  * this; that is correct rather than incidental, since it is likewise the
  * library's own mutation moving the viewport and not the user.
  *
+ * It answers a SECOND question at the same time, and the two are independent
+ * (see the header): whether the offset is still out of range after the removal.
+ * If it is, the container has not reconciled it and reconcileScrollRange owes a
+ * write. A partial reconciliation arms both, which is why neither test returns
+ * early on the other.
+ *
  * @param scrollTopBefore  The container's offset read before the mutation.
  */
 export function noteContentShrink(scrollTopBefore: number): void {
@@ -290,19 +362,77 @@ export function noteContentShrink(scrollTopBefore: number): void {
   if (scrollEl.scrollTop < scrollTopBefore) {
     shrinkArmed = true;
   }
+  // The epsilon keeps its original job here too: scrollHeight and clientHeight
+  // are integer-rounded while scrollTop is fractional, so a correctly
+  // reconciled offset can read a fraction of a pixel past the end. Correcting
+  // that would write on every shrink pass for no visible gain.
+  if (distanceFromBottom() < -CLAMP_EPSILON_PX) {
+    rangeCorrectionOwed = true;
+  }
+}
+
+/**
+ * Move the offset back inside the container's range when a caller's own row
+ * removal left it past the end of the content. A no-op unless noteContentShrink
+ * armed it in this pass, so it is safe to call after every removal.
+ *
+ * A RENDERER SEAM. It is public because the whole scroll namespace is
+ * re-exported, not because a consumer has a reason to call it; an out-of-band
+ * call finds nothing armed and does nothing.
+ *
+ * Call it in the same pass as noteContentShrink and BEFORE the position
+ * invariants (the view restore, the read anchor, the bottom pin), so those
+ * measure a geometry the container agrees with. Deliberately NOT folded into
+ * either neighbour: `stickToBottom` is follow-gated by contract and a HOLDING
+ * reader whose history was discarded is stranded over empty space just the same
+ * (the read anchor stands down for a discard, so the pin cannot own this), and
+ * `noteContentShrink` is named for a read and the flush tail's own ordering
+ * comment depends on it not writing.
+ *
+ * The destination is the maximum offset, which for a reader who was HOLDING is
+ * the tail with follow still off. That is this design's ratified degradation for
+ * a reading position whose lines no longer exist (docs/scroll-position-fidelity.md
+ * §3.4, §5), not a new decision.
+ *
+ * The write goes through writePreservingFollow, so the scroll event it produces
+ * cannot re-derive the state: a following reader stays following, and a holding
+ * reader stays holding at the bottom.
+ *
+ * One accepted overlap, recorded so it is not read as an oversight. On a
+ * container that reports an offset past the maximum during an overscroll bounce,
+ * a bounce that coincides with a row-removing pass (cap eviction under heavy
+ * streaming) satisfies the gate, and this write then cuts the bounce short at
+ * the offset it was settling towards anyway. Refusing the correction whenever
+ * the offset was ALREADY out of range before the mutation would avoid that, at
+ * the price of skipping the repair for the whole rest of the session whenever
+ * the two coincide. A cut animation lasts one frame; a stranded viewport lasts
+ * until the user scrolls. The bounce loses.
+ */
+export function reconcileScrollRange(): void {
+  if (!scrollEl || !rangeCorrectionOwed) {
+    return;
+  }
+  rangeCorrectionOwed = false;
+  writePreservingFollow(bottomOffset());
 }
 
 /**
  * Pin the viewport to the bottom iff the user is following. Called by the
  * renderer after each flush. A no-op when holding (scrolled up) or already at
  * the bottom, so it never fights the user and never scrolls redundantly.
+ *
+ * Only the positive branch of distanceFromBottom is this function's business: an
+ * offset PAST the end of the content is a geometry error rather than a following
+ * reader who fell behind, and reconcileScrollRange owns it (see the header).
+ * Correcting it here instead would fight an overscroll bounce, which presents
+ * the same arithmetic with nothing wrong.
  */
 export function stickToBottom(): void {
   if (!scrollEl || !following) {
     return;
   }
   if (distanceFromBottom() > 0) {
-    scrollEl.scrollTop = scrollEl.scrollHeight;
+    scrollEl.scrollTop = bottomOffset();
   }
 }
 
@@ -314,7 +444,7 @@ export function scrollToBottom(): void {
   if (!scrollEl) {
     return;
   }
-  scrollEl.scrollTop = scrollEl.scrollHeight;
+  scrollEl.scrollTop = bottomOffset();
   setFollowing(true);
 }
 

package/src/store.ts

@@ -1262,10 +1262,12 @@ export class LineStore {
     const tailKeys = [...this.lines.keys()]
       .filter((k) => !this.browse.has(k))
       .sort((a, b) => a - b);
+    // `excess >= 1` here, so no guard: `tailCount` is `lines.size -
+    // browse.size` while `tailKeys.length` is `lines.size` minus the browse
+    // keys that are ACTUALLY in `lines`, so `tailKeys.length >= tailCount`
+    // unconditionally — and reaching this line means the gate above found
+    // `tailCount > keep`.
     const excess = tailKeys.length - keep;
-    if (excess <= 0) {
-      return false;
-    }
     const winFloor = this.win.height > 0 ? this.win.base : Number.POSITIVE_INFINITY;
     return this.classifyAsBrowse(tailKeys.slice(0, excess).filter((k) => k < winFloor)) > 0;
   }
@@ -1445,7 +1447,6 @@ export class LineStore {
     this.everEvictedThrough = -1;
     this.erasedThrough = -1;
     this.unconfirmedFrom = Number.POSITIVE_INFINITY;
-    this.paging = false;
     this.serverOldest = -1;
     this.win = emptyWindow();
     this.alt = false;
@@ -1933,11 +1934,15 @@ export class LineStore {
         // keeps the classification consistent if one ever does.)
         this.everEvictedThrough = Math.max(this.everEvictedThrough, victim);
       }
-      if (this.lines.size === 0) {
-        this.oldest = -1;
-        this.highest = -1;
-        return;
-      }
+      // No empty-store arm: the walk cannot evict the last line. The loop
+      // guard's `cursor < this.highest` conjunct stops it once the cursor
+      // reaches the newest key, and with a protected window the sibling
+      // `cursor > winBottom` cannot hold there either. That is the ONLY thing
+      // holding when the target is 0, which `new LineStore(0)` produces
+      // (`evictionBatch(0)` is 1, so `target = 0 - 1 + 1`; the bare
+      // constructor accepts 0, unlike `render.init` and `fromSnapshot`, which
+      // both require a positive integer) — a reason to leave that conjunct
+      // alone.
       // Advance to the lowest remaining key above the victim. Contiguous
       // history (the common case: live scroll-off, resume replay, a
       // cat-bigfile burst) leaves victim + 1 present -- an O(1) probe. Only a