@cplieger/web-terminal-engine 2.3.2 → 2.3.3

package/jsr.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/web-terminal-engine",
-  "version": "2.3.2",
+  "version": "2.3.3",
   "exports": {
     ".": "./src/index.ts"
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/web-terminal-engine",
-  "version": "2.3.2",
+  "version": "2.3.3",
   "type": "module",
   "scripts": {
     "typecheck": "tsc -p tsconfig.json",
@@ -15,11 +15,11 @@
     "@typescript/native": "npm:typescript@7.0.2",
     "@vitest/coverage-v8": "4.1.10",
     "esbuild": "0.28.1",
-    "eslint": "10.6.0",
-    "fast-check": "4.8.0",
+    "eslint": "10.7.0",
+    "fast-check": "4.9.0",
     "happy-dom": "20.10.6",
     "pngjs": "7.0.0",
-    "prettier": "3.9.4",
+    "prettier": "3.9.5",
     "typescript": "npm:@typescript/typescript6@6.0.2",
     "typescript-eslint": "8.63.0",
     "vitest": "4.1.10"

package/src/scroll.ts

@@ -2,11 +2,11 @@
 //
 // One piece of state: `following`. The user is "following" when the viewport is
 // at (or within a small tolerance of) the bottom; otherwise they have scrolled
-// up to read and are "holding". The state is derived purely from scroll
-// position on every scroll event — there is no debounce window, no suppress
-// timer, and no programmatic-vs-user flag. That heuristic soup (a 100px
-// tolerance, a 150ms debounce, a 60-second touch window) was the source of the
-// view-jumping and scroll-interruption bugs (the legacy heuristic-soup
+// up to read and are "holding". The state is derived purely from the scroll
+// events — position plus movement direction — with no debounce window, no
+// suppress timer, and no programmatic-vs-user flag. That heuristic soup (a
+// 100px tolerance, a 150ms debounce, a 60-second touch window) was the source
+// of the view-jumping and scroll-interruption bugs (the legacy heuristic-soup
 // failure mode; see the #web-terminal-engine steering doc, "Design rationale").
 //
 // The renderer calls stickToBottom() once after each flush: if following, pin
@@ -15,13 +15,32 @@
 // Appending content at the bottom does not fire a scroll event, so following
 // stays true across new output and the post-flush pin lands correctly. Pinning
 // to the bottom produces a scroll event whose recomputation yields
-// following=true again (no churn). Scrolling up past the tolerance flips to
-// holding; scrolling back flips to following.
+// following=true again (no churn; the pin only ever moves DOWN). Scrolling
+// back to within the tolerance of the bottom re-engages following.
+//
+// Disengaging is direction-based, not tolerance-based: ANY upward movement
+// that leaves a real gap below flips to holding at once. A tolerance-only
+// rule lost a race under heavy streaming — the renderer flushes (and pins)
+// every frame, so each frame's upward scroll increment restarted from the
+// bottom the previous pin reset it to, and unless a single frame's delta
+// exceeded the tolerance the user was yanked back down every few milliseconds
+// (the "scroll up fights me during output" bug). Per the HTML event loop the
+// scroll steps run before that frame's rAF flush, so the first upward tick
+// flips holding before the next pin can fire. The nothing-below guard keeps
+// one non-user case following: when content SHRINKS (top-row eviction, a
+// clear), the browser clamps scrollTop DOWN to the new maximum — an upward
+// move that lands exactly at the bottom, which must not break auto-follow.
 
 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
+// (a clamp lands at the bottom, but scrollTop can be subpixel-off); far below
+// any real one-frame user scroll increment.
+const CLAMP_EPSILON_PX = 1;
 
 let scrollEl: HTMLElement | null = null;
 let following = true;
+let lastScrollTop = 0;
 let onFollowChange: ((scrolledUp: boolean) => void) | null = null;
 let scrollHandler: (() => void) | null = null;
 
@@ -65,8 +84,24 @@ export function init(opts: {
   scrollEl = opts.scrollEl;
   onFollowChange = opts.onUserScrollChange ?? null;
   following = true;
+  lastScrollTop = scrollEl.scrollTop;
   scrollHandler = () => {
-    setFollowing(atBottom());
+    if (!scrollEl) {
+      return;
+    }
+    const top = scrollEl.scrollTop;
+    const movedUp = top < lastScrollTop;
+    lastScrollTop = top;
+    // Upward movement with content still below = the user pulling away from
+    // the live tail: hold immediately, however small the move (see the header
+    // comment for why the tolerance alone lost the streaming race). An upward
+    // move that lands AT the bottom is the browser clamping after a content
+    // shrink, not the user; everything else derives from position as before.
+    if (movedUp && distanceFromBottom() > CLAMP_EPSILON_PX) {
+      setFollowing(false);
+    } else {
+      setFollowing(atBottom());
+    }
   };
   scrollEl.addEventListener("scroll", scrollHandler, { passive: true });
 }