@cplieger/web-terminal-engine 1.3.2 → 2.0.0

package/jsr.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/web-terminal-engine",
-  "version": "1.3.2",
+  "version": "2.0.0",
   "exports": {
     ".": "./src/index.ts"
   },

package/package.json

@@ -1,21 +1,26 @@
 {
   "name": "@cplieger/web-terminal-engine",
-  "version": "1.3.2",
+  "version": "2.0.0",
   "type": "module",
   "scripts": {
     "typecheck": "tsgo -p tsconfig.json",
     "typecheck:tests": "tsgo -p tsconfig.test.json",
-    "test": "vitest --run"
+    "test": "vitest --run",
+    "test:e2e": "playwright test"
   },
   "devDependencies": {
     "@eslint/js": "10.0.1",
+    "@playwright/test": "1.61.1",
+    "@types/pngjs": "6.0.5",
     "@vitest/coverage-v8": "4.1.9",
+    "esbuild": "0.28.1",
     "eslint": "10.6.0",
     "fast-check": "4.8.0",
     "happy-dom": "20.10.6",
-    "prettier": "3.8.5",
+    "pngjs": "7.0.0",
+    "prettier": "3.9.4",
     "typescript": "6.0.3",
-    "typescript-eslint": "8.62.0",
+    "typescript-eslint": "8.62.1",
     "vitest": "4.1.9"
   },
   "description": "Browser terminal engine: VT500 screen buffer, DOM renderer, and binary wire protocol",
@@ -35,7 +40,7 @@
   "files": [
     "src/",
     "!src/**/*.test.ts",
-    "!src/**/__test-helpers__",
+    "!src/**/test-helpers",
     "!src/**/fc-strict-setup.ts",
     "jsr.json"
   ]

package/src/connection.ts

@@ -40,20 +40,58 @@ let lastSentCols = 0;
 let lastSentRows = 0;
 let wsPath = "/ws";
 
-// Resume-protocol state. sessionId persists across iOS tab-suspend/reload
-// via sessionStorage. Without this persistence, an iOS Safari tab unload
-// (which Safari does aggressively when the user backgrounds the tab) and
-// subsequent reconstruction from history triggers a fresh JS module load
-// → new sessionId → server treats it as a new session → resumeAck.received
-// returns 0 → applyAck(0) doesn't trim the outbox → retransmitOutbox sends
-// every queued chunk again, causing the duplicate-message-resend bug.
+// --- Per-session resume state (the switching cache's connection half) ---
+//
+// Each server session carries its own reliable-input accounting: an outbox of
+// unacked bytes, byte counters, and the last server boot-epoch it saw. Scoping
+// this per session (rather than one module-global set) is what lets a tab switch
+// reconnect to a different session without replaying the previous tab's unacked
+// bytes onto it and without firing a false server-restart reset, because each
+// session's epoch is compared only against its own bootEpoch (design section 8).
+interface ResumeState {
+  id: string; // server session id: both the routing id (?session=) and the resume id
+  bytesSent: number; // total bytes ever passed to sendBinary for this session
+  bytesAcked: number; // confirmed by server inputAck/resumeAck
+  outbox: Uint8Array[]; // unacked chunks (sum of lengths = bytesSent - bytesAcked)
+  outboxBytes: number; // running sum of outbox chunk lengths; keeps applyAck O(n) not O(n²)
+  lastServerEpoch: number | null; // process-start nanos last seen for this session
+}
+
+const sessions = new Map<string, ResumeState>();
+// The session the live socket currently serves. null until the first connect or
+// setSession; the unmanaged single-terminal path lazily creates a default
+// session with a sessionStorage-backed id.
+let activeId: string | null = null;
+// managed = a consumer selected sessions explicitly via setSession, so the WS URL
+// carries ?session=<id>. Unmanaged keeps the bare wsPath and a sessionStorage id,
+// preserving the original single-terminal behavior and its iOS-resume semantics
+// (sessionStorage survives iOS tab-suspend/BFCache, so an unmanaged reload
+// resumes rather than orphaning its outbox). A tabbed shell is managed; it
+// rebuilds tabs from GET /api/sessions on reload (section 17), so it needs no
+// client-side id persistence.
+let managed = false;
+
 const SESSION_ID_KEY = "vterm-session-id";
-const sessionId = loadOrCreateSessionId();
-let bytesSent = 0; // total bytes ever passed to sendBinary
-let bytesAcked = 0; // confirmed by server inputAck/resumeAck
-const outbox: Uint8Array[] = []; // chunks of unacked bytes (sum = bytesSent - bytesAcked)
-let outboxBytes = 0; // running sum of outbox chunk lengths; keeps applyAck O(n) instead of O(n²)
-let lastServerEpoch: number | null = null; // process-start nanos of the last connected server
+
+function newResumeState(id: string): ResumeState {
+  return { id, bytesSent: 0, bytesAcked: 0, outbox: [], outboxBytes: 0, lastServerEpoch: null };
+}
+
+function ensureState(id: string): ResumeState {
+  let s = sessions.get(id);
+  if (s === undefined) {
+    s = newResumeState(id);
+    sessions.set(id, s);
+  }
+  return s;
+}
+
+// activeState returns the ResumeState the live socket serves, lazily creating
+// the default (unmanaged) session from a sessionStorage-backed id on first use.
+function activeState(): ResumeState {
+  activeId ??= loadOrCreateSessionId();
+  return ensureState(activeId);
+}
 
 // --- Client-side liveness (bug 2 defense-in-depth) ---
 //
@@ -181,17 +219,18 @@ export function init(callbacks: Callbacks): void {
  * buffer reuse.
  */
 export function sendBinary(data: Uint8Array): boolean {
-  if (outboxBytes + data.length > MAX_OUTBOX_BYTES) {
+  const st = activeState();
+  if (st.outboxBytes + data.length > MAX_OUTBOX_BYTES) {
     cb?.onOutboxFull?.();
     return false;
   }
-  // Always go through the outbox. Bytes leave it only when the server
-  // explicitly acks them — guarantees correct retransmission after a
+  // Always go through the active session's outbox. Bytes leave it only when the
+  // server explicitly acks them — guarantees correct retransmission after a
   // network blip even if ws.send() reported success.
   const copy = new Uint8Array(data); // defensive copy (caller may reuse buffer)
-  outbox.push(copy);
-  outboxBytes += copy.length;
-  bytesSent += copy.length;
+  st.outbox.push(copy);
+  st.outboxBytes += copy.length;
+  st.bytesSent += copy.length;
   if (connState.status === "connected") {
     connState.sock.send(copy.buffer.slice(copy.byteOffset, copy.byteOffset + copy.byteLength));
   }
@@ -218,40 +257,37 @@ export function sendResize(): void {
   sendControl({ type: "resize", cols, rows });
 }
 
-// applyAck drops chunks from the front of the outbox until the
-// running total of unacked bytes matches (bytesSent - newAck). Runs
-// in O(chunks_dropped) by tracking outboxBytes incrementally rather
-// than re-summing on every loop iteration.
-function applyAck(received: number): void {
-  if (received <= bytesAcked) {
+// applyAck drops chunks from the front of the session's outbox until the
+// running total of unacked bytes matches (bytesSent - newAck). Runs in
+// O(chunks_dropped) by tracking outboxBytes incrementally rather than
+// re-summing on every loop iteration.
+function applyAck(st: ResumeState, received: number): void {
+  if (received <= st.bytesAcked) {
     return;
   }
-  bytesAcked = Math.min(received, bytesSent);
-  const targetUnacked = bytesSent - bytesAcked;
-  while (outbox.length > 0 && outboxBytes > targetUnacked) {
+  st.bytesAcked = Math.min(received, st.bytesSent);
+  const targetUnacked = st.bytesSent - st.bytesAcked;
+  while (st.outbox.length > 0 && st.outboxBytes > targetUnacked) {
     // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- length checked above
-    const head = outbox[0]!;
-    const dropFromHead = outboxBytes - targetUnacked;
+    const head = st.outbox[0]!;
+    const dropFromHead = st.outboxBytes - targetUnacked;
     if (head.length <= dropFromHead) {
-      outbox.shift();
-      outboxBytes -= head.length;
+      st.outbox.shift();
+      st.outboxBytes -= head.length;
     } else {
-      outbox[0] = head.subarray(dropFromHead);
-      outboxBytes -= dropFromHead;
+      st.outbox[0] = head.subarray(dropFromHead);
+      st.outboxBytes -= dropFromHead;
       break;
     }
   }
 }
 
-// On reconnect, after sending the resume control message and getting
-// resumeAck, replay anything still in the outbox. The server has
-// adjusted bytesAcked already — only unacked bytes remain.
-function retransmitOutbox(): void {
-  if (connState.status !== "connected") {
-    return;
-  }
-  for (const chunk of outbox) {
-    connState.sock.send(
+// On reconnect, after sending the resume control message and getting resumeAck,
+// replay anything still in the session's outbox over its (now open) socket. The
+// server has adjusted bytesAcked already — only unacked bytes remain.
+function retransmitOutbox(sock: WebSocket, st: ResumeState): void {
+  for (const chunk of st.outbox) {
+    sock.send(
       chunk.buffer.slice(chunk.byteOffset, chunk.byteOffset + chunk.byteLength) as ArrayBuffer,
     );
   }
@@ -330,17 +366,11 @@ function heartbeatTick(): void {
   }
 }
 
-export function reconnectNow(): void {
-  // Unconditional teardown. On iOS wake (visibilitychange + pageshow), the
-  // socket frequently reads OPEN/"connected" for a while but is actually a
-  // zombie — the OS froze it during sleep and frames printed meanwhile never
-  // arrive. The old early-return on "connected" trusted that stale state and
-  // skipped the reconnect, which is exactly why content printed during sleep
-  // stayed missing until a manual refresh (bug 2). So we never trust the
-  // current state on a wake: abort + close whatever socket exists and
-  // reconnect. The resume protocol (by absolute index) then backfills exactly
-  // the missed lines, so a reconnect over a still-healthy socket is a cheap,
-  // duplicate-free no-op rather than a risk.
+// teardown aborts and closes the live socket (if any) and stops the heartbeat
+// and any scheduled reconnect, leaving the module disconnected. It never touches
+// per-session resume state, so a later connect() resumes cleanly. Shared by
+// reconnectNow (reconnects after) and disconnect/forgetSession (do not).
+function teardown(): void {
   if (connState.status === "connecting" || connState.status === "connected") {
     // Abort BEFORE close: aborting detaches all listeners on the existing
     // sock, so frames arriving between close() and the close handshake aren't
@@ -355,9 +385,64 @@ export function reconnectNow(): void {
   stopHeartbeat();
   cancelScheduledReconnect();
   connState = { status: "disconnected" };
+}
+
+export function reconnectNow(): void {
+  // Unconditional teardown. On iOS wake (visibilitychange + pageshow), the
+  // socket frequently reads OPEN/"connected" for a while but is actually a
+  // zombie — the OS froze it during sleep and frames printed meanwhile never
+  // arrive. The old early-return on "connected" trusted that stale state and
+  // skipped the reconnect, which is exactly why content printed during sleep
+  // stayed missing until a manual refresh (bug 2). So we never trust the
+  // current state on a wake: abort + close whatever socket exists and
+  // reconnect. The resume protocol (by absolute index) then backfills exactly
+  // the missed lines, so a reconnect over a still-healthy socket is a cheap,
+  // duplicate-free no-op rather than a risk.
+  teardown();
   connect();
 }
 
+/**
+ * setSession switches the live socket to a different server session, keeping
+ * every session's resume state intact (design section 5, the switch). The
+ * current socket is torn down (its outbox and byte counters preserved for a
+ * later switch back) and a fresh socket connects to `id` with its own resume
+ * state, sending `?session=id`. Calling this marks the module "managed": the WS
+ * URL then carries the session id. A no-op when `id` is already the active,
+ * connected session.
+ */
+export function setSession(id: string): void {
+  managed = true;
+  ensureState(id);
+  if (id === activeId && (connState.status === "connected" || connState.status === "connecting")) {
+    return; // already serving this session
+  }
+  activeId = id;
+  reconnectNow();
+}
+
+/**
+ * forgetSession drops a session's resume state (on tab close, design section 17).
+ * If it was the active session, the live socket is torn down without
+ * reconnecting; the shell then selects another tab via setSession.
+ */
+export function forgetSession(id: string): void {
+  sessions.delete(id);
+  if (id === activeId) {
+    activeId = null;
+    teardown();
+  }
+}
+
+/**
+ * disconnect tears down the live socket without reconnecting. Per-session resume
+ * state is kept, so a later setSession/connect resumes cleanly. Used when the
+ * shell has no active tab to show (e.g. the last tab closed).
+ */
+export function disconnect(): void {
+  teardown();
+}
+
 export function connect(): void {
   // Guard against double-call: a stray invocation while a previous
   // socket is still CONNECTING/OPEN would orphan it (its handlers
@@ -384,7 +469,18 @@ export function connect(): void {
 
   cb?.onConnecting?.();
 
-  const sock = new WebSocket(wsURL(location.protocol, location.host, wsPath));
+  // The resume state this socket serves, captured for the socket's lifetime.
+  // A switch aborts this socket's listeners, so even a late frame is handled
+  // against the session it was opened for, never whoever is active now.
+  const st = activeState();
+  let url = wsURL(location.protocol, location.host, wsPath);
+  if (managed) {
+    // Route the socket to this session (SessionManager's WebSocketHandler
+    // dispatches on ?session=). The unmanaged single-terminal path keeps the
+    // bare wsPath, matching resume purely by the resume frame's sessionId.
+    url += (url.includes("?") ? "&" : "?") + "session=" + encodeURIComponent(st.id);
+  }
+  const sock = new WebSocket(url);
   sock.binaryType = "arraybuffer";
 
   // One AbortController governs the lifetime of THIS sock's listeners.
@@ -427,8 +523,8 @@ export function connect(): void {
       sock.send(
         controlFrame({
           type: "resume",
-          sessionId,
-          sentBytes: bytesSent,
+          sessionId: st.id,
+          sentBytes: st.bytesSent,
           // Highest absolute line index the client holds (-1 if none). The
           // server replays everything after it, so lines printed while the
           // device slept are backfilled exactly on wake (bug 2), with no
@@ -499,14 +595,14 @@ export function connect(): void {
       // of the previous boot's input). Reset state and notify the UI.
       const epoch = msg.serverEpoch;
       if (epoch !== undefined && epoch !== 0) {
-        if (lastServerEpoch !== null && lastServerEpoch !== epoch) {
-          bytesSent = 0;
-          bytesAcked = 0;
-          outbox.length = 0;
-          outboxBytes = 0;
+        if (st.lastServerEpoch !== null && st.lastServerEpoch !== epoch) {
+          st.bytesSent = 0;
+          st.bytesAcked = 0;
+          st.outbox.length = 0;
+          st.outboxBytes = 0;
           cb?.onServerRestart?.();
         }
-        lastServerEpoch = epoch;
+        st.lastServerEpoch = epoch;
       }
       // Resync guard 8.2.2: hand the server's retained-history bounds to the
       // consumer so it can surface a trim marker when history the client was
@@ -525,16 +621,16 @@ export function connect(): void {
       // since the last successful ack is irrecoverable but at least
       // not duplicated. Skip this branch when bytesSent = 0 (genuine
       // first-connect; received=0 is correct).
-      if (msg.received === 0 && bytesAcked > 0) {
-        bytesSent = 0;
-        bytesAcked = 0;
-        outbox.length = 0;
-        outboxBytes = 0;
+      if (msg.received === 0 && st.bytesAcked > 0) {
+        st.bytesSent = 0;
+        st.bytesAcked = 0;
+        st.outbox.length = 0;
+        st.outboxBytes = 0;
         cb?.onServerRestart?.();
         return;
       }
-      applyAck(msg.received);
-      retransmitOutbox();
+      applyAck(st, msg.received);
+      retransmitOutbox(sock, st);
       return;
     }
     if (msg.type === "modes") {
@@ -546,9 +642,10 @@ export function connect(): void {
         msg.mouseMode,
         msg.applicationKeypad,
         msg.reverseVideo,
+        msg.mousePixels,
       );
       if (typeof msg.inputAck === "number") {
-        applyAck(msg.inputAck);
+        applyAck(st, msg.inputAck);
       }
       // Notify the UI so it can react to mode changes (e.g. clear
       // scrollback on alt-screen entry — handled by the caller).
@@ -556,7 +653,7 @@ export function connect(): void {
       return;
     }
     if (typeof msg.inputAck === "number") {
-      applyAck(msg.inputAck);
+      applyAck(st, msg.inputAck);
     }
     cb?.onMessage(msg);
   }

package/src/index.ts

@@ -1,4 +1,6 @@
 export * from "./types.js";
+export { LineStore } from "./store.js";
+export type { WindowState, StoreChanges } from "./store.js";
 export * as render from "./render.js";
 export * as keyboard from "./keyboard.js";
 export * as scroll from "./scroll.js";
@@ -8,3 +10,11 @@ export * as connection from "./connection.js";
 export { decodeWireBinary } from "./wire-binary.js";
 export { controlFrame, CONTROL_FRAME_PREFIX } from "./wire.js";
 export { wsURL } from "./wsurl.js";
+export { connectStatusStream } from "./status-stream.js";
+export type {
+  SessionStatus,
+  StatusStream,
+  StatusStreamCallbacks,
+  EventSourceFactory,
+  EventSourceLike,
+} from "./status-stream.js";

package/src/keyboard.ts

@@ -14,7 +14,7 @@
 // vt screen tracks both bracketed paste (?2004) and DECCKM (?1) and
 // emits a modes frame whenever they change.
 
-import { isApplicationCursor, isApplicationKeypad, isBracketedPaste } from "./modes.js";
+import { isApplicationCursor, isBracketedPaste } from "./modes.js";
 
 /** Result of mapping a keyboard event. */
 export type KeyboardResult =
@@ -23,6 +23,18 @@ export type KeyboardResult =
   | { kind: "scroll-down" } // Shift+PageDown — handled locally
   | { kind: "ignore" }; // Modifier-only press, etc.
 
+/**
+ * KeyboardModes is the mode state `mapKeyboardEvent` reads: DECCKM (application
+ * cursor keys) and DECKPAM (application keypad). Passed explicitly so the shared
+ * input maps against the active tab's modes and so the mapping is testable
+ * without mutating global state. The `modes` module namespace satisfies this
+ * structurally; a tabbed shell passes its active session's modes.
+ */
+export interface KeyboardModes {
+  isApplicationCursor: () => boolean;
+  isApplicationKeypad: () => boolean;
+}
+
 const ESC = "\x1b";
 const DEL = "\x7f";
 
@@ -42,11 +54,11 @@ function modifiersDigit(ev: KeyboardEvent): number {
 // When the application has set DECCKM, the modifier-less form switches
 // from CSI to SS3 (ESC O letter); modifier-bearing forms stay on CSI
 // because they have no SS3 equivalent.
-function csiLetter(letter: string, ev: KeyboardEvent): string {
+function csiLetter(letter: string, ev: KeyboardEvent, modes: KeyboardModes): string {
   const m = modifiersDigit(ev);
   if (m === 1) {
     if (
-      isApplicationCursor() &&
+      modes.isApplicationCursor() &&
       (letter === "A" ||
         letter === "B" ||
         letter === "C" ||
@@ -123,8 +135,12 @@ const KEYPAD_SS3: Record<string, string | undefined> = {
  * Caller is responsible for ev.preventDefault() when the result is
  * "send" or "scroll-*"; we don't call it here so the function stays
  * pure and testable.
+ *
+ * `modes` supplies the active session's DECCKM/DECKPAM state; pass the `modes`
+ * module namespace for the single-terminal case or the active tab's modes in a
+ * tabbed shell.
  */
-export function mapKeyboardEvent(ev: KeyboardEvent): KeyboardResult {
+export function mapKeyboardEvent(ev: KeyboardEvent, modes: KeyboardModes): KeyboardResult {
   // Modifier-only presses (Shift, Ctrl, Alt, Meta) — no-op.
   if (ev.key === "Shift" || ev.key === "Control" || ev.key === "Alt" || ev.key === "Meta") {
     return { kind: "ignore" };
@@ -139,7 +155,7 @@ export function mapKeyboardEvent(ev: KeyboardEvent): KeyboardResult {
   // We detect numpad keys via ev.code (Numpad0-9, NumpadDecimal,
   // NumpadSubtract, NumpadAdd, NumpadMultiply, NumpadDivide, NumpadEnter).
   if (
-    isApplicationKeypad() &&
+    modes.isApplicationKeypad() &&
     !ev.ctrlKey &&
     !ev.altKey &&
     !ev.metaKey &&
@@ -175,15 +191,15 @@ export function mapKeyboardEvent(ev: KeyboardEvent): KeyboardResult {
   // Cursor keys — CSI form with optional modifiers (CSI 1;{m}{letter}).
   const arrow = ARROW_LETTER[ev.key];
   if (arrow !== undefined) {
-    return { kind: "send", bytes: csiLetter(arrow, ev) };
+    return { kind: "send", bytes: csiLetter(arrow, ev, modes) };
   }
 
   // Home / End — CSI {H,F} with optional modifiers.
   if (ev.key === "Home") {
-    return { kind: "send", bytes: csiLetter("H", ev) };
+    return { kind: "send", bytes: csiLetter("H", ev, modes) };
   }
   if (ev.key === "End") {
-    return { kind: "send", bytes: csiLetter("F", ev) };
+    return { kind: "send", bytes: csiLetter("F", ev, modes) };
   }
 
   // Insert / Delete / PageUp / PageDown (no Shift) — CSI tilde forms.

package/src/modes.ts

@@ -20,6 +20,7 @@ let applicationCursor = false;
 let applicationKeypad = false;
 let mouseMode = 0; // 0=off, 1000=normal, 1002=button-event, 1003=any-event
 let mouseSGR = false;
+let mousePixels = false; // DEC 1016: report pixel coords instead of cell coords
 let focusReporting = false;
 let reverseVideo = false;
 
@@ -36,6 +37,7 @@ export function setModes(
   mMode?: number,
   appKeypad?: boolean,
   revVideo?: boolean,
+  mPixels?: boolean,
 ): void {
   bracketedPaste = bracketed;
   applicationCursor = appCursor;
@@ -54,6 +56,9 @@ export function setModes(
   if (revVideo !== undefined) {
     reverseVideo = revVideo;
   }
+  if (mPixels !== undefined) {
+    mousePixels = mPixels;
+  }
 }
 
 /** True when the server has DEC 2004 (bracketed paste) enabled. */
@@ -79,6 +84,12 @@ export function isMouseSGR(): boolean {
   return mouseSGR;
 }
 
+/** True when the server has DEC 1016 (SGR-pixels mouse) enabled: mouse reports
+ *  carry pixel coordinates instead of cell coordinates. */
+export function isMousePixels(): boolean {
+  return mousePixels;
+}
+
 /** True when the server has DEC 1004 (focus event reporting) enabled. */
 export function isFocusReporting(): boolean {
   return focusReporting;

package/src/mouse.ts

@@ -14,7 +14,7 @@
 //   - urxvt encoding (mode 1015): not supported.
 //   - DEFAULT encoding (raw bytes): not supported; only SGR 1006.
 
-import { getMouseMode, isMouseSGR, isFocusReporting } from "./modes.js";
+import { getMouseMode, isMouseSGR, isMousePixels, isFocusReporting } from "./modes.js";
 
 const ESC = "\x1b";
 
@@ -59,12 +59,14 @@ export function encodeSGR(code: number, col: number, row: number, release: boole
 
 /** Map DOM button index to xterm button number. */
 function domButtonToXterm(button: number): number {
-  // DOM: 0=left, 1=middle, 2=right
-  // xterm: 0=left, 1=middle, 2=right
+  // DOM MouseEvent.button: 0=left, 1=middle, 2=right, 3=back, 4=forward.
+  // xterm: 0/1/2 for left/middle/right; the "additional buttons" (X11 8-11,
+  // reached via DOM back/forward) use the +128 extended-button encoding, so
+  // back (DOM 3 = X11 8) → 128 and forward (DOM 4 = X11 9) → 129.
   if (button <= 2) {
     return button;
   }
-  return 0; // fallback
+  return 128 + (button - 3);
 }
 
 /**
@@ -100,12 +102,25 @@ export function init(h: MouseInputHandler): void {
   el.addEventListener("focusout", onFocusOut);
 }
 
+// pixelToCell returns the coordinate pair to report for a mouse event. Normally
+// that's the 1-based cell column/row; under DEC 1016 (SGR-pixels) it's instead
+// the 1-based pixel offset within the terminal element (same SGR grammar, so
+// encodeSGR is reused unchanged). The {col,row} field names carry whichever the
+// active mode reports.
 function pixelToCell(e: MouseEvent): { col: number; row: number } | null {
   if (!handler) {
     return null;
   }
   const el = handler.termElement();
   const rect = el.getBoundingClientRect();
+  if (isMousePixels()) {
+    const px = Math.round(e.clientX - rect.left);
+    const py = Math.round(e.clientY - rect.top);
+    if (px < 0 || py < 0) {
+      return null;
+    }
+    return { col: px + 1, row: py + 1 }; // 1-based pixel offsets
+  }
   const { width, height } = handler.cellSize();
   if (width <= 0 || height <= 0) {
     return null;
@@ -120,7 +135,7 @@ function pixelToCell(e: MouseEvent): { col: number; row: number } | null {
 
 function onMouseDown(e: MouseEvent): void {
   const mode = getMouseMode();
-  if (mode === 0 || !isMouseSGR() || !handler) {
+  if (mode === 0 || !(isMouseSGR() || isMousePixels()) || !handler) {
     return;
   }
   const pos = pixelToCell(e);
@@ -135,7 +150,7 @@ function onMouseDown(e: MouseEvent): void {
 
 function onMouseUp(e: MouseEvent): void {
   const mode = getMouseMode();
-  if (mode === 0 || !isMouseSGR() || !handler) {
+  if (mode === 0 || !(isMouseSGR() || isMousePixels()) || !handler) {
     return;
   }
   const pos = pixelToCell(e);
@@ -151,7 +166,7 @@ function onMouseUp(e: MouseEvent): void {
 
 function onMouseMove(e: MouseEvent): void {
   const mode = getMouseMode();
-  if (mode === 0 || !isMouseSGR() || !handler) {
+  if (mode === 0 || !(isMouseSGR() || isMousePixels()) || !handler) {
     return;
   }
   // mode 1000: no motion events
@@ -167,14 +182,16 @@ function onMouseMove(e: MouseEvent): void {
   if (!pos) {
     return;
   }
-  const btn = e.buttons ? (e.buttons & 1 ? 0 : e.buttons & 4 ? 1 : e.buttons & 2 ? 2 : 0) : 0;
+  // No button held (bare motion in mode 1003) reports xterm's "no button"
+  // code 3, not 0 — code 0 would be read as a left-button drag during hover.
+  const btn = e.buttons ? (e.buttons & 1 ? 0 : e.buttons & 4 ? 1 : e.buttons & 2 ? 2 : 0) : 3;
   const code = buttonCode(btn, true, e.shiftKey, e.altKey, e.ctrlKey);
   handler.send(encodeSGR(code, pos.col, pos.row, false));
 }
 
 function onWheel(e: WheelEvent): void {
   const mode = getMouseMode();
-  if (mode === 0 || !isMouseSGR() || !handler) {
+  if (mode === 0 || !(isMouseSGR() || isMousePixels()) || !handler) {
     return;
   }
   const pos = pixelToCell(e);

package/src/render.ts

@@ -110,7 +110,11 @@ function measureCellWidth(): number {
 let output: HTMLElement;
 let termWrap: HTMLElement;
 
-const store = new LineStore();
+// The store the renderer reflects. Module-private by default (a consumer that
+// never calls bind() gets one implicit store, the original single-terminal
+// behavior). The tabs feature keeps one LineStore per tab and calls bind() on
+// switch to point the renderer at the active tab's cache (design section 6).
+let store = new LineStore();
 // abs index -> its row element. The DOM children of `output` are these
 // elements, kept in ascending data-abs order.
 const rowEls = new Map<number, HTMLDivElement>();
@@ -215,6 +219,69 @@ export function resetScrollback(): void {
   scheduleFlush();
 }
 
+/**
+ * Bind the renderer to a different store and rebuild the surface from it. The
+ * tabs feature calls this on every switch to point the one renderer at the
+ * active tab's cached LineStore (design sections 5, 6, 8). The DOM is wiped and
+ * repainted viewport-first from the new store; this is local, so the last-known
+ * screen paints without a network round-trip.
+ */
+export function bind(next: LineStore): void {
+  store = next;
+  rebuild();
+}
+
+/**
+ * The store the renderer is currently bound to. Exposed so the shell can feed
+ * decoded frames into the active tab's store and read its resume bounds.
+ */
+export function boundStore(): LineStore {
+  return store;
+}
+
+/**
+ * Wipe the DOM and rebuild it from the current store, viewport-first and
+ * budgeted. The live window (what the user sees) builds first, then scrollback
+ * from newest to oldest so rows adjacent to the viewport fill in before deep
+ * history; the existing per-frame budget spreads a large backlog across frames
+ * so the switch never janks. Used by bind(); also safe to call directly to
+ * force a full repaint of the current store.
+ */
+export function rebuild(): void {
+  output.replaceChildren();
+  rowEls.clear();
+  renderQueue.clear();
+  trimMarkerEl = null;
+  cursorAbs = -1;
+  altRendered = false;
+  prevCursorCol = -1;
+  prevCursorHidden = false;
+  prevCursorStyleVal = -1;
+  // Alt screen paints from the ephemeral grid in the flush, so it needs no
+  // absolute-index queueing here.
+  if (!store.isAlt()) {
+    const oldest = store.oldestIndex();
+    const highest = store.highestIndex();
+    if (highest >= 0) {
+      const winStart = Math.max(store.getWindow().base, oldest);
+      // Live window first (viewport), ascending.
+      for (let abs = winStart; abs <= highest; abs++) {
+        if (store.getLine(abs) !== undefined) {
+          renderQueue.add(abs);
+        }
+      }
+      // Then scrollback, newest to oldest, so rows nearest the viewport fill in
+      // before deep history.
+      for (let abs = winStart - 1; abs >= oldest; abs--) {
+        if (store.getLine(abs) !== undefined) {
+          renderQueue.add(abs);
+        }
+      }
+    }
+  }
+  scheduleFlush();
+}
+
 /**
  * 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
@@ -408,6 +475,12 @@ function buildRowSpans(runs: WireRun[], cursorAt: number): (HTMLSpanElement | HT
             prev.style.letterSpacing = `${cellWidth * 2 - w}px`;
           }
         }
+        // The spacer occupies the wide char's second cell, so it advances the
+        // column exactly like a printed cell. The engine reports cursor_col in
+        // true cell coordinates (a wide glyph moves curX by 2), so col must
+        // count this cell too — otherwise a visible cursor positioned after a
+        // wide char lands one cell too far right per preceding wide char.
+        col++;
         continue;
       }
       if (col === cursorAt) {

package/src/status-stream.ts

@@ -0,0 +1,95 @@
+// Client for the server's session status stream (Server-Sent Events at
+// /api/sessions/events). A thin EventSource wrapper: it parses each status event
+// and fans it out to a callback. The reconnect-resync policy (re-fetching the
+// session list after a gap) is the consumer's job; onOpen fires on every
+// (re)open so the consumer can trigger it. Pairs with the Go
+// terminal.SessionManager EventsHandler.
+
+/** SessionStatus is one session's current status as carried on the stream. It
+ *  mirrors the server's status event. */
+export interface SessionStatus {
+  readonly id: string;
+  readonly status: "working" | "idle" | "input" | "exited";
+  readonly title: string;
+  readonly createdAt: string;
+  /** 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 {
+  /** Called for each status event. */
+  onStatus: (status: SessionStatus) => void;
+  /** Called on every (re)open, including auto-reconnects, so the consumer can
+   *  resync after a gap (the stream only carries future changes). */
+  onOpen?: () => void;
+  /** Called when the stream errors; the EventSource then auto-reconnects. */
+  onError?: () => void;
+}
+
+/** EventSourceLike is the minimal surface used here, so the stream can be tested
+ *  without a DOM EventSource (the default factory adapts a real one). */
+export interface EventSourceLike {
+  addEventListener: (type: string, listener: (event: MessageEvent) => void) => void;
+  close: () => void;
+}
+
+/** EventSourceFactory builds an EventSourceLike for a URL. */
+export type EventSourceFactory = (url: string) => EventSourceLike;
+
+export interface StatusStream {
+  /** Closes the stream and stops reconnection. */
+  close: () => void;
+}
+
+const defaultFactory: EventSourceFactory = (url) => {
+  const es = new EventSource(url);
+  return {
+    addEventListener: (type, listener) => {
+      es.addEventListener(type, listener as unknown as EventListener);
+    },
+    close: () => {
+      es.close();
+    },
+  };
+};
+
+/** connectStatusStream opens the status stream at path and fans events out to
+ *  cb. make defaults to a real EventSource; tests inject a fake. */
+export function connectStatusStream(
+  path: string,
+  cb: StatusStreamCallbacks,
+  make: EventSourceFactory = defaultFactory,
+): StatusStream {
+  const es = make(path);
+  const { onOpen, onError } = cb;
+  if (onOpen) {
+    es.addEventListener("open", () => {
+      onOpen();
+    });
+  }
+  es.addEventListener("message", (event) => {
+    const raw: unknown = event.data;
+    if (typeof raw !== "string") {
+      return; // non-text frame, ignore
+    }
+    let status: SessionStatus;
+    try {
+      status = JSON.parse(raw) as SessionStatus;
+    } catch {
+      return; // skip a malformed frame, keep the stream
+    }
+    cb.onStatus(status);
+  });
+  if (onError) {
+    es.addEventListener("error", () => {
+      onError();
+    });
+  }
+  return {
+    close: () => {
+      es.close();
+    },
+  };
+}

package/src/store.ts

@@ -183,6 +183,12 @@ export class LineStore {
       return;
     }
     this.exitAltIfNeeded();
+    if (msg.scrollbackCleared) {
+      // ED3 (erase scrollback): the app cleared its saved lines (kiro-cli does
+      // this on every resize redraw). Drop our matching history below the live
+      // window so the previous frame doesn't accumulate beneath the new one.
+      this.dropHistoryBelow(msg.base);
+    }
     this.updateWindow(msg);
     for (const y of msg.changed) {
       const row = msg.rows[y];
@@ -190,6 +196,7 @@ export class LineStore {
         this.applyLine(msg.base + y, row);
       }
     }
+    this.truncateBelowWindow();
   }
 
   /** Apply a decoded scroll/history frame: each line at firstIndex + i. */
@@ -297,6 +304,70 @@ export class LineStore {
     this.enforceCap();
   }
 
+  // dropHistoryBelow evicts all retained lines with an absolute index below
+  // `base` — the scrollback history under the live window. Called when the
+  // server signals ED3 (erase scrollback): an inline TUI (kiro-cli) clears its
+  // saved lines on every resize redraw, so the client drops its matching
+  // history to stop the previous frame accumulating beneath the new one. Window
+  // rows (>= base) are kept and refreshed by the frame carrying the signal.
+  // everEvictedThrough is left untouched: the app discarded the lines
+  // deliberately (not a cap trim), so no "earlier output trimmed" marker fits.
+  private dropHistoryBelow(base: number): void {
+    if (this.oldest < 0 || this.oldest >= base) {
+      return;
+    }
+    for (let abs = this.oldest; abs < base; abs++) {
+      if (this.lines.delete(abs)) {
+        this.evicted.add(abs);
+        this.dirty.delete(abs);
+      }
+    }
+    if (base > this.highest) {
+      this.oldest = -1;
+      this.highest = -1;
+    } else {
+      this.oldest = base;
+    }
+  }
+
+  // truncateBelowWindow evicts every retained line past the window's bottom row.
+  // The window's bottom row is the most recent line in the terminal, so no line
+  // can exist at a higher absolute index. A resize that SHRINKS the screen (the
+  // iOS soft keyboard opening) moves the window bottom up while the taller
+  // screen's former bottom rows stay in the store at higher indices — stranded
+  // below the live window. Cap eviction only trims the top/oldest, so nothing
+  // removes them: they linger as phantom blank rows beneath the real content, an
+  // "empty" region the user can scroll into and the reason the content never
+  // appears to shrink to fit on a short viewport. Evicting them keeps the tail
+  // invariant (highest === window bottom); it is the tail-side complement to the
+  // top-side cap eviction.
+  private truncateBelowWindow(): void {
+    if (this.highest < 0) {
+      return;
+    }
+    const windowBottom = this.win.base + this.win.height - 1;
+    if (this.highest <= windowBottom) {
+      return;
+    }
+    for (let abs = windowBottom + 1; abs <= this.highest; abs++) {
+      if (this.lines.delete(abs)) {
+        this.evicted.add(abs);
+        this.dirty.delete(abs);
+      }
+    }
+    // New highest is the greatest retained index at or below the window bottom.
+    let h = windowBottom;
+    while (h >= this.oldest && !this.lines.has(h)) {
+      h--;
+    }
+    if (h >= this.oldest) {
+      this.highest = h;
+    } else {
+      this.highest = -1;
+      this.oldest = -1;
+    }
+  }
+
   private enforceCap(): void {
     while (this.lines.size > this.maxLines && this.oldest >= 0 && this.oldest < this.highest) {
       const victim = this.oldest;

package/src/types.ts

@@ -59,6 +59,13 @@ export interface ScreenMessage {
   cursorBlink?: boolean;
   /** True if the server emitted a BEL since the last screen update. */
   bell?: boolean;
+  /**
+   * 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
+   * discard the previous frame; honoring it stops stale frames accumulating.
+   */
+  scrollbackCleared?: boolean;
   /** Server-confirmed bytesReceived for the input ACK protocol. */
   inputAck?: number;
 }
@@ -122,6 +129,8 @@ export interface ModesMessage {
   focusReporting: boolean;
   /** DEC 5: screen is in reverse-video mode. */
   reverseVideo: boolean;
+  /** DEC 1016: mouse reports carry pixel coordinates instead of cell coords. */
+  mousePixels: boolean;
   /** Mouse tracking: 0=off, 1000=normal, 1002=button-event, 1003=any-event. */
   mouseMode: number;
   /** Server-confirmed bytesReceived for the input ACK protocol. */
@@ -141,13 +150,23 @@ export interface TitleMessage {
   inputAck?: number;
 }
 
+/**
+ * Clipboard text an app copied via OSC 52 (`OSC 52 ; c ; <base64> ST`). The
+ * client writes it to the system clipboard. Set-only: the query form is
+ * refused server-side, so this message never carries a read request.
+ */
+export interface ClipboardMessage {
+  /** Discriminator — always `"clipboard"`. */
+  type: "clipboard";
+  /** Text to place on the system clipboard. */
+  text: string;
+  /** Server-confirmed bytesReceived for the input ACK protocol. */
+  inputAck?: number;
+}
+
 /** Discriminated union of all messages the server can send to the client. */
 export type ServerMessage =
-  | ScreenMessage
-  | ScrollMessage
-  | ResumeAckMessage
-  | ModesMessage
-  | TitleMessage;
+  ScreenMessage | ScrollMessage | ResumeAckMessage | ModesMessage | TitleMessage | ClipboardMessage;
 
 /**
  * Discriminated union of all control messages the client can send to the

package/src/wire-binary.ts

@@ -10,6 +10,7 @@ import type {
   ResumeAckMessage,
   ModesMessage,
   TitleMessage,
+  ClipboardMessage,
   ServerMessage,
 } from "./types.js";
 
@@ -20,6 +21,7 @@ const MSG_RESUME_ACK = 2;
 const MSG_MODES = 3;
 const MSG_TITLE = 4;
 const MSG_PONG = 5;
+const MSG_CLIPBOARD = 6;
 
 /**
  * Wire protocol version. Sent by the client in the `resume` control message so
@@ -35,6 +37,7 @@ const MODE_FLAG_MOUSE_SGR = 4;
 const MODE_FLAG_FOCUS_REPORTING = 8;
 const MODE_FLAG_APP_KEYPAD = 16;
 const MODE_FLAG_REVERSE_VIDEO = 32;
+const MODE_FLAG_MOUSE_PIXELS = 64;
 
 class Cursor {
   view: DataView;
@@ -177,6 +180,7 @@ function decodeWireBinaryInner(buf: ArrayBuffer): ServerMessage | null {
     const bell = (cursorFlags & 2) !== 0;
     const cursorBlink = (cursorFlags & 4) !== 0;
     const altActive = (cursorFlags & 8) !== 0;
+    const scrollbackCleared = (cursorFlags & 16) !== 0;
     // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment -- pre-allocated array filled below
     const rows: WireRun[][] = new Array(screenHeight);
     // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment -- pre-allocated array filled below
@@ -197,6 +201,7 @@ function decodeWireBinaryInner(buf: ArrayBuffer): ServerMessage | null {
       cursorHidden,
       cursorBlink,
       bell,
+      scrollbackCleared,
       inputAck,
     };
     return msg;
@@ -223,6 +228,7 @@ function decodeWireBinaryInner(buf: ArrayBuffer): ServerMessage | null {
       mouseSGR: (flags & MODE_FLAG_MOUSE_SGR) !== 0,
       focusReporting: (flags & MODE_FLAG_FOCUS_REPORTING) !== 0,
       reverseVideo: (flags & MODE_FLAG_REVERSE_VIDEO) !== 0,
+      mousePixels: (flags & MODE_FLAG_MOUSE_PIXELS) !== 0,
       mouseMode,
       inputAck,
     };
@@ -234,6 +240,12 @@ function decodeWireBinaryInner(buf: ArrayBuffer): ServerMessage | null {
     const msg: TitleMessage = { type: "title", title, inputAck };
     return msg;
   }
+  if (msgType === MSG_CLIPBOARD) {
+    const textLen = c.u16();
+    const text = c.utf8(textLen);
+    const msg: ClipboardMessage = { type: "clipboard", text, inputAck };
+    return msg;
+  }
   if (msgType === MSG_PONG) {
     // Liveness pong: no payload to deliver. The message listener already
     // refreshed the activity clock on arrival, so there is nothing to do