@cplieger/web-terminal-engine 6.2.0 → 6.4.0-dev.11

package/jsr.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/web-terminal-engine",
-  "version": "6.2.0",
+  "version": "6.4.0-dev.11",
   "type": "module",
   "scripts": {
     "typecheck": "tsc -p tsconfig.json",
@@ -16,24 +16,24 @@
   "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",
     "@types/pngjs": "6.0.5",
     "@typescript/native": "npm:typescript@7.0.2",
-    "@vitest/browser-playwright": "5.0.3",
-    "@vitest/coverage-v8": "5.0.3",
+    "@vitest/browser-playwright": "5.0.5",
+    "@vitest/coverage-v8": "5.0.5",
     "esbuild": "0.28.2",
-    "eslint": "10.12.0",
+    "eslint": "10.13.0",
     "fast-check": "4.10.2",
-    "knip": "6.40.0",
-    "playwright": "1.64.0",
+    "knip": "6.41.0",
+    "playwright": "1.64.1",
     "pngjs": "7.0.0",
-    "prettier": "3.9.9",
+    "prettier": "3.9.10",
     "typescript": "npm:@typescript/typescript6@6.0.2",
-    "typescript-eslint": "8.71.1",
-    "vitest": "5.0.3"
+    "typescript-eslint": "8.71.2",
+    "vitest": "5.0.5"
   },
   "overrides": {
     "qs": "^6.15.2"

package/src/index.ts

@@ -40,6 +40,7 @@ export { wsURL } from "./wsurl.js";
 export { WS_PATH, SESSIONS_PATH, SESSION_EVENTS_PATH } from "./routes.js";
 export { connectStatusStream } from "./status-stream.js";
 export type {
+  KnownStatus,
   SessionInfo,
   SessionStatus,
   StatusStream,

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.
 
@@ -339,10 +339,10 @@ function anyModifier(ev: KeyboardEvent): boolean {
 }
 
 /**
- * The kitty "unicode-key-code": the UNSHIFTED (lower-case / base-layout)
- * codepoint of the key. Letters and digits are read from ev.code (the physical
- * key), so a composed Alt/Option character on macOS still maps to its base key;
- * other single-character keys fall back to the case-folded ev.key.
+ * The kitty "unicode-key-code", read as the UNSHIFTED US-layout codepoint of
+ * the physical key: letters, digits and KITTY_CODE_BASE's punctuation come from
+ * ev.code, so a composed Option character or a shifted symbol maps to its base
+ * key; any other single-character key falls back to the case-folded ev.key.
  */
 function kittyKeyCodepoint(ev: KeyboardEvent): number {
   const code = ev.code;
@@ -431,6 +431,12 @@ function encodeKittyDisambiguate(ev: KeyboardEvent): KeyboardResult {
     if (ev.metaKey && !ev.ctrlKey && !ev.altKey) {
       return { kind: "ignore" };
     }
+    // A desktop AltGr character arrives with ctrlKey and altKey clear, so it stays
+    // text: on Windows, Chromium and Firefox swap Ctrl+Alt for AltGraph whenever
+    // the chord types a character (https://chromestatus.com/feature/5059438092222464,
+    // https://searchfox.org/mozilla-central/source/widget/windows/KeyboardLayout.cpp).
+    // AltGraph must not exempt a key here: Firefox sets it on every macOS Option
+    // chord (widget/cocoa/nsCocoaUtils.mm), and Ctrl+Option+a is 97;7u.
     if (ev.ctrlKey || ev.altKey || ev.metaKey) {
       const cp = kittyKeyCodepoint(ev);
       if (cp > 0) {
@@ -480,15 +486,6 @@ export function mapKeyboardEvent(ev: KeyboardEvent, modes: KeyboardModes): Keybo
     }
   }
 
-  // Browser-reserved meta combos (Cmd+R, Cmd+T, Cmd+Q, Cmd+W on Mac;
-  // Ctrl+R, Ctrl+T, Ctrl+W with no Shift on others). Let the browser
-  // 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.)
-
   // Shift+PageUp / Shift+PageDown — local scrollback navigation
   // (matches xterm.js KeyboardResultType.PAGE_UP/PAGE_DOWN).
   if (ev.key === "PageUp" && ev.shiftKey && !ev.ctrlKey && !ev.altKey && !ev.metaKey) {
@@ -590,7 +587,9 @@ export function mapKeyboardEvent(ev: KeyboardEvent, modes: KeyboardModes): Keybo
     return { kind: "ignore" }; // let `input` event handle plain space
   }
 
-  // Single printable character with modifiers.
+  // Single printable character with modifiers. Neither branch takes Meta, so
+  // the browser keeps Cmd+R/T/W/C/V; Ctrl+R/T/W go to the PTY, where readline
+  // binds them.
   if (ev.key.length === 1) {
     const ch = ev.key;
 

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.
@@ -1352,10 +1352,9 @@ export function createRenderer(opts: RendererOptions): Renderer {
     if (el === null) {
       return null;
     }
+    // Non-negative: rowAtViewportTop answers only with a CONTENT row, and
+    // isContentRow requires a parsed index that resolves back to that element.
     const abs = rowAbs(el);
-    if (abs < 0) {
-      return null;
-    }
     return {
       abs,
       screenTop: el.offsetTop - scroll.currentScrollTop(),
@@ -1468,10 +1467,10 @@ export function createRenderer(opts: RendererOptions): Renderer {
       abs >= gap.hi
         ? Math.max(gap.lo, gap.hi - budget, floor) // approaching from BELOW the gap's top
         : Math.max(gap.lo, floor); // approaching from above: start at the gap's low edge
+    // At least 1, so no caller has to re-check it: every gap the store returns
+    // satisfies `hi > lo` and `hi > pagingFloor`, and `budget` is at least 1,
+    // which puts `fromAbs` strictly below `gap.hi` on both approaches.
     const maxLines = Math.min(budget, gap.hi - fromAbs);
-    if (maxLines < 1) {
-      return;
-    }
     requestHistoryFn(fromAbs, maxLines);
   }
 

package/src/status-stream.ts

@@ -7,6 +7,11 @@
 
 import { nextBackoffDelay } from "./reconnect.js";
 
+/** KnownStatus is a status the server derives itself, one per Go terminal.Status*
+ *  constant. */
+export type KnownStatus =
+  "working" | "idle" | "input" | "done" | "exited" | "crashed" | "failed" | "warning";
+
 /** SessionInfo is one session's wire shape: the JSON object the session REST
  *  API (GET/POST /api/sessions) returns per session, kept in lockstep with the Go
  *  terminal.SessionInfo by hand.
@@ -16,26 +21,19 @@ import { nextBackoffDelay } from "./reconnect.js";
  *  a CLIENT-DERIVED automatic title a client asked the server to remember. */
 export interface SessionInfo {
   readonly id: string;
-  /** the session's current status. "working"/"idle"/"exited"/"crashed" are
-   *  derived by the server; "input"/"done" are latched from a classified OSC 9
-   *  notification; "failed" is OSC 9;4 progress state 2 and "warning" is state 4
-   *  (iTerm2 semantics), both of which PERSIST until the program changes the
-   *  progress state. "exited" and "crashed" split the session's end: "exited" is
-   *  an ordinary one (status 0, or any exit the server itself caused — a closed
-   *  session, the idle reaper, a server shutdown), "crashed" is a non-zero exit
-   *  status or a terminating signal the program was not asked for, so a routine
-   *  restart never renders as a failure. Neither is a progress state: they
-   *  outrank everything, and nothing clears them. A consumer must tolerate an
-   *  UNKNOWN status string from a newer server: the stream is parsed, not
-   *  validated, and an unrecognised value is forwarded rather than dropped
-   *  (forward compatibility across the wire floor). */
-  readonly status:
-    "working" | "idle" | "input" | "done" | "exited" | "crashed" | "failed" | "warning";
+  /** the session's current status. The server derives a KnownStatus from the
+   *  program's OSC 7501 report, or from OSC 9;4 progress while it has sent none
+   *  since a hard reset (RIS); "exited" and "crashed" mark the process's end
+   *  and nothing clears them. A classified OSC 9 notification latches whatever
+   *  string the server's classifier returns, and a newer server may add values,
+   *  so a consumer must handle any other string: the stream forwards it
+   *  unchanged. The engine's docs/sessions.md gives every mapping. */
+  readonly status: KnownStatus | (string & {});
   readonly title: string;
   /** 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;
@@ -72,11 +70,11 @@ export interface SessionInfo {
    *  view: a list built from that hybrid still names the live set exactly, so the
    *  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.
-   *  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. */
+  /** true once the session has emitted a genuine activity signal — an OSC 7501
+   *  report, OSC 9;4 progress or a classified OSC 9 notification.
+   *  Sticky for the session's life, a hard reset (RIS) included. Consumers
+   *  reveal the per-tab activity dot only when this is set; a program that
+   *  emits none of the three (a plain shell) keeps its tab dot hidden. */
   readonly reportsActivity?: boolean;
   /** the session's SECONDARY activity: a host-reported background activity that
    *  OUTLIVES the turn, carried beside `status` and never merged into it. The
@@ -84,15 +82,25 @@ export interface SessionInfo {
    *  (stopped and resumable, nobody is being asked) and `"input"` (a background
    *  task is blocked on the user); absent or an empty string means no secondary
    *  activity, and a consumer must tolerate an UNKNOWN value from a newer server
-   *  by rendering nothing for it.
-   *
-   *  Typed `string`, deliberately NOT a union like `status`: that union's own doc
-   *  already admits it must tolerate values outside itself, which forces a cast at
-   *  every forward-compatible site. Absent from a server that reports none. */
+   *  by rendering nothing for it. Absent from a server that reports none. */
   readonly activity?: string;
   /** how many sources produced `activity`: >= 1 whenever `activity` is non-empty,
    *  0 when it is empty or the host does not count them. */
   readonly activityCount?: number;
+  /** numbers the occurrence of the session's status. A sweep raises it by one
+   *  when it emits a changed status, a status a classified notification latched
+   *  since the last sweep, or an input, done or failed status after an OSC 7501
+   *  report since then created a record, changed one's state or kind, or
+   *  cleared one, and so changed which record the status came from, or its
+   *  state or kind, at that report. A report keeping a record's state and kind
+   *  raises it only by changing the status. It never falls for one id; 0,
+   *  absent on the wire, means nothing numbered yet. */
+  readonly statusSeq?: number;
+  /** the highest `statusSeq` any reader acknowledged through
+   *  `PUT /api/sessions/{id}/seen`. Never falls for one id and never exceeds
+   *  `statusSeq`; a status that calls for attention is unread while
+   *  `statusSeq > seenSeq`. */
+  readonly seenSeq?: number;
 }
 
 /** SessionStatus is one session's current status as carried on the status
@@ -101,9 +109,10 @@ export interface SessionInfo {
 export interface SessionStatus extends SessionInfo {
   /** true when the session is gone (closed or reaped); the consumer drops it. */
   readonly removed?: boolean;
-  /** the OSC 9;4 percentage: -1 when absent or unknown (no sequence seen, or a
-   *  state that carries none — clear/indeterminate), else 0-100. Paired with
-   *  `status` to render a determinate bar. */
+  /** the session's percentage: the OSC 7501 report's `progress` when it
+   *  carries one, else the OSC 9;4 percentage. -1 when absent or unknown (no
+   *  sequence seen, or a state that carries none — clear/indeterminate), else
+   *  0-100. Paired with `status` to render a determinate bar. */
   readonly progressValue?: number;
   /** the OSC 9 notification message, delivered to EVERY subscriber whether or
    *  not the server has a status classifier installed. A notification is an

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;