@cplieger/web-terminal-engine 3.5.0 → 3.7.0

package/src/types.ts

@@ -108,6 +108,18 @@ export interface ResumeAckMessage {
    * shows a "history trimmed" marker rather than misaligning.
    */
   oldestIndex?: number;
+  /**
+   * The server DECLARES that it serves demand-paged scrollback (`history`
+   * controls) and that its ring is deep enough to back the client shrinking its
+   * resident tail. Absent on any server too old to carry the ack's third
+   * length-gated tail, which reads the same as false: no paging.
+   *
+   * Capability is declared here rather than probed with a request because this
+   * ack is the first frame of every resume batch — the client knows one RTT
+   * after attach, with nothing sent and no way to mistake a slow link for an
+   * old server.
+   */
+  historyPaging?: boolean;
   /**
    * The server's wire-protocol revision (third length-gated tail, absent on
    * older servers). A value OUTSIDE the client's supported range means one
@@ -229,7 +241,23 @@ export type ControlMessage =
       sentBytes: number;
       haveThrough: number;
       protocolVersion: number;
+      /**
+       * Bound the replay to the newest N missing lines. Optional: omitted means
+       * "no bound", which is every pre-paging client's behavior and what an
+       * old server does regardless. Honored only by a server that declares
+       * paging, and clamped by BOTH sides to the same constant so the value
+       * sent equals the value honored (docs/paged-scrollback.md §4.5).
+       */
+      replayMax?: number;
     }
+  /**
+   * Request a page of retained scrollback: at most `maxLines` lines starting at
+   * absolute index `fromAbs`. The reply is an ordinary scroll frame, made
+   * correlatable by falling inside the requested window rather than by a request
+   * id — within a boot epoch an absolute index is immutable, so a frame that
+   * satisfies the window carries the same bytes the awaited reply would have.
+   */
+  | { type: "history"; fromAbs: number; maxLines: number }
   | { type: "ping" }
   /**
    * v4 typed-framing transition (see WIRE_PROTOCOL_VERSION in

package/src/wire-binary.ts

@@ -143,12 +143,16 @@ function decodeWireBinaryInner(buf: ArrayBuffer): ServerMessage | null {
     // Optional tails, length-gated for back-compat with older servers:
     //   >= 17 bytes: + serverEpoch (restart detection)
     //   >= 33 bytes: + committed + oldestIndex (resume gap detection)
-    //   >= 35 bytes: + serverWireVersion + ackFlags (bit0 = ledgerLost)
+    //   >= 35 bytes: + serverWireVersion + ackFlags (bit0 = ledgerLost,
+    //                  bit1 = historyPaging). Unknown bits are IGNORED, which
+    //                  is what lets the server add capabilities here without a
+    //                  protocol bump.
     let serverEpoch: number | undefined;
     let committed: number | undefined;
     let oldestIndex: number | undefined;
     let serverWireVersion: number | undefined;
     let ledgerLost: boolean | undefined;
+    let historyPaging: boolean | undefined;
     if (buf.byteLength >= 17) {
       serverEpoch = c.u64();
     }
@@ -160,6 +164,7 @@ function decodeWireBinaryInner(buf: ArrayBuffer): ServerMessage | null {
       serverWireVersion = c.u8();
       const ackFlags = c.u8();
       ledgerLost = (ackFlags & 1) !== 0;
+      historyPaging = (ackFlags & 2) !== 0;
     }
     const msg: ResumeAckMessage = { type: "resumeAck", received: inputAck };
     if (serverEpoch !== undefined) {
@@ -177,6 +182,9 @@ function decodeWireBinaryInner(buf: ArrayBuffer): ServerMessage | null {
     if (ledgerLost !== undefined) {
       msg.ledgerLost = ledgerLost;
     }
+    if (historyPaging !== undefined) {
+      msg.historyPaging = historyPaging;
+    }
     return msg;
   }
   if (msgType === MSG_ACK_ONLY) {