@cplieger/web-terminal-engine 5.1.0 → 5.2.0

package/README.md

@@ -93,7 +93,7 @@ document.addEventListener("keydown", (ev) => {
 - **`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)`, `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.
+- **`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 drops the report. The client writes no focus bytes in either case, because one client cannot answer for a session two devices may be attached to and a client-written `CSI I` would override a keep-unfocused policy it cannot see; the next resumeAck re-asserts the current value once the capabilities are known. 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.1.0",
+  "version": "5.2.0",
   "license": "MPL-2.0",
   "exports": {
     ".": "./src/index.ts"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/web-terminal-engine",
-  "version": "5.1.0",
+  "version": "5.2.0",
   "type": "module",
   "scripts": {
     "typecheck": "tsc -p tsconfig.json",

package/src/connection.ts

@@ -334,14 +334,6 @@ let clientFocused = false;
  */
 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;
 
@@ -362,17 +354,16 @@ function clearHistoryTimers(): void {
 /**
  * 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.
+ * capabilities, and the focus latch. 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 resetForNewSocket(): void {
   clearHistoryTimers();
   history = newHistoryState();
   caps = { ephemeralInput: false, serverFocus: false };
   focusReported = null;
-  lastFocusReportingSeen = false;
 }
 
 /**
@@ -727,35 +718,29 @@ export function sendEphemeral(text: string): boolean {
  * 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.
+ * session; where it did not, the report is dropped.
  */
 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.
+    // Focus is STATE, so a report with no socket to carry it is DROPPED rather
+    // than held: the widget's value may change again before the next socket
+    // exists, and a held report would assert a focus it may since have lost.
+    // Nothing is lost by dropping it — the resumeAck re-reports the current
+    // value on the new socket.
     return;
   }
-  if (focused === focusReported) {
+  if (!caps.serverFocus || !connState.upgraded) {
+    // A server that does not derive the answer gets NO report, because the client
+    // never writes the DEC 1004 bytes itself. Nothing is lost by dropping it: the
+    // resumeAck re-reports the current value once the capabilities are known.
     return;
   }
-  focusReported = focused;
-  if (caps.serverFocus && connState.upgraded) {
-    sendControl({ type: "focus", focused });
-    return;
-  }
-  if (!modes.isFocusReporting()) {
+  if (focused === focusReported) {
     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"));
+  focusReported = focused;
+  sendControl({ type: "focus", focused });
 }
 
 function sendControl(msg: ControlMessage): void {
@@ -1766,18 +1751,6 @@ 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);
       }

package/src/modes.ts

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

package/src/status-stream.ts

@@ -74,6 +74,21 @@ export interface SessionInfo {
    *  only when this is set; a program that emits no OSC 9 signal (a plain shell)
    *  keeps its tab dot hidden. */
   readonly reportsActivity?: boolean;
+  /** the session's SECONDARY activity: a host-reported background activity that
+   *  OUTLIVES the turn, carried beside `status` and never merged into it. The
+   *  closed set is `"working"` (a background task is running), `"waiting"`
+   *  (stopped and resumable, nobody is being asked) and `"input"` (a background
+   *  task is blocked on the user); absent or an empty string means no secondary
+   *  activity, and a consumer must tolerate an UNKNOWN value from a newer server
+   *  by rendering nothing for it.
+   *
+   *  Typed `string`, deliberately NOT a union like `status`: that union's own doc
+   *  already admits it must tolerate values outside itself, which forces a cast at
+   *  every forward-compatible site. Absent from a server that reports none. */
+  readonly activity?: string;
+  /** how many sources produced `activity`: >= 1 whenever `activity` is non-empty,
+   *  0 when it is empty or the host does not count them. */
+  readonly activityCount?: number;
 }
 
 /** SessionStatus is one session's current status as carried on the status

package/src/types.ts

@@ -122,10 +122,12 @@ export interface ResumeAckMessage {
   /**
    * 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.
+   * its own keep-unfocused declaration, and honors the `focus` control. Absent
+   * (or false) means the server does not, and the report is DROPPED — the client
+   * writes no focus bytes in either case, because one client cannot answer for a
+   * session two devices may be attached to and a client-written CSI I would
+   * override a keep-unfocused policy it cannot see. Report the terminal widget's
+   * focus with `connection.setClientFocus` regardless of this bit.
    */
   serverFocus?: boolean;
   /**