@brass-build/client 0.1.0 → 0.2.0

package/dist/ws-client.js

@@ -4,35 +4,71 @@
 // frame when the last detaches.
 //
 // Reconnect: on `close` back off (1s..30s) and replay the "wanted-state" set
-// of topics. After ~5 minutes of failure *while foregrounded* bail and fire
-// `onError`, keeping the wanted-state so a later resume / `subscribe`
-// recovers.
-//
-// Background-tab resilience: a hidden tab throttles timers but wall-clock
-// (which the give-up budget measures) keeps advancing, so running the budget
-// while hidden would bail on a healthy connection. The reconnect loop pauses
-// while `document.hidden`; foregrounding (`visibilitychange`) or coming back
-// `online` resets the backoff + budget and reconnects with a fresh token.
+// of topics. After `RECONNECT_MAX_ATTEMPTS` consecutive failures it fires
+// `onError` once and drops to a slow retry, so a wrong verdict costs a
+// reader a delay rather than their connection. One counter both bounds and
+// paces the loop, and it counts attempts rather than time (see the
+// constant), so a hidden tab goes on reconnecting under the same bound as a
+// visible one. What clears it is a socket the server answered, or a reader
+// coming back via `visibilitychange` / `online`.
 //
 // Heartbeat: send `{ type: 'ping' }` every 60 seconds while any topic is
 // subscribed. One interval serves two purposes: it resets the server's
 // 10-minute idle timeout (only client-originated frames do), and it is the
 // presence liveness signal (the server refreshes `last_seen` on each ping;
 // the staleness threshold is 3 missed heartbeats). The server replies
-// `pong`; a topic-less `{ type: 'error', reason: 'bad_message' }` is
-// accepted as a no-op too, so a deploy without the `ping` handler is
-// tolerated. Both are dropped.
+// `pong`. A topic-less `{ type: 'error', reason: 'bad_message' }` is the
+// server's catch-all rejection, so it is swallowed rather than surfaced (a
+// deploy without the `ping` handler answers a heartbeat with it) but never
+// counted as the connection working. Both are dropped.
 import { IDLE_TOPIC, holdsFrames, step, } from './topic-lifecycle.js';
 import { SDK_CLIENT_ID } from './version.js';
 const RECONNECT_DELAYS_MS = [1000, 2000, 4000, 8000, 16000, 30000];
-const RECONNECT_GIVE_UP_MS = 5 * 60 * 1000;
+// Failed attempts before the loop reports and slows, counted rather than
+// timed because the loop's pacing is not ours: a hidden page's timers are
+// throttled to roughly one firing a minute while wall-clock runs on at full
+// speed. A budget measured in time therefore either bails on a healthy
+// connection the moment a reader tabs away, or excludes hidden time and
+// leaves a hidden page unbounded. A count measures what the loop actually
+// did, so neither the page's visibility nor the machine's clock enters into
+// it.
+//
+// Against the delays above this spans 301s, so a foregrounded page reaches it
+// in about five minutes, which is what a genuinely broken connection
+// (offline, signed out, endpoint down) looks like. A throttled one takes as
+// long as its own timers take, roughly a quarter hour. Retuning the delays
+// re-prices this, which `ws-client.test.ts` pins.
+const RECONNECT_MAX_ATTEMPTS = 15;
+// What the loop backs off to once it has passed that threshold. It keeps
+// retrying at this pace for as long as topics are wanted, so a client is
+// never left with nothing running: a misjudged connection recovers on its
+// own within one interval instead of waiting for a reader to come back.
+// Against an endpoint that is genuinely down this is the whole standing
+// cost, which is why it is minutes rather than the 30s ceiling above.
+const RECONNECT_IDLE_DELAY_MS = 5 * 60_000;
 const HEARTBEAT_INTERVAL_MS = 60_000;
+// When a socket sends its FIRST ping. The steady cadence answers API
+// Gateway's 10-minute idle timeout; this one exists so the reconnect loop
+// can tell a working connection from a flapping one.
+//
+// It is a MINIMUM LIFETIME, not a latency tweak, and that is the part to
+// keep: a `pong` is the only thing a quiet subscription can draw (a topic
+// with no activity produces its ack and then nothing), so this delay is how
+// long a socket must survive before it can clear the count. Send the first
+// ping at open instead and a backend that accepts, answers and drops in
+// 200ms credits itself on every socket, so the loop never ends and retries
+// at the 1s floor for as long as the page is open.
+//
+// A background page clamps its timers to about a minute, so a hidden reader
+// on a quiet topic falls back to the steady cadence. That page is bounded
+// rather than wrong: it parks, and returning to it clears the count. A
+// hidden page doing WORK is unaffected, because its ops draw `op_ack`.
+const HEARTBEAT_FIRST_MS = 10_000;
 // Cap on the frames held for one topic's unacked subscribe, matching the
-// `outboundQueue` bound. Both hold the same kind of mid-reconnect frames
-// (a disconnect rolls every wanted topic back to `subscribing`, so ops sent
-// during the reconnect window are HELD here rather than in `outboundQueue`),
-// so both need the same memory ceiling or a doc edited through a long outage
-// grows one queue without bound. Generous for a single user's in-flight ops.
+// `outboundQueue` bound. A disconnect rolls every wanted topic back to
+// `subscribing`, so both queues hold the same kind of mid-reconnect frame
+// and both need the same memory ceiling, or a topic written to through a
+// long outage grows one of them without bound.
 const MAX_QUEUED_FRAMES = 1024;
 export class BrassWsClient {
     opts;
@@ -54,23 +90,53 @@ export class BrassWsClient {
     topics = new Map();
     listeners = new Map();
     // Outbound frames queued while the socket is not OPEN. Drained on `open`
-    // (after subscribe replay) so an optimistic `mutate()` survives a reconnect
-    // window.
+    // (after subscribe replay) so a frame nobody re-asserts survives a
+    // reconnect window.
     outboundQueue = [];
     // Per-topic queues of frames held while `holdsFrames` says the topic's
     // subscribe is unacked: a topic-scoped frame (`presence`, `op`) sent
-    // before the `subscribed` reply races the SUB# row write and the
+    // before the `subscribed` reply races the subscription record write and the
     // server's conditional update fails as a spurious `forbidden`. The
     // machine's `flush_held` / `drop_held` effects drain or discard them.
-    // Bounded per topic (`MAX_QUEUED_FRAMES`, drop-oldest) so a doc edited
-    // through a long outage can't grow it without limit.
+    // Bounded per topic (`MAX_QUEUED_FRAMES`, drop-oldest) so a topic written
+    // to through a long outage can't grow it without limit.
     pendingTopicSends = new Map();
+    // Topics whose subscriber re-asserts its own identified frames (see
+    // `SubscribeOptions.ownsFrameRetry`). Held per topic rather than per
+    // listener because the decision is about the frame's fate on the wire,
+    // which every listener on the topic shares.
+    ownFrameRetryTopics = new Set();
     // Warn-once latch for held-queue overflow drops, reset when a topic's held
     // frames flush on the `subscribed` ack, so each unacked window reports once.
     heldOverflowReported = false;
-    reconnectAttempt = 0;
-    reconnectStartedAt = null;
+    // Consecutive failures, which paces the loop AND decides whether this
+    // connection is working at all. One number answers both, because the two
+    // questions have the same evidence behind them: a socket that opened is
+    // not progress, so pacing on opening pins the delay at the 1s floor
+    // against a backend that accepts and hangs up, at ~86,000 sockets a day
+    // per tab for zero connected time. Only a frame the server sent in answer
+    // to this client clears it.
+    failedAttempts = 0;
+    // Latches the failing report, so one incident is reported once however
+    // long it lasts.
+    reportedFailing = false;
+    // Credited frames on the CURRENT socket, reset on open. Two of them is
+    // what re-arms the latch, and the pair is the point: a single answer is
+    // survivable by a socket that dies straight after, where a second means
+    // this socket lived past `HEARTBEAT_FIRST_MS` into the steady cadence and
+    // is genuinely serving the reader. Without a recovery-observed clear the
+    // latch never lifts on its own, since `resume` returns early while a
+    // socket is open and a Node client has no `visibilitychange` to fire it,
+    // so a second outage after a recovery would go unreported for the life of
+    // the process.
+    creditsThisSocket = 0;
     reconnectTimer = null;
+    // Sockets this client has opened. Every topic and every open document
+    // rides this one socket, so the count is a fact about the client rather
+    // than about any one of them. Reported in a client's own sync-health
+    // report, where a high count beside unacked work is what distinguishes a
+    // connection that keeps dropping mid-write from one that is merely slow.
+    socketsOpened = 0;
     // Warn-once latch for outbound-queue overflow drops; reset when the queue
     // drains on a successful (re)connect, so each disconnect reports at most
     // once.
@@ -87,14 +153,22 @@ export class BrassWsClient {
     // Returns an unsubscribe that detaches THIS callback only; the WS-level
     // subscription stays open while other callbacks remain, and the unsubscribe
     // frame is sent only when the last detaches.
-    subscribe(topic, callback) {
+    subscribe(topic, callback, options = {}) {
         let set = this.listeners.get(topic);
         const firstForTopic = !set;
         if (!set) {
-            set = new Set();
+            set = new Map();
             this.listeners.set(topic, set);
         }
-        set.add(callback);
+        set.set(callback, {
+            ...(options.onSubscribed ? { onSubscribed: options.onSubscribed } : {}),
+            ...(options.onEnded ? { onEnded: options.onEnded } : {}),
+            // Attaching to an already-established subscription: the next ack this
+            // listener sees is a reconnect, and the gap since attach is real.
+            expectGap: this.topics.get(topic)?.phase === 'established',
+        });
+        if (options.ownsFrameRetry)
+            this.ownFrameRetryTopics.add(topic);
         if (firstForTopic) {
             this.dispatch(topic, { type: 'user_subscribe' });
             void this.ensureConnected();
@@ -104,7 +178,16 @@ export class BrassWsClient {
             // reconnect in flight (a prior give-up or a drop while hidden): a fresh
             // subscribe is the retry signal. (A pending reconnect timer is left
             // alone so its backoff isn't reset.)
-            this.resume();
+            //
+            // A closed client goes through the front door instead, because
+            // `resume()` refuses one and this branch would otherwise be the single
+            // retry signal with no way out: subscribing a topic the wanted-state
+            // still holds would leave the client dead for good, where subscribing
+            // any other topic recovers it.
+            if (this.closedByUser)
+                void this.ensureConnected();
+            else
+                this.resume();
         }
         return () => {
             const current = this.listeners.get(topic);
@@ -114,6 +197,7 @@ export class BrassWsClient {
             if (current.size > 0)
                 return;
             this.listeners.delete(topic);
+            this.ownFrameRetryTopics.delete(topic);
             this.dispatch(topic, { type: 'user_unsubscribe' });
             // Drop the connection once no topic is wanted, so no idle socket lingers.
             if (this.listeners.size === 0) {
@@ -140,9 +224,31 @@ export class BrassWsClient {
         else {
             this.topics.set(topic, state);
         }
+        // Teardown detaches the topic's callbacks, so the subscribers owed an
+        // end notice are captured before the effects drop them and told once the
+        // topic is released: a subscriber that closes itself from `onEnded` then
+        // finds nothing left to unsubscribe. `fire_error` carries the same reason
+        // to the session-wide channel; this notice is what reaches the one
+        // subscriber that has to give up the work it holds for the topic.
+        const ending = event.type === 'error' && effects.some((e) => e.kind === 'drop_listeners')
+            ? {
+                reason: event.reason,
+                metas: [...(this.listeners.get(topic)?.values() ?? [])],
+            }
+            : null;
         for (const effect of effects) {
             this.runEffect(topic, effect);
         }
+        if (ending) {
+            for (const meta of ending.metas) {
+                try {
+                    meta.onEnded?.({ reason: ending.reason });
+                }
+                catch {
+                    // A bad listener must not break the others or kill the read loop.
+                }
+            }
+        }
     }
     runEffect(topic, effect) {
         switch (effect.kind) {
@@ -171,6 +277,11 @@ export class BrassWsClient {
             case 'drop_listeners':
                 this.listeners.delete(topic);
                 return;
+            case 'deliver_error':
+                // Rebuilt rather than forwarded: a topic error frame is exactly
+                // these three fields.
+                this.fanOut(topic, { type: 'error', topic, reason: effect.reason });
+                return;
             case 'fire_error':
                 this.opts.fireError(new Error(`Brass WebSocket subscribe(${topic}): ${effect.reason}`));
                 return;
@@ -181,22 +292,29 @@ export class BrassWsClient {
     // ops that must survive a mid-session reconnect). Failures (overflow, closed
     // transport) are silently dropped.
     send(frame) {
-        // Topic-scoped frames sent before the `subscribed` ack race the SUB# row
+        // Topic-scoped frames sent before the `subscribed` ack race the subscription record
         // write and surface as spurious `forbidden`, so hold them until the ack
         // (see `pendingTopicSends`). The machine's `holdsFrames` covers every
         // unacked wanted state (fresh subscribe, reconnect replay, retry).
         const topic = topicOfFrame(frame);
         const topicState = topic !== undefined ? this.topics.get(topic) : undefined;
+        // Buffering this frame would duplicate it, because its owner sends it
+        // again on the next `subscribed` ack (see `ownsFrameRetry`).
+        const ownerResends = topic !== undefined &&
+            this.ownFrameRetryTopics.has(topic) &&
+            isIdentifiedFrame(frame);
         if (topic !== undefined && topicState && holdsFrames(topicState)) {
+            if (ownerResends)
+                return;
             let queue = this.pendingTopicSends.get(topic);
             if (!queue) {
                 queue = [];
                 this.pendingTopicSends.set(topic, queue);
             }
             // Bounded like `outboundQueue`: drop the oldest held frame on
-            // overflow. Safe to drop here because an op is re-asserted by the
-            // per-doc resend tracker (keyed independently on `client_op_id`), and
-            // a dropped presence frame is superseded by the next `set()`.
+            // overflow. What reaches this queue is a frame nobody re-asserts (the
+            // ones that are re-asserted took the `ownerResends` exit above), so
+            // the drop is reported.
             if (queue.length >= MAX_QUEUED_FRAMES) {
                 queue.shift();
                 if (!this.heldOverflowReported) {
@@ -214,6 +332,8 @@ export class BrassWsClient {
             this.sendFrame(frame);
             return;
         }
+        if (ownerResends)
+            return;
         // Bounded so a misbehaving caller can't leak memory; 1024 is generous for
         // a single user's mid-session ops during a reconnect (each typically <1KB).
         if (this.outboundQueue.length >= 1024) {
@@ -242,6 +362,10 @@ export class BrassWsClient {
         // continuation that is about to bail.
         this.connectEpoch++;
         this.connecting = false;
+        // `failedAttempts` deliberately survives. An app reaches `close()`
+        // routinely rather than only on teardown, so clearing it here lets a
+        // client one step from the bound start over on every cycle and the loop
+        // never ends. A frame from the server is what clears it.
         this.removeLifecycleListeners();
         if (this.reconnectTimer) {
             clearTimeout(this.reconnectTimer);
@@ -266,6 +390,10 @@ export class BrassWsClient {
         }
     }
     async ensureConnected() {
+        // The reconnect bound is deliberately not consulted here. A caller's own
+        // connect always attempts, so a client parked on the bound still reaches
+        // a network that has recovered, and the frame that comes back clears the
+        // count. What the bound stops is the unattended retry loop.
         if (this.ws && this.ws.readyState === this.ws.OPEN)
             return;
         if (this.connecting)
@@ -328,6 +456,10 @@ export class BrassWsClient {
                 // The `close` handler runs after `error` and drives reconnect;
                 // swallowing keeps a transient network error from bubbling.
             });
+            // The superseded socket's `close` is dropped by the identity guard, so
+            // `onClose` never runs for it and its heartbeat would outlive it.
+            if (prev)
+                this.stopHeartbeat();
             if (prev) {
                 try {
                     prev.close();
@@ -343,7 +475,25 @@ export class BrassWsClient {
             if (epoch !== this.connectEpoch)
                 return;
             this.connecting = false;
-            this.opts.fireError(err instanceof Error ? err : new Error(String(err)));
+            // Reported until the loop has said the connection is failing, then
+            // left to that one report. The throw here repeats on every attempt of
+            // an outage, so relaying each one turns a single incident into an
+            // error per attempt for as long as it lasts.
+            if (!this.reportedFailing) {
+                this.opts.fireError(err instanceof Error ? err : new Error(String(err)));
+            }
+            // The token and the assertion reject on a momentary outage (a shed
+            // `/refresh`), which is the same transient the reconnect loop backs
+            // off on when a live socket drops. The throw happens before any
+            // socket exists, so no `close` event drives that loop and the retry
+            // is scheduled from here, on the same backoff and the same give-up
+            // budget. A signed-out session resolves null instead and takes the
+            // branch above, which stays terminal.
+            if (this.closedByUser)
+                return;
+            if (this.listeners.size === 0)
+                return;
+            this.scheduleReconnect();
         }
     }
     buildUrl(token, assertion) {
@@ -366,8 +516,8 @@ export class BrassWsClient {
     }
     onOpen() {
         this.connecting = false;
-        this.reconnectAttempt = 0;
-        this.reconnectStartedAt = null;
+        this.socketsOpened += 1;
+        this.creditsThisSocket = 0;
         // `socket_open` per topic: re-subscribes every wanted topic (in
         // subscription order) with a fresh retry grant, and prunes `tornDown`
         // leftovers. Runs before the outbound drain so the server sees the
@@ -379,6 +529,15 @@ export class BrassWsClient {
         this.flushOutbound();
         this.startHeartbeat();
     }
+    // Re-`send` each drained frame rather than writing it straight to the
+    // socket: the topic it belongs to has just been re-subscribed and its ack
+    // is still outstanding, so a frame written now races the server's
+    // subscription record write and comes back `not_subscribed`, which tears
+    // the topic down
+    // and leaves the document deaf on a live connection. `send` applies the
+    // hold (or the drop) the topic's current state calls for. The queue is
+    // swapped out first, so a frame `send` re-queues lands in the new array
+    // instead of being re-drained here.
     flushOutbound() {
         if (!this.ws || this.ws.readyState !== this.ws.OPEN)
             return;
@@ -386,7 +545,7 @@ export class BrassWsClient {
         this.outboundQueue = [];
         this.outboundOverflowReported = false;
         for (const frame of drained) {
-            this.sendFrame(frame);
+            this.send(frame);
         }
     }
     onMessage(ev) {
@@ -403,9 +562,46 @@ export class BrassWsClient {
         const type = frame.type;
         if (typeof type !== 'string')
             return;
+        // The connection is working, so the reconnect loop starts over.
+        //
+        // What these have in common is that each ANSWERS something this client
+        // sent, which is why they read as the connection working where the rest
+        // of the protocol does not: the subscribe handshake is `subscribed` and
+        // then `doc_init` or `presence_snapshot`, so a backend that accepts,
+        // acks and hangs up would credit itself on every cycle, and an `error`
+        // frame is the server reporting it could NOT do the work.
+        //
+        // Credited as the evidence arrives rather than when the socket ends,
+        // because `close()` drops its own socket's `close` event (it nulls
+        // `this.ws` first, so the identity guard rejects it) and an app reaches
+        // `close()` routinely, so a session that ended that way would credit
+        // nothing however well it worked.
+        //
+        // Getting this wrong is survivable by design: the count decides when the
+        // loop slows and reports, not whether it runs at all, so a client this
+        // rule misjudges is late to a notification rather than disconnected.
+        if (type === 'pong' || type === 'op_ack') {
+            this.failedAttempts = 0;
+            this.creditsThisSocket += 1;
+            if (this.creditsThisSocket >= 2)
+                this.reportedFailing = false;
+        }
         if (type === 'subscribed' && typeof frame.topic === 'string') {
             // `flush_held` drains the frames held back for the unacked subscribe.
             this.dispatch(frame.topic, { type: 'subscribed_ack' });
+            const acked = this.listeners.get(frame.topic);
+            if (acked) {
+                for (const meta of acked.values()) {
+                    const resubscribed = meta.expectGap;
+                    meta.expectGap = true;
+                    try {
+                        meta.onSubscribed?.({ resubscribed });
+                    }
+                    catch {
+                        // A bad listener must not break the others or kill the read loop.
+                    }
+                }
+            }
             return;
         }
         if (type === 'unsubscribed') {
@@ -420,18 +616,22 @@ export class BrassWsClient {
         if (type === 'error') {
             const topic = typeof frame.topic === 'string' ? frame.topic : undefined;
             const reason = typeof frame.reason === 'string' ? frame.reason : 'error';
-            // A deploy without the `ping` handler replies to our ping with a
-            // topic-less `bad_message` instead of `pong`; treat it as a heartbeat
-            // ack (see the header).
+            // The server's catch-all rejection: a deploy without the `ping`
+            // handler answers a heartbeat with it, and one without the
+            // `client_report` handler answers every sync-health report with it.
+            // Swallowed so a version skew is not an error the app sees, and
+            // deliberately not credited above, since a client whose every frame is
+            // refused would otherwise read its own rejections as a healthy socket.
             if (reason === 'bad_message' && !topic)
                 return;
             if (topic) {
-                // The machine decides: silent retry, swallow, or teardown +
-                // `fire_error`. A topic with no live state (already unsubscribed
-                // or torn down our side) swallows: the canonical case is a
-                // presence-update racing a `doc_gone` eviction, whose late
-                // `forbidden` reply would otherwise surface as a misleading
-                // "subscribe(...): forbidden" with no subscribe in flight to fail.
+                // The machine decides: silent retry, delivery to the topic's
+                // callbacks, swallow, or teardown + `fire_error`. A topic with no
+                // live state (already unsubscribed or torn down our side) swallows:
+                // the canonical case is a presence-update racing a `doc_gone`
+                // eviction, whose late `forbidden` reply would otherwise surface as
+                // a misleading "subscribe(...): forbidden" with no subscribe in
+                // flight to fail.
                 this.dispatch(topic, { type: 'error', reason });
                 return;
             }
@@ -440,16 +640,19 @@ export class BrassWsClient {
         }
         // Topic-scoped server frames: fan out to every callback for the topic.
         if (typeof frame.topic === 'string') {
-            const set = this.listeners.get(frame.topic);
-            if (!set)
-                return;
-            for (const cb of set) {
-                try {
-                    cb(frame);
-                }
-                catch {
-                    // A bad listener must not break the others or kill the read loop.
-                }
+            this.fanOut(frame.topic, frame);
+        }
+    }
+    fanOut(topic, frame) {
+        const set = this.listeners.get(topic);
+        if (!set)
+            return;
+        for (const cb of set.keys()) {
+            try {
+                cb(frame);
+            }
+            catch {
+                // A bad listener must not break the others or kill the read loop.
             }
         }
     }
@@ -468,38 +671,62 @@ export class BrassWsClient {
             return;
         this.scheduleReconnect();
     }
-    scheduleReconnect() {
-        // Don't run the loop while hidden: throttled timers but advancing
-        // wall-clock would burn the give-up budget without real attempts and bail
-        // on a healthy connection. `resume()` restarts with a fresh budget on
-        // foreground / network recovery.
-        if (this.isHidden())
+    // Tell the app the connection is failing, once per incident. `onError`
+    // has no dedupe of its own and reaches every listener, so an app that
+    // surfaces it would otherwise show the same outage repeatedly: the count
+    // is cleared by any credited frame, and a flapping link supplies one every
+    // so often, which starts a fresh episode each time.
+    reportFailing() {
+        if (this.reportedFailing)
             return;
-        if (this.reconnectStartedAt === null) {
-            this.reconnectStartedAt = Date.now();
-        }
-        if (Date.now() - this.reconnectStartedAt >= RECONNECT_GIVE_UP_MS) {
-            this.opts.fireError(new Error('Brass WebSocket subscribe: reconnect gave up after 5 minutes'));
-            // Keep the wanted-state: a resume / fresh `subscribe` recovers by
-            // replaying it. The budget resets so resume starts clean; clearing
-            // listeners here would make the bail permanent (the background-tab bug
-            // this guards against).
-            this.reconnectAttempt = 0;
-            this.reconnectStartedAt = null;
-            return;
-        }
-        const idx = Math.min(this.reconnectAttempt, RECONNECT_DELAYS_MS.length - 1);
-        const delay = RECONNECT_DELAYS_MS[idx];
-        this.reconnectAttempt += 1;
+        this.reportedFailing = true;
+        this.opts.fireError(new Error(`Brass WebSocket subscribe: reconnect failing after ${RECONNECT_MAX_ATTEMPTS} attempts`));
+    }
+    scheduleReconnect() {
+        this.failedAttempts += 1;
+        if (this.failedAttempts >= RECONNECT_MAX_ATTEMPTS)
+            this.reportFailing();
+        // Past the threshold the loop SLOWS; it does not stop. Stopping is what
+        // makes a wrong verdict expensive: deciding a working connection is dead
+        // leaves a reader disconnected with nothing retrying, and every rule for
+        // telling a working connection from a failing one has some client it
+        // misjudges (a quiet topic draws no traffic, a short socket answers
+        // nothing, a flapping backend answers everything). Slowing costs one
+        // attempt every few minutes against an endpoint that is genuinely down,
+        // and it takes the whole class of "gave up on a healthy network" out of
+        // the design rather than out of the current predicate.
+        //
+        // The slow phase costs a reader who is being served by short sockets:
+        // a subscriber that never writes draws no `op_ack`, and a socket that
+        // dies before `HEARTBEAT_FIRST_MS` draws no `pong`, so frames pushed to
+        // it never speed the loop back up. Measured against a server pushing one
+        // event every 30s, that reader receives 4% of them at a 9s socket
+        // lifetime where pacing on opening receives 82%. It is the accepted
+        // cost: the signal that buys those frames back is one a hangup backend
+        // satisfies without carrying anything, which is the 86,000-sockets-a-day
+        // trade, and this reader still gets a full `doc_init` resync on every
+        // reconnect plus the failing report.
+        const delay = this.failedAttempts > RECONNECT_MAX_ATTEMPTS
+            ? RECONNECT_IDLE_DELAY_MS
+            : RECONNECT_DELAYS_MS[Math.min(this.failedAttempts - 1, RECONNECT_DELAYS_MS.length - 1)];
+        // Clear before arming. An out-of-band connect (a `send` during a backoff
+        // window) can bring this through a second time with a timer already
+        // armed, and the overwritten handle is one `close()` cannot reach: it
+        // fires afterwards, and `ensureConnected` re-enters at the front door,
+        // clearing `closedByUser` and standing a socket and heartbeat back up.
+        if (this.reconnectTimer)
+            clearTimeout(this.reconnectTimer);
         this.reconnectTimer = setTimeout(() => {
             this.reconnectTimer = null;
+            // The user may have closed us while this was armed.
+            if (this.closedByUser)
+                return;
             void this.ensureConnected();
         }, delay);
     }
-    // Foreground return / network recovery: reset the backoff + give-up budget
-    // and reconnect promptly with a fresh token instead of waiting out a long
-    // delay or staying dead after a bail. No-op when nothing is wanted, the user
-    // closed us, or a socket is already open.
+    // Foreground return / network recovery: a reader is back, so reconnect
+    // promptly with a fresh token rather than waiting out a long delay or
+    // staying parked after a bail.
     resume() {
         if (this.closedByUser)
             return;
@@ -511,10 +738,22 @@ export class BrassWsClient {
             clearTimeout(this.reconnectTimer);
             this.reconnectTimer = null;
         }
-        this.reconnectAttempt = 0;
-        this.reconnectStartedAt = null;
+        this.failedAttempts = 0;
+        this.reportedFailing = false;
         void this.ensureConnected();
     }
+    /** Reconnects this client has made: every socket after the first. */
+    get reconnectCount() {
+        return Math.max(0, this.socketsOpened - 1);
+    }
+    /** Whether the page is hidden right now. */
+    get pageHidden() {
+        return this.isHidden();
+    }
+    /** Whether a socket is open right now. */
+    get connected() {
+        return this.ws !== null && this.ws.readyState === this.ws.OPEN;
+    }
     isHidden() {
         const doc = globalThis.document;
         return doc?.hidden === true;
@@ -525,7 +764,7 @@ export class BrassWsClient {
         const doc = globalThis.document;
         if (doc && typeof doc.addEventListener === 'function') {
             const listener = () => {
-                if (doc.hidden !== true)
+                if (!this.isHidden())
                     this.resume();
             };
             this.visibilityListener = listener;
@@ -553,13 +792,19 @@ export class BrassWsClient {
     }
     startHeartbeat() {
         this.stopHeartbeat();
-        this.heartbeatTimer = setInterval(() => {
-            this.sendIfOpen({ type: 'ping' });
-        }, HEARTBEAT_INTERVAL_MS);
+        // One handle, re-armed after each ping, so the first delay can differ
+        // from the cadence without a second timer to keep in step.
+        const arm = (delay) => {
+            this.heartbeatTimer = setTimeout(() => {
+                this.sendIfOpen({ type: 'ping' });
+                arm(HEARTBEAT_INTERVAL_MS);
+            }, delay);
+        };
+        arm(HEARTBEAT_FIRST_MS);
     }
     stopHeartbeat() {
         if (this.heartbeatTimer) {
-            clearInterval(this.heartbeatTimer);
+            clearTimeout(this.heartbeatTimer);
             this.heartbeatTimer = null;
         }
     }
@@ -583,6 +828,11 @@ export class BrassWsClient {
 function isObject(value) {
     return typeof value === 'object' && value !== null;
 }
+// True for a frame the server answers by name, which is what lets a
+// subscriber that holds it re-assert exactly that frame later.
+function isIdentifiedFrame(frame) {
+    return isObject(frame) && typeof frame['client_op_id'] === 'string';
+}
 // The frame's topic, if any. `send()` uses it to decide whether the frame is
 // subject to the subscribe-pending hold (see `pendingTopicSends`). Returns
 // `undefined` for transport frames (`subscribe` / `unsubscribe` / `ping` /