@cplieger/web-terminal-engine 1.4.0 → 2.0.0

package/jsr.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/web-terminal-engine",
-  "version": "1.4.0",
+  "version": "2.0.0",
   "type": "module",
   "scripts": {
     "typecheck": "tsgo -p tsconfig.json",
@@ -18,7 +18,7 @@
     "fast-check": "4.8.0",
     "happy-dom": "20.10.6",
     "pngjs": "7.0.0",
-    "prettier": "3.9.3",
+    "prettier": "3.9.4",
     "typescript": "6.0.3",
     "typescript-eslint": "8.62.1",
     "vitest": "4.1.9"

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") {
@@ -549,7 +645,7 @@ export function connect(): void {
         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).
@@ -557,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/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

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();
+    },
+  };
+}