@cplieger/web-terminal-ui 7.3.2 → 8.0.0

package/src/predict.ts

@@ -1,181 +1,155 @@
-// Predictive local echo (INPUT-01) — Mosh-style mini-VT that advances
-// a "predicted cursor" optimistically as the user types, before the
-// server's next screen frame confirms or contradicts the prediction.
-//
-// On the wire we still send everything through the connection module;
-// this is purely a local-render optimisation. The visible effect is
-// that the cursor moves immediately on each keystroke even on a 200 ms
-// link, so typing feels responsive instead of laggy.
-//
-// Scope (deliberately conservative — wrong predictions are worse than
-// missing predictions, since they look like the terminal is broken):
-//   - printable ASCII / UTF-8 codepoints: advance one cell per
-//     codepoint (approximate for fullwidth / combining marks; snaps
-//     to truth on next server frame).
-//   - Backspace (0x08) and DEL (0x7f): cursor back one cell.
-//   - CR (0x0d): col = 0.
-//   - LF (0x0a): row += 1 (clamped to height-1).
-//   - Anything else (ESC sequences, TAB, other C0): suspend prediction
-//     until the next server frame. Suspending hides the predicted
-//     cursor so the user sees only the server's truth.
-//
-// Each server screen frame resets the predicted cursor to the server's
-// reported position and re-arms prediction. So a wrong prediction is
-// at most one flushInterval (50 ms) old before correction.
+// Predictive local echo: a Mosh-style mini-VT that advances a predicted cursor
+// as the user types, before the server's next screen frame confirms it. Purely a
+// local-render optimisation, deliberately conservative because a wrong
+// prediction looks like a broken terminal: printable codepoints advance one
+// cell, BS/DEL back one, CR to col 0, LF down one row; anything else (ESC, TAB,
+// other C0) suspends prediction until the next server frame, which resets the
+// predicted cursor to the server's position and re-arms it.
 
-let predRow = 0;
-let predCol = 0;
-let predActive = false;
-let predPendingWrap = false; // matches server VT pendingWrap semantics
-let predFrozen = false; // true when server cursor is hidden (selection prompts)
-let cols = 80;
-let rows = 30;
-
-let onChange: (() => void) | null = null;
-
-/** Subscribe to predicted-cursor changes (the renderer registers
- *  this so it can move its predicted-cursor overlay). */
-export function subscribe(cb: () => void): void {
-  onChange = cb;
+/** One pane's predicted cursor. */
+export interface Predictor {
+  /** Subscribe to predicted-cursor changes; one subscriber (the overlay). */
+  subscribe(cb: () => void): void;
+  /** The screen size the wrap arithmetic uses; the predicted position is
+   *  clamped into it. */
+  setDimensions(cols: number, rows: number): void;
+  /** Drop every prediction and hide the overlay (a server restart, a switch). */
+  reset(): void;
+  /** Reset to the server's reported cursor and re-arm, unless the server cursor
+   *  is hidden (a selection prompt), which freezes prediction. */
+  onScreenFrame(serverRow: number, serverCol: number, cursorHidden?: boolean): void;
+  /** Apply locally-typed bytes; suspends on the first byte it cannot model. */
+  applyInput(bytes: Uint8Array): void;
+  /** `active` is false while prediction is suspended. */
+  get(): { row: number; col: number; active: boolean };
+  /** Clear the subscriber and the state. */
+  dispose(): void;
 }
 
-/** Update the screen dimensions used for wrap calculations. Should be
- *  called whenever the renderer learns a new size from the server. */
-export function setDimensions(c: number, r: number): void {
-  if (c > 0) {
-    cols = c;
-  }
-  if (r > 0) {
-    rows = r;
-  }
-  const prevCol = predCol;
-  const prevRow = predRow;
-  // Clamp predicted position to new bounds so a resize mid-typing
-  // doesn't leave predCol/predRow past the edge.
-  if (predCol >= cols) {
-    predCol = cols - 1;
-  }
-  if (predRow >= rows) {
-    predRow = rows - 1;
-  }
-  // Notify subscribers when the clamp moved the predicted cursor, so the
-  // renderer's overlay doesn't show a stale (possibly off-screen) position
-  // until the next server frame arrives.
-  if (predCol !== prevCol || predRow !== prevRow) {
+export function createPredictor(): Predictor {
+  let predRow = 0;
+  let predCol = 0;
+  let predActive = false;
+  let predPendingWrap = false;
+  let predFrozen = false;
+  let cols = 80;
+  let rows = 30;
+  let onChange: (() => void) | null = null;
+
+  function reset(): void {
+    predRow = 0;
+    predCol = 0;
+    predActive = false;
+    predPendingWrap = false;
+    predFrozen = false;
     onChange?.();
   }
-}
-
-/** Reset all prediction state. Called on server restart to avoid
- *  stale cursor overlay from the previous session. */
-export function reset(): void {
-  predRow = 0;
-  predCol = 0;
-  predActive = false;
-  predPendingWrap = false;
-  predFrozen = false;
-  onChange?.();
-}
 
-/** Reset prediction to the server's reported cursor and re-arm.
- *  When the server cursor is hidden (e.g. during a selection prompt),
- *  prediction is frozen — the ghost cursor disappears and typed input
- *  doesn't move it. */
-export function onScreenFrame(serverRow: number, serverCol: number, cursorHidden?: boolean): void {
-  predRow = serverRow;
-  predCol = serverCol;
-  predPendingWrap = false;
-  predFrozen = cursorHidden ?? false;
-  predActive = !predFrozen;
-  onChange?.();
-}
-
-/** Apply locally-typed input bytes to the predicted cursor. Bails out
- *  (suspending prediction) on the first byte we can't model. Also
- *  bails when frozen (cursor hidden — user is in a selection prompt). */
-export function applyInput(bytes: Uint8Array): void {
-  if (!predActive || predFrozen) {
-    return;
-  }
-  let i = 0;
-  while (i < bytes.length) {
-    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- index checked by loop condition
-    const b = bytes[i]!;
-    if (b === 0x1b) {
-      // ESC — start of an escape sequence. Don't try to model it.
-      predActive = false;
-      onChange?.();
-      return;
-    }
-    if (b === 0x08 || b === 0x7f) {
-      // BS / DEL — backspace one cell.
-      predPendingWrap = false;
-      if (predCol > 0) {
-        predCol--;
-      } else if (predRow > 0) {
-        // wrap to end of previous row (terminals typically don't,
-        // but kiro-cli's prompt frequently does on Backspace at col
-        // 0, so this is closer to expected behavior than staying put)
-        predRow--;
+  return {
+    subscribe(cb) {
+      onChange = cb;
+    },
+    setDimensions(c, r) {
+      if (c > 0) {
+        cols = c;
+      }
+      if (r > 0) {
+        rows = r;
+      }
+      const prevCol = predCol;
+      const prevRow = predRow;
+      if (predCol >= cols) {
         predCol = cols - 1;
       }
-      i++;
-      continue;
-    }
-    if (b === 0x0d) {
-      // CR
-      predPendingWrap = false;
-      predCol = 0;
-      i++;
-      continue;
-    }
-    if (b === 0x0a) {
-      // LF
+      if (predRow >= rows) {
+        predRow = rows - 1;
+      }
+      if (predCol !== prevCol || predRow !== prevRow) {
+        onChange?.();
+      }
+    },
+    reset,
+    onScreenFrame(serverRow, serverCol, cursorHidden) {
+      predRow = serverRow;
+      predCol = serverCol;
       predPendingWrap = false;
-      predRow = Math.min(predRow + 1, rows - 1);
-      i++;
-      continue;
-    }
-    if (b < 0x20) {
-      // Other C0 — probably interpreted by the application; bail.
-      predActive = false;
+      predFrozen = cursorHidden ?? false;
+      predActive = !predFrozen;
       onChange?.();
-      return;
-    }
-    // Printable ASCII or UTF-8 lead byte. Detect the codepoint length
-    // and advance one cell. Mirror the server's pendingWrap semantics
-    // so the predicted cursor matches the server VT exactly: when
-    // pendingWrap is set we wrap to (row+1, 0) BEFORE writing, then
-    // record pendingWrap if the new col is the last one.
-    let len = 1;
-    if (b >= 0xc0 && b < 0xe0) {
-      len = 2;
-    } else if (b >= 0xe0 && b < 0xf0) {
-      len = 3;
-    } else if (b >= 0xf0) {
-      len = 4;
-    }
-    i += len;
-    if (predPendingWrap) {
-      predCol = 0;
-      predRow = Math.min(predRow + 1, rows - 1);
-      predPendingWrap = false;
-    }
-    if (predCol >= cols - 1) {
-      // Last column: don't advance, set pendingWrap for the next char.
-      predCol = cols - 1;
-      predPendingWrap = true;
-    } else {
-      predCol++;
-    }
-  }
-  onChange?.();
-}
-
-/** Current predicted cursor state. `active` is false when prediction
- *  is suspended (e.g. after an unmodelled byte). When the predicted
- *  position equals the server's position, the renderer should hide
- *  the overlay so the user sees only one cursor. */
-export function get(): { row: number; col: number; active: boolean } {
-  return { row: predRow, col: predCol, active: predActive };
+    },
+    applyInput(bytes) {
+      if (!predActive || predFrozen) {
+        return;
+      }
+      let i = 0;
+      while (i < bytes.length) {
+        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- index checked by loop condition
+        const b = bytes[i]!;
+        if (b === 0x1b) {
+          predActive = false;
+          onChange?.();
+          return;
+        }
+        if (b === 0x08 || b === 0x7f) {
+          predPendingWrap = false;
+          if (predCol > 0) {
+            predCol--;
+          } else if (predRow > 0) {
+            // kiro-cli's prompt wraps a Backspace at col 0 to the previous row.
+            predRow--;
+            predCol = cols - 1;
+          }
+          i++;
+          continue;
+        }
+        if (b === 0x0d) {
+          predPendingWrap = false;
+          predCol = 0;
+          i++;
+          continue;
+        }
+        if (b === 0x0a) {
+          predPendingWrap = false;
+          predRow = Math.min(predRow + 1, rows - 1);
+          i++;
+          continue;
+        }
+        if (b < 0x20) {
+          predActive = false;
+          onChange?.();
+          return;
+        }
+        // Mirror the server VT's pendingWrap: at the last column stay put and
+        // wrap before the NEXT character.
+        let len = 1;
+        if (b >= 0xc0 && b < 0xe0) {
+          len = 2;
+        } else if (b >= 0xe0 && b < 0xf0) {
+          len = 3;
+        } else if (b >= 0xf0) {
+          len = 4;
+        }
+        i += len;
+        if (predPendingWrap) {
+          predCol = 0;
+          predRow = Math.min(predRow + 1, rows - 1);
+          predPendingWrap = false;
+        }
+        if (predCol >= cols - 1) {
+          predCol = cols - 1;
+          predPendingWrap = true;
+        } else {
+          predCol++;
+        }
+      }
+      onChange?.();
+    },
+    get() {
+      return { row: predRow, col: predCol, active: predActive };
+    },
+    dispose() {
+      onChange = null;
+      reset();
+    },
+  };
 }