@cplieger/web-terminal-engine 1.3.2 → 1.4.0

package/jsr.json

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

package/package.json

@@ -1,21 +1,26 @@
 {
   "name": "@cplieger/web-terminal-engine",
-  "version": "1.3.2",
+  "version": "1.4.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.3",
     "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

@@ -546,6 +546,7 @@ export function connect(): void {
         msg.mouseMode,
         msg.applicationKeypad,
         msg.reverseVideo,
+        msg.mousePixels,
       );
       if (typeof msg.inputAck === "number") {
         applyAck(msg.inputAck);

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

@@ -408,6 +408,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/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