@cplieger/web-terminal-engine 4.0.3 → 5.0.1

package/jsr.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/web-terminal-engine",
-  "version": "4.0.3",
+  "version": "5.0.1",
   "type": "module",
   "scripts": {
     "typecheck": "tsc -p tsconfig.json",
@@ -17,7 +17,7 @@
     "@stryker-mutator/vitest-runner": "10.0.0",
     "@types/pngjs": "6.0.5",
     "@typescript/native": "npm:typescript@7.0.2",
-    "@vitest/coverage-v8": "4.1.10",
+    "@vitest/coverage-v8": "4.1.11",
     "esbuild": "0.28.2",
     "eslint": "10.8.1",
     "fast-check": "4.9.0",
@@ -26,7 +26,7 @@
     "prettier": "3.9.6",
     "typescript": "npm:@typescript/typescript6@6.0.2",
     "typescript-eslint": "8.67.0",
-    "vitest": "4.1.10"
+    "vitest": "4.1.11"
   },
   "overrides": {
     "qs": "^6.15.2"

package/src/connection.ts

@@ -443,9 +443,16 @@ export interface Callbacks {
    *  it. */
   onWireIncompatible?(details: WireIncompatibility): void;
   computeSize(): { cols: number; rows: number };
-  /** Returns the highest absolute line index the client currently holds, or
-   *  -1 if it holds nothing. Sent as `haveThrough` on resume so the server
-   *  replays only the lines missed (e.g. printed while the device slept).
+  /** Returns the highest absolute line index the client will not ask the server
+   *  to re-send, or -1 to request a full retained replay. Sent as `haveThrough`
+   *  on resume so the server replays only the lines missed (e.g. printed while
+   *  the device slept).
+   *
+   *  NOT simply the highest index held. A client that holds a row PROVISIONALLY
+   *  — a screen row the application drew, which the server has not committed at
+   *  that absolute index — must not claim it, or the replay starts above it and
+   *  the provisional copy is never corrected. Wire this to
+   *  `render.getReplayBoundary`, which answers exactly that question.
    *  When absent, the client requests a full retained replay (-1). */
   getHaveThrough?(): number;
   /** Fired on resume with the server's retained-history bounds: `committed`

package/src/render.ts

@@ -7,7 +7,7 @@
 // "scrollback": the live window is simply the last `height` absolute indices,
 // and a line that scrolls into history just stops being updated. This is what
 // removes the live/history reconciliation that caused the duplicate-rows and
-// view-jumping bugs (see the #web-terminal-engine steering doc, "Design rationale").
+// view-jumping bugs.
 //
 // Decode frames feed the store (handleScreen/handleScroll); a single
 // requestAnimationFrame flush drains the store's change set and applies it:
@@ -587,14 +587,29 @@ function collapseContentSpaceOverlays(): void {
 }
 
 /**
- * Highest absolute line index the client holds, or -1 if empty. This is the
- * resume `haveThrough` value (it replaces the old DOM-row count). Exposed so
- * the connection layer can request only the lines the client is missing.
+ * Highest absolute line index the client holds, or -1 if empty. Exposed so a
+ * consumer can ask how far this store's content reaches; it is NOT the resume
+ * `haveThrough` (that is getReplayBoundary below, and the difference is a bug
+ * when the two are confused).
  */
 export function getHighestIndex(): number {
   return store.highestIndex();
 }
 
+/**
+ * The resume `haveThrough`: the highest index this client will not ask the
+ * server to re-send. Wire this to Callbacks.getHaveThrough, never
+ * getHighestIndex.
+ *
+ * The two differ by whatever the store holds provisionally — screen rows the
+ * application drew and the server has not committed at those indices — and
+ * claiming those on the wire is what leaves a stale copy of the last screen
+ * parked in scrollback after a reattach. See LineStore.replayBoundary.
+ */
+export function getReplayBoundary(): number {
+  return store.replayBoundary();
+}
+
 /**
  * Record the server's retained-history bounds from a resumeAck (committed =
  * one past the newest retained, oldest = oldest retained absolute index). The

package/src/scroll.ts

@@ -7,7 +7,7 @@
 // suppress timer, and no programmatic-vs-user flag. That heuristic soup (a
 // 100px tolerance, a 150ms debounce, a 60-second touch window) was the source
 // of the view-jumping and scroll-interruption bugs (the legacy heuristic-soup
-// failure mode; see the #web-terminal-engine steering doc, "Design rationale").
+// failure mode).
 //
 // The renderer calls stickToBottom() once after each flush: if following, pin
 // to the new bottom; if holding, do nothing. Holding the reading position when

package/src/store.ts

@@ -1,8 +1,7 @@
 // Absolute-index line store: the client's authoritative model of the
 // terminal. One buffer keyed by absolute line index, with the live screen
 // window sliding along it. This is the data model that resolves the
-// live/history split (see the #web-terminal-engine steering doc, "Design
-// rationale"): there is no separate
+// live/history split: there is no separate
 // "live zone" and "scrollback" here, only lines addressed by absolute index,
 // the last `height` of which happen to still be changing.
 //
@@ -40,6 +39,15 @@ const MAX_LINES = COMPATIBILITY_TAIL_CAP;
  * anything that does not match, so an older snapshot is discarded rather than
  * misread. There is deliberately no migration path: a discarded snapshot costs
  * one full resume, which is exactly the behavior of not having persisted at all.
+ *
+ * One carve-out, because the rule above exists to prevent MISREADING and this
+ * cannot be misread: adding an OPTIONAL field whose absence is defined to mean
+ * exactly the pre-existing behaviour needs no bump. `fromSnapshot` reads fields
+ * individually off an `unknown` record and validates each, so an older entry
+ * simply lacks the key and takes the documented absent path. The test is whether
+ * a v-matching entry written by the previous release still hydrates to the same
+ * store it would have before; if it does not, bump. `unconfirmedFrom` is the
+ * first field added under this carve-out.
  */
 const SNAPSHOT_VERSION = 1;
 
@@ -92,6 +100,24 @@ export interface StoreSnapshot {
   oldest: number;
   /** Highest absolute index in `lines`. Write-side metadata; see `oldest`. */
   highest: number;
+  /**
+   * The saving store's provisional floor: the lowest index at or above which its
+   * content had not been confirmed as committed history by the server. ABSENT
+   * when everything it held was confirmed, and absent in every snapshot written
+   * before this field existed, which is the same state and takes the same path.
+   *
+   * Carried because the alternative is a reloaded page telling the server "no
+   * need to re-send" about screen rows it only ever saw the application draw.
+   * The window descriptor cannot serve here (see above: a stale one is
+   * load-bearing in two places), and this is not geometry — it is one index,
+   * meaningless to interpret as anything else.
+   *
+   * `fromSnapshot` treats a malformed value as absent rather than rejecting the
+   * snapshot. Being wrong in that direction costs a replayed screenful; rejecting
+   * would throw away a whole session's history over a field that is an
+   * optimisation of correctness, not a correctness precondition.
+   */
+  unconfirmedFrom?: number;
   /**
    * The retained lines as [absoluteIndex, runs] pairs, ascending. Pairs rather
    * than an object keyed by index, because object keys stringify and absolute
@@ -160,8 +186,7 @@ function isWireRunArray(value: unknown): value is WireRun[] {
  * streaming session into one whole-layer invalidation PER LINE — on WebKit
  * (which re-rasterizes the resident tiles each time) that is the single largest
  * compositor cost this client can trigger, and on a memory-pressured iPhone it
- * is churn the page cannot afford (see the web-terminal-ui steering doc, "iOS
- * memory ceiling"). Batching keeps appends eviction-free between passes, so the
+ * is churn the page cannot afford. Batching keeps appends eviction-free between passes, so the
  * layer shifts once per batch instead of once per line. The retained count is
  * hard-bounded at `max(maxLines, live-window height)` after every apply — the
  * window is never evicted (a cap at or below the screen height keeps the full
@@ -470,11 +495,68 @@ export class LineStore {
     return Math.max(this.effectiveTailCap, this.win.height);
   }
 
-  /** Highest absolute index held, or -1 if empty. Used as resume `haveThrough`. */
+  /** Highest absolute index held, or -1 if empty. */
   highestIndex(): number {
     return this.highest;
   }
 
+  /**
+   * The lowest absolute index at or above which this store's content has NOT
+   * been confirmed as committed history by the server, or +Infinity when
+   * everything held is confirmed.
+   *
+   * The distinction this tracks is real and the map cannot express it. A row
+   * arriving in a SCREEN frame lands at `base + y`, which is a screen POSITION
+   * the application repaints in place, so the content held at that absolute
+   * index is what the app most recently drew there — provisional until the row
+   * scrolls off and the server commits it. A row arriving in a SCROLL or history
+   * frame is the opposite: the server has committed it, at that index, for good.
+   *
+   * One number rather than a per-row flag or a second key set. The rows above
+   * this floor are always a contiguous suffix of the store, because a screen
+   * frame's window is contiguous and lowers the floor to its base, while a
+   * durable frame that reaches the floor from below raises it past the range it
+   * delivered. `paged-scrollback.md` §5.3 records why a parallel structure over
+   * the same map is the shape to avoid: the one that was tried, a maintained
+   * companion count, was wrong at four mutation sites and reached -96.
+   *
+   * Movement is deliberately asymmetric. Lowering is unconditional, because a
+   * screen frame is proof its window is provisional. Raising happens only when a
+   * durable frame reaches the floor from at or below it, so a chunk landing
+   * above a still-unconfirmed gap leaves the floor where it is. That direction
+   * is the safe one to be wrong in: too low costs a few replayed rows, too high
+   * is the defect this exists to prevent.
+   */
+  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.
+   */
+  replayBoundary(): number {
+    if (this.highest < 0) {
+      return this.highest;
+    }
+    // unconfirmedFrom is +Infinity when nothing is provisional, so the min is
+    // `highest` and this is a no-op for a store fed only by durable frames.
+    return Math.min(this.highest, this.unconfirmedFrom - 1);
+  }
+
   /** Lowest absolute index held, or -1 if empty. */
   oldestIndex(): number {
     return this.oldest;
@@ -601,6 +683,12 @@ export class LineStore {
     }
     this.exitAltIfNeeded();
     this.updateWindow(msg);
+    // Every index in this window is provisional: the app repaints these screen
+    // positions in place, so what the store holds there is the last thing drawn,
+    // not what the server will commit at that absolute index. Unconditional and
+    // independent of `changed`, because an unchanged row still holds provisional
+    // content from an earlier frame.
+    this.markUnconfirmedFrom(msg.base);
     for (const y of msg.changed) {
       const row = msg.rows[y];
       if (row !== undefined) {
@@ -643,6 +731,11 @@ export class LineStore {
           this.applyLine(abs, row);
         }
       }
+      // Confirm only the prefix the alt gate actually ACCEPTED. The rows at or
+      // above the frozen base were dropped, so they are not committed history as
+      // far as this store is concerned and must not raise the floor over
+      // themselves.
+      this.confirmRange(msg.firstIndex, Math.min(msg.lines.length, base - msg.firstIndex));
       return;
     }
     for (let i = 0; i < msg.lines.length; i++) {
@@ -651,6 +744,75 @@ export class LineStore {
         this.applyLine(msg.firstIndex + i, row);
       }
     }
+    this.confirmRange(msg.firstIndex, msg.lines.length);
+  }
+
+  /**
+   * Lower the provisional floor to `base`: everything from there up is content
+   * the application drew, not content the server committed. See
+   * `unconfirmedFrom` for why the floor moves in only one direction here.
+   */
+  private markUnconfirmedFrom(base: number): void {
+    if (!Number.isInteger(base) || base < 0) {
+      return; // a malformed frame must not move the floor
+    }
+    if (base < this.unconfirmedFrom) {
+      this.unconfirmedFrom = base;
+    }
+  }
+
+  /**
+   * Raise the provisional floor past a range the server just committed, and heal
+   * it when the range proves the old floor is unreachable.
+   *
+   * The reach test is the correctness argument for the ordinary case. A chunk
+   * landing above the floor leaves rows between the floor and the chunk still
+   * provisional, so raising past it would claim exactly the rows this mechanism
+   * exists to exclude. Under the normal dispatch order the test passes: a screen
+   * frame lowers the floor to its new base and the scroll chunks carrying the rows
+   * that just scrolled off start at or below that floor. When those chunks do NOT
+   * arrive — the server writes each payload as its own message and ignores write
+   * errors, so a socket that dies mid-dispatch is ordinary — the floor stays put
+   * and the next resume asks for the range again.
+   *
+   * The HEAL is the second clause, and without it the floor wedges permanently.
+   * Three ordinary events deliver content far above the floor and leave nothing
+   * that can ever reach it: an ED3 (which drops every line below the new base,
+   * taking the floor's own neighbourhood with it), a clamped replay, and the ring
+   * eviction every server eventually performs. Measured before the heal existed: a
+   * store whose floor sat at 99 still reported 99 after fifteen healthy frames had
+   * carried `highest` to 297, and after a clamped replay took it to 5223. Every
+   * attach then asked for a maximal replay forever, and `snapshot()` persisted the
+   * wedge across reloads — strictly worse than the defect the floor exists to fix.
+   *
+   * So a range arriving entirely above `oldest` while the floor sits BELOW
+   * `oldest` heals it: nothing at or above the floor is held any more, so there is
+   * nothing left to protect, and holding the claim down protects only rows that no
+   * longer exist. This is safe in the one direction that matters — it never raises
+   * the floor over a row the store still holds provisionally, because such a row
+   * would be at or above `oldest` by definition.
+   *
+   * `applyHistoryScroll` deliberately does not call this. A demand-paged reply
+   * fetches history strictly below the resident tail; it can neither reach the
+   * floor nor witness the floor being orphaned.
+   */
+  private confirmRange(firstIndex: number, count: number): void {
+    if (!Number.isInteger(firstIndex) || firstIndex < 0 || count <= 0) {
+      return;
+    }
+    const end = firstIndex + count;
+    if (firstIndex > this.unconfirmedFrom) {
+      // The heal: the floor names an index the store no longer holds, so it is
+      // protecting nothing. Recorded through the same path as an ordinary raise so
+      // there is one writer, not two.
+      if (this.oldest >= 0 && this.unconfirmedFrom < this.oldest) {
+        this.unconfirmedFrom = Math.max(end, this.oldest);
+      }
+      return; // otherwise a gap below stays provisional
+    }
+    if (end > this.unconfirmedFrom) {
+      this.unconfirmedFrom = end;
+    }
   }
 
   /**
@@ -1122,6 +1284,23 @@ export class LineStore {
    * descriptor, because the batch's own window frame re-establishes it at the
    * new base — those rows stop being window rows the moment it lands.
    *
+   * The band top is `sentHaveThrough` and deliberately does NOT follow the wire
+   * value down now that `replayBoundary()` supplies it. The two questions are
+   * different: the wire value asks "what will I not ask for", the band asks "what
+   * did I claim to hold before the server answered". Rows above the sent value
+   * arrived from the server as committed content, so they are real history and
+   * must not be reclassified as disposable cache; rows this store holds only
+   * provisionally sit at or above the boundary and are covered by the replay,
+   * which now starts at `boundary + 1` precisely because of it.
+   *
+   * One residual, deliberately not addressed here. When the replay start is
+   * CLAMPED above the boundary (`committed - replayMax`, reachable when a
+   * background tab printed more than roughly `tailCap` lines), the provisional
+   * rows are neither replayed nor banded, so they stay tail-classified and lose
+   * the browse budget's TTL sweep. Widening the band to cover them would change a
+   * pinned invariant that two existing cases assert, so it is recorded in
+   * docs/resume-watermark.md rather than changed in passing.
+   *
    * The retirement leaves the same transition's later steps reading a window of
    * height 0, so state precisely what that costs rather than forbidding it: the
    * only window-derived bound they touch is `enforceCap`'s, which loses the live
@@ -1144,7 +1323,19 @@ export class LineStore {
       predicted = Math.max(predicted, committed - sentReplayMax);
     }
     if (predicted <= base || this.oldest < 0 || sentHaveThrough < this.oldest) {
-      // No jump, or an empty/fresh store where the predicate fires vacuously.
+      // No jump, or nothing this socket claimed is still held, so the stranded
+      // band is empty and there is nothing to reclassify.
+      //
+      // The third clause used to mean only "an empty or fresh store", because the
+      // wire value was the highest held index and so never sat below `oldest`.
+      // The replay boundary can: a post-ED3 store has `oldest === win.base` and
+      // claims `win.base - 1`. That is still the right answer here, for the
+      // reason above rather than the original one — the band is `keys <=
+      // sentHaveThrough`, which is empty exactly when this fires, so both the
+      // reclassify and the budget pass it gates would be no-ops. The descriptor
+      // is then not retired either, which is equally harmless: retirement exists
+      // so a band containing old window rows survives the batch's own window
+      // frame, and there is no band.
       return false;
     }
     // The stranded band is every retained key at or below what this socket told
@@ -1253,6 +1444,7 @@ export class LineStore {
     this.highest = -1;
     this.everEvictedThrough = -1;
     this.erasedThrough = -1;
+    this.unconfirmedFrom = Number.POSITIVE_INFINITY;
     this.paging = false;
     this.serverOldest = -1;
     this.win = emptyWindow();
@@ -1353,6 +1545,11 @@ export class LineStore {
       oldest: first,
       highest: last,
       lines,
+      // OMITTED when nothing held is provisional, which is also what an older
+      // snapshot looks like, so absent and "all confirmed" are deliberately the
+      // same state on the way back in. JSON has no Infinity, so a sentinel value
+      // would have to be invented and then defended; absence needs neither.
+      ...(Number.isFinite(this.unconfirmedFrom) ? { unconfirmedFrom: this.unconfirmedFrom } : {}),
     };
   }
 
@@ -1449,6 +1646,15 @@ export class LineStore {
     store.highest = highest;
     // Everything below the tail is gone as far as this store is concerned.
     store.everEvictedThrough = oldest - 1;
+    // Restore the saving store's provisional floor. A malformed or absent value
+    // leaves it at +Infinity, which is the pre-existing behaviour: the whole
+    // hydrated tail reads as confirmed and the first resume claims all of it.
+    // Read off the unknown record like every other field, and clamped into the
+    // kept range because the tail may have been trimmed above the saved floor.
+    const savedFloor: unknown = rec["unconfirmedFrom"];
+    if (typeof savedFloor === "number" && Number.isInteger(savedFloor) && savedFloor >= 0) {
+      store.unconfirmedFrom = savedFloor;
+    }
     // The renderer must build every hydrated row: nothing is on screen yet.
     for (const abs of store.lines.keys()) {
       store.dirty.add(abs);
@@ -1482,7 +1688,6 @@ export class LineStore {
 
   /**
    * applyLine is the guarded core. It enforces the apply-line guard set
-   * (see the #web-terminal-engine steering doc, "Design rationale"):
    * valid index, not stale, idempotent, and
    * cap-bounded. Returns nothing; effects are recorded in the dirty/evicted
    * sets for the next drain.
@@ -1579,6 +1784,15 @@ export class LineStore {
   private applyScrollbackCleared(base: number): void {
     this.solicitedPending = null;
     this.raisePagingFloor(base);
+    // The provisional floor moves up with the erase. Everything below `base` is
+    // about to be dropped, so a floor down there would name rows the store no
+    // longer holds and hold the resume claim below them forever: measured as a
+    // floor stuck at 99 while `highest` climbed to 297 over fifteen healthy
+    // frames, which turned every attach into a maximal replay. Never LOWERS the
+    // floor, so a floor already above the erase bound keeps protecting its rows.
+    if (base > this.unconfirmedFrom) {
+      this.unconfirmedFrom = base;
+    }
     if (this.oldest < 0 || this.oldest >= base) {
       return;
     }

package/src/types.ts

@@ -37,8 +37,7 @@ export interface ScreenMessage {
    * Absolute line index of the top screen row (row 0). A changed row at
    * window index `y` has absolute index `base + y`. The client stores
    * every line by absolute index, so applying a row is idempotent and
-   * never duplicates (see the #web-terminal-engine steering doc,
-   * "Design rationale").
+   * never duplicates.
    */
   base: number;
   /** Cursor position as [row, col], zero-indexed within the window. */