@cplieger/web-terminal-engine 2.2.1 → 2.3.2

package/jsr.json

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

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@cplieger/web-terminal-engine",
-  "version": "2.2.1",
+  "version": "2.3.2",
   "type": "module",
   "scripts": {
-    "typecheck": "tsgo -p tsconfig.json",
-    "typecheck:tests": "tsgo -p tsconfig.test.json",
+    "typecheck": "tsc -p tsconfig.json",
+    "typecheck:tests": "tsc -p tsconfig.test.json",
     "test": "vitest --run",
     "test:e2e": "playwright test"
   },
@@ -12,16 +12,17 @@
     "@eslint/js": "10.0.1",
     "@playwright/test": "1.61.1",
     "@types/pngjs": "6.0.5",
-    "@vitest/coverage-v8": "4.1.9",
+    "@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",
     "happy-dom": "20.10.6",
     "pngjs": "7.0.0",
     "prettier": "3.9.4",
-    "typescript": "6.0.3",
-    "typescript-eslint": "8.62.1",
-    "vitest": "4.1.9"
+    "typescript": "npm:@typescript/typescript6@6.0.2",
+    "typescript-eslint": "8.63.0",
+    "vitest": "4.1.10"
   },
   "description": "Browser terminal engine: VT500 screen buffer, DOM renderer, and binary wire protocol",
   "license": "GPL-3.0-or-later",

package/src/connection.ts

@@ -199,7 +199,7 @@ export interface Callbacks {
    *  missing) from a still-loading state. Resync guard 8.2.2. */
   onResumeBounds?(committed: number, oldest: number): void;
   /** Optional WebSocket endpoint path (default "/ws"). vibekit serves
-   *  the shell at "/api/shell/ws"; vibecli at "/ws". */
+   *  the shell at "/api/shell/ws"; web-terminal-kiro at "/ws". */
   wsPath?: string;
 }
 
@@ -257,6 +257,18 @@ export function sendResize(): void {
   sendControl({ type: "resize", cols, rows });
 }
 
+// resetSessionAfterRestart clears a session's reliable-input accounting and
+// notifies the UI. Called when the server's boot epoch changes (restart) or when
+// the server no longer recognizes the session (received=0 with prior acks) -- both
+// invalidate the local bytesSent/bytesAcked/outbox state.
+function resetSessionAfterRestart(st: ResumeState): void {
+  st.bytesSent = 0;
+  st.bytesAcked = 0;
+  st.outbox.length = 0;
+  st.outboxBytes = 0;
+  cb?.onServerRestart?.();
+}
+
 // applyAck drops chunks from the front of the session's outbox until the
 // running total of unacked bytes matches (bytesSent - newAck). Runs in
 // O(chunks_dropped) by tracking outboxBytes incrementally rather than
@@ -491,7 +503,19 @@ export function connect(): void {
   //   removed atomically and can't fire again.
   const connectAbort = new AbortController();
   const timeoutId = setTimeout(() => {
+    // Aborting detaches every listener registered with connectAbort.signal
+    // (abort algorithms run BEFORE the abort event fires), INCLUDING the
+    // "close" listener that normally schedules the reconnect. A connect that
+    // never opens (SYN dropped by a firewall / an overloaded server) would
+    // otherwise leave connState pinned at "connecting" with no auto-retry.
+    // Drive the reconnect explicitly, mirroring the close handler.
     connectAbort.abort();
+    if (connState.status === "connecting" && connState.sock === sock) {
+      stopHeartbeat();
+      connState = { status: "disconnected" };
+      cb?.onClose();
+      scheduleReconnect();
+    }
   }, 10_000);
   connectAbort.signal.addEventListener("abort", () => {
     clearTimeout(timeoutId);
@@ -560,16 +584,35 @@ export function connect(): void {
       // even decode it. A malformed frame that decodes to null still counts.
       markActivity();
       if (ev.data instanceof ArrayBuffer) {
-        handleDecoded(decodeWireBinary(ev.data));
+        try {
+          handleDecoded(decodeWireBinary(ev.data));
+        } catch (err) {
+          // Mirror the Blob branch below: a throw here (a consumer onMessage
+          // callback, or the documented re-throw of a non-RangeError from
+          // decodeWireBinary) is logged with engine context instead of
+          // surfacing as a bare uncaught exception, so field observability is
+          // the same across ArrayBuffer (non-iOS) and Blob (iOS Safari) frames.
+          console.error("vterm: dropped binary frame", err);
+        }
         return;
       }
       if (ev.data instanceof Blob) {
         const blob = ev.data;
-        blobChain = blobChain.then(() =>
-          blob.arrayBuffer().then((ab) => {
+        blobChain = blobChain
+          .then(() => blob.arrayBuffer())
+          .then((ab) => {
             handleDecoded(decodeWireBinary(ab));
-          }),
-        );
+          })
+          .catch((err: unknown) => {
+            // A throw here (typically a consumer onMessage callback) must NOT
+            // poison the chain: without this catch blobChain stays rejected and
+            // every later Blob frame's .then is skipped, silently dropping all
+            // binary frames until reconnect. iOS Safari delivers binary WS
+            // frames as Blob, and markActivity() already ran on arrival, so the
+            // liveness probe never fires -> the tab looks connected but renders
+            // nothing. Log and continue; arrival order is preserved.
+            console.error("vterm: dropped binary (blob) frame", err);
+          });
         return;
       }
       if (typeof ev.data === "string") {
@@ -596,11 +639,7 @@ export function connect(): void {
       const epoch = msg.serverEpoch;
       if (epoch !== undefined && epoch !== 0) {
         if (st.lastServerEpoch !== null && st.lastServerEpoch !== epoch) {
-          st.bytesSent = 0;
-          st.bytesAcked = 0;
-          st.outbox.length = 0;
-          st.outboxBytes = 0;
-          cb?.onServerRestart?.();
+          resetSessionAfterRestart(st);
         }
         st.lastServerEpoch = epoch;
       }
@@ -622,11 +661,7 @@ export function connect(): void {
       // not duplicated. Skip this branch when bytesSent = 0 (genuine
       // first-connect; received=0 is correct).
       if (msg.received === 0 && st.bytesAcked > 0) {
-        st.bytesSent = 0;
-        st.bytesAcked = 0;
-        st.outbox.length = 0;
-        st.outboxBytes = 0;
-        cb?.onServerRestart?.();
+        resetSessionAfterRestart(st);
         return;
       }
       applyAck(st, msg.received);

package/src/keyboard.ts

@@ -722,7 +722,7 @@ export interface MobileToolbarController {
 /**
  * Wire a mobile / touch toolbar of on-screen keyboard buttons (Ctrl,
  * arrows, Tab, Enter, Esc, plus a collapse toggle) to a vterm send
- * sink. This was duplicated across vibekit and vibecli — same wire
+ * sink. This was duplicated across vibekit and web-terminal-kiro — same wire
  * sequences, same sticky-Ctrl semantics, same DECCKM nuance — so it
  * lives here.
  *

package/src/render.ts

@@ -162,6 +162,22 @@ let defaultSpacing = 0;
 let onCursorMove: (() => void) | null = null;
 let pendingFrame: number | undefined;
 
+// Bounded error-path reschedule (l-f28 / d-u4-1). The drain loop deletes a
+// queued row only AFTER upsertRow succeeds, so a row whose build throws stays
+// queued. flushRender's catch reschedules to finish a partial drain and to
+// retry a transient throw (a font/measureText race), but a row that throws
+// deterministically would otherwise turn catch -> rAF -> throw into a ~60fps
+// busy loop (CPU/battery burn + per-frame console spam) that never stops, even
+// on an idle session. `flushDrainedThisPass` records forward progress (queued
+// rows actually built this pass; reset at each flushRenderInner entry, and
+// visible to the catch because a mid-drain throw leaves it at the count so
+// far). `renderNoProgressStreak` counts consecutive passes that threw with zero
+// progress; once it passes the cap the catch stops rescheduling and lets the
+// next inbound frame retry (the pre-l-f28 behavior for a stuck row).
+let flushDrainedThisPass = 0;
+let renderNoProgressStreak = 0;
+const MAX_RENDER_NO_PROGRESS_RETRIES = 3;
+
 /**
  * Initialize the renderer by attaching it to a pair of DOM elements: the
  * scrollable terminal wrapper and the inner output container that receives
@@ -197,6 +213,8 @@ export function init(opts: {
     cancelAnimationFrame(pendingFrame);
     pendingFrame = undefined;
   }
+  flushDrainedThisPass = 0;
+  renderNoProgressStreak = 0;
   startCursorBlink();
 }
 
@@ -239,6 +257,37 @@ export function boundStore(): LineStore {
   return store;
 }
 
+/**
+ * Queue every retained line for building, viewport-first: the live window rows
+ * (what the user sees) in ascending order first, then scrollback newest->oldest
+ * so rows adjacent to the viewport fill before deep history. Iterates the
+ * retained key set (forEachLine), NOT the integer range [oldest, highest], so a
+ * sparse store (a frame whose base jumped far from a retained index) never
+ * freezes the drain. Shared by the two wipe-and-rebuild-from-store paths
+ * (rebuild() and the alt-exit branch in flushRenderInner) so both order rows
+ * identically; the per-frame budget then spreads a large backlog across frames
+ * without janking.
+ */
+function queueRowsViewportFirst(): void {
+  const winBase = store.getWindow().base;
+  const inWindow: number[] = [];
+  const belowWindow: number[] = [];
+  store.forEachLine((abs) => {
+    if (abs >= winBase) {
+      inWindow.push(abs);
+    } else {
+      belowWindow.push(abs);
+    }
+  });
+  for (const abs of inWindow) {
+    renderQueue.add(abs);
+  }
+  for (let i = belowWindow.length - 1; i >= 0; i--) {
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- index in range
+    renderQueue.add(belowWindow[i]!);
+  }
+}
+
 /**
  * Wipe the DOM and rebuild it from the current store, viewport-first and
  * budgeted. The live window (what the user sees) builds first, then scrollback
@@ -257,27 +306,13 @@ export function rebuild(): void {
   prevCursorCol = -1;
   prevCursorHidden = false;
   prevCursorStyleVal = -1;
+  // Fresh surface: a stale give-up streak from a prior store must not deny the
+  // rebuilt surface its full transient-retry budget.
+  renderNoProgressStreak = 0;
   // Alt screen paints from the ephemeral grid in the flush, so it needs no
   // absolute-index queueing here.
   if (!store.isAlt()) {
-    const oldest = store.oldestIndex();
-    const highest = store.highestIndex();
-    if (highest >= 0) {
-      const winStart = Math.max(store.getWindow().base, oldest);
-      // Live window first (viewport), ascending.
-      for (let abs = winStart; abs <= highest; abs++) {
-        if (store.getLine(abs) !== undefined) {
-          renderQueue.add(abs);
-        }
-      }
-      // Then scrollback, newest to oldest, so rows nearest the viewport fill in
-      // before deep history.
-      for (let abs = winStart - 1; abs >= oldest; abs--) {
-        if (store.getLine(abs) !== undefined) {
-          renderQueue.add(abs);
-        }
-      }
-    }
+    queueRowsViewportFirst();
   }
   scheduleFlush();
 }
@@ -554,7 +589,7 @@ function buildRowSpans(runs: WireRun[], cursorAt: number): (HTMLSpanElement | HT
       const a = document.createElement("a");
       a.href = href;
       a.target = "_blank";
-      a.rel = "noopener";
+      a.rel = "noopener noreferrer";
       // OSC 8 app hyperlink: base `.term-link`. Auto-detected URLs additionally
       // get `.term-autolink` (see linkifySpans).
       a.className = "term-link";
@@ -620,14 +655,46 @@ function flushRender(): void {
   pendingFrame = undefined;
   try {
     flushRenderInner();
+    // A clean pass means the error condition (if any) has cleared, so give a
+    // later transient error its full retry budget again. Any backlog reschedule
+    // was already issued from flushRenderInner's own end-of-body.
+    renderNoProgressStreak = 0;
   } catch (err) {
     console.error("vterm: render error", err);
+    // flushRenderInner threw mid-drain, skipping its own end-of-body
+    // "if (renderQueue.size > 0) scheduleFlush()" reschedule, so rows still
+    // queued would strand until the next external scheduleFlush() (a new
+    // frame). Reschedule here to finish the drain and to retry a transient
+    // throw (l-f28) -- but BOUND it. The drain loop deletes a row only after
+    // upsertRow succeeds, so a row that throws deterministically stays queued;
+    // an unconditional catch -> rAF -> throw reschedule is then a ~60fps busy
+    // loop that never stops, even on an idle session. Reschedule while the pass
+    // made forward progress (the backlog is shrinking) or the consecutive
+    // no-progress streak is under the cap (covers a transient font/measureText
+    // race that clears within a frame or two); once passes throw with zero
+    // progress past the cap, stop and let the next inbound frame (drainChanges)
+    // retry -- the pre-l-f28 behavior for a permanently stuck row.
+    if (renderQueue.size === 0) {
+      renderNoProgressStreak = 0;
+    } else if (flushDrainedThisPass > 0) {
+      renderNoProgressStreak = 0;
+      scheduleFlush();
+    } else if (renderNoProgressStreak < MAX_RENDER_NO_PROGRESS_RETRIES) {
+      renderNoProgressStreak++;
+      scheduleFlush();
+    } else {
+      console.error("vterm: giving up render retry after repeated no-progress errors");
+    }
   }
   // Single auto-follow invariant, applied after every DOM mutation.
   stickToBottomIfFollowing();
 }
 
 function flushRenderInner(): void {
+  // Forward-progress accounting for the bounded error-path reschedule. Reset at
+  // entry, incremented per drained row below; a mid-drain throw leaves it at
+  // the count-so-far for flushRender's catch to read.
+  flushDrainedThisPass = 0;
   const ch = store.drainChanges();
 
   if (ch.fullReset) {
@@ -666,13 +733,15 @@ function flushRenderInner(): void {
     return;
   }
   if (altRendered) {
-    // Just exited alt: drop the ephemeral rows and rebuild from the store.
+    // Just exited alt: drop the ephemeral rows and rebuild from the store,
+    // viewport-first (shared with rebuild()) so the visible viewport fills
+    // before deep scrollback on a large-history alt-exit.
     altRendered = false;
     output.replaceChildren();
     rowEls.clear();
     renderQueue.clear();
     trimMarkerEl = null;
-    store.forEachLine((abs) => renderQueue.add(abs));
+    queueRowsViewportFirst();
   }
 
   // Queue this frame's changed rows for building.
@@ -705,14 +774,16 @@ function flushRenderInner(): void {
 
   // 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.
-  let built = 0;
+  // flushDrainedThisPass doubles as the per-frame budget counter and the
+  // forward-progress signal the error-path reschedule reads (it was reset to 0
+  // at entry and nothing between there and here touches it).
   for (const abs of renderQueue) {
-    if (built >= MAX_ROWS_PER_FRAME) {
+    if (flushDrainedThisPass >= MAX_ROWS_PER_FRAME) {
       break;
     }
     upsertRow(abs);
     renderQueue.delete(abs);
-    built++;
+    flushDrainedThisPass++;
   }
 
   updateTrimMarker();

package/src/status-stream.ts

@@ -5,12 +5,18 @@
 // (re)open so the consumer can trigger it. Pairs with the Go
 // terminal.SessionManager EventsHandler.
 
+import { nextBackoffDelay } from "./reconnect.js";
+
 /** SessionStatus is one session's current status as carried on the stream. It
  *  mirrors the server's status event. */
 export interface SessionStatus {
   readonly id: string;
   readonly status: "working" | "idle" | "input" | "done" | "exited";
   readonly title: string;
+  /** the raw client-set title (before the OSC fallback baked into `title`); a
+   *  consumer that treats the program's OSC window title as unreliable reads
+   *  this instead of `title`. */
+  readonly clientTitle?: string;
   readonly createdAt: string;
   /** true when the session is gone (closed or reaped); the consumer drops it. */
   readonly removed?: boolean;
@@ -30,7 +36,9 @@ export interface StatusStreamCallbacks {
   /** Called on every (re)open, including auto-reconnects, so the consumer can
    *  resync after a gap (the stream only carries future changes). */
   onOpen?: () => void;
-  /** Called when the stream errors; the EventSource then auto-reconnects. */
+  /** Called when the stream errors. A transient drop is auto-reconnected by
+   *  EventSource; a permanent close (non-2xx / wrong content-type) is
+   *  re-established by this module with capped backoff. */
   onError?: () => void;
 }
 
@@ -39,6 +47,10 @@ export interface StatusStreamCallbacks {
 export interface EventSourceLike {
   addEventListener: (type: string, listener: (event: MessageEvent) => void) => void;
   close: () => void;
+  /** EventSource.readyState: 0 CONNECTING, 1 OPEN, 2 CLOSED. A permanent close
+   *  (non-2xx response / wrong content-type / auth failure) sets CLOSED and
+   *  native auto-reconnect never fires; the module re-establishes on CLOSED. */
+  readonly readyState: number;
 }
 
 /** EventSourceFactory builds an EventSourceLike for a URL. */
@@ -58,6 +70,9 @@ const defaultFactory: EventSourceFactory = (url) => {
     close: () => {
       es.close();
     },
+    get readyState() {
+      return es.readyState;
+    },
   };
 };
 
@@ -68,33 +83,62 @@ export function connectStatusStream(
   cb: StatusStreamCallbacks,
   make: EventSourceFactory = defaultFactory,
 ): StatusStream {
-  const es = make(path);
+  let es: EventSourceLike;
+  let closed = false;
+  let reconnectTimer: ReturnType<typeof setTimeout> | undefined;
+  let backoffMs = 500;
   const { onOpen, onError } = cb;
-  if (onOpen) {
+  const open = (): void => {
+    es = make(path);
     es.addEventListener("open", () => {
-      onOpen();
+      backoffMs = 500; // reset backoff on a successful (re)open
+      if (onOpen) {
+        onOpen();
+      }
+    });
+    es.addEventListener("message", (event) => {
+      const raw: unknown = event.data;
+      if (typeof raw !== "string") {
+        return; // non-text frame, ignore
+      }
+      let status: SessionStatus;
+      try {
+        status = JSON.parse(raw) as SessionStatus;
+      } catch {
+        console.warn("vterm: dropped malformed status-stream frame");
+        return; // skip a malformed frame, keep the stream
+      }
+      cb.onStatus(status);
     });
-  }
-  es.addEventListener("message", (event) => {
-    const raw: unknown = event.data;
-    if (typeof raw !== "string") {
-      return; // non-text frame, ignore
-    }
-    let status: SessionStatus;
-    try {
-      status = JSON.parse(raw) as SessionStatus;
-    } catch {
-      return; // skip a malformed frame, keep the stream
-    }
-    cb.onStatus(status);
-  });
-  if (onError) {
     es.addEventListener("error", () => {
-      onError();
+      if (onError) {
+        onError();
+      }
+      // Native EventSource auto-reconnect covers a transient drop but NOT a
+      // permanent close (server restart -> proxy 502/non-2xx, auth 401/403,
+      // wrong content-type), which sets readyState CLOSED and never retries.
+      // Re-establish so per-tab status doesn't freeze until a page reload while
+      // the terminal WS recovers on its own backoff. onOpen fires on the reopen,
+      // so the consumer's resync still runs.
+      if (es.readyState === 2 && !closed && reconnectTimer === undefined) {
+        const step = nextBackoffDelay(backoffMs);
+        reconnectTimer = setTimeout(() => {
+          reconnectTimer = undefined;
+          if (!closed) {
+            open();
+          }
+        }, step.scheduledMs);
+        backoffMs = step.nextBaseMs;
+      }
     });
-  }
+  };
+  open();
   return {
     close: () => {
+      closed = true;
+      if (reconnectTimer !== undefined) {
+        clearTimeout(reconnectTimer);
+      }
       es.close();
     },
   };

package/src/store.ts

@@ -151,7 +151,12 @@ export class LineStore {
     if (this.oldest < 0) {
       return;
     }
-    for (let abs = this.oldest; abs <= this.highest; abs++) {
+    // Iterate the retained keys (bounded by maxLines), sorted ascending, not the
+    // integer range [oldest, highest]: a frame whose base jumps far from a
+    // retained index makes that range ~2^53 wide and freezes the tab (the DoS
+    // enforceCap is written to avoid).
+    const keys = [...this.lines.keys()].sort((a, b) => a - b);
+    for (const abs of keys) {
       const runs = this.lines.get(abs);
       if (runs !== undefined) {
         cb(abs, runs);
@@ -316,8 +321,10 @@ export class LineStore {
     if (this.oldest < 0 || this.oldest >= base) {
       return;
     }
-    for (let abs = this.oldest; abs < base; abs++) {
-      if (this.lines.delete(abs)) {
+    // Bounded key-scan (like enforceCap), not an integer walk over [oldest, base).
+    for (const abs of [...this.lines.keys()]) {
+      if (abs < base) {
+        this.lines.delete(abs);
         this.evicted.add(abs);
         this.dirty.delete(abs);
       }
@@ -349,19 +356,21 @@ export class LineStore {
     if (this.highest <= windowBottom) {
       return;
     }
-    for (let abs = windowBottom + 1; abs <= this.highest; abs++) {
-      if (this.lines.delete(abs)) {
+    // Bounded key-scan (like enforceCap), NOT an integer walk over
+    // [windowBottom+1, highest]: a frame whose base drops far below a high
+    // retained index would otherwise loop up to ~2^53 times and freeze the tab.
+    let newHighest = -1;
+    for (const abs of [...this.lines.keys()]) {
+      if (abs > windowBottom) {
+        this.lines.delete(abs);
         this.evicted.add(abs);
         this.dirty.delete(abs);
+      } else if (abs > newHighest) {
+        newHighest = abs;
       }
     }
-    // New highest is the greatest retained index at or below the window bottom.
-    let h = windowBottom;
-    while (h >= this.oldest && !this.lines.has(h)) {
-      h--;
-    }
-    if (h >= this.oldest) {
-      this.highest = h;
+    if (newHighest >= 0) {
+      this.highest = newHighest;
     } else {
       this.highest = -1;
       this.oldest = -1;

package/src/wire-binary.ts

@@ -43,6 +43,12 @@ const MODE_FLAG_APP_KEYPAD = 16;
 const MODE_FLAG_REVERSE_VIDEO = 32;
 const MODE_FLAG_MOUSE_PIXELS = 64;
 
+// Shared across all one-shot decode() calls (no {stream:true} is used here), so
+// a single module-level instance is safe and avoids allocating a fresh
+// TextDecoder per styled run / OSC-8 URI on the hot decode path (a single
+// scroll frame can carry thousands of runs).
+const textDecoder = new TextDecoder();
+
 class Cursor {
   view: DataView;
   bytes: Uint8Array;
@@ -84,7 +90,7 @@ class Cursor {
   utf8(len: number): string {
     const slice = this.bytes.subarray(this.off, this.off + len);
     this.off += len;
-    return new TextDecoder().decode(slice);
+    return textDecoder.decode(slice);
   }
 }
 
@@ -121,6 +127,7 @@ function readRowRuns(c: Cursor): WireRun[] {
  */
 export function decodeWireBinary(buf: ArrayBuffer): ServerMessage | null {
   if (buf.byteLength < 9) {
+    console.warn("vterm: dropped undersized wire frame", buf.byteLength);
     return null;
   }
   try {
@@ -131,6 +138,7 @@ export function decodeWireBinary(buf: ArrayBuffer): ServerMessage | null {
     // the caller skip this frame rather than crashing the decode loop.
     // The next flush will carry a complete snapshot anyway.
     if (err instanceof RangeError) {
+      console.warn("vterm: dropped malformed/truncated wire frame", buf.byteLength);
       return null;
     }
     throw err;
@@ -261,5 +269,6 @@ function decodeWireBinaryInner(buf: ArrayBuffer): ServerMessage | null {
     // here — returning null keeps it out of the onMessage path.
     return null;
   }
+  console.warn("vterm: unknown wire message type", msgType);
   return null;
 }