@cplieger/web-terminal-engine 1.3.0 → 1.3.2

package/README.md

@@ -77,10 +77,10 @@ document.addEventListener("keydown", (ev) => {
 
 ## API
 
-- **`render`** — DOM renderer driven by `ScreenMessage` / `ScrollMessage` frames. `init`, `handleScreen`, `handleScroll`, `updateFontMetrics`, `computeSize`, `getCursorPx`, `setPredictedCursor`, `resetScreen`, `resetScrollback`, `getScrollbackRowCount`, `updateReverseVideo`.
+- **`render`** — DOM renderer driven by `ScreenMessage` / `ScrollMessage` frames. `init`, `handleScreen`, `handleScroll`, `updateFontMetrics`, `computeSize`, `getCursorPx`, `setPredictedCursor`, `resetScreen`, `resetScrollback`, `getHighestIndex`, `noteResumeBounds`, `updateReverseVideo`.
 - **`keyboard`** — Translates `KeyboardEvent` to terminal byte sequences. `mapKeyboardEvent`, `bracketTextForPaste`, `prepareTextForTerminal`, `ctrlByteFor`. Honors `applicationCursor`, `applicationKeypad`, `bracketedPaste`. For touch / mobile UIs, `bindMobileToolbar({toolbar, send, ids?})` wires `pointerdown` handlers for an on-screen Ctrl/arrows/Tab/Enter/Esc toolbar (with sticky-Ctrl semantics and DECCKM-aware arrows), 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`, `scrollToBottom`, `suppressScroll`, `isUserScrolledUp`, `isInUserScroll`.
+- **`scroll`** — Auto-follow tracker for the scroll container. `init`, `stickToBottom`, `scrollToBottom`, `isUserScrolledUp`.
 - **`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.
 - **`connection`** — Client → server WebSocket lifecycle: owns the socket, exponential-backoff reconnect, and the resume/inputAck reliability layer (outbox + server-restart detection). `init(callbacks)`, `connect`, `sendBinary(bytes)`, `sendResize`, `reconnectNow`. The callbacks expose `onMessage(ServerMessage)`, `onOpen`/`onClose`/`onConnecting`/`onOutboxFull`/`onServerRestart`, a `computeSize()` provider, and an optional `wsPath` (defaults to `"/ws"`). It decodes frames internally and applies `modes.setModes` for you, so a consumer only needs to dispatch screen/scroll to `render`. Prefer this over wiring `WebSocket` + `decodeWireBinary` by hand unless you need full control.

package/jsr.json

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

package/package.json

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

package/src/connection.ts

@@ -373,6 +373,14 @@ export function connect(): void {
       /* ignore */
     }
   }
+  // Re-entry while a backoff reconnect is pending (e.g. a consumer calling
+  // connect() to restore a panel during the 500ms-8s backoff window): clear the
+  // scheduled timer so it cannot fire later and spawn a SECOND socket alongside
+  // the one created below. The orphaned timer resets connState to disconnected
+  // and calls connect() again, while the existing socket's listeners stay bound
+  // (its abort never fired) -> a duplicate server connection + double delivery.
+  // cancelScheduledReconnect is a no-op in any non-reconnecting state.
+  cancelScheduledReconnect();
 
   cb?.onConnecting?.();
 

package/src/render.ts

@@ -137,6 +137,9 @@ let cursorAbs = -1; // absolute index of the row the cursor is on
 let cursorCol = 0;
 let cursorHidden = false;
 let cursorStyleVal = 0; // 0-6: DECSCUSR
+let prevCursorCol = -1;
+let prevCursorHidden = false;
+let prevCursorStyleVal = -1;
 
 function cursorClassName(): string {
   // DECSCUSR: 0/1=blinking block, 2=steady block, 3=blinking underline,
@@ -463,7 +466,7 @@ function buildRowSpans(runs: WireRun[], cursorAt: number): (HTMLSpanElement | HT
   }
   if (out.length === 0) {
     const span = document.createElement("span");
-    span.innerHTML = " ";
+    span.textContent = "\u00a0";
     out.push(span);
   }
   return linkifySpans(out);
@@ -561,15 +564,28 @@ function flushRenderInner(): void {
     renderQueue.add(abs);
   }
 
-  // The cursor rows are built every frame regardless of the budget so the
-  // inline cursor span is always current (it moves off the old row and onto
-  // the new one); a huge backlog must never make the caret lag.
+  // The cursor rows are built regardless of the budget so the inline cursor span
+  // is always current; a huge backlog must never make the caret lag. But skip
+  // rebuilding the current cursor row when neither the cursor's visual state nor
+  // the row content changed: an unconditional replaceChildren() would discard a
+  // text selection on that row, defeating the byte-identical selection-preserving
+  // guarantee the store idempotency gives every other row.
   if (prevCursorAbs !== newCursorAbs && prevCursorAbs >= 0) {
     upsertRow(prevCursorAbs);
     renderQueue.delete(prevCursorAbs);
   }
-  upsertRow(newCursorAbs);
+  const cursorVisualChanged =
+    prevCursorAbs !== newCursorAbs ||
+    cursorCol !== prevCursorCol ||
+    cursorHidden !== prevCursorHidden ||
+    cursorStyleVal !== prevCursorStyleVal;
+  if (cursorVisualChanged || renderQueue.has(newCursorAbs)) {
+    upsertRow(newCursorAbs);
+  }
   renderQueue.delete(newCursorAbs);
+  prevCursorCol = cursorCol;
+  prevCursorHidden = cursorHidden;
+  prevCursorStyleVal = cursorStyleVal;
 
   // Drain up to MAX_ROWS_PER_FRAME queued rows this frame; the rest carry over
   // to the next frame (scheduled below) so one big burst never blocks paint.

package/src/store.ts

@@ -15,7 +15,7 @@
 import type { ScreenMessage, ScrollMessage, WireRun } from "./types.js";
 
 /** Maximum lines retained client-side. Older lines are evicted from the top. */
-export const MAX_LINES = 5000;
+const MAX_LINES = 5000;
 
 /** The live screen window: a fixed `height`-row block at the tail of the buffer. */
 export interface WindowState {
@@ -305,12 +305,25 @@ export class LineStore {
         this.evicted.add(victim);
         this.dirty.delete(victim);
       }
-      // Advance oldest past the evicted line and any hole.
-      let next = victim + 1;
-      while (next <= this.highest && !this.lines.has(next)) {
-        next++;
+      // Advance oldest to the lowest remaining key. After evicting the current
+      // oldest, contiguous history (the common case: live scroll-off, resume
+      // replay, a cat-bigfile burst) leaves victim + 1 present -- an O(1) probe.
+      // Only a hole at the boundary falls back to a full key scan. That scan is
+      // bounded by map size (<= maxLines), NOT by the integer gap to the next
+      // retained line, so a malformed/compromised frame whose base jumps far
+      // ahead of a retained low index cannot make eviction walk billions of
+      // indices (an algorithmic-complexity DoS that freezes the tab).
+      if (this.lines.has(victim + 1)) {
+        this.oldest = victim + 1;
+      } else {
+        let min = -1;
+        for (const k of this.lines.keys()) {
+          if (min < 0 || k < min) {
+            min = k;
+          }
+        }
+        this.oldest = min;
       }
-      this.oldest = next > this.highest && !this.lines.has(this.highest) ? -1 : next;
       if (this.lines.size === 0) {
         this.oldest = -1;
         this.highest = -1;

package/src/wire-binary.ts

@@ -60,10 +60,16 @@ class Cursor {
     return v;
   }
   u64(): number {
-    // Number(v) is safe here: all values this protocol encodes in u64
-    // fields (bytesReceived, serverEpoch) fit within JavaScript's 53-bit
-    // integer precision. If the protocol ever needs true 64-bit values,
-    // this must return BigInt instead.
+    // Number(v) loses precision above 2^53. That is safe for every u64 this
+    // protocol decodes because of how each value is USED, not because they all fit:
+    //   - base / firstIndex / committed / oldestIndex / inputAck (bytesReceived)
+    //     stay well under 2^53 for any realistic session, so arithmetic is exact.
+    //   - serverEpoch is the server's time.Now().UnixNano() (~1.77e18, far ABOVE
+    //     2^53), so it DOES drop low bits here. That is harmless: it is only ever
+    //     equality-compared to detect a restart, and Number() is deterministic, so
+    //     one epoch always maps to one double and two distinct boots differ by far
+    //     more than the ~256ns rounding granularity at that magnitude.
+    // If a future u64 field needs exact values above 2^53, return BigInt instead.
     const v = this.view.getBigUint64(this.off, true);
     this.off += 8;
     return Number(v);