@cplieger/web-terminal-engine 3.10.2 → 3.10.4

package/jsr.json

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

package/package.json

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

package/src/render.ts

@@ -494,6 +494,11 @@ function queueRowsViewportFirst(): void {
  * history; the existing per-frame budget spreads a large backlog across frames
  * so the switch never janks. Used by bind(); also safe to call directly to
  * force a full repaint of the current store.
+ *
+ * The wipe covers content space in full: the rows AND the four overlays anchored
+ * into it (see collapseContentSpaceOverlays). Leaving the overlays behind left
+ * the container a measured 81081px of scroll range over zero rows of content,
+ * which is a black pane the bottom pin refuses to correct.
  */
 export function rebuild(): void {
   // The wipe is the largest content shrink this module performs, and it happens
@@ -515,6 +520,9 @@ export function rebuild(): void {
   // Fresh surface: a stale give-up streak from a prior store must not deny the
   // rebuilt surface its full transient-retry budget.
   renderNoProgressStreak = 0;
+  // The rows are not the only thing in content space. Collapse the overlays
+  // with them, BEFORE the offset below is read.
+  collapseContentSpaceOverlays();
   // Alt screen paints from the ephemeral grid in the flush, so it needs no
   // absolute-index queueing here.
   if (!store.isAlt()) {
@@ -524,6 +532,60 @@ export function rebuild(): void {
   scheduleFlush();
 }
 
+/**
+ * Drop every CONTENT-SPACE overlay's hold on the scroll container, as part of a
+ * wipe. Four elements sit INSIDE the container carrying a `top` in content
+ * coordinates — the caret, the predicted cursor, the IME view and the consumer's
+ * hidden textarea — so each one holds the container's scrollable overflow at the
+ * offset it was last placed at. `output.replaceChildren()` removes the rows and
+ * leaves all four.
+ *
+ * Measured on a 4769-row tab in Chromium: after the wipe the scroller had ZERO
+ * rows of content and an 81081px scroll range, held by the caret and the
+ * textarea still sitting at 81064px, with the viewport parked at 80281px over
+ * nothing. Two consequences, and the second is why this is not cosmetic:
+ *
+ *   - The reader sees that empty region, which paints the terminal's background:
+ *     a black pane, and then a partial row clipped to the top edge once the
+ *     drain's growing block reaches the parked offset.
+ *   - `stickToBottom` is DISARMED. It measures `distanceFromBottom()` against
+ *     the phantom height, reads 0 — already at the bottom — and pins nothing, so
+ *     the invariant that would otherwise rescue the view refuses to act for
+ *     exactly as long as the phantom height survives.
+ *
+ * The renderer heals all four at the END of the first flush
+ * (`positionCursorOverlay` plus `onCursorMove`), so the window is normally one
+ * frame and invisible. It stops being one frame whenever that tail does not
+ * run on time: a long frame (the wipe tears down thousands of rows), a throw
+ * mid-drain (the catch skips the tail and the bounded give-up can stop
+ * rescheduling), or a full reset arriving with the switch's reconnect. The
+ * reported symptom is a scroll tick clearing it, which fits: a scroll re-enters
+ * the built block, and the block sits at the TOP of the phantom range.
+ *
+ * Collapsing here also makes the wipe's clamp SYNCHRONOUS, which two callers
+ * need. `noteContentShrink` arms only when it observes the position actually
+ * move, so a deferred clamp left the wipe — the largest shrink this module
+ * performs — with nothing to announce. And `bind` records
+ * `pendingRestore.lastWrote` from the same offset, so a deferred clamp
+ * (measured: 80281 -> 4346) then read as a 76000px foreign write and threw away
+ * the reading position the switch was restoring.
+ */
+function collapseContentSpaceOverlays(): void {
+  // `cursorAbs` is -1 by now, which is the state positionCursorOverlay already
+  // hides for; go through it rather than restating the class name here.
+  positionCursorOverlay(undefined);
+  // The outgoing session's prediction cannot describe the incoming screen
+  // either. The consumer re-pushes it from the `onCursorMove` below, which is
+  // its call to make and cannot re-inflate anything: `rowEls` is empty, so
+  // setPredictedCursor's own fallback places it at the content origin.
+  predCursorEl?.classList.remove("visible");
+  // The IME view and the hidden textarea are the CONSUMER's, reachable only
+  // through the cursor seam — and after a wipe the cursor genuinely has no row,
+  // so the seam is accurate rather than borrowed. `getCursorPx` reports the
+  // content origin while `rowEls` is empty, so the handler moves them there.
+  onCursorMove?.();
+}
+
 /**
  * Highest absolute line index the client holds, or -1 if empty. This is the
  * resume `haveThrough` value (it replaces the old DOM-row count). Exposed so

package/src/scroll.ts

@@ -265,14 +265,16 @@ function writePreservingFollow(next: number): void {
  * absolutely-positioned overlay) — and a lingering arm swallows the next real
  * gesture.
  *
- * That last case is live in this codebase rather than illustrative: the caret
- * overlay, the predicted cursor, the IME composition view and the consumer's
- * hidden textarea all sit inside the scroll container carrying a `top` in CONTENT
- * coordinates. Nothing resets them on a wipe: the renderer's `init` drops the two
- * it owns (the caret and the predicted cursor), a full consumer remount recreates
- * the other two, and `rebuild` does neither. So a wipe can leave scrollHeight held
- * above the built content by a stale overlay, the clamp never happens, and there
- * is nothing for this arm to cover. See `docs/tab-switch-repaint.md` §6.2.
+ * That last case used to be live here rather than illustrative, and it is why
+ * the caller's ORDER matters: the caret, the predicted cursor, the IME view and
+ * the consumer's hidden textarea all sit inside the scroll container carrying a
+ * `top` in CONTENT coordinates, so any one of them left at the old offset holds
+ * scrollHeight above the built content and the clamp never happens. `rebuild`
+ * now collapses all four as part of its wipe, before it calls this
+ * (`render.ts` collapseContentSpaceOverlays), so the clamp it announces is real.
+ * A caller that removes content without collapsing whatever else is anchored in
+ * that space arms nothing and gets no announcement. See
+ * `docs/tab-switch-repaint.md` §6.2.
  *
  * A native-scroll-anchoring adjustment (Chrome/Firefox lowering scrollTop as
  * rows are removed above the viewport) also moves the position and also arms