@cplieger/web-terminal-engine 5.0.8 → 5.1.0

package/README.md

@@ -32,9 +32,17 @@ const out = document.getElementById("term-output") as HTMLElement;
 render.init({ output: out, termWrap: wrap }); // optional: maxLines (retained-line cap, default 5000)
 scroll.init({ scrollEl: wrap });
 mouse.init({
-  send: (data) => ws.send(data),
-  cellSize: () => ({ width: cellW, height: cellH }),
+  // Best-effort input: return whether the report reached a live socket, so a
+  // refused one is forgotten instead of retried. With the connection module this
+  // is `connection.sendEphemeral`.
+  sendReport: (data) => {
+    ws.send(data);
+    return true;
+  },
+  cellSize: render.cellSize,
   termElement: () => wrap,
+  gridElement: () => out, // the rows' own box: no padding, no scrollbar gutter
+  gridSize: render.gridSize, // the RENDERED grid, not the size this client would like
 });
 
 ws.binaryType = "arraybuffer";
@@ -77,15 +85,15 @@ document.addEventListener("keydown", (ev) => {
 
 ## API
 
-- **`render`** — DOM renderer driven by `ScreenMessage` / `ScrollMessage` frames. `init` (accepts `maxLines`, the retained-line cap — memory-constrained consumers pass a smaller budget; history above the cap is evicted from the top in batches, and the live screen is never evicted, so a cap at or below the terminal height keeps the full screen with no scrollback), `handleScreen`, `handleScroll`, `updateFontMetrics`, `computeSize`, `getCursorPx`, `setPredictedCursor`, `resetScreen`, `resetScrollback`, `getHighestIndex`, `noteResumeBounds`, `updateReverseVideo`.
+- **`render`** — DOM renderer driven by `ScreenMessage` / `ScrollMessage` frames. `init` (accepts `maxLines`, the retained-line cap — memory-constrained consumers pass a smaller budget; history above the cap is evicted from the top in batches, and the live screen is never evicted, so a cap at or below the terminal height keeps the full screen with no scrollback), `handleScreen`, `handleScroll`, `updateFontMetrics`, `computeSize`, `cellSize`, `gridSize`, `getCursorPx`, `setPredictedCursor`, `resetScreen`, `resetScrollback`, `getHighestIndex`, `noteResumeBounds`, `updateReverseVideo`.
 - **`keyboard`** — Translates `KeyboardEvent` to terminal byte sequences. `mapKeyboardEvent`, `bracketTextForPaste`, `prepareTextForTerminal`, `ctrlByteFor`, plus the shared logical-key encodings (`plainCursorKeySeq`, `plainEscapeSeq`) the toolbar module reuses. Honors `applicationCursor`, `applicationKeypad`, `bracketedPaste`.
 - **`toolbar`** — On-screen mobile toolbar widget (moved out of `keyboard` in v3). `bindMobileToolbar({toolbar, send, ids?})` wires `pointerdown` handlers for an on-screen Ctrl/arrows/Tab/Enter/Esc toolbar (with sticky-Ctrl semantics and kitty/DECCKM-aware arrows byte-identical to the physical-key path), returning a `MobileToolbarController` exposing `applyStickyCtrl`, `setCtrlArmed`, `isCtrlArmed`, and `dispose`.
-- **`mouse`** — SGR 1006 mouse + focus reporting encoder. `init`, `encodeSGR`, `MouseInputHandler`. Auto-gates on `mouseMode > 0`.
+- **`mouse`** — SGR 1006 mouse encoder. `init`, `encodeSGR`, `resyncGesture`, `disarmGesture`, `MouseInputHandler`. Auto-gates on `mouseMode > 0`. `MouseInputHandler` carries two optional members, both defaulting to today's behaviour: `gridElement` names the element whose box IS the grid (the scroll container's own box includes its padding and scrollbar gutter, so it is not that box), and `gridSize` supplies the dimensions of the grid ON SCREEN — `render.gridSize`, not the size this client measured — so every report is clamped into it and rows are measured up from the bottom edge (the screen window is the tail of the content). Its required `sendReport(data)` returns whether the report reached a live socket; wire it to `connection.sendEphemeral`. Four consequences of mouse input being best-effort: a release is emitted only for a press that was DELIVERED (a release whose press never arrived is its own desync, because the application never learned the button went down); a drag reports a held button only while the application believes that button is down, so motion for an undelivered gesture is dropped under mode 1002 and reports as no-button under 1003; `resyncGesture()`, called once the resumeAck has declared the server's capabilities (not from `onOpen`, where the ephemeral channel is not yet known, so the release would take the reliable fallback), emits one release for any button the last reading says is now up, so a drag is not left pressed across a reconnect; and motion is coalesced to one report per animation frame, latest wins, while press, release and wheel are never coalesced (a wheel report is a notch count against a screen, so coalescing loses scroll distance). `resyncGesture` shares one gate with the handlers, and each of them enforces it: a gesture stranded by the application turning tracking off is FORGOTTEN by whichever one next observes tracking off, because a release nothing asked for reaches the PTY as keystrokes. tmux answers the same way at attach, clearing `mouse_drag_flag` as it disables the modes. `disarmGesture()` forgets a held gesture without reporting anything — call it when pointing one terminal's socket at another session, since the record belongs to the session that saw the press. Focus reporting is NOT here: it is transport state, and it lives in `connection.setClientFocus`.
 - **`scroll`** — Auto-follow tracker for the scroll container. `init`, `stickToBottom`, `scrollToBottom`, `isUserScrolledUp`, `currentScrollTop`, `restoreView`, `adjustForContentShift`, plus two renderer seams: `noteContentShrink(scrollTopBefore)` says a row removal rather than a gesture caused the scroll event about to arrive, and `reconcileScrollRange()` moves the offset back inside the container's range when the container did not reconcile the shrink itself. The second exists because clamping an offset the content shrank out from under is an implementation behaviour and not a specified one: Blink and Gecko reconcile during layout, WebKit does not, and without the correction an iOS viewport is left parked past the end of the content after an application clears the screen, showing background with the content above it until the reader scrolls.
 - **`modes`** — DEC private mode state (synced from server's `ModesMessage`). `setModes`, `isBracketedPaste`, `isApplicationCursor`, `getMouseMode`, `isMouseSGR`, `isFocusReporting`, `isApplicationKeypad`, `isReverseVideo`.
 - **`decodeWireBinary(buf)`**: Top-level decoder for the binary WebSocket frames. Returns a `ServerMessage` or `null` for invalid/truncated frames.
 - **Wire compatibility metadata**: `WIRE_PROTOCOL_VERSION`, `MIN_SUPPORTED_SERVER_WIRE_VERSION`, `WIRE_INCOMPATIBLE_CLOSE_CODE`, and `WIRE_COMPATIBILITY` publish this client release's directional contract. The same values ship as a language-neutral JSON artifact for non-TypeScript consumers — see [Wire compatibility manifest](#wire-compatibility-manifest).
-- **`connection`**: Client → server WebSocket lifecycle: owns the socket, exponential-backoff reconnect, and the resume/inputAck reliability layer (outbox + server-restart detection). `init(callbacks)`, `connect`, `sendBinary(bytes)`, `sendResize`, `reconnectNow`. The callbacks expose `onMessage(ServerMessage)`, `onOpen`/`onClose`/`onConnecting`/`onOutboxFull`/`onServerRestart`, `onWireVersionMismatch`, and the definitive `onWireIncompatible`; a `computeSize()` provider; and an optional `wsPath` (defaults to `"/ws"`). An explicit below-floor server revision or close code 4002 stops automatic reconnects until `disconnect()` or a page reload. Version-silent and future-revision servers remain tolerated. The module decodes frames internally and applies `modes.setModes`, so a consumer only needs to dispatch screen/scroll to `render`. Prefer this over wiring `WebSocket` + `decodeWireBinary` by hand unless you need full control.
+- **`connection`**: Client → server WebSocket lifecycle: owns the socket, exponential-backoff reconnect, and the resume/inputAck reliability layer (outbox + server-restart detection). `init(callbacks)`, `connect`, `sendBinary(bytes)`, `sendEphemeral(text)`, `setClientFocus(focused)`, `sendResize`, `reconnectNow`. `sendEphemeral` carries BEST-EFFORT input (mouse reports): it sends only when a socket is live right now, returns whether it did, and never touches the outbox or the byte counters, so a report is forgotten rather than replayed against a screen the resume has since repainted. Against a server that declares neither capability it falls back to `sendBinary`, because an unrecognized control is dropped post-latch and total silence is a worse failure than a stale report — on that path the report rides the reliable outbox and can be retransmitted after a reconnect. `setClientFocus` reports the terminal widget's focus: it sends the `focus` control when the server declared it derives the DEC 1004 answer (from attachment state, every attached client's report, and its own `terminal.WithKeepUnfocused`), and otherwise writes `CSI I` / `CSI O` itself while the application has 1004 enabled — including on the enable edge, so an application that turns focus reporting on while the tab is already focused is told so immediately. The callbacks expose `onMessage(ServerMessage)`, `onOpen`/`onClose`/`onConnecting`/`onOutboxFull`/`onServerRestart`, `onWireVersionMismatch`, and the definitive `onWireIncompatible`; a `computeSize()` provider; and an optional `wsPath` (defaults to `"/ws"`). An explicit below-floor server revision or close code 4002 stops automatic reconnects until `disconnect()` or a page reload. Version-silent and future-revision servers remain tolerated. The module decodes frames internally and applies `modes.setModes`, so a consumer only needs to dispatch screen/scroll to `render`. Prefer this over wiring `WebSocket` + `decodeWireBinary` by hand unless you need full control.
 - **`controlFrame(msg)` / `wsURL(proto, host, path?)`** — Low-level helpers for the client → server protocol (0x00-prefixed JSON control frames, WebSocket URL building). Used internally by `connection`; exported for advanced consumers.
 
 Wire types (`WireRun`, `ScreenMessage`, `ScrollMessage`, `ModesMessage`, `TitleMessage`, `ResumeAckMessage`, `ServerMessage`, `ControlMessage`) are re-exported from the package root and match the Go server's wire format byte-for-byte.

package/jsr.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/web-terminal-engine",
-  "version": "5.0.8",
+  "version": "5.1.0",
   "type": "module",
   "scripts": {
     "typecheck": "tsc -p tsconfig.json",
@@ -11,22 +11,24 @@
   "devDependencies": {
     "@cplieger/web-terminal-engine-v3": "npm:@cplieger/web-terminal-engine@2.8.0",
     "@eslint/js": "10.0.1",
-    "@playwright/test": "1.62.1",
+    "@playwright/test": "1.63.0",
     "@stryker-mutator/core": "10.0.0",
     "@stryker-mutator/typescript-checker": "10.0.0",
     "@stryker-mutator/vitest-runner": "10.0.0",
     "@types/pngjs": "6.0.5",
     "@typescript/native": "npm:typescript@7.0.2",
-    "@vitest/coverage-v8": "4.1.11",
+    "@vitest/browser": "5.0.0",
+    "@vitest/browser-playwright": "5.0.0",
+    "@vitest/coverage-v8": "5.0.0",
     "esbuild": "0.28.2",
-    "eslint": "10.8.1",
+    "eslint": "10.10.0",
     "fast-check": "4.9.0",
-    "happy-dom": "20.11.6",
+    "playwright": "1.63.0",
     "pngjs": "7.0.0",
     "prettier": "3.9.6",
     "typescript": "npm:@typescript/typescript6@6.0.2",
-    "typescript-eslint": "8.67.0",
-    "vitest": "4.1.11"
+    "typescript-eslint": "8.70.0",
+    "vitest": "5.0.0"
   },
   "overrides": {
     "qs": "^6.15.2"

package/src/connection.ts

@@ -43,6 +43,7 @@ import * as modes from "./modes.js";
 // end of the gap fills.
 import { PAGE_SIZE } from "./store.js";
 import * as render from "./render.js";
+import * as mouse from "./mouse.js";
 import type { ControlMessage, ScrollMessage, ServerMessage } from "./types.js";
 import { INITIAL_DELAY_MS, nextBackoffDelay } from "./reconnect.js";
 
@@ -304,6 +305,48 @@ function newHistoryState(): HistoryState {
 
 let history: HistoryState = newHistoryState();
 
+/**
+ * The capabilities the server DECLARED on this socket's resume ack. Per-socket
+ * for the same reason as HistoryState: a carried-over capability would send a
+ * control to a server that never declared it, and post-latch an unrecognized
+ * text control is tolerated and DROPPED — so the message would vanish silently.
+ */
+interface ServerCaps {
+  /** ackFlags bit3: the server serves the `ephemeralInput` control. */
+  ephemeralInput: boolean;
+  /** ackFlags bit2: the server derives the DEC 1004 answer from `focus`. */
+  serverFocus: boolean;
+}
+
+let caps: ServerCaps = { ephemeralInput: false, serverFocus: false };
+
+/**
+ * Whether the consumer's terminal widget is focused. Per PAGE, not per socket:
+ * it is the widget's own state and must survive a reconnect, because the new
+ * socket has to be told the CURRENT value.
+ */
+let clientFocused = false;
+
+/**
+ * The focus value THIS socket has been told, or null when it has been told
+ * nothing. Per socket, so a reconnect re-asserts focus instead of suppressing it
+ * as a repeat.
+ */
+let focusReported: boolean | null = null;
+
+/**
+ * The 1004 state last seen in a modes frame on this socket, for the fallback
+ * path's enable-edge detection. Per socket: a fresh socket is re-announced its
+ * modes, and the edge has to be detected against nothing rather than against the
+ * previous socket's last value.
+ */
+let lastFocusReportingSeen = false;
+
+/** WebSocket.OPEN. Spelled out because a test's fake constructor has no statics. */
+const WS_OPEN = 1;
+
+const ephemeralEncoder = new TextEncoder();
+
 /** Cancel both timers and release single-flight. */
 function clearHistoryTimers(): void {
   if (history.dataTimer !== null) {
@@ -317,14 +360,19 @@ function clearHistoryTimers(): void {
 }
 
 /**
- * Reset the fetch state for a new socket: capability, single-flight, pacing and
- * the adaptive budget all go together, atomically. Splitting them is how a
- * client ends up paging against a server that never declared it, or bursting
- * into a depleted server bucket.
+ * Reset everything a new socket must not inherit: the fetch state (capability,
+ * single-flight, pacing and the adaptive budget), the declared server
+ * capabilities, and the focus reporting latches. All of it goes together,
+ * atomically. Splitting them is how a client ends up paging against a server
+ * that never declared it, bursting into a depleted server bucket, or holding a
+ * focus report back from the new socket as a repeat of what the old one was told.
  */
-function resetHistoryForSocket(): void {
+function resetForNewSocket(): void {
   clearHistoryTimers();
   history = newHistoryState();
+  caps = { ephemeralInput: false, serverFocus: false };
+  focusReported = null;
+  lastFocusReportingSeen = false;
 }
 
 /**
@@ -642,6 +690,74 @@ function textControl(msg: ControlMessage): string {
   return JSON.stringify(msg);
 }
 
+/**
+ * sendEphemeral delivers BEST-EFFORT input. Where the server declared
+ * `ephemeralInput` it sends only on a live socket, never queues, never
+ * retransmits, and never touches `outbox`, `outboxBytes`, `bytesSent`,
+ * `bytesAcked` or `onOutboxFull`; where it did NOT, the report falls back to
+ * reliable input, so it can be retransmitted after a resume and describe a
+ * screen since repainted. Returns whether it was sent; on false the caller's
+ * contract is to FORGET the event, because a mouse report carries no sequence
+ * number. Refusing on a closing socket is what xterm.js's AttachAddon and ttyd
+ * both do.
+ */
+export function sendEphemeral(text: string): boolean {
+  if (connState.status !== "connected" || connState.sock.readyState !== WS_OPEN) {
+    return false;
+  }
+  if (!connState.upgraded || !caps.ephemeralInput) {
+    // Fall back to RELIABLE input rather than dropping the report. An
+    // unrecognized text control is tolerated and dropped post-latch, so the
+    // report would vanish entirely, and total silence is a worse failure than a
+    // stale report: a third-party or mid-upgrade server keeps a working mouse.
+    // What is DEGRADED on this path: the report rides the reliable outbox, so a
+    // click made before a disconnect is retransmitted after the resume has
+    // repainted the screen.
+    return sendBinary(ephemeralEncoder.encode(text));
+  }
+  connState.sock.send(textControl({ type: "ephemeralInput", data: text }));
+  return true;
+}
+
+/**
+ * setClientFocus reports whether the consumer's terminal widget is focused.
+ *
+ * Focus is STATE, so it is reconciled rather than replayed: the latest value
+ * wins, a repeat of the value already reported sends nothing, a report made
+ * while no socket is live is dropped rather than queued, and a reconnect
+ * re-asserts the current one. Where the server declared `serverFocus` this sends
+ * the `focus` control and the server derives the DEC 1004 answer for the whole
+ * session; otherwise the client writes the legacy CSI I / CSI O itself, and only
+ * while the application has 1004 enabled.
+ */
+export function setClientFocus(focused: boolean): void {
+  clientFocused = focused;
+  if (connState.status !== "connected") {
+    // A focus report is never QUEUED. The fallback path below writes through the
+    // RELIABLE outbox, so a report made while the socket is down would be
+    // retransmitted on reconnect and re-assert a focus the widget may since have
+    // lost, which is the replay this whole derivation exists to remove. Nothing
+    // is lost by dropping it: both the resumeAck and the 1004 enable edge
+    // re-report the current value on the new socket.
+    return;
+  }
+  if (focused === focusReported) {
+    return;
+  }
+  focusReported = focused;
+  if (caps.serverFocus && connState.upgraded) {
+    sendControl({ type: "focus", focused });
+    return;
+  }
+  if (!modes.isFocusReporting()) {
+    return;
+  }
+  // The legacy path, and it rides the RELIABLE outbox: a focus report can be
+  // retransmitted after a blip, re-asserting a state that may no longer be true.
+  // That is one of the things the server-owned path fixes.
+  sendBinary(ephemeralEncoder.encode(focused ? "\x1b[I" : "\x1b[O"));
+}
+
 function sendControl(msg: ControlMessage): void {
   if (connState.status !== "connected") {
     return;
@@ -700,10 +816,6 @@ export function sendResize(): void {
   sendControl({ type: "resize", cols, rows });
 }
 
-// resetLedger drops a session's reliable-input accounting. Called when the
-// server's boot epoch changes (restart) or when the server no longer recognizes
-// the session -- both invalidate the local bytesSent/bytesAcked/outbox state.
-// The three entry points below differ only in whether the UI hears about it.
 // resetLedger drops a session's reliable-input accounting. Called whenever the
 // server no longer holds the ledger these counters were keyed to (a restart, an
 // idle-GC'd resume key, a session the server does not recognize): its
@@ -885,7 +997,7 @@ function teardown(): void {
     }
   }
   stopHeartbeat();
-  resetHistoryForSocket();
+  resetForNewSocket();
   cb?.clearSolicited?.();
   cancelScheduledReconnect();
   connState = { status: "disconnected" };
@@ -1341,7 +1453,7 @@ export function connect(): void {
       // exact values, so the replay-jump prediction must be computed from them
       // — never from store state, which a frame arriving between send and ack
       // could have moved, masking a real jump (docs/paged-scrollback.md §4.5).
-      resetHistoryForSocket();
+      resetForNewSocket();
       const sentHaveThrough = cb?.getHaveThrough?.() ?? -1;
       // ALWAYS a number. A consumer may ask for fewer lines than the protocol
       // ceiling, but it cannot opt OUT of the bound: the server clamps to the
@@ -1555,6 +1667,18 @@ export function connect(): void {
       // nothing ever sent, and the store keeps its compatibility tail cap.
       history.paging = msg.historyPaging === true;
       history.acked = true;
+      // The other two capabilities off the same tail, and the focus re-report
+      // for this socket. Placed here — with the capability handling, BEFORE the
+      // ledger-lost / session-forgotten early returns — for the same reason
+      // onResumeTransition is: a ledger loss is not a capability event, and the
+      // long-absence attach that loses its ledger still needs its focus state
+      // asserted on the new socket.
+      caps = {
+        ephemeralInput: msg.ephemeralInput === true,
+        serverFocus: msg.serverFocus === true,
+      };
+      focusReported = null;
+      setClientFocus(clientFocused);
       // The store's ONE ack transition, dispatched BEFORE the early returns
       // below. A ledger loss is not a capability event, and the long-absence
       // attach that loses its ledger is exactly the one carrying a replay jump
@@ -1608,6 +1732,12 @@ export function connect(): void {
         connState.status === "connected" && connState.sock === sock && connState.upgraded,
         st,
       );
+      // The transport answers for itself here, as it does for focus: the resume is
+      // complete, `upgraded` and `caps` are both set, so this is the first instant
+      // a best-effort report can leave. A gesture still recorded from before the
+      // gap is cancelled now, or the application holds that button for the rest of
+      // the session. Inert until a consumer has called `mouse.init`.
+      mouse.resyncGesture();
       return;
     }
     if (msg.type === "ackOnly") {
@@ -1636,6 +1766,18 @@ export function connect(): void {
       };
       st.modes = snap;
       modes.applySnapshot(snap);
+      if (!caps.serverFocus) {
+        // The 1004 ENABLE edge on the fallback path. An application that enables
+        // focus reporting while the tab is already focused otherwise gets nothing
+        // until the user clicks away; xterm.js's _reportFocus reports the current
+        // state at that instant, and this client did not.
+        const rising = msg.focusReporting && !lastFocusReportingSeen;
+        lastFocusReportingSeen = msg.focusReporting;
+        if (rising) {
+          focusReported = null;
+          setClientFocus(clientFocused);
+        }
+      }
       if (typeof msg.inputAck === "number") {
         applyAck(st, msg.inputAck);
       }
@@ -1719,7 +1861,7 @@ export function connect(): void {
       // The fetch state belonged to THIS socket: kill its timers so neither
       // fires against a dead socket, and release the solicited window so the
       // store stops admitting lines below its stale-re-send watermark.
-      resetHistoryForSocket();
+      resetForNewSocket();
       cb?.clearSolicited?.();
       if (ev.code === WIRE_INCOMPATIBLE_CLOSE_CODE) {
         const reason =

package/src/mouse.ts

@@ -7,14 +7,18 @@
 //   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).
+// Mouse reports are BEST-EFFORT: a report carries no sequence number and
+// describes a screen a resume may since have repainted, so `sendReport` may
+// refuse one and a refused report is forgotten rather than retried. Focus is not
+// mouse input at all — it is transport state the server derives — and lives in
+// `connection.setClientFocus`.
 //
 // 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, isMousePixels, isFocusReporting } from "./modes.js";
+import { getMouseMode, isMouseSGR, isMousePixels } from "./modes.js";
 
 const ESC = "\x1b";
 
@@ -75,12 +79,32 @@ function domButtonToXterm(button: number): number {
  * 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;
+  /**
+   * Sends one encoded report as best-effort input. Returns whether it reached a
+   * live socket; `false` means it was NOT sent and must not be retried (see
+   * `connection.sendEphemeral`).
+   */
+  sendReport: (data: string) => boolean;
   /** 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;
+  /**
+   * Returns the element whose box IS the grid: its top-left is cell (1,1)'s
+   * origin and its bottom edge is the last row's bottom. Defaults to
+   * `termElement()`, which is only the same box when that element carries no
+   * padding and no reserved scrollbar gutter.
+   */
+  gridElement?: () => HTMLElement;
+  /**
+   * Returns the dimensions of the grid currently on screen (the engine
+   * renderer's `gridSize`). Supplying it clamps every report into the grid and
+   * anchors the row arithmetic to the grid's bottom edge; omitting it keeps the
+   * top-anchored, unclamped hit test. Rows must be the RENDERED height, not the
+   * height this client would like: the hit test anchors on it, so a disagreement
+   * shifts every reported row rather than loosening a bound.
+   */
+  gridSize?: () => { cols: number; rows: number };
 }
 
 let handler: MouseInputHandler | null = null;
@@ -101,6 +125,81 @@ let lastMotion = "";
 // registrations on the SAME element, but a re-init on a NEW element would
 // otherwise leak the old one's listeners).
 let attachedEl: HTMLElement | null = null;
+// One warning per wiring, not per event: a non-positive cell size makes every
+// report vanish, which is indistinguishable from mouse-tracking being off, and
+// that silence is why a consumer wiring cellSize to a guess went unnoticed.
+let warnedDegenerateCell = false;
+// The same silence for the other divisor, and it is worse: an empty grid clamps
+// every coordinate to 0, so instead of vanishing the report becomes a confident
+// (1,1) for every pointer position.
+let warnedDegenerateGrid = false;
+// The buttons whose PRESS was actually delivered, with the coordinates that
+// press reported. This is what the APPLICATION believes is held, so it also
+// decides which reports are truthful: a release is emitted only for a recorded
+// button, and a motion report claims a held button only for a recorded one.
+const pressed = new Map<number, { col: number; row: number }>();
+// DOM MouseEvent.button index -> its bit in MouseEvent.buttons. Middle and right
+// are SWAPPED between the two (button 1 = middle = bit 4; button 2 = right =
+// bit 2), so `1 << button` is wrong.
+const BUTTONS_BIT = [1, 4, 2, 8, 16] as const;
+// The freshest `buttons` bitmask any mouse event gave this element, which is the
+// only reading of present button state the DOM offers outside an event.
+let lastButtons = 0;
+// The motion report waiting for the next animation frame, and the frame handle
+// that will flush it. Motion coalesces to one report per frame, latest wins.
+let pendingMotion: string | null = null;
+let motionFrame: number | null = null;
+
+// The one predicate every read and every write of `pressed` is gated on: the
+// application is asking for SGR-encoded reports right now. A record written
+// under tracking outlives the mode that created it, and an SGR release written
+// once tracking is off lands in the PTY as ordinary keystrokes.
+function trackingActive(): boolean {
+  return getMouseMode() !== 0 && (isMouseSGR() || isMousePixels());
+}
+
+// Forget the held-gesture record and the button reading it is judged against.
+function clearGesture(): void {
+  pressed.clear();
+  lastButtons = 0;
+}
+
+// True when the application is not tracking, and the shared gate for every
+// handler and for resyncGesture. Forgetting the record here is what closes the
+// stranded-gesture sequence: an SGR release written while nothing asked for one
+// reaches the PTY as keystrokes, and carrying the record into a later re-enable
+// would describe a press that program never saw. tmux answers the same way at
+// attach, disabling every mouse mode and clearing mouse_drag_flag with it
+// (tty.c, tty_start_tty).
+function trackingOff(): boolean {
+  if (trackingActive()) {
+    return false;
+  }
+  clearGesture();
+  return true;
+}
+
+// Drop the pending motion report and disarm its frame. A press, release or wheel
+// CANCELS rather than flushes: the button event carries a newer position, so
+// ordering is correct by construction and the superseded motion is exactly what
+// coalescing is entitled to drop.
+function cancelPendingMotion(): void {
+  pendingMotion = null;
+  if (motionFrame !== null) {
+    cancelAnimationFrame(motionFrame);
+    motionFrame = null;
+  }
+}
+
+function flushMotion(): void {
+  motionFrame = null;
+  const seq = pendingMotion;
+  pendingMotion = null;
+  if (seq === null || !handler) {
+    return;
+  }
+  handler.sendReport(seq);
+}
 
 function detach(): void {
   if (!attachedEl) {
@@ -110,14 +209,12 @@ function detach(): void {
   attachedEl.removeEventListener("mouseup", onMouseUp);
   attachedEl.removeEventListener("mousemove", onMouseMove);
   attachedEl.removeEventListener("wheel", onWheel);
-  attachedEl.removeEventListener("focusin", onFocusIn);
-  attachedEl.removeEventListener("focusout", onFocusOut);
   attachedEl = null;
 }
 
 /**
- * Initialize the mouse module by attaching pointer/wheel/focus listeners to
- * the terminal element. Listeners gate on the active mouse mode + SGR 1006
+ * Initialize the mouse module by attaching pointer/wheel 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.
  *
  * Returns an idempotent disposer that detaches the listeners and resets the
@@ -130,14 +227,16 @@ export function init(h: MouseInputHandler): () => void {
   handler = h;
   shiftBypass = false;
   lastMotion = "";
+  warnedDegenerateCell = false;
+  warnedDegenerateGrid = false;
+  clearGesture();
+  cancelPendingMotion();
   const el = h.termElement();
   attachedEl = el;
   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);
   return function dispose(): void {
     if (attachedEl !== el) {
       return; // superseded by a later init — nothing of ours left to detach
@@ -146,43 +245,169 @@ export function init(h: MouseInputHandler): () => void {
     handler = null;
     shiftBypass = false;
     lastMotion = "";
+    clearGesture();
+    cancelPendingMotion();
   };
 }
 
+/**
+ * resyncGesture cancels a gesture left in flight, called once the resume has
+ * declared the server's capabilities (the resumeAck, not the socket's open: the
+ * ephemeral channel is not yet known at open, so a release sent there would take
+ * the reliable fallback and become the one replayable mouse report). A button the
+ * server believes is still held is a stuck drag for the rest of the session. For
+ * each recorded button the last reading says is now UP it emits one release at
+ * that press's coordinates; a button still down is left alone, because it
+ * genuinely is.
+ *
+ * This reports PRESENT state, which is what RFB and Guacamole do implicitly with
+ * their next message, not a replay of the missed release. The synthesis is OUR
+ * JUDGEMENT — no reference addresses a producer-side resync (tmux resets its own
+ * gesture model at attach, but tmux is the CONSUMER and can) — chosen over
+ * emitting nothing and letting the next real click unstick the application. Its
+ * bound: the reading is the freshest the browser gave THIS element, so a release
+ * that happened off-element is invisible either way.
+ */
+export function resyncGesture(): void {
+  if (!handler) {
+    return;
+  }
+  cancelPendingMotion();
+  if (trackingOff()) {
+    return;
+  }
+  for (const [button, pos] of [...pressed]) {
+    if ((lastButtons & (BUTTONS_BIT[button] ?? 0)) !== 0) {
+      continue; // still held
+    }
+    const code = buttonCode(domButtonToXterm(button), false, false, false, false);
+    if (handler.sendReport(encodeSGR(code, pos.col, pos.row, true))) {
+      pressed.delete(button); // only a DELIVERED release ends the gesture, as in onMouseUp
+    }
+  }
+}
+
+/**
+ * disarmGesture forgets the held gesture without reporting anything, for a
+ * consumer pointing one terminal's socket at a different session.
+ *
+ * The record says what the OUTGOING session's application believes is held, and
+ * this module is per terminal while sessions multiplex over it, so a release
+ * surviving the switch would reach a session that never saw the press — the
+ * desync `pressed` exists to prevent, arriving through resyncGesture. Nothing is
+ * emitted instead: the same treatment the consumer gives every other latched
+ * input class on a switch.
+ */
+export function disarmGesture(): void {
+  cancelPendingMotion();
+  clearGesture();
+}
+
 // 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) {
+  const h = handler;
+  if (!h) {
     return null;
   }
-  const el = handler.termElement();
+  const el = (h.gridElement ?? h.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) {
+  const grid = h.gridSize?.() ?? null;
+  if (grid !== null && (grid.cols <= 0 || grid.rows <= 0)) {
+    // rows 0 is the documented pre-first-frame answer (render.gridSize): the
+    // server has not described the screen yet, so refuse without spending the
+    // warning latch that exists to make a genuine mis-wiring loud.
+    if (grid.cols > 0 && grid.rows === 0) {
       return null;
     }
-    return { col: px + 1, row: py + 1 }; // 1-based pixel offsets
+    warnUnmeasuredGrid(grid.cols, grid.rows);
+    return null;
+  }
+  if (isMousePixels()) {
+    const box = grid === null ? null : pixelBox(h, grid);
+    if (box === null) {
+      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
+    }
+    // Same origin as the cell branch below — the grid's BOTTOM edge — so one
+    // press resolves to the same row under either encoding. Measured from the
+    // box's top edge instead, a partial top row shifts every pixel report by up
+    // to a cell.
+    return {
+      col: clampToGrid(Math.round(e.clientX - rect.left), box.width) + 1,
+      row: clampToGrid(Math.round(e.clientY - (rect.bottom - box.height)), box.height) + 1,
+    };
   }
-  const { width, height } = handler.cellSize();
+  const { width, height } = h.cellSize();
   if (width <= 0 || height <= 0) {
+    warnUnmeasuredCell(width, height);
     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) {
+  const col0 = Math.floor((e.clientX - rect.left) / width);
+  if (grid === null) {
+    const row0 = Math.floor((e.clientY - rect.top) / height);
+    if (col0 < 0 || row0 < 0) {
+      return null;
+    }
+    return { col: col0 + 1, row: row0 + 1 };
+  }
+  // The screen window is the TAIL of the content, so the grid is bottom-anchored:
+  // on the primary screen a bottom-pinned view shows a PARTIAL row at the top and
+  // row 0 begins below the box's top edge, which top-anchored arithmetic reports
+  // one row out for.
+  const row0 = grid.rows - 1 - Math.floor((rect.bottom - e.clientY) / height);
+  return { col: clampToGrid(col0, grid.cols) + 1, row: clampToGrid(row0, grid.rows) + 1 };
+}
+
+/** Clamp a 0-based grid coordinate into `0..limit-1`, and never below 0. */
+function clampToGrid(value: number, limit: number): number {
+  return Math.max(0, Math.min(value, limit - 1));
+}
+
+// The grid's own box in pixels, or null while the cell is unmeasured — in which
+// case a pixel report goes out UNCLAMPED rather than being withheld: the offset
+// is still the right offset, only its bound is unknown.
+function pixelBox(
+  h: MouseInputHandler,
+  grid: { cols: number; rows: number },
+): { width: number; height: number } | null {
+  const { width, height } = h.cellSize();
+  if (width <= 0 || height <= 0) {
     return null;
   }
-  return { col, row };
+  return { width: grid.cols * width, height: grid.rows * height };
+}
+
+function warnUnmeasuredCell(width: number, height: number): void {
+  if (warnedDegenerateCell) {
+    return;
+  }
+  warnedDegenerateCell = true;
+  console.warn(
+    `vterm: mouse reports suppressed, cellSize() answered ${String(width)}x${String(height)}`,
+  );
+}
+
+function warnUnmeasuredGrid(cols: number, rows: number): void {
+  if (warnedDegenerateGrid) {
+    return;
+  }
+  warnedDegenerateGrid = true;
+  console.warn(
+    `vterm: mouse reports suppressed, gridSize() answered ${String(cols)}x${String(rows)}`,
+  );
 }
 
 function onMouseDown(e: MouseEvent): void {
-  const mode = getMouseMode();
-  if (mode === 0 || !(isMouseSGR() || isMousePixels()) || !handler) {
+  lastButtons = e.buttons;
+  if (trackingOff() || !handler) {
     return;
   }
   if (e.shiftKey) {
@@ -196,37 +421,66 @@ function onMouseDown(e: MouseEvent): void {
   if (!pos) {
     return;
   }
+  cancelPendingMotion();
   const code = buttonCode(domButtonToXterm(e.button), false, e.shiftKey, e.altKey, e.ctrlKey);
-  handler.send(encodeSGR(code, pos.col, pos.row, false));
+  if (handler.sendReport(encodeSGR(code, pos.col, pos.row, false))) {
+    // Only a DELIVERED press starts a gesture, so onMouseUp cannot report a
+    // release for a press the application never saw.
+    pressed.set(e.button, pos);
+  }
   e.preventDefault();
 }
 
 function onMouseUp(e: MouseEvent): void {
-  const mode = getMouseMode();
-  if (mode === 0 || !(isMouseSGR() || isMousePixels()) || !handler) {
-    return;
-  }
-  if (shiftBypass) {
-    // Release of a Shift-initiated (native-selection) gesture: report nothing.
-    shiftBypass = false;
+  lastButtons = e.buttons;
+  if (trackingOff() || !handler) {
     return;
   }
+  const bypassed = shiftBypass;
+  shiftBypass = false;
+  cancelPendingMotion();
   const pos = pixelToCell(e);
   if (!pos) {
+    // The record SURVIVES a release that could not be reported. `pressed` is what
+    // the application believes is held, and it was told nothing here, so
+    // resyncGesture must still find the button and cancel it on the next open.
+    return;
+  }
+  if (pressed.has(e.button)) {
+    const btn = domButtonToXterm(e.button);
+    const code = buttonCode(btn, false, e.shiftKey, e.altKey, e.ctrlKey);
+    if (handler.sendReport(encodeSGR(code, pos.col, pos.row, true))) {
+      pressed.delete(e.button); // only a DELIVERED release ends the gesture
+    }
+  }
+  if (bypassed) {
+    // The Shift-initiated gesture is the browser's (native selection), so its
+    // own default is left alone; a button recorded BEFORE the bypass began
+    // belongs to a delivered gesture and is still owed the release above.
     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));
   lastMotion = ""; // gesture over: next motion always reports
   e.preventDefault();
 }
 
+// The button to report as held: the highest-priority DOM button that is both
+// down now and recorded as delivered, or null when the application believes none
+// is. Priority matches the DOM's own left/middle/right order.
+function heldButton(buttons: number): number | null {
+  for (const button of [0, 1, 2]) {
+    if ((buttons & (BUTTONS_BIT[button] ?? 0)) !== 0 && pressed.has(button)) {
+      return button;
+    }
+  }
+  return null;
+}
+
 function onMouseMove(e: MouseEvent): void {
-  const mode = getMouseMode();
-  if (mode === 0 || !(isMouseSGR() || isMousePixels()) || !handler) {
+  lastButtons = e.buttons;
+  if (trackingOff() || !handler) {
     return;
   }
+  const mode = getMouseMode();
   if (shiftBypass && e.buttons) {
     return; // a Shift-initiated drag is a native selection; don't report it
   }
@@ -236,7 +490,11 @@ function onMouseMove(e: MouseEvent): void {
   if (mode === 1000) {
     return;
   }
-  if (mode === 1002 && !e.buttons) {
+  // A button the application never saw pressed is not held for reporting
+  // purposes: a drag whose press was refused (or began off the element) would
+  // otherwise start a drag the pairing rule above then refuses to end.
+  const held = heldButton(e.buttons);
+  if (mode === 1002 && held === null) {
     return;
   }
   const pos = pixelToCell(e);
@@ -245,25 +503,28 @@ function onMouseMove(e: MouseEvent): void {
   }
   // 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);
+  const code = buttonCode(held ?? 3, true, e.shiftKey, e.altKey, e.ctrlKey);
   const seq = encodeSGR(code, pos.col, pos.row, false);
   if (seq === lastMotion) {
     return; // same cell, same buttons/modifiers: suppress the duplicate report
   }
   lastMotion = seq;
-  handler.send(seq);
+  // Coalesce MOTION to one report per animation frame, latest wins. Under DEC
+  // 1016 the cell dedup above does nothing, so pixel mode would otherwise emit
+  // one report per DOM mousemove.
+  pendingMotion = seq;
+  motionFrame ??= requestAnimationFrame(flushMotion);
 }
 
 function onWheel(e: WheelEvent): void {
-  const mode = getMouseMode();
-  if (mode === 0 || !(isMouseSGR() || isMousePixels()) || !handler) {
+  if (trackingOff() || !handler) {
     return;
   }
   const pos = pixelToCell(e);
   if (!pos) {
     return;
   }
+  cancelPendingMotion();
   // Wheel up = button 64, wheel down = button 65. A gesture with NO vertical
   // component — a horizontal trackpad swipe, or shift-wheel where the browser
   // routes the delta to deltaX — has no wheel button to report: xterm.js's
@@ -273,24 +534,14 @@ function onWheel(e: WheelEvent): void {
   // wheel, and letting a sideways swipe through would scroll the page instead.
   // Reporting 65 here (the pre-fix behavior, `deltaY < 0 ? 64 : 65` with no
   // zero case) scrolled the TUI DOWN on a sideways gesture.
+  //
+  // A wheel report is never coalesced: it is a NOTCH COUNT against a screen, so
+  // dropping one loses scroll distance — which is why xterm.js expands a single
+  // WheelEvent into N discrete reports.
   if (e.deltaY !== 0) {
     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));
+    handler.sendReport(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/render.ts

@@ -1355,9 +1355,7 @@ function flushRender(): void {
   const anchor = captureReadAnchor();
   try {
     flushRenderInner();
-    // A clean pass means the error condition (if any) has cleared, so give a
-    // later transient error its full retry budget again. Any backlog reschedule
-    // was already issued from flushRenderInner's own end-of-body.
+    // Clean pass: give a later transient error its full retry budget again.
     renderNoProgressStreak = 0;
   } catch (err) {
     console.error("vterm: render error", err);
@@ -1525,7 +1523,6 @@ function flushRenderInner(): void {
     }
   }
 
-  // Refresh cursor state from the window.
   const win = store.getWindow();
   const newCursorAbs = win.base + win.cursorRow;
   cursorAbs = newCursorAbs;
@@ -1538,11 +1535,9 @@ function flushRenderInner(): void {
   // resulting mode is unchanged.
   syncCursorBlink();
 
-  // Alt screen: render the ephemeral grid instead of the absolute buffer.
-  // Returning here skips the dirtyLines queueing below — safe by invariant:
-  // main-buffer rows never repaint while alt is active, and the alt-exit
-  // branch below rebuilds EVERYTHING via queueRowsViewportFirst, so any line
-  // dirtied during the alt session is repainted at exit.
+  // Skips the dirtyLines queueing below — safe: main-buffer rows never
+  // repaint while alt is active, and alt-exit rebuilds via
+  // queueRowsViewportFirst, repainting any line dirtied during the alt session.
   if (store.isAlt()) {
     const altRows = store.getAltRows();
     renderAlt(altRows);
@@ -1570,7 +1565,6 @@ function flushRenderInner(): void {
     queueRowsViewportFirst();
   }
 
-  // Queue this frame's changed rows for building.
   for (const abs of ch.dirtyLines) {
     renderQueue.add(abs);
   }
@@ -2222,6 +2216,9 @@ export function updateFontMetrics(): void {
   const measuredW = measureCellWidth();
   cellWidth = Math.round(measuredW);
   cellHeight = parseFloat(cs.lineHeight) || 17;
+  // The column count is derived from the cell, so the cache gridSize reads is
+  // stale as of this call.
+  measuredCols = 0;
   defaultSpacing = cellWidth - measuredW;
   output.style.letterSpacing = `${defaultSpacing}px`;
   document.documentElement.style.setProperty("--char-w", `${cellWidth}px`);
@@ -2255,6 +2252,13 @@ export function updateFontMetrics(): void {
 const MIN_COLS = 20;
 const MIN_ROWS = 5;
 
+// The column count of the most recent measurement, which is the count the
+// resize announce carried to the server. gridSize() reads it instead of
+// measuring, because it is called on every raw mousemove while an application
+// tracks motion and computeSize() costs a computed-style read plus two layout
+// reads. 0 until the first measurement.
+let measuredCols = 0;
+
 /**
  * Compute the integer (cols, rows) the terminal element can fit at current
  * font metrics, clamped to a minimum of 20×5. Used to decide what dimensions
@@ -2268,9 +2272,36 @@ export function computeSize(): { cols: number; rows: number } {
   const contentH = termWrap.clientHeight - padY;
   const cols = Math.max(MIN_COLS, Math.floor(contentW / cellWidth));
   const rows = Math.max(MIN_ROWS, Math.floor(contentH / cellHeight));
+  measuredCols = cols;
   return { cols, rows };
 }
 
+/**
+ * The dimensions of the grid currently ON SCREEN — what
+ * `mouse.MouseInputHandler.gridSize` wants, so a pointer resolves against the
+ * rows the reader is actually looking at.
+ *
+ * Deliberately not `computeSize()`, whose rows are the size this client WOULD
+ * like: the server's screen is last-writer-wins across every attached client
+ * and relaxes to the smallest on disconnect, so a second attached device — or
+ * any local resize before the next screen frame lands — leaves the measured
+ * height describing a grid nothing is painting. The row hit test anchors on this
+ * number rather than merely clamping to it, so a disagreement of N shifts every
+ * reported row by N. The alt grid keeps its own height, and a TUI runs there.
+ *
+ * Columns stay the measured count: the store has none to answer with (a row's
+ * trailing blank cells are trimmed off the wire) and the axis only bounds a
+ * report, where over-reporting costs nothing.
+ *
+ * Rows are 0 until the first screen frame lands, which the mouse module treats
+ * as "no grid yet" and refuses to report against — the honest answer, since
+ * nothing knows the screen's height before the server describes it.
+ */
+export function gridSize(): { cols: number; rows: number } {
+  const rows = store.isAlt() ? store.getAltRows().length : store.getWindow().height;
+  return { cols: measuredCols > 0 ? measuredCols : computeSize().cols, rows };
+}
+
 // rowTopInTermWrap returns a row element's top in termWrap's coordinate space
 // (the space every absolutely-positioned overlay — caret, predicted cursor,
 // composition view — resolves against). A bare `offsetTop` is NOT that: it is
@@ -2355,6 +2386,16 @@ export function getCursorPx(): { left: number; top: number; cellH: number } {
   };
 }
 
+/**
+ * The measured pixel size of one cell — what `mouse.MouseInputHandler.cellSize`
+ * wants. Only meaningful once `updateFontMetrics` has measured this terminal's
+ * font; before that it answers the module's power-on fallback, not the font in
+ * use.
+ */
+export function cellSize(): { width: number; height: number } {
+  return { width: cellWidth, height: cellHeight };
+}
+
 // --- Caret overlay ---
 //
 // The real cursor is a single absolutely-positioned element appended to

package/src/types.ts

@@ -119,6 +119,23 @@ export interface ResumeAckMessage {
    * old server.
    */
   historyPaging?: boolean;
+  /**
+   * The server DECLARES that it owns DEC 1004 focus for this session: it derives
+   * the answer from attachment state, every attached client's reported focus and
+   * its own keep-unfocused declaration, and honors the `focus` control. Report
+   * the terminal widget's focus with `connection.setClientFocus` and write no
+   * focus bytes. Absent (or false) means the server does not, and the client
+   * writes CSI I / CSI O itself while the application has 1004 enabled.
+   */
+  serverFocus?: boolean;
+  /**
+   * The server DECLARES that it serves the `ephemeralInput` control: a
+   * best-effort input channel it does not count against the resume ledger, for
+   * input whose value expires (mouse reports). Absent (or false) means the
+   * server does not, and `connection.sendEphemeral` falls back to reliable
+   * input rather than dropping the report.
+   */
+  ephemeralInput?: boolean;
   /**
    * The server's wire-protocol revision (third length-gated tail, absent on
    * older servers). A value OUTSIDE the client's supported range means one
@@ -258,6 +275,20 @@ export type ControlMessage =
    */
   | { type: "history"; fromAbs: number; maxLines: number }
   | { type: "ping" }
+  /**
+   * The terminal widget's focus, reported so the server can derive the DEC 1004
+   * answer for the whole session (it sees every attached client, a socket dying
+   * without a focus-out, and its own keep-unfocused declaration; the browser sees
+   * none of that). Sent only to a server that declared `serverFocus`.
+   */
+  | { type: "focus"; focused: boolean }
+  /**
+   * Best-effort input the server does not count against the resume ledger:
+   * mouse reports, whose value expires because they describe a screen that may
+   * since have been repainted. Carried as a JSON string, so an ESC is \u001b.
+   * Sent only to a server that declared `ephemeralInput`.
+   */
+  | { type: "ephemeralInput"; data: string }
   /**
    * v4 typed-framing transition (see WIRE_PROTOCOL_VERSION in
    * wire-compatibility.ts): the first

package/src/wire-binary.ts

@@ -144,7 +144,8 @@ function decodeWireBinaryInner(buf: ArrayBuffer): ServerMessage | null {
     //   >= 17 bytes: + serverEpoch (restart detection)
     //   >= 33 bytes: + committed + oldestIndex (resume gap detection)
     //   >= 35 bytes: + serverWireVersion + ackFlags (bit0 = ledgerLost,
-    //                  bit1 = historyPaging). Unknown bits are IGNORED, which
+    //                  bit1 = historyPaging, bit2 = serverFocus,
+    //                  bit3 = ephemeralInput). Unknown bits are IGNORED, which
     //                  is what lets the server add capabilities here without a
     //                  protocol bump.
     let serverEpoch: number | undefined;
@@ -153,6 +154,8 @@ function decodeWireBinaryInner(buf: ArrayBuffer): ServerMessage | null {
     let serverWireVersion: number | undefined;
     let ledgerLost: boolean | undefined;
     let historyPaging: boolean | undefined;
+    let serverFocus: boolean | undefined;
+    let ephemeralInput: boolean | undefined;
     if (buf.byteLength >= 17) {
       serverEpoch = c.u64();
     }
@@ -165,6 +168,8 @@ function decodeWireBinaryInner(buf: ArrayBuffer): ServerMessage | null {
       const ackFlags = c.u8();
       ledgerLost = (ackFlags & 1) !== 0;
       historyPaging = (ackFlags & 2) !== 0;
+      serverFocus = (ackFlags & 4) !== 0;
+      ephemeralInput = (ackFlags & 8) !== 0;
     }
     const msg: ResumeAckMessage = { type: "resumeAck", received: inputAck };
     if (serverEpoch !== undefined) {
@@ -185,6 +190,12 @@ function decodeWireBinaryInner(buf: ArrayBuffer): ServerMessage | null {
     if (historyPaging !== undefined) {
       msg.historyPaging = historyPaging;
     }
+    if (serverFocus !== undefined) {
+      msg.serverFocus = serverFocus;
+    }
+    if (ephemeralInput !== undefined) {
+      msg.ephemeralInput = ephemeralInput;
+    }
     return msg;
   }
   if (msgType === MSG_ACK_ONLY) {