@cplieger/web-terminal-engine 2.7.0 → 3.0.0

package/src/scroll.ts

@@ -136,3 +136,28 @@ export function scrollToBottom(): void {
 export function isUserScrolledUp(): boolean {
   return !following;
 }
+
+/**
+ * The viewport's current scroll offset, for a consumer keeping per-view
+ * scroll memory (a tabbed shell saving the position of the tab it is
+ * leaving). Pairs with restoreScrollTop. This module owns the container's
+ * scrollTop; consumers read it through this seam rather than the DOM element
+ * so an engine-side change to the scroll geometry cannot silently break them.
+ */
+export function currentScrollTop(): number {
+  return scrollEl ? scrollEl.scrollTop : 0;
+}
+
+/**
+ * Restore a previously saved scroll offset (per-view scroll memory: a tabbed
+ * shell re-entering a tab whose user had scrolled up to read). The offset is
+ * applied verbatim; the follow/hold state then re-derives from the resulting
+ * scroll event exactly as it does for a user scroll, so a restored read
+ * position holds and a restored at-bottom position re-engages following.
+ */
+export function restoreScrollTop(top: number): void {
+  if (!scrollEl) {
+    return;
+  }
+  scrollEl.scrollTop = top;
+}

package/src/status-stream.ts

@@ -7,9 +7,11 @@
 
 import { nextBackoffDelay } from "./reconnect.js";
 
-/** SessionStatus is one session's current status as carried on the stream. It
- *  mirrors the server's status event. */
-export interface SessionStatus {
+/** SessionInfo is one session's wire shape: the JSON object the session REST
+ *  API (GET/POST /api/sessions) returns per session. Mirrors the Go
+ *  terminal.SessionInfo — the two are kept in lockstep by hand (single 6-field
+ *  type; flip to wiregen if this surface grows). */
+export interface SessionInfo {
   readonly id: string;
   readonly status: "working" | "idle" | "input" | "done" | "exited";
   readonly title: string;
@@ -18,8 +20,6 @@ export interface SessionStatus {
    *  this instead of `title`. */
   readonly clientTitle?: string;
   readonly createdAt: string;
-  /** true when the session is gone (closed or reaped); the consumer drops it. */
-  readonly removed?: boolean;
   /** 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
@@ -28,6 +28,14 @@ export interface SessionStatus {
   readonly reportsActivity?: boolean;
 }
 
+/** SessionStatus is one session's current status as carried on the status
+ *  stream (SSE): the REST wire shape plus the stream-only removal marker. It
+ *  mirrors the server's status event. */
+export interface SessionStatus extends SessionInfo {
+  /** true when the session is gone (closed or reaped); the consumer drops it. */
+  readonly removed?: boolean;
+}
+
 /** StatusStreamCallbacks are the consumer's hooks. Declared as function-typed
  *  properties (not method shorthand) so destructuring them is safe. */
 export interface StatusStreamCallbacks {

package/src/store.ts

@@ -136,9 +136,17 @@ export class LineStore {
     return this.alt;
   }
 
-  /** A copy of the ephemeral alt-screen grid rows. */
-  getAltRows(): WireRun[][] {
-    return this.altRows.map((r) => r.slice());
+  /**
+   * The ephemeral alt-screen grid rows, as a read-only view of the store's
+   * internal arrays (no copy: the pre-2026-07 deep copy allocated the whole
+   * grid on every flush while a full-screen TUI was active — measured at real
+   * cost in the render bench). Row identity is meaningful: applyScreen
+   * replaces exactly the changed rows' arrays and leaves unchanged rows
+   * reference-identical, which is what lets the renderer reconcile the alt
+   * grid row-by-row instead of rebuilding it (renderAlt).
+   */
+  getAltRows(): readonly (readonly WireRun[])[] {
+    return this.altRows;
   }
 
   /**

package/src/toolbar.ts

@@ -0,0 +1,270 @@
+// On-screen mobile keyboard toolbar: a DOM widget (button lookup, ARIA
+// painting, a listener registry, sticky-Ctrl state) wiring touch buttons to a
+// terminal send sink. Split out of keyboard.ts (2026-07): that module is the
+// pure key-ENCODING layer (KeyboardEvent -> wire bytes), and a DOM widget
+// buried in it made both harder to navigate. The wire encodings themselves
+// stay in keyboard.ts — this module consumes its exported logical-key homes
+// (plainCursorKeySeq / plainEscapeSeq / kittyCtrlCharSeq / ctrlByteFor), so
+// the toolbar cannot drift from the physical-key path (the equivalence
+// fixtures in toolbar.test.ts pin the two byte-for-byte).
+//
+// This was duplicated across vibekit and web-terminal-kiro — same wire
+// sequences, same sticky-Ctrl semantics, same DECCKM nuance — so it lives in
+// the engine.
+
+import {
+  ctrlByteFor,
+  kittyCtrlCharSeq,
+  kittyDisambiguateActive,
+  plainCursorKeySeq,
+  plainEscapeSeq,
+} from "./keyboard.js";
+import { isApplicationCursor } from "./modes.js";
+
+/**
+ * Default DOM ids for the on-screen mobile keyboard toolbar buttons,
+ * inside the toolbar container element passed to `bindMobileToolbar`.
+ * Override individual ids via `BindMobileToolbarOptions.ids`.
+ */
+export const DEFAULT_TOOLBAR_IDS = {
+  toggle: "kb-toggle",
+  ctrl: "kb-ctrl",
+  up: "kb-up",
+  down: "kb-down",
+  left: "kb-left",
+  right: "kb-right",
+  tab: "kb-tab",
+  enter: "kb-enter",
+  esc: "kb-esc",
+} as const;
+
+/** Per-button id overrides for `bindMobileToolbar`. */
+export interface MobileToolbarIds {
+  readonly toggle?: string;
+  readonly ctrl?: string;
+  readonly up?: string;
+  readonly down?: string;
+  readonly left?: string;
+  readonly right?: string;
+  readonly tab?: string;
+  readonly enter?: string;
+  readonly esc?: string;
+}
+
+/** Options for `bindMobileToolbar`. */
+export interface BindMobileToolbarOptions {
+  /**
+   * Toolbar container element. Buttons are looked up by id within this
+   * element via `querySelector('#<id>')`. The same element is the one
+   * `kb-toggle` adds/removes the `.collapsed` class on.
+   */
+  readonly toolbar: HTMLElement;
+  /**
+   * Send sink for arrow keys, Tab, Enter, Esc — i.e. for everything
+   * the toolbar emits. Sticky-Ctrl input goes through `applyStickyCtrl`
+   * on the controller; the consumer is responsible for routing
+   * keyboard / paste / IME text through it before handing the result
+   * to the same `send`.
+   */
+  readonly send: (bytes: string) => void;
+  /** Optional id overrides. Missing keys fall back to defaults. */
+  readonly ids?: MobileToolbarIds;
+  /**
+   * Fired whenever the sticky-Ctrl state changes (toolbar press,
+   * `setCtrlArmed`, or auto-disarm after applying a Ctrl byte).
+   */
+  readonly onCtrlChange?: (armed: boolean) => void;
+}
+
+/** Returned from `bindMobileToolbar`; manages sticky-Ctrl state and tear-down. */
+export interface MobileToolbarController {
+  /**
+   * Apply sticky-Ctrl to a piece of input text.
+   *   - When NOT armed: returns `text` unchanged.
+   *   - Armed AND `text.length === 1`: returns the matching Ctrl byte
+   *     (`ctrlByteFor(text)`), or the original char when no mapping
+   *     exists. Always disarms.
+   *   - Armed AND longer (e.g. paste, IME commit): returns `text`
+   *     unchanged and disarms — applying Ctrl to a multi-char string
+   *     would garble it.
+   */
+  applyStickyCtrl(text: string): string;
+  /** Programmatically arm/disarm Ctrl. Updates the toolbar button visuals (`.armed` class + `aria-pressed`) + fires `onCtrlChange`. */
+  setCtrlArmed(on: boolean): void;
+  /** Whether sticky-Ctrl is currently armed. */
+  isCtrlArmed(): boolean;
+  /** Detach all event listeners and reset the toolbar to a non-armed state. Idempotent. */
+  dispose(): void;
+}
+
+/**
+ * Wire a mobile / touch toolbar of on-screen keyboard buttons (Ctrl,
+ * arrows, Tab, Enter, Esc, plus a collapse toggle) to a vterm send
+ * sink.
+ *
+ * Each button's `pointerdown` is intercepted with `preventDefault()`
+ * so the press never fires a focus change or scroll on the host page.
+ *
+ * Arrow keys and Escape emit exactly what an unmodified physical key press
+ * emits: the shared logical-key encodings live in keyboard.ts
+ * (plainCursorKeySeq honors kitty disambiguate over DECCKM, then DECCKM's
+ * SS3 form; plainEscapeSeq is CSI 27 u under kitty, bare ESC otherwise).
+ */
+export function bindMobileToolbar(opts: BindMobileToolbarOptions): MobileToolbarController {
+  const ids = { ...DEFAULT_TOOLBAR_IDS, ...opts.ids };
+  let armed = false;
+
+  function findBtn(id: string): HTMLElement | null {
+    // IDs are kebab-case ASCII; no CSS escaping needed.
+    return opts.toolbar.querySelector<HTMLElement>(`#${id}`);
+  }
+
+  const toggleBtn = findBtn(ids.toggle);
+  const ctrlBtn = findBtn(ids.ctrl);
+  const upBtn = findBtn(ids.up);
+  const downBtn = findBtn(ids.down);
+  const leftBtn = findBtn(ids.left);
+  const rightBtn = findBtn(ids.right);
+  const tabBtn = findBtn(ids.tab);
+  const enterBtn = findBtn(ids.enter);
+  const escBtn = findBtn(ids.esc);
+
+  function paintCtrlBtn(on: boolean): void {
+    if (!ctrlBtn) {
+      return;
+    }
+    ctrlBtn.classList.toggle("armed", on);
+    // Keep the ARIA toggle state in sync with the visual `.armed` class so
+    // assistive tech announces the sticky-Ctrl button as pressed/unpressed.
+    // The scaffold ships kb-ctrl as `aria-pressed="false"`; consumers used to
+    // own this in their own setCtrlArmed before delegating the toolbar here.
+    ctrlBtn.setAttribute("aria-pressed", on ? "true" : "false");
+  }
+
+  function setCtrlArmed(on: boolean): void {
+    if (armed === on) {
+      // Still update visuals defensively (e.g. after dispose was called
+      // and someone re-armed via setCtrlArmed) — but skip the change
+      // notification to keep onCtrlChange edge-triggered.
+      paintCtrlBtn(on);
+      return;
+    }
+    armed = on;
+    paintCtrlBtn(on);
+    opts.onCtrlChange?.(on);
+  }
+
+  // Arrow buttons emit exactly what an unmodified physical arrow press emits
+  // (the toolbar.test.ts equivalence fixtures pin the two paths together).
+  // Mode bits come from the module-global state — the toolbar's source until
+  // P3 threads per-session modes through it.
+  function arrowSeq(letter: "A" | "B" | "C" | "D"): string {
+    return plainCursorKeySeq(letter, kittyDisambiguateActive(), isApplicationCursor());
+  }
+
+  // Listener registry so dispose() can detach them all.
+  const cleanups: (() => void)[] = [];
+  function on(el: HTMLElement | null, handler: (e: PointerEvent) => void): void {
+    if (!el) {
+      return;
+    }
+    const wrapped = (e: Event): void => {
+      handler(e as PointerEvent);
+    };
+    el.addEventListener("pointerdown", wrapped);
+    cleanups.push(() => {
+      el.removeEventListener("pointerdown", wrapped);
+    });
+  }
+
+  on(toggleBtn, (e) => {
+    e.preventDefault();
+    // Show/hide the toolbar. Deliberately does NOT clear armed Ctrl —
+    // toggling visibility shouldn't lose state.
+    opts.toolbar.classList.toggle("collapsed");
+  });
+
+  on(ctrlBtn, (e) => {
+    e.preventDefault();
+    setCtrlArmed(!armed);
+  });
+
+  on(upBtn, (e) => {
+    e.preventDefault();
+    setCtrlArmed(false);
+    opts.send(arrowSeq("A"));
+  });
+  on(downBtn, (e) => {
+    e.preventDefault();
+    setCtrlArmed(false);
+    opts.send(arrowSeq("B"));
+  });
+  on(rightBtn, (e) => {
+    e.preventDefault();
+    setCtrlArmed(false);
+    opts.send(arrowSeq("C"));
+  });
+  on(leftBtn, (e) => {
+    e.preventDefault();
+    setCtrlArmed(false);
+    opts.send(arrowSeq("D"));
+  });
+
+  on(tabBtn, (e) => {
+    e.preventDefault();
+    setCtrlArmed(false);
+    opts.send("\t");
+  });
+  on(enterBtn, (e) => {
+    e.preventDefault();
+    setCtrlArmed(false);
+    opts.send("\r");
+  });
+  on(escBtn, (e) => {
+    e.preventDefault();
+    setCtrlArmed(false);
+    // The shared logical-Escape encoding (CSI 27 u under kitty disambiguate,
+    // bare ESC otherwise) — same single home the physical path uses.
+    opts.send(plainEscapeSeq(kittyDisambiguateActive()));
+  });
+
+  function applyStickyCtrl(text: string): string {
+    if (!armed) {
+      return text;
+    }
+    if (text.length === 1) {
+      setCtrlArmed(false);
+      // Under kitty disambiguate, Ctrl+char is the CSI-u form with the
+      // spec's UNSHIFTED codepoint (shift folded into the modifier),
+      // byte-identical with the physical-keyboard path: Ctrl+':' is 59;6u
+      // from both, never 58;5u.
+      if (kittyDisambiguateActive()) {
+        const seq = kittyCtrlCharSeq(text);
+        if (seq !== null) {
+          return seq;
+        }
+      }
+      const ctrl = ctrlByteFor(text);
+      return ctrl ?? text;
+    }
+    // Multi-char input (paste, IME commit) — applying Ctrl to a string
+    // would garble it. Disarm and pass through verbatim.
+    setCtrlArmed(false);
+    return text;
+  }
+
+  function dispose(): void {
+    setCtrlArmed(false);
+    for (const c of cleanups) {
+      c();
+    }
+    cleanups.length = 0;
+  }
+
+  return {
+    applyStickyCtrl,
+    setCtrlArmed,
+    isCtrlArmed: () => armed,
+    dispose,
+  };
+}

package/src/types.ts

@@ -108,6 +108,40 @@ export interface ResumeAckMessage {
    * shows a "history trimmed" marker rather than misaligning.
    */
   oldestIndex?: number;
+  /**
+   * The server's wire-protocol revision (third length-gated tail, absent on
+   * older servers). A value OUTSIDE the client's supported range means one
+   * side runs a stale bundle/binary; the connection module warns and fires
+   * `onWireVersionMismatch` so the UI can offer a reload. Versions inside
+   * the range are normal pairings (a v3 server just means the socket stays
+   * in sentinel mode); a value >= 4 additionally triggers the typed-framing
+   * upgrade (docs/wire-v4-typed-framing.md).
+   */
+  serverWireVersion?: number;
+  /**
+   * Set when the resume key missed the server's registry while this client
+   * claimed sent bytes: the input ledger was reclaimed (idle GC / cap
+   * eviction), so the server cannot vouch for any previously sent input.
+   * The connection module responds deterministically with its designed loss
+   * semantic — drop the outbox and notify (`onServerRestart`) — instead of
+   * replaying possibly-duplicate input. Absent on older servers (the
+   * `received === 0 && bytesAcked > 0` heuristic remains as their fallback).
+   */
+  ledgerLost?: boolean;
+}
+
+/**
+ * Bare input-ack frame. Sent from the server's flush tick when input was
+ * applied but no content frame carried the advanced ack within the tick
+ * (e.g. typing into a no-echo `read -s`), so outbox trimming never depends
+ * on the app producing output. Transport-internal: the connection module
+ * consumes it and does not forward it to `onMessage`.
+ */
+export interface AckOnlyMessage {
+  /** Discriminator — always `"ackOnly"`. */
+  type: "ackOnly";
+  /** Server-confirmed bytesReceived for the input ACK protocol. */
+  inputAck: number;
 }
 
 /**
@@ -173,7 +207,13 @@ export interface ClipboardMessage {
 
 /** Discriminated union of all messages the server can send to the client. */
 export type ServerMessage =
-  ScreenMessage | ScrollMessage | ResumeAckMessage | ModesMessage | TitleMessage | ClipboardMessage;
+  | ScreenMessage
+  | ScrollMessage
+  | ResumeAckMessage
+  | ModesMessage
+  | TitleMessage
+  | ClipboardMessage
+  | AckOnlyMessage;
 
 /**
  * Discriminated union of all control messages the client can send to the
@@ -188,4 +228,11 @@ export type ControlMessage =
       haveThrough: number;
       protocolVersion: number;
     }
-  | { type: "ping" };
+  | { type: "ping" }
+  /**
+   * v4 typed-framing transition (docs/wire-v4-typed-framing.md §4): the first
+   * TEXT message a client sends after the resumeAck proves the server speaks
+   * wire revision >= 4. Receiving it latches the server's connection to typed
+   * mode (text = control, binary = full-alphabet PTY input); otherwise a no-op.
+   */
+  | { type: "upgrade" };

package/src/wire-binary.ts

@@ -22,19 +22,8 @@ const MSG_MODES = 3;
 const MSG_TITLE = 4;
 const MSG_PONG = 5;
 const MSG_CLIPBOARD = 6;
+const MSG_ACK_ONLY = 7;
 
-/**
- * Wire protocol version. Sent by the client in the `resume` control message so
- * the server can detect a client built against a different protocol revision
- * (e.g. a stale cached bundle after a breaking change) and warn rather than
- * silently mis-decode. Bump on any breaking change to the binary frame layout
- * or control-message shape. Mirrors `wireProtocolVersion` in wire_binary.go.
- *
- * v3: the modes frame gained a trailing kbdFlags byte (kitty keyboard
- * protocol). Decoding is tolerant of a pre-v3 server (kbdFlags defaults to 0
- * when the byte is absent), so the bump only drives the mismatch warning.
- */
-export const WIRE_PROTOCOL_VERSION = 3;
 const MODE_FLAG_BRACKETED_PASTE = 1;
 const MODE_FLAG_APP_CURSOR_KEYS = 2;
 const MODE_FLAG_MOUSE_SGR = 4;
@@ -154,9 +143,12 @@ 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)
     let serverEpoch: number | undefined;
     let committed: number | undefined;
     let oldestIndex: number | undefined;
+    let serverWireVersion: number | undefined;
+    let ledgerLost: boolean | undefined;
     if (buf.byteLength >= 17) {
       serverEpoch = c.u64();
     }
@@ -164,6 +156,11 @@ function decodeWireBinaryInner(buf: ArrayBuffer): ServerMessage | null {
       committed = c.u64();
       oldestIndex = c.u64();
     }
+    if (buf.byteLength >= 35) {
+      serverWireVersion = c.u8();
+      const ackFlags = c.u8();
+      ledgerLost = (ackFlags & 1) !== 0;
+    }
     const msg: ResumeAckMessage = { type: "resumeAck", received: inputAck };
     if (serverEpoch !== undefined) {
       msg.serverEpoch = serverEpoch;
@@ -174,8 +171,19 @@ function decodeWireBinaryInner(buf: ArrayBuffer): ServerMessage | null {
     if (oldestIndex !== undefined) {
       msg.oldestIndex = oldestIndex;
     }
+    if (serverWireVersion !== undefined) {
+      msg.serverWireVersion = serverWireVersion;
+    }
+    if (ledgerLost !== undefined) {
+      msg.ledgerLost = ledgerLost;
+    }
     return msg;
   }
+  if (msgType === MSG_ACK_ONLY) {
+    // Bare ack: header only (type + inputAck). Applied to the outbox by the
+    // connection module and never forwarded to consumers.
+    return { type: "ackOnly", inputAck };
+  }
   if (msgType === MSG_SCREEN) {
     // Sparse row array: the frame carries only changed rows (indexed by
     // row_idx). The client allocates a full screenHeight-sized array but

package/src/wire-compatibility.ts

@@ -0,0 +1,29 @@
+// Public wire-compatibility metadata for the independently released browser
+// client. The Go server exposes the complementary directional floor from its
+// terminal package. Keep both current revisions equal; their minimum peer
+// revisions may diverge as each receiver retires old decode paths.
+
+/** Current wire revision emitted by this browser client. */
+export const WIRE_PROTOCOL_VERSION = 4;
+
+/** Oldest explicitly declared server revision this client accepts. */
+export const MIN_SUPPORTED_SERVER_WIRE_VERSION = 3;
+
+/** Definitive private WebSocket close code for an incompatible declared peer. */
+export const WIRE_INCOMPATIBLE_CLOSE_CODE = 4002;
+
+/** Machine-readable compatibility metadata shipped in every TS release. */
+export const WIRE_COMPATIBILITY = Object.freeze({
+  protocolVersion: WIRE_PROTOCOL_VERSION,
+  minimumServerProtocolVersion: MIN_SUPPORTED_SERVER_WIRE_VERSION,
+  incompatibleCloseCode: WIRE_INCOMPATIBLE_CLOSE_CODE,
+});
+
+/** Details surfaced when the connection is stopped for wire incompatibility. */
+export interface WireIncompatibility {
+  readonly source: "server-version" | "server-close";
+  readonly clientVersion: number;
+  readonly minimumServerVersion: number;
+  readonly serverVersion?: number;
+  readonly reason: string;
+}

package/src/wire.ts

@@ -1,15 +1,23 @@
 // Pure wire-format helpers for the client → server WebSocket protocol.
 //
-// Protocol: every WebSocket message the client sends to the server is a
-// binary frame whose first byte tags the message type:
+// v3 framing (the bootstrap/fallback encoding): every client→server message
+// is a binary frame whose first byte tags the message type:
 //
 //   0x00  control message (JSON-encoded {type, ...} payload)
 //   any   raw terminal input bytes
 //
-// The 0x00 prefix is the only framing convention; raw input flows
-// through the rest of the byte space, because terminal input never
-// starts a write with NUL. See the Go terminal package's frame parser
-// for the receiving end.
+// Disambiguation rule (amended with the parse-fallback): a solitary [0x00],
+// and any 0x00-leading frame that is not a valid control message, are literal
+// terminal input; 0x00 + valid control JSON is the reserved control channel.
+// The client additionally never emits a multi-byte 0x00-leading input frame
+// in v3 mode (sendInputFrames splits leading NULs into solitary frames), so
+// in practice the reserved channel only ever carries real controls.
+//
+// v4 framing (docs/wire-v4-typed-framing.md) retires the sentinel once a
+// socket upgrades: control messages travel as WebSocket TEXT frames and
+// binary frames are full-alphabet PTY input. This module's controlFrame stays
+// the encoding for the v3 bootstrap (every socket's first resume) and for
+// v3-mode sockets (older servers).
 //
 // Pulled into a dedicated module so unit tests can exercise the framing
 // without spinning up a WebSocket. Pure: no DOM, no WebSocket, no