@cplieger/web-terminal-engine 5.2.0 → 6.0.0

package/src/status-stream.ts

@@ -139,6 +139,11 @@ export interface EventSourceLike {
 /** EventSourceFactory builds an EventSourceLike for a URL. */
 export type EventSourceFactory = (url: string) => EventSourceLike;
 
+/** StatusStream is the handle connectStatusStream returns: the consumer's only
+ *  hold on a live stream, and close is the whole of it — everything else the
+ *  stream does is reported through the callbacks. Closing is final and there is
+ *  no reopen; it cancels a scheduled reconnect as well as the current stream, so
+ *  a consumer that wants status back calls connectStatusStream again. */
 export interface StatusStream {
   /** Closes the stream and stops reconnection. */
   close: () => void;

package/src/store.ts

@@ -309,6 +309,36 @@ function rowEqual(a: WireRun[], b: WireRun[]): boolean {
   return true;
 }
 
+/**
+ * The client's model of one terminal: lines keyed by absolute index, the live
+ * screen window sliding along the tail, and the change set a renderer drains each
+ * frame. Holds no DOM and reads no globals, so a consumer may own several (one
+ * per tab) and bind whichever is visible.
+ *
+ * Applying is idempotent by absolute index, which is what makes re-delivery —
+ * resume replay, a doubled frame from a zombie socket — incapable of duplicating
+ * a row. The apply methods enforce the store's invariants themselves and refuse
+ * rather than throw: a frame that violates one is dropped, so a malformed or
+ * misordered stream degrades to missing content, never to an exception in the
+ * middle of a render. A drop is not reported either, so a caller that needs to
+ * know what the store holds asks it (oldestIndex, highestIndex, retainedRanges)
+ * instead of tracking what it sent.
+ *
+ * What the caller must hold up:
+ *
+ * - Feed the store every frame the server sends, in arrival order, and pass
+ *   `viewportAbs`/`following` where a method asks for them. The store never
+ *   infers where the reader is; the renderer is the only layer that knows.
+ * - Drain with drainChanges once per frame and apply the result. Nothing is
+ *   re-reported, so a skipped drain loses the notification, not the content.
+ * - Treat every reader (getLine, forEachLine, getAltRows) as a view onto live
+ *   state: the runs are the store's own, valid until the next apply, and are not
+ *   to be mutated.
+ *
+ * Residency is a HISTORY budget floored at the live window, so a small cap keeps
+ * the full screen and simply retains no scrollback; the constructor documents the
+ * difference between supplying one and letting the engine choose.
+ */
 export class LineStore {
   private lines = new Map<number, WireRun[]>();
   private oldest = -1; // lowest retained absolute index (-1 = empty)
@@ -1951,7 +1981,7 @@ export class LineStore {
       // `cursor > winBottom` cannot hold there either. That is the ONLY thing
       // holding when the target is 0, which `new LineStore(0)` produces
       // (`evictionBatch(0)` is 1, so `target = 0 - 1 + 1`; the bare
-      // constructor accepts 0, unlike `render.init` and `fromSnapshot`, which
+      // constructor accepts 0, unlike `createRenderer` and `fromSnapshot`, which
       // both require a positive integer) — a reason to leave that conjunct
       // alone.
       // Advance to the lowest remaining key above the victim. Contiguous

package/src/terminal.ts

@@ -0,0 +1,135 @@
+import { type Connection, type ConnectionCallbacks, createConnection } from "./connection.js";
+import { createModeState, type ModeSnapshot, type ModeState } from "./modes.js";
+import { createMouseController, type MouseController } from "./mouse.js";
+import { createRenderer, type Renderer } from "./render.js";
+import { createScrollController, type ScrollController } from "./scroll.js";
+
+/** What `createTerminalEngine` binds to and forwards to its five parts. */
+export interface TerminalEngineOptions {
+  /** Inner element that receives the row children. */
+  output: HTMLElement;
+  /** Outer scroll container; also the mouse listeners' element. */
+  termWrap: HTMLElement;
+  /**
+   * The consumer's connection callbacks. `onMessage` receives every frame after
+   * the engine has routed `screen`, `scroll` and `modes` frames to its renderer.
+   */
+  callbacks: ConnectionCallbacks;
+  /** WebSocket endpoint path (default "/ws"). */
+  wsPath?: string;
+  /** The `sessionStorage` key of the unmanaged session id; distinct per engine on one page. */
+  sessionIdKey?: string;
+  /** Retained-line cap for the renderer's implicit store; see `RendererOptions.maxLines`. */
+  maxLines?: number;
+  onCursorMove?: () => void;
+  onUserScrollChange?: (scrolledUp: boolean) => void;
+  /** Initial mode state (default `POWER_ON_MODES`). */
+  initialModes?: Readonly<ModeSnapshot>;
+}
+
+/** One terminal: a renderer, a scroll controller, a connection, a mouse controller and a mode state. */
+export interface TerminalEngine {
+  readonly renderer: Renderer;
+  readonly scroll: ScrollController;
+  readonly connection: Connection;
+  readonly mouse: MouseController;
+  readonly modes: ModeState;
+  /** Disposes the five parts in reverse build order; each part is idempotent, so this is too. */
+  dispose(): void;
+}
+
+/**
+ * Composes the five factories into one engine that shares nothing with another
+ * engine on the same page. It does not connect and does not measure fonts: call
+ * `engine.renderer.updateFontMetrics()` when the font is ready and
+ * `engine.connection.connect()` to start. Throws, holding nothing, when a part
+ * cannot be built.
+ */
+export function createTerminalEngine(opts: TerminalEngineOptions): TerminalEngine {
+  // `renderer` and `connection` are assigned below; every closure that reads them
+  // runs from a DOM event or a socket message, none of which can fire before this
+  // function returns.
+  let renderer: Renderer;
+  let connection: Connection;
+  const built: { dispose(): void }[] = [];
+  let modes: ModeState;
+  let scroll: ScrollController;
+  let mouse: MouseController;
+  try {
+    modes = createModeState(opts.initialModes);
+    built.push(modes);
+    scroll = createScrollController({
+      scrollEl: opts.termWrap,
+      ...(opts.onUserScrollChange === undefined
+        ? {}
+        : { onUserScrollChange: opts.onUserScrollChange }),
+      onScrollPosition: () => {
+        renderer.handleScrollPosition();
+      },
+    });
+    built.push(scroll);
+    renderer = createRenderer({
+      output: opts.output,
+      termWrap: opts.termWrap,
+      scroll,
+      modes,
+      ...(opts.onCursorMove === undefined ? {} : { onCursorMove: opts.onCursorMove }),
+      ...(opts.maxLines === undefined ? {} : { maxLines: opts.maxLines }),
+      requestHistory: (from, max) => connection.requestHistory(from, max),
+      historyBudget: () => connection.historyBudget(),
+    });
+    built.push(renderer);
+    mouse = createMouseController({
+      modes,
+      termElement: () => opts.termWrap,
+      gridElement: () => opts.output,
+      cellSize: () => renderer.cellSize(),
+      gridSize: () => renderer.gridSize(),
+      sendReport: (data) => connection.sendEphemeral(data),
+    });
+    built.push(mouse);
+    const consumer = opts.callbacks;
+    const routed: ConnectionCallbacks = {
+      ...consumer,
+      onMessage(msg) {
+        if (msg.type === "screen") {
+          renderer.handleScreen(msg);
+        } else if (msg.type === "scroll") {
+          renderer.handleScroll(msg);
+        } else if (msg.type === "modes") {
+          renderer.updateReverseVideo();
+        }
+        consumer.onMessage(msg);
+      },
+    };
+    // The last acquisition: nothing after it can throw, so the connection needs
+    // no entry in `built`.
+    connection = createConnection({
+      renderer,
+      modes,
+      mouse,
+      callbacks: routed,
+      ...(opts.wsPath === undefined ? {} : { wsPath: opts.wsPath }),
+      ...(opts.sessionIdKey === undefined ? {} : { sessionIdKey: opts.sessionIdKey }),
+    });
+  } catch (err) {
+    for (const part of built.reverse()) {
+      part.dispose();
+    }
+    throw err;
+  }
+  return {
+    renderer,
+    scroll,
+    connection,
+    mouse,
+    modes,
+    dispose(): void {
+      connection.dispose();
+      mouse.dispose();
+      renderer.dispose();
+      scroll.dispose();
+      modes.dispose();
+    },
+  };
+}

package/src/toolbar.ts

@@ -1,25 +1,18 @@
 // 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.
+// terminal send sink. The wire encodings live in keyboard.ts; this module
+// consumes its logical-key homes (plainCursorKeySeq, plainEscapeSeq,
+// kittyCtrlCharSeq, ctrlByteFor) so the toolbar cannot drift from the
+// physical-key path, which toolbar.test.ts pins byte-for-byte.
 
 import {
   ctrlByteFor,
+  type KeyboardModes,
   kittyCtrlCharSeq,
   kittyDisambiguateActive,
   plainCursorKeySeq,
   plainEscapeSeq,
 } from "./keyboard.js";
-import { isApplicationCursor } from "./modes.js";
 
 /**
  * Default DOM ids for the on-screen mobile keyboard toolbar buttons,
@@ -67,6 +60,11 @@ export interface BindMobileToolbarOptions {
    * to the same `send`.
    */
   readonly send: (bytes: string) => void;
+  /**
+   * The mode state of the terminal the toolbar types into, read at each press:
+   * the arrow and Escape bytes depend on its kitty and DECCKM bits.
+   */
+  readonly modes: KeyboardModes;
   /** Optional id overrides. Missing keys fall back to defaults. */
   readonly ids?: MobileToolbarIds;
   /**
@@ -79,14 +77,11 @@ export interface BindMobileToolbarOptions {
 /** 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.
+   * Apply sticky-Ctrl to a piece of input text. Not armed: `text` unchanged.
+   * Armed and one character: the matching Ctrl byte (`ctrlByteFor`), or the
+   * character when none exists. Armed and longer (paste, IME commit): `text`
+   * unchanged, since Ctrl over a multi-character string would garble it.
+   * Every armed call disarms.
    */
   applyStickyCtrl(text: string): string;
   /** Programmatically arm/disarm Ctrl. Updates the toolbar button visuals (`.armed` class + `aria-pressed`) + fires `onCtrlChange`. */
@@ -98,17 +93,12 @@ export interface MobileToolbarController {
 }
 
 /**
- * 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).
+ * 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, through the shared
+ * encodings in keyboard.ts.
  */
 export function bindMobileToolbar(opts: BindMobileToolbarOptions): MobileToolbarController {
   const ids = { ...DEFAULT_TOOLBAR_IDS, ...opts.ids };
@@ -134,18 +124,12 @@ export function bindMobileToolbar(opts: BindMobileToolbarOptions): MobileToolbar
       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.
+      // Repaint without notifying, so onCtrlChange stays edge-triggered.
       paintCtrlBtn(on);
       return;
     }
@@ -156,10 +140,12 @@ export function bindMobileToolbar(opts: BindMobileToolbarOptions): MobileToolbar
 
   // 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());
+    return plainCursorKeySeq(
+      letter,
+      kittyDisambiguateActive(opts.modes),
+      opts.modes.isApplicationCursor(),
+    );
   }
 
   // Listener registry so dispose() can detach them all.
@@ -225,7 +211,7 @@ export function bindMobileToolbar(opts: BindMobileToolbarOptions): MobileToolbar
     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()));
+    opts.send(plainEscapeSeq(kittyDisambiguateActive(opts.modes)));
   });
 
   function applyStickyCtrl(text: string): string {
@@ -238,7 +224,7 @@ export function bindMobileToolbar(opts: BindMobileToolbarOptions): MobileToolbar
       // 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()) {
+      if (kittyDisambiguateActive(opts.modes)) {
         const seq = kittyCtrlCharSeq(text);
         if (seq !== null) {
           return seq;