@voltkit-rtc/client 0.6.1 → 0.7.1

package/dist/esm/network.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Network quality, from the media transports' WebRTC statistics: round-trip
+ * time, packet loss in the worse direction, and the bandwidth the browser
+ * estimates it can use. A level sums them up for a UI, with documented
+ * thresholds (docs/SDK-CONTRACT.md, "Network quality").
+ *
+ * The parsers are pure, like stats.ts: they take the stats objects of a
+ * getStats() report and the previous sample's counters.
+ */
+import type { StatsEntry } from './stats.js';
+export type NetworkQualityLevel = 'excellent' | 'good' | 'poor' | 'bad';
+export interface NetworkQuality {
+    level: NetworkQualityLevel;
+    /** Round trip to the media server, in ms; null before the browser has measured one. */
+    rttMs: number | null;
+    /** Packets lost over the last interval, in percent, the worse of sending and receiving; null when nothing moved. */
+    lossPct: number | null;
+    /** The bandwidth the browser estimates it can use, in kbps: upload while publishing, else download when reported. */
+    availableKbps: number | null;
+}
+/** How often the transports are sampled while someone listens for `networkQuality`. */
+export declare const NETWORK_QUALITY_INTERVAL_MS = 3000;
+/**
+ * The thresholds: the first level whose round trip and loss are both below
+ * its limits, else `bad`. An unknown value does not lower the level.
+ */
+export declare const NETWORK_QUALITY_LEVELS: readonly {
+    level: Exclude<NetworkQualityLevel, 'bad'>;
+    rttMsBelow: number;
+    lossPctBelow: number;
+}[];
+export declare function networkLevel(rttMs: number | null, lossPct: number | null): NetworkQualityLevel;
+/** One transport's counters at one moment; the next sample's deltas are taken against it. */
+export interface TransportSample {
+    /** The selected candidate pair's current round trip, in ms. */
+    rttMs: number | null;
+    /** The round trip RTCP reports from the server, in ms (a fallback). */
+    remoteRttMs: number | null;
+    /** RTP packets sent, and how many of them the server reported lost. */
+    packetsSent: number;
+    remotePacketsLost: number;
+    /** RTP packets received, and how many were lost on the way. */
+    packetsReceived: number;
+    packetsLost: number;
+    /** Bits per second the browser estimates it can send / receive. */
+    availableOutgoing: number | null;
+    availableIncoming: number | null;
+}
+/** The counters of one transport's report. */
+export declare function readTransportStats(report: Iterable<StatsEntry>): TransportSample;
+/**
+ * The quality now, from each transport's sample and the one before it (by
+ * key; a transport that is new, or whose counters went backwards, gives no
+ * loss for this interval). `publishing` picks the upload estimate.
+ */
+export declare function networkQualityOf(current: ReadonlyMap<string, TransportSample>, previous: ReadonlyMap<string, TransportSample>, publishing: boolean): NetworkQuality;
+/**
+ * Samples the transports on a timer while wanted and reports each interval.
+ * The first report comes as soon as a round trip is known; loss needs the
+ * previous interval's counters, so it is null until the second.
+ */
+export declare class NetworkQualityWatch {
+    /** Each live transport's report, by a key that changes when the transport does. */
+    private readonly sample;
+    private readonly publishing;
+    private readonly report;
+    private readonly intervalMs;
+    private timer;
+    private previous;
+    private sampling;
+    private generation;
+    constructor(
+    /** Each live transport's report, by a key that changes when the transport does. */
+    sample: () => Promise<Map<string, Iterable<StatsEntry>>>, publishing: () => boolean, report: (quality: NetworkQuality) => void, intervalMs?: number);
+    get running(): boolean;
+    /** Start or stop sampling. Safe to call as often as anything changes. */
+    set(wanted: boolean): void;
+    private tick;
+}
+//# sourceMappingURL=network.d.ts.map

package/dist/esm/network.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"network.d.ts","sourceRoot":"","sources":["../../src/network.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C,MAAM,MAAM,mBAAmB,GAAG,WAAW,GAAG,MAAM,GAAG,MAAM,GAAG,KAAK,CAAC;AAExE,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,mBAAmB,CAAC;IAC3B,uFAAuF;IACvF,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,oHAAoH;IACpH,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,qHAAqH;IACrH,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED,uFAAuF;AACvF,eAAO,MAAM,2BAA2B,OAAO,CAAC;AAEhD;;;GAGG;AACH,eAAO,MAAM,sBAAsB,EAAE,SAAS;IAAE,KAAK,EAAE,OAAO,CAAC,mBAAmB,EAAE,KAAK,CAAC,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,EAIrI,CAAC;AAEF,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,mBAAmB,CAK9F;AAED,6FAA6F;AAC7F,MAAM,WAAW,eAAe;IAC9B,+DAA+D;IAC/D,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,uEAAuE;IACvE,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,uEAAuE;IACvE,WAAW,EAAE,MAAM,CAAC;IACpB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,+DAA+D;IAC/D,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,mEAAmE;IACnE,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;CAClC;AAKD,8CAA8C;AAC9C,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,eAAe,CA8ChF;AAID;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,eAAe,CAAC,EAC7C,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,eAAe,CAAC,EAC9C,UAAU,EAAE,OAAO,GAClB,cAAc,CA4BhB;AAED;;;;GAIG;AACH,qBAAa,mBAAmB;IAO5B,mFAAmF;IACnF,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAV7B,OAAO,CAAC,KAAK,CAA+C;IAC5D,OAAO,CAAC,QAAQ,CAAsC;IACtD,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,UAAU,CAAK;;IAGrB,mFAAmF;IAClE,MAAM,EAAE,MAAM,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,UAAU,CAAC,CAAC,CAAC,EACxD,UAAU,EAAE,MAAM,OAAO,EACzB,MAAM,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,IAAI,EACzC,UAAU,SAA8B;IAG3D,IAAI,OAAO,IAAI,OAAO,CAErB;IAED,yEAAyE;IACzE,GAAG,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI;YAYZ,IAAI;CAsBnB"}

package/dist/esm/network.js

@@ -0,0 +1,183 @@
+/** How often the transports are sampled while someone listens for `networkQuality`. */
+export const NETWORK_QUALITY_INTERVAL_MS = 3000;
+/**
+ * The thresholds: the first level whose round trip and loss are both below
+ * its limits, else `bad`. An unknown value does not lower the level.
+ */
+export const NETWORK_QUALITY_LEVELS = [
+    { level: 'excellent', rttMsBelow: 150, lossPctBelow: 1 },
+    { level: 'good', rttMsBelow: 300, lossPctBelow: 3 },
+    { level: 'poor', rttMsBelow: 500, lossPctBelow: 8 },
+];
+export function networkLevel(rttMs, lossPct) {
+    for (const l of NETWORK_QUALITY_LEVELS) {
+        if ((rttMs === null || rttMs < l.rttMsBelow) && (lossPct === null || lossPct < l.lossPctBelow))
+            return l.level;
+    }
+    return 'bad';
+}
+const num = (value) => (typeof value === 'number' && Number.isFinite(value) ? value : 0);
+const optNum = (value) => (typeof value === 'number' && Number.isFinite(value) ? value : undefined);
+/** The counters of one transport's report. */
+export function readTransportStats(report) {
+    const entries = [...report].filter((e) => typeof e === 'object' && e !== null);
+    const byId = new Map();
+    for (const entry of entries)
+        if (typeof entry.id === 'string')
+            byId.set(entry.id, entry);
+    // The candidate pair in use: the transport's selected one, else a nominated
+    // succeeded pair (Firefox reports no transport entry).
+    let pair;
+    for (const transport of entries.filter((e) => e.type === 'transport')) {
+        const selected = typeof transport.selectedCandidatePairId === 'string' ? byId.get(transport.selectedCandidatePairId) : undefined;
+        if (selected) {
+            pair = selected;
+            break;
+        }
+    }
+    if (!pair) {
+        const pairs = entries.filter((e) => e.type === 'candidate-pair');
+        pair = pairs.find((p) => p.nominated === true && p.state === 'succeeded') ?? pairs.find((p) => p.selected === true);
+    }
+    const rtt = optNum(pair?.currentRoundTripTime);
+    let remoteRtt;
+    let packetsSent = 0;
+    let remotePacketsLost = 0;
+    let packetsReceived = 0;
+    let packetsLost = 0;
+    for (const e of entries) {
+        if (e.type === 'outbound-rtp')
+            packetsSent += num(e.packetsSent);
+        else if (e.type === 'remote-inbound-rtp') {
+            remotePacketsLost += Math.max(0, num(e.packetsLost));
+            const r = optNum(e.roundTripTime);
+            if (r !== undefined)
+                remoteRtt = Math.max(remoteRtt ?? 0, r);
+        }
+        else if (e.type === 'inbound-rtp') {
+            packetsReceived += num(e.packetsReceived);
+            packetsLost += Math.max(0, num(e.packetsLost));
+        }
+    }
+    const out = optNum(pair?.availableOutgoingBitrate);
+    const inc = optNum(pair?.availableIncomingBitrate);
+    return {
+        rttMs: rtt === undefined ? null : Math.round(rtt * 1000),
+        remoteRttMs: remoteRtt === undefined ? null : Math.round(remoteRtt * 1000),
+        packetsSent,
+        remotePacketsLost,
+        packetsReceived,
+        packetsLost,
+        availableOutgoing: out ?? null,
+        availableIncoming: inc ?? null,
+    };
+}
+const pct = (lost, total) => (total > 0 ? Math.round((Math.min(lost, total) / total) * 1000) / 10 : null);
+/**
+ * The quality now, from each transport's sample and the one before it (by
+ * key; a transport that is new, or whose counters went backwards, gives no
+ * loss for this interval). `publishing` picks the upload estimate.
+ */
+export function networkQualityOf(current, previous, publishing) {
+    let rttMs = null;
+    let lossPct = null;
+    let upload = null;
+    let download = null;
+    for (const [key, now] of current) {
+        const rtt = now.rttMs ?? now.remoteRttMs;
+        if (rtt !== null)
+            rttMs = Math.max(rttMs ?? 0, rtt);
+        if (now.availableOutgoing !== null)
+            upload = Math.max(upload ?? 0, now.availableOutgoing);
+        if (now.availableIncoming !== null)
+            download = Math.max(download ?? 0, now.availableIncoming);
+        const before = previous.get(key);
+        if (!before)
+            continue;
+        const sent = now.packetsSent - before.packetsSent;
+        const remoteLost = now.remotePacketsLost - before.remotePacketsLost;
+        const received = now.packetsReceived - before.packetsReceived;
+        const lost = now.packetsLost - before.packetsLost;
+        // Counters only go forward on one transport; backwards is a new one.
+        const up = sent >= 0 && remoteLost >= 0 ? pct(remoteLost, sent) : null;
+        const down = received >= 0 && lost >= 0 ? pct(lost, received + lost) : null;
+        for (const value of [up, down])
+            if (value !== null)
+                lossPct = Math.max(lossPct ?? 0, value);
+    }
+    const bandwidth = publishing ? upload ?? download : download ?? upload;
+    return {
+        level: networkLevel(rttMs, lossPct),
+        rttMs,
+        lossPct,
+        availableKbps: bandwidth === null ? null : Math.round(bandwidth / 1000),
+    };
+}
+/**
+ * Samples the transports on a timer while wanted and reports each interval.
+ * The first report comes as soon as a round trip is known; loss needs the
+ * previous interval's counters, so it is null until the second.
+ */
+export class NetworkQualityWatch {
+    sample;
+    publishing;
+    report;
+    intervalMs;
+    timer = null;
+    previous = new Map();
+    sampling = false;
+    generation = 0;
+    constructor(
+    /** Each live transport's report, by a key that changes when the transport does. */
+    sample, publishing, report, intervalMs = NETWORK_QUALITY_INTERVAL_MS) {
+        this.sample = sample;
+        this.publishing = publishing;
+        this.report = report;
+        this.intervalMs = intervalMs;
+    }
+    get running() {
+        return this.timer !== null;
+    }
+    /** Start or stop sampling. Safe to call as often as anything changes. */
+    set(wanted) {
+        if (wanted && !this.timer) {
+            this.timer = setInterval(() => void this.tick(), this.intervalMs);
+            void this.tick();
+        }
+        else if (!wanted && this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+            this.generation += 1;
+            this.previous = new Map();
+        }
+    }
+    async tick() {
+        if (this.sampling)
+            return;
+        const generation = this.generation;
+        this.sampling = true;
+        try {
+            const reports = await this.sample();
+            if (generation !== this.generation || !this.timer)
+                return;
+            const current = new Map();
+            for (const [key, report] of reports)
+                current.set(key, readTransportStats(report));
+            const first = this.previous.size === 0;
+            const quality = networkQualityOf(current, this.previous, this.publishing());
+            this.previous = current;
+            // Nothing to report without a transport, or before a second sample
+            // when not even the round trip is known yet.
+            if (current.size === 0 || (first && quality.rttMs === null))
+                return;
+            this.report(quality);
+        }
+        catch {
+            // Statistics are best effort; the next interval tries again.
+        }
+        finally {
+            this.sampling = false;
+        }
+    }
+}
+//# sourceMappingURL=network.js.map

package/dist/esm/network.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"network.js","sourceRoot":"","sources":["../../src/network.ts"],"names":[],"mappings":"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"}

package/dist/esm/token.d.ts

@@ -0,0 +1,17 @@
+/**
+ * When a room token expires, read from the token itself. Not verified -- the
+ * server does that -- and only used to warn before the token the SDK would
+ * reconnect with lapses (`tokenExpiring`).
+ */
+/** How long before the token's expiry `tokenExpiring` fires. */
+export declare const TOKEN_EXPIRING_LEAD_MS = 60000;
+/**
+ * The socket URL with the token as its `token` query parameter. Joined by
+ * hand rather than with `URL.searchParams`: React Native's `URL` is a partial
+ * polyfill (older releases had no `searchParams.set`), and a WebSocket URL has
+ * no fragment, so the string form is the same as the URL object's.
+ */
+export declare function socketUrl(wsUrl: string, token: string): string;
+/** The `exp` claim of a JWT, in unix milliseconds; null for a token that is not a readable JWT. */
+export declare function tokenExpiresAt(token: string): number | null;
+//# sourceMappingURL=token.d.ts.map

package/dist/esm/token.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token.d.ts","sourceRoot":"","sources":["../../src/token.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,gEAAgE;AAChE,eAAO,MAAM,sBAAsB,QAAS,CAAC;AAE7C;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAE9D;AAED,mGAAmG;AACnG,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAU3D"}

package/dist/esm/token.js

@@ -0,0 +1,31 @@
+/**
+ * When a room token expires, read from the token itself. Not verified -- the
+ * server does that -- and only used to warn before the token the SDK would
+ * reconnect with lapses (`tokenExpiring`).
+ */
+/** How long before the token's expiry `tokenExpiring` fires. */
+export const TOKEN_EXPIRING_LEAD_MS = 60_000;
+/**
+ * The socket URL with the token as its `token` query parameter. Joined by
+ * hand rather than with `URL.searchParams`: React Native's `URL` is a partial
+ * polyfill (older releases had no `searchParams.set`), and a WebSocket URL has
+ * no fragment, so the string form is the same as the URL object's.
+ */
+export function socketUrl(wsUrl, token) {
+    return `${wsUrl}${wsUrl.includes('?') ? '&' : '?'}token=${encodeURIComponent(token)}`;
+}
+/** The `exp` claim of a JWT, in unix milliseconds; null for a token that is not a readable JWT. */
+export function tokenExpiresAt(token) {
+    const payload = typeof token === 'string' ? token.split('.')[1] : undefined;
+    if (!payload || typeof globalThis.atob !== 'function')
+        return null;
+    try {
+        const base64 = payload.replace(/-/g, '+').replace(/_/g, '/');
+        const json = JSON.parse(globalThis.atob(base64 + '='.repeat((4 - (base64.length % 4)) % 4)));
+        return typeof json.exp === 'number' && Number.isFinite(json.exp) && json.exp > 0 ? json.exp * 1000 : null;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=token.js.map

package/dist/esm/token.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"token.js","sourceRoot":"","sources":["../../src/token.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,gEAAgE;AAChE,MAAM,CAAC,MAAM,sBAAsB,GAAG,MAAM,CAAC;AAE7C;;;;;GAKG;AACH,MAAM,UAAU,SAAS,CAAC,KAAa,EAAE,KAAa;IACpD,OAAO,GAAG,KAAK,GAAG,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,SAAS,kBAAkB,CAAC,KAAK,CAAC,EAAE,CAAC;AACxF,CAAC;AAED,mGAAmG;AACnG,MAAM,UAAU,cAAc,CAAC,KAAa;IAC1C,MAAM,OAAO,GAAG,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAC5E,IAAI,CAAC,OAAO,IAAI,OAAO,UAAU,CAAC,IAAI,KAAK,UAAU;QAAE,OAAO,IAAI,CAAC;IACnE,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QAC7D,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAsB,CAAC;QAClH,OAAO,OAAO,IAAI,CAAC,GAAG,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;IAC5G,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltkit-rtc/client",
-  "version": "0.6.1",
+  "version": "0.7.1",
   "description": "Browser SDK for VoltKit RTC: realtime audio/video rooms, chat and live broadcast publishing.",
   "keywords": [
     "voltkit",

package/src/broadcast.ts

@@ -75,22 +75,31 @@ export async function whipOffer(
   offerSdp: string,
   timeoutMs = WHIP_TIMEOUT_MS,
 ): Promise<{ answerSdp: string; resource: string | null }> {
+  // One deadline for the request and the whole answer: the signal stays
+  // armed while the body is read.
+  const signal = AbortSignal.timeout(timeoutMs);
+  // Never echo the URL or the error: the URL carries the publish token.
+  const failed = (err: unknown, otherwise: string) => new WhipError(0,
+    signal.aborted || (err as Error)?.name === 'TimeoutError' ? 'the media server did not answer in time' : otherwise);
   let res: Response;
   try {
     res = await fetch(whipUrl, {
       method: 'POST',
       headers: { 'Content-Type': 'application/sdp', Accept: 'application/sdp' },
       body: offerSdp,
-      signal: AbortSignal.timeout(timeoutMs),
+      signal,
     });
   } catch (err) {
-    // Never echo the URL: it carries the publish token.
-    const timedOut = (err as Error)?.name === 'TimeoutError';
-    throw new WhipError(0, timedOut
-      ? 'the media server did not answer in time'
-      : 'could not reach the media server');
+    throw failed(err, 'could not reach the media server');
+  }
+  let body: string;
+  try {
+    // A deadline or a connection lost after the headers is the same failure
+    // as one before them, and is reported the same way.
+    body = await res.text();
+  } catch (err) {
+    throw failed(err, 'the connection to the media server was lost');
   }
-  const body = await res.text();
   if (res.status !== 201 && res.status !== 200) {
     const line = body.split('\n')[0]?.trim().slice(0, 200);
     throw new WhipError(res.status, line || 'the media server refused the stream');

package/src/chat.ts

@@ -7,7 +7,9 @@
  * nothing else -- for an audience that is watching a broadcast over a CDN and
  * has no reason to be on an SFU.
  */
+import { isTerminalError } from './errors.js';
 import type { Role } from './index.js';
+import { socketUrl } from './token.js';
 
 export interface ChatMessage {
   /** Monotonic within a channel, so the oldest id held is a paging cursor. */
@@ -95,16 +97,6 @@ interface Pending {
 
 const RPC_TIMEOUT_MS = 15_000;
 const MAX_RECONNECT_ATTEMPTS = 8;
-/** A token that is wrong will be wrong next time too; retrying only adds noise. */
-const TERMINAL_JOIN_ERRORS = new Set([
-  'bad-token',
-  'no-token',
-  // The account cannot use the service until it is topped up or restored.
-  'quota-exhausted',
-  'daily-limit-reached',
-  'monthly-limit-reached',
-  'tenant-suspended',
-]);
 
 const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
 
@@ -120,6 +112,11 @@ export class ChatClient {
   private token: string;
   private joinResult: ChatJoinResult | null = null;
   private closedByUs = false;
+  /**
+   * Bumped by close(). A connect() under way when it ran -- the app's, or a
+   * reconnect's -- sees the change after its await and stops.
+   */
+  private lifecycle = 0;
   private reconnecting = false;
   private reconnectAttempt = 0;
   /** Set by the first successful join. Only a session that has joined is reconnected. */
@@ -155,10 +152,12 @@ export class ChatClient {
   }
 
   async connect(): Promise<ChatJoinResult> {
+    const lifecycle = this.lifecycle;
     let result: ChatJoinResult;
     try {
       await this.openSocket();
       result = (await this.rpc('join', { token: this.token })) as ChatJoinResult;
+      if (lifecycle !== this.lifecycle) throw new Error('the chat was closed while connecting');
     } catch (err) {
       // Never joined: the app has the error. Left open, the socket would be
       // closed by the server's join deadline, and that would start
@@ -179,9 +178,7 @@ export class ChatClient {
   private openSocket(): Promise<void> {
     this.detachSocket();
     return new Promise((resolve, reject) => {
-      const url = new URL(this.wsUrl);
-      url.searchParams.set('token', this.token);
-      const ws = new WebSocket(url.toString());
+      const ws = new WebSocket(socketUrl(this.wsUrl, this.token));
       this.ws = ws;
 
       const onError = () => reject(new Error('websocket failed to open'));
@@ -213,18 +210,28 @@ export class ChatClient {
     });
   }
 
-  private detachSocket(): void {
+  private detachSocket(reason = 'superseded'): void {
     const ws = this.ws;
     this.ws = null;
     if (ws && ws.readyState <= WebSocket.OPEN) {
       try {
-        ws.close(1000, 'superseded');
+        ws.close(1000, reason);
       } catch {
         /* already closing */
       }
     }
   }
 
+  /**
+   * A reconnect that ends the session lets go of its socket: a refused join
+   * leaves it open, and it would otherwise stay attached, and sending, after
+   * closed.
+   */
+  private releaseSocket(): void {
+    this.detachSocket('gave up');
+    this.failAllPending(new Error('the chat has ended'));
+  }
+
   /** Single-flight, with backoff: the same shape as the room client's. */
   private async scheduleReconnect(): Promise<void> {
     if (this.reconnecting || this.closedByUs) return;
@@ -234,6 +241,7 @@ export class ChatClient {
         this.reconnectAttempt += 1;
         if (this.reconnectAttempt > MAX_RECONNECT_ATTEMPTS) {
           this.emit('error', new Error(`gave up after ${MAX_RECONNECT_ATTEMPTS} reconnect attempts`));
+          this.releaseSocket();
           this.closedByUs = true;
           this.emit('closed', 'gave-up');
           return;
@@ -245,8 +253,15 @@ export class ChatClient {
           await this.connect();
           return;
         } catch (err) {
+          // Closed while this attempt was under way, and that has been
+          // reported: nothing follows closed.
+          if (this.closedByUs) return;
           this.emit('error', err as Error);
-          if (err instanceof ChatRpcError && TERMINAL_JOIN_ERRORS.has(err.code)) {
+          // A token that is wrong will be wrong next time too, and an account
+          // that ran out stays out until topped up: the registry's terminal
+          // codes, shared with StreamClient. Retrying only adds noise.
+          if (err instanceof ChatRpcError && isTerminalError(err.code)) {
+            this.releaseSocket();
             this.closedByUs = true;
             this.emit('closed', 'gave-up');
             return;
@@ -259,12 +274,20 @@ export class ChatClient {
   }
 
   close(): void {
-    if (this.closedByUs) return;
+    // Whatever socket is held is released even when the session has already
+    // ended: one opened by a connect() after an earlier close() would
+    // otherwise be out of reach. `closed` is still reported once.
+    const wasOpen = !this.closedByUs;
     this.closedByUs = true;
+    this.lifecycle += 1;
     const ws = this.ws;
     this.ws = null;
     ws?.close(1000, 'client closed');
-    this.emit('closed', 'left');
+    // Detached first, so the socket's own close handler no longer fails what
+    // was waiting on it: done here, or a join or a send in flight would wait
+    // out its 15 s timeout.
+    this.failAllPending(new Error('the chat was closed'));
+    if (wasOpen) this.emit('closed', 'left');
   }
 
   private rpc(method: string, params: unknown = {}): Promise<unknown> {
@@ -298,6 +321,9 @@ export class ChatClient {
     } catch {
       return;
     }
+    // Valid JSON that is not a message object ("null" would throw below) is
+    // ignored like any other frame that is not a message.
+    if (typeof msg !== 'object' || msg === null) return;
     if (typeof msg.id === 'number') {
       const p = this.pending.get(msg.id);
       if (!p) return;