@cplieger/web-terminal-engine 5.2.0 → 5.3.0

package/jsr.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/web-terminal-engine",
-  "version": "5.2.0",
+  "version": "5.3.0",
   "license": "MPL-2.0",
   "exports": {
     ".": "./src/index.ts"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/web-terminal-engine",
-  "version": "5.2.0",
+  "version": "5.3.0",
   "type": "module",
   "scripts": {
     "typecheck": "tsc -p tsconfig.json",
@@ -17,18 +17,18 @@
     "@stryker-mutator/vitest-runner": "10.0.0",
     "@types/pngjs": "6.0.5",
     "@typescript/native": "npm:typescript@7.0.2",
-    "@vitest/browser": "5.0.0",
-    "@vitest/browser-playwright": "5.0.0",
-    "@vitest/coverage-v8": "5.0.0",
+    "@vitest/browser": "5.0.1",
+    "@vitest/browser-playwright": "5.0.1",
+    "@vitest/coverage-v8": "5.0.1",
     "esbuild": "0.28.2",
     "eslint": "10.10.0",
-    "fast-check": "4.9.0",
+    "fast-check": "4.10.1",
     "playwright": "1.63.0",
     "pngjs": "7.0.0",
-    "prettier": "3.9.6",
+    "prettier": "3.9.7",
     "typescript": "npm:@typescript/typescript6@6.0.2",
     "typescript-eslint": "8.70.0",
-    "vitest": "5.0.0"
+    "vitest": "5.0.1"
   },
   "overrides": {
     "qs": "^6.15.2"

package/src/connection.ts

@@ -416,8 +416,18 @@ function loadOrCreateSessionId(): string {
   }
 }
 
-// Exported for unit testing of the RNG fallback. Not part of the
-// stable client API surface; callers use loadOrCreateSessionId.
+/**
+ * generateSessionId mints a fresh session id: a `crypto.randomUUID` where that
+ * exists, otherwise 16 CSPRNG bytes as hex (128 bits, the fallback for a
+ * non-secure-context origin). Throws when neither is available rather than
+ * falling back to a weaker source — the caller gets no id, not a guessable one.
+ *
+ * Never returns an id already in use: nothing here reads storage, so a caller
+ * that wants the tab's existing session must go through loadOrCreateSessionId.
+ *
+ * Exported for unit testing of the RNG fallback. Not part of the
+ * stable client API surface; callers use loadOrCreateSessionId.
+ */
 export function generateSessionId(): string {
   if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
     return crypto.randomUUID();
@@ -438,6 +448,30 @@ export function generateSessionId(): string {
   throw new Error("vterm: no cryptographically secure RNG available for session id");
 }
 
+/**
+ * Callbacks is everything this module needs from its consumer, handed to init
+ * once. Four members are required because no other layer can answer them: where
+ * a decoded frame goes (onMessage), the two socket-lifecycle edges the UI has to
+ * reflect (onOpen, onClose), and the terminal's current geometry (computeSize,
+ * which must return integer cols/rows > 0 — the server FLOORS an out-of-range
+ * resize rather than dropping it).
+ *
+ * The optional members are two different kinds. The notifications
+ * (onConnecting, onOutboxFull, onProcessExit, onServerRestart, the two wire
+ * callbacks) each change what the module DOES when wired, and every one says how
+ * in its own comment; absence is the documented legacy treatment, never a
+ * failure. The resume and history members (getHaveThrough, getReplayMax,
+ * onResumeTransition, onResumeBounds, onHistoryReply, noteSolicited,
+ * clearSolicited, onHistoryRetry) are engine-owned — supply nothing and the
+ * renderer answers them itself (engineDefaults below). getReplayMax is the one
+ * override that is expected.
+ *
+ * Every member is called, never captured: the module reads the current one at
+ * each event, so an implementation may depend on state that changes between
+ * calls (a bound store, a viewport in flight). A consumer callback that throws
+ * propagates out of the module's handler, with the single exception of
+ * initialSize, which is isolated (readInitialSize) because it runs mid-open.
+ */
 export interface Callbacks {
   onMessage(msg: ServerMessage): void;
   onOpen(): void;
@@ -603,6 +637,17 @@ function engineDefaults(): Partial<Callbacks> {
   };
 }
 
+/**
+ * init installs the consumer's callbacks and the WS path. It must run before
+ * connect/setSession, and before any sendBinary the consumer expects to reach a
+ * server — the module holds one set of callbacks for the whole page, so a second
+ * call REPLACES them rather than adding to them.
+ *
+ * `wsPath` is read here only, and only when present: a later init that omits it
+ * leaves the path an earlier one set, so an established socket's endpoint is not
+ * silently reinterpreted. Every other member is looked up per event, so a
+ * replacement takes effect on the next one without reconnecting.
+ */
 export function init(callbacks: Callbacks): void {
   // Consumer last: an explicit member wins, an absent one gets the engine's own.
   // The alternative, leaving them absent, is not neutral — the resume send reads
@@ -788,6 +833,19 @@ function readInitialSize(): { cols: number; rows: number } | null {
   return { cols: size.cols, rows: size.rows };
 }
 
+/**
+ * sendResize measures the terminal through Callbacks.computeSize and announces
+ * it to the server. Call it whenever the geometry may have changed (a window
+ * resize, a font-metric update, the soft keyboard opening); it is cheap to call
+ * speculatively because a size equal to the last one SENT is dropped, and the
+ * consumer therefore needs no dedup of its own.
+ *
+ * A no-op when no socket is connected, and the size is not queued for later. A
+ * fresh socket clears the dedup baseline as it opens, so the consumer's next
+ * call after a reconnect always goes out; a consumer that can measure itself at
+ * that moment should wire Callbacks.initialSize instead, which is announced
+ * before the resume and therefore brings the snapshot back at this geometry.
+ */
 export function sendResize(): void {
   if (connState.status !== "connected" || !cb) {
     return;
@@ -988,6 +1046,21 @@ function teardown(): void {
   connState = { status: "disconnected" };
 }
 
+/**
+ * reconnectNow replaces whatever socket exists with a fresh one immediately,
+ * skipping the backoff schedule. This is the call for an event that says the
+ * transport may be stale even though it does not look it — a tab becoming
+ * visible, a pageshow, a device waking — because a socket the OS froze during
+ * sleep keeps reading OPEN while frames printed meanwhile never arrive.
+ *
+ * Safe to call in any state and at any rate: the resume protocol aligns by
+ * absolute line index, so reconnecting over a healthy socket costs one handshake
+ * and delivers no duplicate output. Per-session resume state (outbox, byte
+ * counters) survives, so unacked input is retransmitted rather than dropped.
+ *
+ * Refused, silently, once the peer has been ruled wire-incompatible: that
+ * verdict is terminal for the page and only an explicit disconnect clears it.
+ */
 export function reconnectNow(): void {
   if (connState.status === "incompatible") {
     return;
@@ -1320,6 +1393,22 @@ export function disconnect(): void {
   teardown();
 }
 
+/**
+ * connect opens the WebSocket and starts the module: after init, this is the one
+ * call a consumer needs, and everything that follows (backoff reconnects, the
+ * heartbeat, resume) is driven from here. It returns as soon as the socket is
+ * created — readiness is reported through Callbacks.onOpen, and a connect that
+ * never opens is failed by a 10s timeout that reports onClose and schedules a
+ * retry, so a caller never has to time it out itself.
+ *
+ * At most one socket exists per module, whatever the call pattern: an existing
+ * connecting/connected socket is aborted and closed, and a backoff reconnect
+ * already scheduled is cancelled, so a stray second call cannot leave two
+ * sockets delivering the same session's output twice. Resume state is untouched,
+ * so the new socket picks the session up where the old one left it.
+ *
+ * A no-op once the peer has been ruled wire-incompatible.
+ */
 export function connect(): void {
   if (connState.status === "incompatible") {
     return;

package/src/index.ts

@@ -1,13 +1,111 @@
 export * from "./types.js";
 export { LineStore } from "./store.js";
 export type { WindowState, StoreChanges, StoreSnapshot } from "./store.js";
+/**
+ * The DOM renderer: it owns a `LineStore` of absolute-index lines and reflects
+ * it to one `div.term-row` per line inside a natively-scrolled container, so
+ * there is no live-zone/scrollback split to reconcile. Reach for it to paint
+ * decoded frames (`handleScreen`, `handleScroll`), to measure the grid
+ * (`updateFontMetrics`, `computeSize`, `getCursorPx`), and to swap stores on a
+ * tab switch (`bind`).
+ *
+ * `init` must run once against the two elements before any frame is applied,
+ * and it always installs a fresh implicit store — so a consumer that manages
+ * its own stores binds AFTER init, never before. `getHighestIndex` reports how
+ * far the store's content reaches and is NOT a resume claim; a transport asks
+ * `getReplayBoundary` for that, and wiring the former is the defect the latter
+ * exists to prevent.
+ */
 export * as render from "./render.js";
 export type { ViewMemory } from "./render.js";
+/**
+ * Key encoding, and nothing else: `mapKeyboardEvent` turns a browser
+ * `KeyboardEvent` into either the bytes a PTY expects or a local action, and
+ * the paste helpers (`bracketTextForPaste`, `prepareTextForTerminal`) do the
+ * same for text. Reach for it when your own input surface — a hidden textarea,
+ * an IME composition, a paste handler — has an event and needs the wire form.
+ *
+ * It touches no DOM and sends nothing: the caller delivers the bytes, and the
+ * `scroll-up` / `scroll-down` results carry no bytes at all because local
+ * scrollback navigation is the consumer's to perform. Mode state arrives as an
+ * explicit `KeyboardModes` argument rather than being read from a global, so a
+ * tabbed shell encodes against the active session's modes.
+ */
 export * as keyboard from "./keyboard.js";
+/**
+ * The on-screen mobile key toolbar — the one DOM widget in the engine.
+ * `bindMobileToolbar` wires an existing container's buttons (Ctrl, arrows, Tab,
+ * Enter, Esc, a collapse toggle) to a send sink and returns a controller owning
+ * sticky-Ctrl state and tear-down. Reach for it on a touch UI, where the keys a
+ * physical keyboard supplies have to be painted.
+ *
+ * The consumer supplies the markup; the module only looks buttons up by id
+ * within the container, so a missing button is skipped rather than fatal.
+ * Sticky Ctrl only takes effect on text routed through
+ * `controller.applyStickyCtrl` — the toolbar cannot see keystrokes it did not
+ * emit. Its arrow and Escape bytes come from `keyboard`'s exported logical-key
+ * encodings, so they cannot drift from the physical-key path.
+ */
 export * as toolbar from "./toolbar.js";
+/**
+ * The scroll controller: the single owner of the scroll container's
+ * `scrollTop`, holding one piece of state — whether the viewport is following
+ * the tail or holding a reading position — derived from scroll events alone.
+ * Reach for it to `init` the container and for consumer-facing controls: a
+ * jump-to-bottom button (`scrollToBottom`), and `isUserScrolledUp` to decide
+ * whether new output deserves an affordance.
+ *
+ * Everything else here is the renderer's to call around its own DOM mutations
+ * (`stickToBottom`, `adjustForContentShift`, `noteContentShrink`). A consumer
+ * that writes `scrollTop` directly is competing with this module for the same
+ * value, which is how a held reading position gets lost.
+ */
 export * as scroll from "./scroll.js";
+/**
+ * The DEC private-mode mirror for the ACTIVE session — bracketed paste,
+ * application cursor and keypad, mouse tracking and its encoding, focus
+ * reporting, reverse video, kitty keyboard flags. Reach for it to read what the
+ * application has turned on, most often to decide whether a paste needs
+ * bracketing or whether a mouse gesture belongs to the terminal at all.
+ *
+ * It is a module singleton with one writer: `connection` applies every inbound
+ * modes frame and, in a tabbed shell, restores the target session's snapshot
+ * inside `setSession`. A consumer that calls `setModes` is racing that writer.
+ * Values lag the server by the one frame in flight, and an unseen session
+ * starts at `POWER_ON_MODES`, where bracketed paste is already ON so the first
+ * paste cannot be delivered as typed input.
+ */
 export * as modes from "./modes.js";
+/**
+ * Mouse input for the terminal: SGR 1006 encoding (`encodeSGR`) plus `init`,
+ * which attaches pointer and wheel listeners to an element and returns an
+ * idempotent disposer. Reach for it when the terminal element should forward
+ * clicks, drags and wheel ticks to the application rather than the page.
+ *
+ * The listeners gate on the mode state, so they are inert until the
+ * application enables tracking — which is also why selection and page
+ * scrolling keep working in a normal shell. Reports are best-effort: one
+ * describes a screen a resume may since have repainted, so a refused report is
+ * forgotten rather than retried. Focus is not mouse input and lives in
+ * `connection.setClientFocus`.
+ */
 export * as mouse from "./mouse.js";
+/**
+ * The client-to-server transport. It owns the socket, the jittered
+ * exponential-backoff reconnect, and the resume/inputAck layer that makes input
+ * survive a reconnect: a bounded outbox retransmitted against the server's
+ * acked byte count, resume by absolute index, and server-restart detection via
+ * the boot epoch. Reach for it to `init` the callbacks, `connect`, send input
+ * (`sendBinary`), announce geometry (`sendResize`), and switch sessions
+ * (`setSession`).
+ *
+ * It decodes frames and applies mode changes itself, so a consumer's
+ * `onMessage` only has to route screen and scroll to the renderer. Supply as
+ * few of the resume and history callbacks as possible: an omitted one gets the
+ * renderer's own answer, read per resume rather than captured, and overriding
+ * one means deciding a local fact on the engine's behalf — `getReplayMax`, how
+ * much history the client keeps resident, is the one override that is expected.
+ */
 export * as connection from "./connection.js";
 export { decodeWireBinary } from "./wire-binary.js";
 export {

package/src/render.ts

@@ -1662,6 +1662,19 @@ function flushRenderInner(): void {
 // scrollTop belongs to `.term`, so any ABSOLUTE pixel value would need the
 // rowTopInTermWrap conversion and would be one padding off without it. A
 // difference cancels the space out.
+
+/**
+ * A saved reading position, in the only terms that survive the content growing
+ * underneath it: which line the reader had at the top of the viewport, where on
+ * screen that row sat, and whether they were following the tail.
+ *
+ * Effectively opaque to the consumer — read one out of the renderer and hand the
+ * same value back to restore it; the fields are documented because JSR publishes
+ * them, not because a caller should compute one. A memory is only meaningful to
+ * the store it was taken from, since `abs` names a line in THAT index space, and
+ * a restore is re-asserted until the named row has been built rather than
+ * applied once.
+ */
 export interface ViewMemory {
   /** Absolute line index of the content row at the viewport top. */
   abs: number;

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)