@cplieger/web-terminal-engine 3.0.1 → 3.0.7

package/jsr.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/web-terminal-engine",
-  "version": "3.0.1",
+  "version": "3.0.7",
   "type": "module",
   "scripts": {
     "typecheck": "tsc -p tsconfig.json",
@@ -21,11 +21,11 @@
     "esbuild": "0.28.1",
     "eslint": "10.7.0",
     "fast-check": "4.9.0",
-    "happy-dom": "20.10.6",
+    "happy-dom": "20.11.0",
     "pngjs": "7.0.0",
-    "prettier": "3.9.5",
+    "prettier": "3.9.6",
     "typescript": "npm:@typescript/typescript6@6.0.2",
-    "typescript-eslint": "8.64.0",
+    "typescript-eslint": "8.65.0",
     "vitest": "4.1.10"
   },
   "description": "Browser terminal engine: VT500 screen buffer, DOM renderer, and binary wire protocol",

package/src/render.ts

@@ -125,13 +125,17 @@ const rowEls = new Map<number, HTMLDivElement>();
 let trimMarkerEl: HTMLDivElement | null = null;
 
 // Rows awaiting a DOM (re)build, processed in budgeted batches across frames.
-// A session restore (kiro-cli's /chat) or a `cat bigfile` dumps thousands of
-// lines in one wire frame; building them all in a single rAF janks or, on a
-// constrained device, hangs the tab. The store still ingests the whole burst
-// at once (it is cheap, pure data); the renderer drains this queue at most
-// MAX_ROWS_PER_FRAME per frame and reschedules until it is empty, so each
-// frame stays short and the terminal fills smoothly. The cursor row is always
-// built regardless of the budget so the caret never lags.
+// A session restore (kiro-cli's /chat), a post-resize transcript reprint, or a
+// `cat bigfile` dumps thousands of lines in one wire frame; building them all
+// in a single rAF janks or, on a constrained device, hangs the tab. The store
+// still ingests the whole burst at once (it is cheap, pure data); the renderer
+// drains this queue at most MAX_ROWS_PER_FRAME per frame and reschedules until
+// it is empty, so each frame stays short. The drain is VIEWPORT-FIRST each
+// frame (see flushRenderInner): live-window rows build before any scrollback
+// backlog, and scrollback drains newest->oldest so the backlog fills upward,
+// above the bottom-pinned viewport — offscreen — instead of visibly streaming
+// through it. The cursor row is always built regardless of the budget so the
+// caret never lags.
 const renderQueue = new Set<number>();
 const MAX_ROWS_PER_FRAME = 300;
 
@@ -245,7 +249,7 @@ export function init(opts: {
   }
   flushDrainedThisPass = 0;
   renderNoProgressStreak = 0;
-  startCursorBlink();
+  syncCursorBlink();
 }
 
 /**
@@ -735,7 +739,11 @@ function flushRenderInner(): void {
   cursorCol = win.cursorCol;
   cursorHidden = win.cursorHidden;
   cursorStyleVal = win.cursorStyle;
-  setCursorBlink(win.cursorBlink);
+  blinkEnabled = win.cursorBlink;
+  // Reconcile the blink interval with the fresh cursor state (blink mode and
+  // DECTCM visibility may both have changed this frame); no-op when the
+  // resulting mode is unchanged.
+  syncCursorBlink();
 
   // Alt screen: render the ephemeral grid instead of the absolute buffer.
   // Returning here skips the dirtyLines queueing below — safe by invariant:
@@ -779,12 +787,31 @@ function flushRenderInner(): void {
     renderQueue.delete(newCursorAbs);
   }
 
-  // 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.
-  // 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).
+  // Drain up to MAX_ROWS_PER_FRAME queued rows this frame, viewport-first;
+  // the rest carry over to the next frame (scheduled below) so one big burst
+  // never blocks paint. Live-window rows build first (ascending), then the
+  // scrollback backlog newest->oldest, so the backlog fills upward above the
+  // bottom-pinned viewport — offscreen. A Set's insertion order did the
+  // opposite under load: a multi-thousand-row backlog (a resume replay,
+  // kiro-cli's post-resize transcript reprint, `cat bigfile`) queued ahead of
+  // freshly-dirtied window rows, so the visible screen either churned through
+  // history or froze (only the force-built cursor row moving) for seconds on
+  // a slow device while the backlog drained. 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).
+  const inWindow: number[] = [];
+  const belowWindow: number[] = [];
   for (const abs of renderQueue) {
+    if (abs >= win.base) {
+      inWindow.push(abs);
+    } else {
+      belowWindow.push(abs);
+    }
+  }
+  inWindow.sort((a, b) => a - b);
+  belowWindow.sort((a, b) => b - a);
+  for (const abs of [...inWindow, ...belowWindow]) {
     if (flushDrainedThisPass >= MAX_ROWS_PER_FRAME) {
       break;
     }
@@ -931,8 +958,20 @@ function stickToBottomIfFollowing(): void {
 
 // --- Cursor blink ---
 const CURSOR_BLINK_MS = 530;
+// While the application hides the cursor (DECTCM — e.g. a full-screen TUI
+// that paints its own cursor cell, like an agent front-end), the fast toggle
+// would only restyle a display:none overlay, so the interval downshifts to
+// this slow re-check: still polling for the cursor's return (a self-healing
+// backstop even if a transition frame were somehow missed — the flush hook is
+// the primary, instant restart), at a fraction of the 530ms blink's wakeups.
+// For agent consumers the hidden-cursor state is the session's steady state.
+const CURSOR_RECHECK_MS = 4000;
 let blinkInterval: ReturnType<typeof setInterval> | null = null;
 let blinkEnabled = true;
+// What the running interval (if any) is configured as. syncCursorBlink()
+// reconfigures only on mode change, so it is safe to call on every flush.
+type BlinkMode = "off" | "idle" | "fast";
+let blinkMode: BlinkMode = "off";
 
 // hiddenDoc reports whether the page is currently background/hidden. The blink
 // interval is gated on it: rAF-driven flushes already freeze in a hidden tab,
@@ -942,25 +981,42 @@ function hiddenDoc(): boolean {
   return typeof document !== "undefined" && document.visibilityState === "hidden";
 }
 
-function startCursorBlink(): void {
-  if (blinkInterval !== null || !blinkEnabled || hiddenDoc()) {
-    return;
+// desiredBlinkMode folds the three gates into an interval mode: no timer at
+// all when blinking is disabled or the page is hidden (both have event-driven
+// restarts — the next mode frame's flush and visibilitychange), the fast
+// phase toggle when the cursor is visible, and the slow re-check while the
+// application hides it.
+function desiredBlinkMode(): BlinkMode {
+  if (!blinkEnabled || hiddenDoc()) {
+    return "off";
   }
-  // The blink class lives on termWrap: the caret overlay is a termWrap child
-  // (not inside output), and the `.cursor-blink-off .term-cursor` descendant
-  // selector must reach it.
-  termWrap.classList.remove("cursor-blink-off");
-  blinkInterval = setInterval(() => {
-    termWrap.classList.toggle("cursor-blink-off");
-  }, CURSOR_BLINK_MS);
+  return cursorHidden ? "idle" : "fast";
 }
 
-function stopCursorBlink(): void {
+// syncCursorBlink reconciles the interval with the current gate state; every
+// mode change resets the phase to solid. Called from the flush (blink mode +
+// DECTCM state), the visibilitychange listener, init(), and the idle re-check
+// itself. The blink class lives on termWrap: the caret overlay is a termWrap
+// child (not inside output), and the `.cursor-blink-off .term-cursor`
+// descendant selector must reach it.
+function syncCursorBlink(): void {
+  const mode = desiredBlinkMode();
+  if (mode === blinkMode) {
+    return;
+  }
+  blinkMode = mode;
   if (blinkInterval !== null) {
     clearInterval(blinkInterval);
     blinkInterval = null;
   }
   termWrap.classList.remove("cursor-blink-off");
+  if (mode === "fast") {
+    blinkInterval = setInterval(() => {
+      termWrap.classList.toggle("cursor-blink-off");
+    }, CURSOR_BLINK_MS);
+  } else if (mode === "idle") {
+    blinkInterval = setInterval(syncCursorBlink, CURSOR_RECHECK_MS);
+  }
 }
 
 // Pause the interval while hidden; resume (cursor solid, phase reset) when the
@@ -972,33 +1028,13 @@ if (typeof document !== "undefined") {
     if ((termWrap as HTMLElement | undefined) === undefined) {
       return;
     }
-    if (hiddenDoc()) {
-      // Stop the timer only: blinkEnabled keeps the server-driven state so
-      // foregrounding can restart without waiting for the next mode frame.
-      if (blinkInterval !== null) {
-        clearInterval(blinkInterval);
-        blinkInterval = null;
-      }
-      termWrap.classList.remove("cursor-blink-off");
-      return;
-    }
-    startCursorBlink();
+    // blinkEnabled/cursorHidden keep their server-driven state across a
+    // background stint, so foregrounding restores the right mode without
+    // waiting for the next frame.
+    syncCursorBlink();
   });
 }
 
-/** Called from the flush when cursorBlink state changes. */
-function setCursorBlink(enabled: boolean): void {
-  if (enabled === blinkEnabled) {
-    return;
-  }
-  blinkEnabled = enabled;
-  if (enabled) {
-    startCursorBlink();
-  } else {
-    stopCursorBlink();
-  }
-}
-
 // --- Font metrics & sizing ---
 /**
  * Re-measure the cell width/height from the rendered DOM. Call after any font