@cplieger/web-terminal-engine 3.2.0 → 3.3.0

package/README.md

@@ -84,12 +84,50 @@ document.addEventListener("keydown", (ev) => {
 - **`scroll`** — Auto-follow tracker for the scroll container. `init`, `stickToBottom`, `scrollToBottom`, `isUserScrolledUp`.
 - **`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.
+- **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.
 - **`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.
 
+## Wire compatibility manifest
+
+The same compatibility numbers are also published as a language-neutral JSON artifact, so a consumer that cannot import TypeScript — a Dockerfile, a shell release gate, a CI script in any language — can read them without scraping source:
+
+```sh
+# npm consumer
+jq -r .wireCompatibility.protocolVersion \
+  node_modules/@cplieger/web-terminal-engine/wire-compatibility.json
+
+# JSR consumer (published as an included file; JSR exports are modules only)
+curl -fsSL https://jsr.io/@cplieger/web-terminal-engine/<version>/wire-compatibility.json
+```
+
+```json
+{
+  "schemaVersion": 1,
+  "generatedBy": "web/src/wire-manifest.ts",
+  "wireCompatibility": {
+    "protocolVersion": 4,
+    "minimumServerProtocolVersion": 3,
+    "incompatibleCloseCode": 4002
+  }
+}
+```
+
+It is generated from `WIRE_COMPATIBILITY` (there is no second copy of the numbers), checked into the repo because the publish pipeline runs no build step, and guarded by a regenerate-and-diff test so it cannot go stale. Its values are pinned to both the TypeScript constants and the Go `terminal` constants, so the three surfaces cannot diverge.
+
+**What you may rely on** (semver-governed public artifact, versioned by the package version):
+
+- The file is present at the package root of every npm tarball and JSR publish, at path `wire-compatibility.json`, and is importable from npm as `@cplieger/web-terminal-engine/wire-compatibility.json`.
+- `schemaVersion` is an integer describing this file's LAYOUT, not the wire protocol. Read it first and reject a value you do not understand.
+- Within a `schemaVersion`, the fields under `wireCompatibility` keep their names, types and meanings, and equal the correspondingly named `WIRE_COMPATIBILITY` members of the same release.
+- New fields may be added under either object in a MINOR release, so parse permissively (ignore unknown keys).
+
+**What is not part of the contract**: `generatedBy` is an informational provenance note. The manifest deliberately carries no package version — the publish step injects that into `package.json` / `jsr.json` after checkout, so a version here would ship frozen at the repo placeholder; read the package version from those files.
+
+**Breaking changes to the manifest** (MAJOR, and always release-noted): removing or renaming a field, changing a field's type or meaning, moving the file, or bumping `schemaVersion`. A change to the wire revision NUMBERS is not a manifest break — reporting them is what the file is for.
+
 ## Browser-only
 
 This package depends on `document`, `HTMLElement`, `MessageChannel`, and other DOM APIs, so it only runs in browser-like environments. The companion Go server runs anywhere Go does.

package/jsr.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/web-terminal-engine",
-  "version": "3.2.0",
+  "version": "3.3.0",
   "exports": {
     ".": "./src/index.ts"
   },
@@ -8,7 +8,8 @@
     "include": [
       "LICENSE",
       "README.md",
-      "src/**/*.ts"
+      "src/**/*.ts",
+      "wire-compatibility.json"
     ],
     "exclude": [
       "src/**/*.test.ts",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/web-terminal-engine",
-  "version": "3.2.0",
+  "version": "3.3.0",
   "type": "module",
   "scripts": {
     "typecheck": "tsc -p tsconfig.json",
@@ -11,7 +11,7 @@
   "devDependencies": {
     "@cplieger/web-terminal-engine-v3": "npm:@cplieger/web-terminal-engine@2.8.0",
     "@eslint/js": "10.0.1",
-    "@playwright/test": "1.61.1",
+    "@playwright/test": "1.62.0",
     "@stryker-mutator/core": "9.6.1",
     "@stryker-mutator/typescript-checker": "9.6.1",
     "@stryker-mutator/vitest-runner": "9.6.1",
@@ -19,7 +19,7 @@
     "@typescript/native": "npm:typescript@7.0.2",
     "@vitest/coverage-v8": "4.1.10",
     "esbuild": "0.28.1",
-    "eslint": "10.7.0",
+    "eslint": "10.8.0",
     "fast-check": "4.9.0",
     "happy-dom": "20.11.1",
     "pngjs": "7.0.0",
@@ -34,7 +34,8 @@
   "description": "Browser terminal engine: VT500 screen buffer, DOM renderer, and binary wire protocol",
   "license": "GPL-3.0-or-later",
   "exports": {
-    ".": "./src/index.ts"
+    ".": "./src/index.ts",
+    "./wire-compatibility.json": "./wire-compatibility.json"
   },
   "types": "./src/index.ts",
   "publishConfig": {
@@ -50,6 +51,7 @@
     "!src/**/*.test.ts",
     "!src/**/test-helpers",
     "!src/**/fc-strict-setup.ts",
-    "jsr.json"
+    "jsr.json",
+    "wire-compatibility.json"
   ]
 }

package/src/connection.ts

@@ -278,12 +278,16 @@ export interface Callbacks {
    *  transient treatment (onClose + backoff reconnect), so existing
    *  consumers are unaffected until they opt in. */
   onProcessExit?(): void;
-  /** Fired when the server's boot-epoch in resumeAck differs from the
-   *  one observed on a previous connection — i.e. the server has
-   *  restarted. By the time this fires, the connection module has
-   *  already reset bytesSent/bytesAcked/outbox so subsequent input
-   *  starts from zero. UI should clear scrollback and surface a
-   *  banner so the user knows old input may have been lost. */
+  /** Fired when the client's queued input can no longer be trusted, which
+   *  happens two ways: the server's boot-epoch in resumeAck differs from the
+   *  one observed on a previous connection (the server restarted), or the
+   *  server no longer holds this session's input ledger AND the outbox still
+   *  held unacked bytes. A forgotten ledger whose every byte was already acked
+   *  does NOT fire this — nothing was lost, and reporting it made a phone
+   *  waking from sleep announce a restart that never happened. By the time this
+   *  fires, the connection module has already reset bytesSent/bytesAcked/outbox
+   *  so subsequent input starts from zero. UI should surface a banner so the
+   *  user knows recent input may have been lost. */
   onServerRestart?(): void;
   /** Fired when a resumeAck carries an explicit server revision outside
    *  [MIN_SUPPORTED_SERVER_WIRE_VERSION, WIRE_PROTOCOL_VERSION]. A newer
@@ -415,18 +419,51 @@ export function sendResize(): void {
   sendControl({ type: "resize", cols, rows });
 }
 
-// resetSessionAfterRestart clears a session's reliable-input accounting and
-// notifies the UI. Called when the server's boot epoch changes (restart) or when
-// the server no longer recognizes the session (received=0 with prior acks) -- both
-// invalidate the local bytesSent/bytesAcked/outbox state.
-function resetSessionAfterRestart(st: ResumeState): void {
+// 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
+// replacement counts from zero, so keeping non-zero counters would make every
+// later ack read as stale in applyAck and the outbox would never trim again.
+function resetLedger(st: ResumeState): void {
   st.bytesSent = 0;
   st.bytesAcked = 0;
   st.outbox.length = 0;
   st.outboxBytes = 0;
+}
+
+// resetSessionAfterRestart resets the ledger and tells the UI the server
+// restarted. Reserved for a boot-epoch change, which is the one cause where
+// that sentence is literally true.
+function resetSessionAfterRestart(st: ResumeState): void {
+  resetLedger(st);
   cb?.onServerRestart?.();
 }
 
+// resetForgottenLedger handles a ledger the server no longer holds (the
+// explicit ledgerLost flag, or the old-server received=0 heuristic). The server
+// forgetting a ledger is not a restart and is not by itself a loss: only the
+// UNACKED remainder was ever at risk. So the UI is notified only when there was
+// one, and a session whose every sent byte was already acked resets silently —
+// nothing can be replayed and nothing was lost.
+//
+// The silent case is the common one, and reporting it was a real defect: an
+// iPad whose screen slept for half an hour woke, reconnected, and announced a
+// server restart that never happened. Server-side, the ledger it claimed had
+// received EXACTLY as many bytes as the client claimed to have sent (10531 ==
+// 10531 in the incident logs), i.e. an empty outbox and a fully-applied
+// session, and the banner still fired.
+function resetForgottenLedger(st: ResumeState): void {
+  const lostUnacked = st.bytesSent > st.bytesAcked;
+  resetLedger(st);
+  if (lostUnacked) {
+    cb?.onServerRestart?.();
+  }
+}
+
 // applyAck drops chunks from the front of the session's outbox until the
 // running total of unacked bytes matches (bytesSent - newAck). Runs in
 // O(chunks_dropped) by tracking outboxBytes incrementally rather than
@@ -901,11 +938,12 @@ export function connect(): void {
       // tail): the resume key missed the server's registry while we claimed
       // sent bytes — our ledger was reclaimed (idle GC / cap eviction). The
       // server cannot vouch for ANY previously sent input, so replaying the
-      // outbox risks duplicate execution. Deterministic drop-and-notify,
+      // outbox risks duplicate execution. Deterministic drop, plus a notify
+      // only when unacked bytes were actually dropped (resetForgottenLedger),
       // covering the bytesAcked === 0 case the heuristic below cannot see
       // (acks that never reached us before the disconnect).
       if (msg.ledgerLost) {
-        resetSessionAfterRestart(st);
+        resetForgottenLedger(st);
         return;
       }
       // Server-doesn't-recognize-this-session safeguard (old-server
@@ -914,12 +952,12 @@ export function connect(): void {
       // our session (idle GC kicked in, or sessionId persistence failed and
       // a reload created a new one). Replaying the outbox would deliver
       // every queued chunk again, causing the iOS tab-suspend
-      // duplicate-resend bug. Drop the outbox and notify the UI as if the
-      // server restarted — input since the last successful ack is
+      // duplicate-resend bug. Drop the outbox, and notify only if it held
+      // unacked bytes — input since the last successful ack is
       // irrecoverable but at least not duplicated. Skip this branch when
       // bytesSent = 0 (genuine first-connect; received=0 is correct).
       if (msg.received === 0 && st.bytesAcked > 0) {
-        resetSessionAfterRestart(st);
+        resetForgottenLedger(st);
         return;
       }
       applyAck(st, msg.received);

package/src/status-stream.ts

@@ -19,7 +19,21 @@ import { nextBackoffDelay } from "./reconnect.js";
  *  remember. */
 export interface SessionInfo {
   readonly id: string;
-  readonly status: "working" | "idle" | "input" | "done" | "exited";
+  /** the session's current status. "working"/"idle"/"exited"/"crashed" are
+   *  derived by the server; "input"/"done" are latched from a classified OSC 9
+   *  notification; "failed" is OSC 9;4 progress state 2 and "warning" is state 4
+   *  (iTerm2 semantics), both of which PERSIST until the program changes the
+   *  progress state. "exited" and "crashed" split the session's end: "exited" is
+   *  an ordinary one (status 0, or any exit the server itself caused — a closed
+   *  session, the idle reaper, a server shutdown), "crashed" is a non-zero exit
+   *  status or a terminating signal the program was not asked for, so a routine
+   *  restart never renders as a failure. Neither is a progress state: they
+   *  outrank everything, and nothing clears them. A consumer must tolerate an
+   *  UNKNOWN status string from a newer server: the stream is parsed, not
+   *  validated, and an unrecognised value is forwarded rather than dropped
+   *  (forward compatibility across the wire floor). */
+  readonly status:
+    "working" | "idle" | "input" | "done" | "exited" | "crashed" | "failed" | "warning";
   readonly title: string;
   /** the raw client-derived automatic title (before the precedence baked into
    *  `title`); a consumer that treats the program's OSC window title as
@@ -46,6 +60,18 @@ export interface SessionInfo {
 export interface SessionStatus extends SessionInfo {
   /** true when the session is gone (closed or reaped); the consumer drops it. */
   readonly removed?: boolean;
+  /** the OSC 9;4 percentage: -1 when absent or unknown (no sequence seen, or a
+   *  state that carries none — clear/indeterminate), else 0-100. Paired with
+   *  `status` to render a determinate bar. */
+  readonly progressValue?: number;
+  /** the OSC 9 notification message, delivered to EVERY subscriber whether or
+   *  not the server has a status classifier installed. A notification is an
+   *  EVENT, not a state: it does not latch a status, so a consumer that wants a
+   *  status out of it decides that itself. */
+  readonly notification?: string;
+  /** the notification's sequence number (monotonic per session), so a repeated
+   *  message is still recognised as a new event. */
+  readonly notificationSeq?: number;
 }
 
 /** StatusStreamCallbacks are the consumer's hooks. Declared as function-typed

package/src/types.ts

@@ -123,9 +123,11 @@ export interface ResumeAckMessage {
    * claimed sent bytes: the input ledger was reclaimed (idle GC / cap
    * eviction), so the server cannot vouch for any previously sent input.
    * The connection module responds deterministically with its designed loss
-   * semantic — drop the outbox and notify (`onServerRestart`) — instead of
-   * replaying possibly-duplicate input. Absent on older servers (the
-   * `received === 0 && bytesAcked > 0` heuristic remains as their fallback).
+   * semantic — drop the outbox rather than replay possibly-duplicate input —
+   * and notifies (`onServerRestart`) only when that outbox actually held
+   * unacked bytes; a fully-acked session lost nothing and resets silently.
+   * Absent on older servers (the `received === 0 && bytesAcked > 0` heuristic
+   * remains as their fallback).
    */
   ledgerLost?: boolean;
 }

package/src/wire-manifest.ts

@@ -0,0 +1,77 @@
+// Generator for the published, language-neutral wire-compatibility manifest
+// (`web/wire-compatibility.json`).
+//
+// Why it exists: the wire revision and directional floor are published as
+// TypeScript constants (wire-compatibility.ts) and as Go constants
+// (terminal.WireProtocolVersion / MinSupportedClientWireVersion). A consumer
+// that is neither — a Dockerfile, a shell release gate, a Python CI script —
+// had no machine-readable surface to read them from and resorted to scraping
+// the TypeScript source with `sed`, which breaks silently on any reformat.
+//
+// This module renders that surface FROM the existing WIRE_COMPATIBILITY export,
+// so the numbers keep exactly one source of truth in the TypeScript half. The
+// rendered text is checked into the repo (see the drift guard in
+// wire-manifest.test.ts) because the publish pipeline runs no build step: npm
+// and JSR publish the working tree as-is, so a manifest generated at publish
+// time would never exist in the tarball.
+//
+// The manifest deliberately does NOT carry the package version. `npm pkg set
+// version` injects that at publish time, after checkout, with no regeneration
+// step — an embedded version would be frozen at the repo's placeholder (0.1.0)
+// in every published artifact. Consumers read the package version from
+// package.json / jsr.json, which the pipeline does rewrite.
+//
+// Public-artifact contract: see the "Wire compatibility manifest" section of
+// web/README.md for what a consumer may rely on and what counts as a breaking
+// change.
+
+import { WIRE_COMPATIBILITY, type WireCompatibility } from "./wire-compatibility.js";
+
+/**
+ * Schema revision of the manifest FILE, independent of the wire protocol
+ * revision it reports. A consumer must reject a `schemaVersion` it does not
+ * understand rather than guess at the shape. Bumped only for a breaking
+ * change to the manifest's own layout (a removed or repurposed field).
+ */
+export const WIRE_MANIFEST_SCHEMA_VERSION = 1;
+
+/** Path of the checked-in artifact this module renders, relative to `web/`. */
+export const WIRE_MANIFEST_PATH = "wire-compatibility.json";
+
+/** Shape of the generated wire-compatibility manifest. */
+export interface WireManifest {
+  /** Schema revision of this file's layout (see WIRE_MANIFEST_SCHEMA_VERSION). */
+  readonly schemaVersion: number;
+  /** Informational provenance note; not part of the parsed contract. */
+  readonly generatedBy: string;
+  /** The same values the TypeScript `WIRE_COMPATIBILITY` export carries. */
+  readonly wireCompatibility: WireCompatibility;
+}
+
+/**
+ * Builds the manifest object from the live TypeScript constants. Nesting the
+ * protocol values under `wireCompatibility` keeps file-level metadata
+ * (`schemaVersion`) in a separate namespace from the payload, so a future
+ * metadata field can never collide with a protocol field name.
+ */
+export function buildWireManifest(): WireManifest {
+  return {
+    schemaVersion: WIRE_MANIFEST_SCHEMA_VERSION,
+    generatedBy: "web/src/wire-manifest.ts",
+    wireCompatibility: {
+      protocolVersion: WIRE_COMPATIBILITY.protocolVersion,
+      minimumServerProtocolVersion: WIRE_COMPATIBILITY.minimumServerProtocolVersion,
+      incompatibleCloseCode: WIRE_COMPATIBILITY.incompatibleCloseCode,
+    },
+  };
+}
+
+/**
+ * Renders the exact bytes of the checked-in manifest: two-space indentation and
+ * a trailing newline, which is what `prettier --check` requires of a JSON file
+ * in this repo. Comparing rendered text (not parsed objects) is what makes the
+ * drift guard able to fail on a hand edit that happens to parse the same.
+ */
+export function renderWireManifest(): string {
+  return `${JSON.stringify(buildWireManifest(), null, 2)}\n`;
+}

package/wire-compatibility.json

@@ -0,0 +1,9 @@
+{
+  "schemaVersion": 1,
+  "generatedBy": "web/src/wire-manifest.ts",
+  "wireCompatibility": {
+    "protocolVersion": 4,
+    "minimumServerProtocolVersion": 3,
+    "incompatibleCloseCode": 4002
+  }
+}