@cplieger/web-terminal-engine 1.2.0

package/src/modes.ts

@@ -0,0 +1,95 @@
+// Current DEC private mode state, as last announced by the server via
+// a wireMsgModes frame. Used by:
+//   - keyboard.ts arrow-key encoder: emits SS3 (ESC O letter) when
+//     applicationCursor is true, CSI (ESC [ letter) otherwise.
+//   - paste handling: wraps in \e[200~..\e[201~ only when
+//     bracketedPaste is on; otherwise sends raw text.
+//   - mouse.ts: encodes mouse events only when mouseMode > 0.
+//   - focus reporting: sends ESC[I / ESC[O when focusReporting is on.
+//
+// Defaults: bracketedPaste starts true because most modern shells
+// (bash 4.4+, zsh, fish) enable it immediately on startup via
+// CSI ?2004h. Starting false would cause the first paste before the
+// server's modes frame arrives to be sent un-bracketed, which shells
+// interpret as typed input (potentially executing pasted commands
+// character-by-character). applicationCursor starts false (normal
+// mode) because that's the VT100 power-on default.
+
+let bracketedPaste = true;
+let applicationCursor = false;
+let applicationKeypad = false;
+let mouseMode = 0; // 0=off, 1000=normal, 1002=button-event, 1003=any-event
+let mouseSGR = false;
+let focusReporting = false;
+let reverseVideo = false;
+
+/**
+ * Update the cached mode state. Called by the consumer whenever the server
+ * sends a `ModesMessage`. Pass-through arguments are optional so older
+ * server builds that don't include all fields don't reset them to defaults.
+ */
+export function setModes(
+  bracketed: boolean,
+  appCursor: boolean,
+  mSGR?: boolean,
+  focus?: boolean,
+  mMode?: number,
+  appKeypad?: boolean,
+  revVideo?: boolean,
+): void {
+  bracketedPaste = bracketed;
+  applicationCursor = appCursor;
+  if (mSGR !== undefined) {
+    mouseSGR = mSGR;
+  }
+  if (focus !== undefined) {
+    focusReporting = focus;
+  }
+  if (mMode !== undefined) {
+    mouseMode = mMode;
+  }
+  if (appKeypad !== undefined) {
+    applicationKeypad = appKeypad;
+  }
+  if (revVideo !== undefined) {
+    reverseVideo = revVideo;
+  }
+}
+
+/** True when the server has DEC 2004 (bracketed paste) enabled. */
+export function isBracketedPaste(): boolean {
+  return bracketedPaste;
+}
+
+/** True when the server has DECCKM (application cursor keys) enabled. */
+export function isApplicationCursor(): boolean {
+  return applicationCursor;
+}
+
+/**
+ * Active mouse tracking mode (xterm DECSET): 0 = off, 1000 = normal,
+ * 1002 = button-event, 1003 = any-event.
+ */
+export function getMouseMode(): number {
+  return mouseMode;
+}
+
+/** True when the server has DEC 1006 (SGR mouse encoding) enabled. */
+export function isMouseSGR(): boolean {
+  return mouseSGR;
+}
+
+/** True when the server has DEC 1004 (focus event reporting) enabled. */
+export function isFocusReporting(): boolean {
+  return focusReporting;
+}
+
+/** True when the server has DECKPAM (application keypad) enabled. */
+export function isApplicationKeypad(): boolean {
+  return applicationKeypad;
+}
+
+/** True when the server has DEC 5 (reverse video / DECSCNM) enabled. */
+export function isReverseVideo(): boolean {
+  return reverseVideo;
+}

package/src/mouse.ts

@@ -0,0 +1,203 @@
+// Mouse event encoding for terminal input (SGR 1006 protocol).
+//
+// Encodes mouse events as SGR sequences: ESC[<code;col;rowM (press/move)
+// or ESC[<code;col;rowm (release). Coordinates are 1-based.
+//
+// Button encoding (matches xterm/xterm.js):
+//   0=left, 1=middle, 2=right, 64=wheel-up, 65=wheel-down
+//   +4=shift, +8=alt, +16=ctrl, +32=motion
+//
+// Focus events: ESC[I (focus in), ESC[O (focus out).
+//
+// Out-of-scope (consumed but not implemented):
+//   - X10 mouse mode (mode 9): not supported.
+//   - urxvt encoding (mode 1015): not supported.
+//   - DEFAULT encoding (raw bytes): not supported; only SGR 1006.
+
+import { getMouseMode, isMouseSGR, isFocusReporting } from "./modes.js";
+
+const ESC = "\x1b";
+
+/** Encode a mouse button code for SGR protocol. */
+function buttonCode(
+  button: number,
+  motion: boolean,
+  shift: boolean,
+  alt: boolean,
+  ctrl: boolean,
+): number {
+  let code = button;
+  if (shift) {
+    code |= 4;
+  }
+  if (alt) {
+    code |= 8;
+  }
+  if (ctrl) {
+    code |= 16;
+  }
+  if (motion) {
+    code |= 32;
+  }
+  return code;
+}
+
+/**
+ * Encode a mouse event into an SGR 1006 escape sequence ready to send to the
+ * terminal as input. The returned string starts with ESC[< and ends with `M`
+ * for press/move or `m` for release.
+ *
+ * @param code  Button code returned from `buttonCode` (button + modifier bits).
+ * @param col   1-based column.
+ * @param row   1-based row.
+ * @param release `true` for release events (terminator `m`), `false` otherwise.
+ */
+export function encodeSGR(code: number, col: number, row: number, release: boolean): string {
+  const final = release ? "m" : "M";
+  return `${ESC}[<${code};${col};${row}${final}`;
+}
+
+/** 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
+  if (button <= 2) {
+    return button;
+  }
+  return 0; // fallback
+}
+
+/**
+ * Adapter the consumer wires into `init` so the mouse module can: send encoded
+ * input bytes to the server, query current cell pixel size for hit-testing,
+ * and access the terminal DOM element to attach listeners to.
+ */
+export interface MouseInputHandler {
+  /** Sends raw input bytes (or escape sequences) to the server. */
+  send: (data: string) => void;
+  /** Returns the current cell pixel size for hit-testing pointer coordinates. */
+  cellSize: () => { width: number; height: number };
+  /** Returns the terminal DOM element to attach mouse listeners to. */
+  termElement: () => HTMLElement;
+}
+
+let handler: MouseInputHandler | null = null;
+let lastButton = -1;
+
+/**
+ * Initialize the mouse module by attaching pointer/wheel/focus listeners to
+ * the terminal element. Listeners gate on the active mouse mode + SGR 1006
+ * encoding; they are no-ops when the server hasn't enabled mouse tracking.
+ */
+export function init(h: MouseInputHandler): void {
+  handler = h;
+  const el = h.termElement();
+  el.addEventListener("mousedown", onMouseDown);
+  el.addEventListener("mouseup", onMouseUp);
+  el.addEventListener("mousemove", onMouseMove);
+  el.addEventListener("wheel", onWheel, { passive: false });
+  el.addEventListener("focusin", onFocusIn);
+  el.addEventListener("focusout", onFocusOut);
+}
+
+function pixelToCell(e: MouseEvent): { col: number; row: number } | null {
+  if (!handler) {
+    return null;
+  }
+  const el = handler.termElement();
+  const rect = el.getBoundingClientRect();
+  const { width, height } = handler.cellSize();
+  if (width <= 0 || height <= 0) {
+    return null;
+  }
+  const col = Math.floor((e.clientX - rect.left) / width) + 1; // 1-based
+  const row = Math.floor((e.clientY - rect.top) / height) + 1; // 1-based
+  if (col < 1 || row < 1) {
+    return null;
+  }
+  return { col, row };
+}
+
+function onMouseDown(e: MouseEvent): void {
+  const mode = getMouseMode();
+  if (mode === 0 || !isMouseSGR() || !handler) {
+    return;
+  }
+  const pos = pixelToCell(e);
+  if (!pos) {
+    return;
+  }
+  lastButton = domButtonToXterm(e.button);
+  const code = buttonCode(lastButton, false, e.shiftKey, e.altKey, e.ctrlKey);
+  handler.send(encodeSGR(code, pos.col, pos.row, false));
+  e.preventDefault();
+}
+
+function onMouseUp(e: MouseEvent): void {
+  const mode = getMouseMode();
+  if (mode === 0 || !isMouseSGR() || !handler) {
+    return;
+  }
+  const pos = pixelToCell(e);
+  if (!pos) {
+    return;
+  }
+  const btn = domButtonToXterm(e.button);
+  const code = buttonCode(btn, false, e.shiftKey, e.altKey, e.ctrlKey);
+  handler.send(encodeSGR(code, pos.col, pos.row, true));
+  lastButton = -1;
+  e.preventDefault();
+}
+
+function onMouseMove(e: MouseEvent): void {
+  const mode = getMouseMode();
+  if (mode === 0 || !isMouseSGR() || !handler) {
+    return;
+  }
+  // mode 1000: no motion events
+  // mode 1002: motion only while button held (drag)
+  // mode 1003: all motion events
+  if (mode === 1000) {
+    return;
+  }
+  if (mode === 1002 && !e.buttons) {
+    return;
+  }
+  const pos = pixelToCell(e);
+  if (!pos) {
+    return;
+  }
+  const btn = e.buttons ? (e.buttons & 1 ? 0 : e.buttons & 4 ? 1 : e.buttons & 2 ? 2 : 0) : 0;
+  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) {
+    return;
+  }
+  const pos = pixelToCell(e);
+  if (!pos) {
+    return;
+  }
+  // Wheel up = button 64, wheel down = button 65
+  const btn = e.deltaY < 0 ? 64 : 65;
+  const code = buttonCode(btn, false, e.shiftKey, e.altKey, e.ctrlKey);
+  handler.send(encodeSGR(code, pos.col, pos.row, false));
+  e.preventDefault();
+}
+
+function onFocusIn(): void {
+  if (!isFocusReporting() || !handler) {
+    return;
+  }
+  handler.send(`${ESC}[I`);
+}
+
+function onFocusOut(): void {
+  if (!isFocusReporting() || !handler) {
+    return;
+  }
+  handler.send(`${ESC}[O`);
+}

package/src/reconnect.ts

@@ -0,0 +1,64 @@
+// Pure reconnect-delay scheduler for the terminal WebSocket.
+//
+// Reconnect strategy: exponential backoff capped at MAX_DELAY_MS, with
+// uniform random jitter in [0, JITTER_MS) added to each scheduled
+// attempt. The per-attempt jitter prevents thundering-herd reconnects
+// when several browser tabs lose connectivity together; the cap keeps
+// the worst-case wait bounded so a long network outage doesn't push
+// the next retry an hour out.
+//
+// Pulled into a dedicated module so the formula is testable without
+// real timers: callers inject `random()` (typically `Math.random`)
+// and receive both the delay to wait this attempt and the new base
+// delay for the next attempt. This separates the math from the
+// timer-side-effect plumbing in the connection module.
+
+/** Initial backoff delay in milliseconds. Used by the first retry after a clean connection. */
+export const INITIAL_DELAY_MS = 500;
+
+/** Maximum (capped) base delay in milliseconds. */
+export const MAX_DELAY_MS = 8000;
+
+/** Maximum jitter added per attempt (uniform random, exclusive upper bound). */
+export const JITTER_MS = 250;
+
+/** Result of computing the next backoff step. */
+interface BackoffStep {
+  /** Milliseconds to wait before the next reconnect attempt. */
+  scheduledMs: number;
+  /** New base delay to feed into the subsequent call. */
+  nextBaseMs: number;
+}
+
+/**
+ * nextBackoffDelay computes the wait time for this attempt and the
+ * new base delay for the next attempt. Pure given a deterministic
+ * `random` function; pass `Math.random` for production.
+ *
+ * Formula:
+ *   scheduledMs = currentBaseMs + random() * JITTER_MS
+ *   nextBaseMs  = min(currentBaseMs * 2, MAX_DELAY_MS)
+ *
+ * `random` is expected to return a number in [0, 1). When undefined
+ * or out of range, the implementation clamps to that interval so
+ * malformed inputs don't yield NaN/negative delays.
+ */
+export function nextBackoffDelay(
+  currentBaseMs: number,
+  random: () => number = Math.random,
+): BackoffStep {
+  const r = clamp01(random());
+  const scheduledMs = currentBaseMs + r * JITTER_MS;
+  const nextBaseMs = Math.min(currentBaseMs * 2, MAX_DELAY_MS);
+  return { scheduledMs, nextBaseMs };
+}
+
+function clamp01(x: number): number {
+  if (!Number.isFinite(x) || x < 0) {
+    return 0;
+  }
+  if (x >= 1) {
+    return 0.999_999_999;
+  }
+  return x;
+}