@cplieger/web-terminal-engine 3.0.0 → 3.0.6

package/jsr.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/web-terminal-engine",
-  "version": "3.0.0",
+  "version": "3.0.6",
   "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/index.ts

@@ -15,7 +15,7 @@ export {
   WIRE_INCOMPATIBLE_CLOSE_CODE,
   WIRE_PROTOCOL_VERSION,
 } from "./wire-compatibility.js";
-export type { WireIncompatibility } from "./wire-compatibility.js";
+export type { WireCompatibility, WireIncompatibility } from "./wire-compatibility.js";
 export { controlFrame, CONTROL_FRAME_PREFIX } from "./wire.js";
 export { wsURL } from "./wsurl.js";
 export { WS_PATH, SESSIONS_PATH, SESSION_EVENTS_PATH } from "./routes.js";

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;
 
@@ -779,12 +783,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;
     }

package/src/wire-compatibility.ts

@@ -12,8 +12,15 @@ export const MIN_SUPPORTED_SERVER_WIRE_VERSION = 3;
 /** Definitive private WebSocket close code for an incompatible declared peer. */
 export const WIRE_INCOMPATIBLE_CLOSE_CODE = 4002;
 
+/** Shape of the machine-readable compatibility metadata object. */
+export interface WireCompatibility {
+  readonly protocolVersion: number;
+  readonly minimumServerProtocolVersion: number;
+  readonly incompatibleCloseCode: number;
+}
+
 /** Machine-readable compatibility metadata shipped in every TS release. */
-export const WIRE_COMPATIBILITY = Object.freeze({
+export const WIRE_COMPATIBILITY: WireCompatibility = Object.freeze({
   protocolVersion: WIRE_PROTOCOL_VERSION,
   minimumServerProtocolVersion: MIN_SUPPORTED_SERVER_WIRE_VERSION,
   incompatibleCloseCode: WIRE_INCOMPATIBLE_CLOSE_CODE,