@cplieger/web-terminal-engine 3.0.7 → 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.0.7",
+  "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.0.7",
+  "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,19 +19,23 @@
     "@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.0",
+    "happy-dom": "20.11.1",
     "pngjs": "7.0.0",
     "prettier": "3.9.6",
     "typescript": "npm:@typescript/typescript6@6.0.2",
     "typescript-eslint": "8.65.0",
     "vitest": "4.1.10"
   },
+  "overrides": {
+    "qs": "^6.15.2"
+  },
   "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": {
@@ -47,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/render.ts

@@ -669,8 +669,80 @@ function scheduleFlush(): void {
   pendingFrame = requestAnimationFrame(flushRender);
 }
 
+// --- Read-position anchoring (manual scroll anchoring) ---
+//
+// A flush can change the content height ABOVE the reading position: rows evicted
+// from the top of history once the retention cap is reached, and the trim marker
+// appearing. Every such change moves whatever the user is reading, unless the
+// viewport is shifted by the same amount.
+//
+// Chrome and Firefox do that natively (scroll anchoring, `overflow-anchor`).
+// WebKit does not implement it at all, so on Safari — including the iPad, where
+// this UI mostly runs — a user scrolled up to read had their position dragged
+// one line per evicted row for as long as output kept arriving.
+//
+// The anchor is the first row at or below the viewport top, found by binary
+// search over the container's children: they are in document order, so their
+// offsetTop is monotonic. ~13 reads for a full 5000-row buffer, and only while
+// the user is actually scrolled up — a following viewport takes this path not at
+// all, because the bottom pin owns its position.
+interface ReadAnchor {
+  el: HTMLElement;
+  /** Where the row sat ON SCREEN: offsetTop minus the scroll offset. Measuring
+   *  the screen position rather than the container offset is what makes the
+   *  correction idempotent — see restoreReadAnchor. */
+  screenTop: number;
+}
+
+function captureReadAnchor(): ReadAnchor | null {
+  if (!scroll.isUserScrolledUp()) {
+    return null; // following: stickToBottom owns the position
+  }
+  const kids = output.children;
+  if (kids.length === 0) {
+    return null;
+  }
+  const offset = scroll.currentScrollTop();
+  let lo = 0;
+  let hi = kids.length - 1;
+  let found: HTMLElement | null = null;
+  while (lo <= hi) {
+    const mid = (lo + hi) >> 1;
+    const el = kids[mid] as HTMLElement;
+    if (el.offsetTop >= offset) {
+      found = el;
+      hi = mid - 1;
+    } else {
+      lo = mid + 1;
+    }
+  }
+  // Everything is above the viewport top (a shrink already clamped past the
+  // last row): anchor on the last row rather than giving up.
+  const el = found ?? (kids[kids.length - 1] as HTMLElement);
+  return { el, screenTop: el.offsetTop - offset };
+}
+
+function restoreReadAnchor(anchor: ReadAnchor | null): void {
+  if (anchor?.el.parentElement !== output) {
+    return; // not holding, or the anchor row was itself evicted (mass trim)
+  }
+  // Correct by how far the row DRIFTED ON SCREEN, not by how much the content
+  // above it changed. The two differ exactly when the browser already did this
+  // itself: Chrome and Firefox have native scroll anchoring, so their offsetTop
+  // change comes with a matching scrollTop change and the screen position is
+  // already right — this then measures zero drift and does nothing. Correcting
+  // the content delta instead would double-compensate there and throw the view
+  // the other way. On Safari, which has no native anchoring, the drift is the
+  // whole content delta and this is the only thing that fixes it.
+  const drift = anchor.el.offsetTop - scroll.currentScrollTop() - anchor.screenTop;
+  scroll.adjustForContentShift(drift);
+}
+
 function flushRender(): void {
   pendingFrame = undefined;
+  // Measured BEFORE any DOM mutation, so the post-mutation read below reveals
+  // exactly how much the content above the reading position moved.
+  const anchor = captureReadAnchor();
   try {
     flushRenderInner();
     // A clean pass means the error condition (if any) has cleared, so give a
@@ -704,6 +776,12 @@ function flushRender(): void {
       console.error("vterm: giving up render retry after repeated no-progress errors");
     }
   }
+  // Two position invariants, applied after every DOM mutation and in this order:
+  // hold the reader's line against content that shifted above it, then (only if
+  // following) pin to the new bottom. They are mutually exclusive by
+  // construction — the anchor is null while following — so the order is for
+  // readability, not correctness.
+  restoreReadAnchor(anchor);
   // Single auto-follow invariant, applied after every DOM mutation.
   stickToBottomIfFollowing();
 }

package/src/scroll.ts

@@ -10,8 +10,13 @@
 // failure mode; see the #web-terminal-engine steering doc, "Design rationale").
 //
 // The renderer calls stickToBottom() once after each flush: if following, pin
-// to the new bottom; if holding, do nothing and let native scroll anchoring
-// (overflow-anchor) hold the reading position when history is inserted above.
+// to the new bottom; if holding, do nothing. Holding the reading position when
+// content ABOVE it changes height (top-of-history eviction at the retention cap,
+// the trim marker appearing) is adjustForContentShift's job, called by the
+// renderer around its DOM mutations. That used to be left to native scroll
+// anchoring (overflow-anchor), which WebKit has never shipped — so on Safari and
+// iPadOS the read position slid up one line per evicted row while the user was
+// scrolled up reading.
 // Appending content at the bottom does not fire a scroll event, so following
 // stays true across new output and the post-flush pin lands correctly. Pinning
 // to the bottom produces a scroll event whose recomputation yields
@@ -148,6 +153,34 @@ export function currentScrollTop(): number {
   return scrollEl ? scrollEl.scrollTop : 0;
 }
 
+/**
+ * Shift the viewport by a content-height change that happened ABOVE the reading
+ * position, so the user keeps looking at the same line. A no-op while following
+ * (the bottom pin owns the position then) and when the delta is zero.
+ *
+ * This is scroll anchoring, done by hand. Chrome and Firefox do it natively
+ * (`overflow-anchor`), and this module's design leaned on that: "if holding, do
+ * nothing and let native scroll anchoring hold the reading position when history
+ * is inserted above". WebKit has never shipped scroll anchoring, so on Safari
+ * — including iPadOS, where this UI mostly lives — nothing compensated, and
+ * every row evicted from the top of history while the user was scrolled up
+ * reading slid their reading position one line further up. Over a streaming
+ * agent session at the retention cap that reads as "the view scrolls itself
+ * while I am trying to read".
+ *
+ * `following` is deliberately NOT touched, and neither is `lastScrollTop`: the
+ * state stays derived purely from the resulting scroll event, exactly as it is
+ * for the bottom pin. Both directions recompute to holding (an upward shift
+ * leaves a gap below; a downward one is not at the bottom), so there is no churn
+ * and no follow flip.
+ */
+export function adjustForContentShift(deltaPx: number): void {
+  if (!scrollEl || following || deltaPx === 0) {
+    return;
+  }
+  scrollEl.scrollTop += deltaPx;
+}
+
 /**
  * Restore a previously saved scroll offset (per-view scroll memory: a tabbed
  * shell re-entering a tab whose user had scrolled up to read). The offset is

package/src/status-stream.ts

@@ -9,16 +9,42 @@ import { nextBackoffDelay } from "./reconnect.js";
 
 /** SessionInfo is one session's wire shape: the JSON object the session REST
  *  API (GET/POST /api/sessions) returns per session. Mirrors the Go
- *  terminal.SessionInfo — the two are kept in lockstep by hand (single 6-field
- *  type; flip to wiregen if this surface grows). */
+ *  terminal.SessionInfo — the two are kept in lockstep by hand (single 7-field
+ *  type; flip to wiregen if this surface grows).
+ *
+ *  Three of the fields are title-shaped and they are not interchangeable:
+ *  `title` is the RESOLVED display title, `pinnedTitle` is the USER's name (set
+ *  and cleared only by a human action, outranking everything else), and
+ *  `clientTitle` is a CLIENT-DERIVED automatic title a client asked the server to
+ *  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-set title (before the OSC fallback baked into `title`); a
-   *  consumer that treats the program's OSC window title as unreliable reads
-   *  this instead of `title`. */
+  /** the raw client-derived automatic title (before the precedence baked into
+   *  `title`); a consumer that treats the program's OSC window title as
+   *  unreliable reads this instead of `title`. */
   readonly clientTitle?: string;
+  /** the user's pinned name, set through PUT /api/sessions/{id}/pinned-title and
+   *  cleared through DELETE on the same path. It outranks every automatic source
+   *  in `title`; it is carried raw so a UI can tell that a pin EXISTS (to offer
+   *  the automatic name again) rather than only seeing its effect. Absent or
+   *  empty means the session has no user-set name. */
+  readonly pinnedTitle?: string;
   readonly createdAt: string;
   /** true once the session has emitted a genuine activity signal — OSC 9;4
    *  progress (kiro-cli, Claude Code, …) or a classified OSC 9 notification.
@@ -34,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
+  }
+}