@cplieger/web-terminal-engine 6.4.0-dev.4 → 6.4.0-dev.6

package/jsr.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/web-terminal-engine",
-  "version": "6.4.0-dev.4",
+  "version": "6.4.0-dev.6",
   "license": "MPL-2.0",
   "exports": {
     ".": "./src/index.ts"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/web-terminal-engine",
-  "version": "6.4.0-dev.4",
+  "version": "6.4.0-dev.6",
   "type": "module",
   "scripts": {
     "typecheck": "tsc -p tsconfig.json",
@@ -16,7 +16,7 @@
   "devDependencies": {
     "@cplieger/web-terminal-engine-v3": "npm:@cplieger/web-terminal-engine@2.8.0",
     "@eslint/js": "10.0.1",
-    "@playwright/test": "1.64.0",
+    "@playwright/test": "1.64.1",
     "@stryker-mutator/core": "10.0.0",
     "@stryker-mutator/typescript-checker": "10.0.0",
     "@stryker-mutator/vitest-runner": "10.0.0",
@@ -28,11 +28,11 @@
     "eslint": "10.12.0",
     "fast-check": "4.10.2",
     "knip": "6.41.0",
-    "playwright": "1.64.0",
+    "playwright": "1.64.1",
     "pngjs": "7.0.0",
     "prettier": "3.9.10",
     "typescript": "npm:@typescript/typescript6@6.0.2",
-    "typescript-eslint": "8.71.1",
+    "typescript-eslint": "8.71.2",
     "vitest": "5.0.4"
   },
   "overrides": {

package/src/keyboard.ts

@@ -1,6 +1,6 @@
 // Keyboard event → terminal byte sequence mapping, mirroring xterm.js's
-// evaluateKeyboardEvent (src/common/input/Keyboard.ts) so vim, readline, Ink
-// and the host application get the keys they expect. Modifier digit per the
+// evaluateKeyboardEvent (src/common/input/Keyboard.ts) so vim, readline and
+// full-screen programs get the keys they expect. Modifier digit per the
 // xterm/VT520 convention: 1=Shift, 2=Alt, 4=Ctrl, 8=Meta, summed then +1 for
 // CSI 1;{n}{letter}. DECCKM and DECKPAM come from the injected mode state,
 // which the server's modes frame keeps current.
@@ -162,9 +162,9 @@ const KEYPAD_SS3: Record<string, string | undefined> = {
 
 // -- Kitty keyboard protocol (progressive enhancement) ----------------------
 // Under an active kitty flag, keys that do NOT produce text are encoded per the
-// kitty protocol so an app that enabled it (Codex via crossterm) gets
-// unambiguous key events. Only the disambiguate flag (0x1) is honored; the
-// server masks off 0x2/0x4/0x8/0x10, so the CSI ?u query reports only 0x1.
+// kitty protocol so an app that enabled it gets unambiguous key events. Only
+// the disambiguate flag (0x1) is honored; the server masks off
+// 0x2/0x4/0x8/0x10, so the CSI ?u query reports only 0x1.
 // Text-producing keys still flow through the hidden textarea as text (this
 // encoder returns "ignore" for them), per the spec and the IME model.
 
@@ -485,9 +485,9 @@ export function mapKeyboardEvent(ev: KeyboardEvent, modes: KeyboardModes): Keybo
   // handle them. Heuristic: only take Ctrl+letter when Shift is NOT
   // held AND the letter is one of the ones xterm consumes (a-z),
   // skipping the few that browsers commonly reserve.
-  // (We deliberately pass Ctrl+R / Ctrl+T / Ctrl+W through to the PTY
-  // — the host application's Ctrl+T transcript view depends on it. Users on macOS
-  // who want browser-reserved combos can use Cmd instead.)
+  // (Ctrl+R, Ctrl+T and Ctrl+W still go to the PTY: readline binds them to
+  // reverse search, transpose and word rubout, and full-screen programs bind
+  // them too. On macOS, Cmd reaches the browser's own combos.)
 
   // Shift+PageUp / Shift+PageDown — local scrollback navigation
   // (matches xterm.js KeyboardResultType.PAGE_UP/PAGE_DOWN).

package/src/render.ts

@@ -330,8 +330,8 @@ export function createRenderer(opts: RendererOptions): Renderer {
   let historyBudgetFn: (() => number) | null = opts.historyBudget ?? null;
 
   // Rows awaiting a DOM (re)build, drained at most MAX_ROWS_PER_FRAME per frame:
-  // a session restore or `cat bigfile` dumps thousands of lines in one frame,
-  // and building them in one rAF hangs a constrained device. The drain is
+  // a session's transcript replay or `cat bigfile` dumps thousands of lines in
+  // one frame, and building them in one rAF hangs a constrained device. The drain is
   // VIEWPORT-FIRST (live-window rows, then scrollback newest->oldest so the
   // backlog fills upward, offscreen above the pinned viewport), and the cursor
   // row is always built so the caret never lags.

package/src/status-stream.ts

@@ -35,7 +35,7 @@ export interface SessionInfo {
   /** the session's short public name, safe to put in a URL: 1 to 64 characters
    *  of `[A-Za-z0-9_-]`, unique among live sessions, and NOT a capability
    *  (nothing attaches with it; only `id` does). The server mints a random one
-   *  and a host may replace it (web-terminal-kiro sets the kiro-cli thread id).
+   *  and a host may replace it (for example with its program's own session id).
    *  Absent from a server before 6.2 and from a status event carrying
    *  `removed`. Untrusted wire text: validate it before use. */
   readonly alias?: string;
@@ -73,7 +73,7 @@ export interface SessionInfo {
    *  server accepts it and it becomes the arrangement every device sees. */
   readonly order?: number;
   /** true once the session has emitted a genuine activity signal — OSC 9;4
-   *  progress (kiro-cli, Claude Code, …) or a classified OSC 9 notification.
+   *  progress or a classified OSC 9 notification.
    *  Sticky for the session's life. Consumers reveal the per-tab activity dot
    *  only when this is set; a program that emits no OSC 9 signal (a plain shell)
    *  keeps its tab dot hidden. */

package/src/store.ts

@@ -433,25 +433,12 @@ export class LineStore {
   private paging = false;
 
   /**
-   * The highest index the APPLICATION erased (ED3), or -1. A second watermark
-   * beside `everEvictedThrough` because the two answer different questions and
-   * only one of them is a trim.
-   *
-   * `everEvictedThrough` means "we dropped this to stay inside a memory budget",
-   * and it drives the "earlier output trimmed" affordance. ED3 is not that: the
-   * app discarded its own scrollback, so a marker would be permanent noise on
-   * kiro-cli (which clears on every resize redraw), which is why ED3 deliberately
-   * leaves it alone. That left NOTHING refusing an erased index, and a page reply
-   * whose data timeout had already released single-flight comes back
-   * UNCORRELATED — through the ordinary scroll path, classified TAIL, so outside
-   * the cache budget and the TTL both. It never leaves.
-   *
-   * Refusing an erased index is unconditionally safe within an epoch: the server's
-   * ring `Clear()` preserves `committed`, so an erased absolute index is never
-   * reused, and no legitimate later frame can carry one. The companion reprint an
-   * app emits in the same tick lands at NEW indices above everything the client
-   * held, which is why this watermark tracks what was actually DROPPED rather than
-   * the cleared bound — the bound would also refuse that reprint.
+   * The highest index the application erased (ED3), or -1. Not
+   * `everEvictedThrough`, which marks budget trims and drives the "earlier output
+   * trimmed" marker that ED3 must not show. Without it a late, uncorrelated page
+   * reply lands as TAIL, outside the cache budget and TTL, and never leaves. Safe
+   * within an epoch: the ring's `Clear()` keeps `committed`, so no erased index is
+   * reused. It tracks what was dropped; the cleared bound would refuse the reprint.
    */
   private erasedThrough = -1;
 
@@ -536,23 +523,12 @@ export class LineStore {
   private unconfirmedFrom = Number.POSITIVE_INFINITY;
 
   /**
-   * The resume REPLAY-EXCLUSION BOUNDARY: the highest index this client will not
-   * ask the server to re-send. Send this as `haveThrough`, never `highestIndex()`.
-   *
-   * The two differ by whatever the store holds provisionally, and that
-   * difference is a correctness bug once it reaches the wire. While a store has
-   * no socket (a background tab) it observes no base advance, so its window rows
-   * keep the content the app drew there, and claiming down to the window's
-   * bottom row tells the server "no need to re-send those" about rows whose
-   * committed content this client has never seen. The server replays strictly
-   * above `haveThrough`, so the provisional copies are never corrected and
-   * surface as scrollback under the new window: measured as a frozen kiro-cli
-   * composer box parked above the live region after almost every tab switch.
-   *
-   * NOT a residency fact and NOT "the highest confirmed row": the index this
-   * returns may be one the store never held or has since evicted. The only
-   * guarantee is `replayBoundary() <= highestIndex()`, with equality whenever
-   * nothing held is provisional.
+   * The resume replay-exclusion boundary: the highest index this client will not
+   * ask the server to re-send. Send it as `haveThrough`, never `highestIndex()`: a
+   * background tab's window rows hold what the app drew there, and claiming them
+   * means their committed content is never re-sent, so a stale input box surfaces
+   * as scrollback. It may name an index never held or since evicted; the only
+   * guarantee is `replayBoundary() <= highestIndex()`, equal when none is provisional.
    */
   replayBoundary(): number {
     if (this.highest < 0) {
@@ -690,30 +666,21 @@ export class LineStore {
     // Re-check the cap AFTER the window settled: a screen frame can LOWER the
     // retention bound without applying a single line — a height shrink whose
     // rows are byte-identical short-circuits applyLine on the idempotency
-    // guard, and applyLine is otherwise the only enforceCap caller. The R3
-    // adversarial rounds' interleaved property test failed on exactly this
-    // shape (~60% of seeds) until the bound was re-checked per FRAME, not
-    // only per content change.
+    // guard, and applyLine is otherwise the only enforceCap caller.
     this.enforceCap();
   }
 
   /** Apply a decoded scroll/history frame: each line at firstIndex + i. */
   applyScroll(msg: ScrollMessage): void {
     if (this.alt) {
-      // History strictly below the frozen MAIN window is safe to store while
-      // the alternate screen is active: the alt display renders from altRows,
-      // never from the abs store, and lines below win.base can only be
-      // main-screen scrollback — a resume batch's replay, or a post-resume
-      // durable chunk that raced an alt flip (the 2026-08 write-ordering
-      // race's last residual, closed here). They surface at alt exit's store
-      // rebuild. Anything AT or ABOVE the frozen base still violates the
-      // protocol invariant (the server never emits live scroll during alt)
-      // and is dropped rather than corrupting the frozen window region. With
-      // no main window ever seen (a fresh tab attaching straight into an
-      // in-alt session) there is no region to protect, so everything is
-      // accepted exactly as on the main-screen path — the alt-exit full
-      // frame overwrites the window region either way. applyLine's guard
-      // set applies to whatever passes.
+      // In alt, rows below the frozen MAIN window base are main-screen history
+      // (a resume replay, or a durable chunk that raced an alt flip) and are
+      // stored: the alt display renders from altRows, and they surface at alt
+      // exit's rebuild. Rows AT or ABOVE the base break the protocol (no live
+      // scroll during alt) and are dropped to keep the frozen window intact.
+      // With no main window ever seen (attaching straight into alt) there is
+      // nothing to protect, so all rows are accepted; the alt-exit full frame
+      // overwrites the window region either way.
       const base = this.win.height > 0 ? this.win.base : Number.POSITIVE_INFINITY;
       for (let i = 0; i < msg.lines.length; i++) {
         const abs = msg.firstIndex + i;
@@ -1133,8 +1100,7 @@ export class LineStore {
      * The store used to derive it from `viewportAbs >= win.base`, and every
      * failure of that derivation was a real defect. It read a window descriptor
      * that step 4 of this very transition RETIRES, so the answer was wrong for
-     * every predicted replay jump (r2's confirmed high, patched by capturing the
-     * value earlier — a fix that left the hazard in place). With no descriptor at
+     * every predicted replay jump. With no descriptor at
      * all, which is the DOMINANT shape here (this ack is the first frame of its
      * batch, so it precedes the window frame, and a hydrated store persists no
      * window), the fallback was wrong in both directions: "not following" strands
@@ -1669,8 +1635,8 @@ export class LineStore {
     return s !== null && abs >= s.lo && abs < s.hi;
   }
 
-  // applyScrollbackCleared handles ED3 (which an inline TUI such as kiro-cli
-  // emits on every resize): drop lines below `base`, leave everEvictedThrough
+  // applyScrollbackCleared handles ED3 (which an inline TUI can emit on every
+  // resize): drop lines below `base`, leave everEvictedThrough
   // alone (a deliberate erase is not a trim), CANCEL the in-flight request
   // (its reply would re-admit the erased rows through the guard-2 exemption),
   // and snap the paging floor to `base` (or the trigger re-fetches them). The
@@ -1754,33 +1720,21 @@ export class LineStore {
   }
 
   private enforceCap(): void {
-    // The gate and the victim
-    // target read `tailCount`, not `lines.size`. Browse cache lives under its
-    // OWN budget, enforced at page-apply time, so live output must not be able
-    // to evict a page the reader is browsing — at the default batch that would
-    // be up to 93 cache lines per applied line.
+    // The gate and the victim target read `tailCount`, not `lines.size`: browse
+    // cache has its OWN budget, enforced at page-apply time, so live output must
+    // not evict a page the reader is browsing (up to 93 cache lines per applied
+    // line at the default batch).
     if (this.tailCount <= this.tailBound) {
       return;
     }
     const target = this.tailBound - evictionBatch(this.tailBound) + 1;
-    // ONE oldest-first eviction walk that SKIPS the live window. The window
-    // is never evictable — the screen is documented as a fixed,
-    // always-present block, so the cap is a HISTORY budget floored at the
-    // live screen (a cap at or below the terminal height keeps the full
-    // screen with zero scrollback). Content ABOVE the window (a resume
-    // replay delivered before its window frame; a malformed stream that
-    // never advances the base) is ordinary evictable history too: the
-    // cursor hops over the window and keeps walking, so the bound
-    // size <= max(maxLines, window height) holds whatever shape the frames
-    // arrive in. Evicting that band OLDEST-first keeps the NEWEST lines —
-    // the ones adjacent to the incoming window — so after the window
-    // advances the retained set converges back to one contiguous block
-    // (R3 adversarial finding: the earlier newest-first tail trim parked a
-    // permanent interior hole under the live screen that resume, which
-    // replays only above haveThrough, could never backfill).
-    // everEvictedThrough advances over every TAIL eviction, including the
-    // hopped band — safe for the window frame that follows a replay because
-    // apply-line guard 2 exempts the live window (see applyLine).
+    // ONE oldest-first eviction walk that SKIPS the live window: the cap is a
+    // history budget floored at the screen height. Content above the window (a
+    // replay delivered before its window frame, a malformed stream) is evictable,
+    // so size <= max(maxLines, window height) holds for any frame order. Oldest-
+    // first keeps the lines next to the window; a newest-first trim leaves a hole
+    // under the live screen that resume cannot backfill. everEvictedThrough also
+    // covers the hopped band, safe because applyLine's guard 2 exempts the window.
     const winBottom = this.win.height > 0 ? this.win.base + this.win.height - 1 : -1;
     const hasWindow = this.win.height > 0;
     let cursor = this.oldest;
@@ -1867,7 +1821,7 @@ export class LineStore {
     if (hopped) {
       // The cursor hopped the window or a browse interval, so the minimum
       // retained key is not the cursor: recompute both bounds once per pass
-      // (bounded scan; once per PASS, never per victim — R3 perf finding).
+      // (bounded scan; once per PASS, never per victim).
       let min = -1;
       let max = -1;
       for (const k of this.lines.keys()) {
@@ -1945,8 +1899,8 @@ export class LineStore {
     // the alt frame. This keeps the retention bound (max(maxLines, window
     // height)) and the guard-2 window exemption defined over the MAIN screen,
     // the region alt exit must restore, rather than over a phantom range
-    // mixing the main base with the alt height (R4 review, all three models:
-    // a smaller alt frame otherwise appeared to lower the bound below the
+    // mixing the main base with the alt height (a smaller alt frame otherwise
+    // appeared to lower the bound below the
     // protected main rows, and the exemption described rows that were not the
     // writable screen).
     const next: WindowState = {

package/src/types.ts

@@ -61,7 +61,7 @@ export interface ScreenMessage {
   /**
    * True when the app issued ED3 (`CSI 3 J`, "erase saved lines") this frame:
    * the client drops its scrollback history (all lines below `base`), matching
-   * a real terminal. Inline TUIs (kiro-cli) emit ED3 on every resize redraw to
+   * a real terminal. Inline TUIs can emit ED3 on every resize redraw to
    * discard the previous frame; honoring it stops stale frames accumulating.
    */
   scrollbackCleared?: boolean;