@cplieger/web-terminal-engine 1.2.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.2.0",
+  "version": "1.3.2",
   "exports": {
     ".": "./src/index.ts"
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/web-terminal-engine",
-  "version": "1.2.0",
+  "version": "1.3.2",
   "type": "module",
   "scripts": {
     "typecheck": "tsgo -p tsconfig.json",
@@ -10,10 +10,10 @@
   "devDependencies": {
     "@eslint/js": "10.0.1",
     "@vitest/coverage-v8": "4.1.9",
-    "eslint": "10.5.0",
+    "eslint": "10.6.0",
     "fast-check": "4.8.0",
     "happy-dom": "20.10.6",
-    "prettier": "3.8.4",
+    "prettier": "3.8.5",
     "typescript": "6.0.3",
     "typescript-eslint": "8.62.0",
     "vitest": "4.1.9"

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/keyboard.ts

@@ -470,7 +470,7 @@ export interface MobileToolbarController {
    *     would garble it.
    */
   applyStickyCtrl(text: string): string;
-  /** Programmatically arm/disarm Ctrl. Updates the toolbar button visuals + fires `onCtrlChange`. */
+  /** Programmatically arm/disarm Ctrl. Updates the toolbar button visuals (`.armed` class + `aria-pressed`) + fires `onCtrlChange`. */
   setCtrlArmed(on: boolean): void;
   /** Whether sticky-Ctrl is currently armed. */
   isCtrlArmed(): boolean;
@@ -513,20 +513,28 @@ export function bindMobileToolbar(opts: BindMobileToolbarOptions): MobileToolbar
   const enterBtn = findBtn(ids.enter);
   const escBtn = findBtn(ids.esc);
 
+  function paintCtrlBtn(on: boolean): void {
+    if (!ctrlBtn) {
+      return;
+    }
+    ctrlBtn.classList.toggle("armed", on);
+    // Keep the ARIA toggle state in sync with the visual `.armed` class so
+    // assistive tech announces the sticky-Ctrl button as pressed/unpressed.
+    // The scaffold ships kb-ctrl as `aria-pressed="false"`; consumers used to
+    // own this in their own setCtrlArmed before delegating the toolbar here.
+    ctrlBtn.setAttribute("aria-pressed", on ? "true" : "false");
+  }
+
   function setCtrlArmed(on: boolean): void {
     if (armed === on) {
       // Still update visuals defensively (e.g. after dispose was called
       // and someone re-armed via setCtrlArmed) — but skip the change
       // notification to keep onCtrlChange edge-triggered.
-      if (ctrlBtn) {
-        ctrlBtn.classList.toggle("armed", on);
-      }
+      paintCtrlBtn(on);
       return;
     }
     armed = on;
-    if (ctrlBtn) {
-      ctrlBtn.classList.toggle("armed", on);
-    }
+    paintCtrlBtn(on);
     opts.onCtrlChange?.(on);
   }
 

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,
@@ -178,6 +181,12 @@ export function init(opts: {
   rowEls.clear();
   renderQueue.clear();
   trimMarkerEl = null;
+  // Drop the predicted-cursor overlay (re-created lazily against the new
+  // termWrap on the next setPredictedCursor call) so re-init starts clean.
+  if (predCursorEl) {
+    predCursorEl.remove();
+    predCursorEl = null;
+  }
   output.replaceChildren();
   cursorAbs = -1;
   if (pendingFrame !== undefined) {
@@ -457,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);
@@ -555,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.
@@ -785,16 +807,28 @@ export function getCursorPx(): { left: number; top: number; cellH: number } {
 
 let predCursorEl: HTMLElement | null = null;
 
+// Create the predicted-cursor overlay the renderer owns. Appended to termWrap
+// (the positioned scroll container) so its absolute left/top math matches the
+// row offsets. Styled by the `.pred-cursor` class from the UI CSS bundle. The
+// renderer owning this means the engine never depends on a host-provided
+// `#pred-cursor` scaffold element.
+function createPredCursorEl(): HTMLElement {
+  const el = document.createElement("div");
+  el.className = "pred-cursor";
+  el.setAttribute("aria-hidden", "true");
+  termWrap.appendChild(el);
+  return el;
+}
+
 /**
  * Show or hide a "predicted" cursor overlay at window-relative (row, col).
  * Useful for client-side echo of typed characters before the server
- * acknowledges them, over high-latency connections.
+ * acknowledges them, over high-latency connections. The overlay element is
+ * created lazily on first use (a consumer that never predicts never creates
+ * it).
  */
 export function setPredictedCursor(row: number, col: number, active: boolean): void {
-  const el = predCursorEl ?? (predCursorEl = document.getElementById("pred-cursor"));
-  if (!el) {
-    return;
-  }
+  const el = predCursorEl ?? (predCursorEl = createPredCursorEl());
   const win = store.getWindow();
   const predAbs = win.base + row;
   if (!active || (predAbs === cursorAbs && col === cursorCol)) {

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);