@cplieger/web-terminal-engine 5.0.4 → 5.0.8

package/jsr.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/web-terminal-engine",
-  "version": "5.0.4",
+  "version": "5.0.8",
   "type": "module",
   "scripts": {
     "typecheck": "tsc -p tsconfig.json",
@@ -21,7 +21,7 @@
     "esbuild": "0.28.2",
     "eslint": "10.8.1",
     "fast-check": "4.9.0",
-    "happy-dom": "20.11.2",
+    "happy-dom": "20.11.6",
     "pngjs": "7.0.0",
     "prettier": "3.9.6",
     "typescript": "npm:@typescript/typescript6@6.0.2",

package/src/connection.ts

@@ -782,7 +782,21 @@ function retransmitOutbox(sock: WebSocket, upgraded: boolean, st: ResumeState):
 }
 
 function scheduleReconnect(): void {
-  if (connState.status === "reconnecting") {
+  // Nothing to schedule when the state already owns a path back to a socket: a
+  // backoff timer is pending ("reconnecting"), or a socket exists that will
+  // drive its own retry from its close handler or its connect timeout
+  // ("connecting"/"connected"). Both callers set "disconnected" before calling
+  // cb.onClose(), so a consumer that reconnects from its own close hook lands
+  // here at "connecting" — and scheduling over it would OVERWRITE connState,
+  // hiding that socket from connect()'s double-call guard, which then never
+  // aborts it: the timer's connect() adds a second live socket with the first
+  // one's listeners still bound, i.e. the duplicate server connection and
+  // double delivery documented inside connect().
+  if (
+    connState.status === "reconnecting" ||
+    connState.status === "connecting" ||
+    connState.status === "connected"
+  ) {
     return;
   }
   const step = nextBackoffDelay(reconnectDelay);

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

@@ -2309,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,
   };
 }
@@ -2381,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.
@@ -2433,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/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;
@@ -1825,6 +1826,17 @@ export class LineStore {
     if (this.highest < 0) {
       return;
     }
+    // No window established yet — the descriptor is still the initial base
+    // 0/height 0, whose bottom row is -1, below every index a line can hold.
+    // This whole pass rests on "the window's bottom row is the most recent line
+    // in the terminal", which says nothing at all when there is no window: a
+    // resume replays history BEFORE the screen frame describing the window, so
+    // taking -1 as the tail bound strands that replay and forgets it, silently
+    // (this path is not a trim, so no marker explains it). Same test `inWindow`
+    // and applyScroll's alt gate use to ask whether a window exists at all.
+    if (this.win.height <= 0) {
+      return;
+    }
     const windowBottom = this.win.base + this.win.height - 1;
     if (this.highest <= windowBottom) {
       return;
@@ -1933,11 +1945,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
@@ -2003,6 +2019,18 @@ export class LineStore {
   }
 
   private updateWindow(msg: ScreenMessage): void {
+    // A base that is not a non-negative integer is not a screen position — the
+    // same validity test markUnconfirmedFrom applies to this very value — so it
+    // must not redefine the window's shape, for the same reason a rows-less
+    // frame must not: `base + height - 1` lands below every retained index, and
+    // truncateBelowWindow then hands the WHOLE store over as stranded past the
+    // live window. That is the silent wipe applyScreen's rows-less guard
+    // records, reached with rows present, and just as silent (this path is not a
+    // trim, so no marker explains the missing transcript). The frame's
+    // addressable rows still apply through applyLine's guard 1.
+    if (!Number.isInteger(msg.base) || msg.base < 0) {
+      return;
+    }
     const next: WindowState = {
       base: msg.base,
       height: msg.rows.length,