@rapidmx/meet-plugin 0.14.1 → 0.16.0

package/apps/shared/relay/RelayReceiver.ts

@@ -2,11 +2,38 @@
 // Copyright (C) 2026 Jean-Philippe Steinmetz. All rights reserved.
 // SPDX-License-Identifier: MPL-2.0
 ///////////////////////////////////////////////////////////////////////////////
+import type { RelayReceiveDiagnostics, RelayReceiveStats } from "../webrtc/types.js";
 import { AudioPlayer } from "./AudioPlayer.js";
-import { decodeFragment, FrameReassembler, KIND_AUDIO } from "./frames.js";
+import { decodeFragment, type Frame, FrameReassembler, KIND_AUDIO, seqIsNewer } from "./frames.js";
 import type { AudioContextLike, RelayEnv } from "./relayEnv.js";
 import { VideoPlayer } from "./VideoPlayer.js";
 
+const SEQ_MODULUS = 0x10000;
+/** A jump in sequence numbers bigger than this is taken for the sender restarting its counter, not for that many
+ * lost frames. Ten seconds of 20 ms audio packets - far more than any real outage the stream would survive. */
+const MAX_COUNTED_SEQ_GAP = 500;
+
+/** Counts one kind's frames as they complete, and the ones the sequence numbers say never did. */
+class ReceiveCounter {
+    readonly stats: RelayReceiveStats = { framesReceived: 0, framesLost: 0, bytesReceived: 0 };
+    private lastSeq: number | undefined;
+
+    fragment(bytes: number): void {
+        this.stats.bytesReceived += bytes;
+    }
+
+    frame(frame: Frame): void {
+        this.stats.framesReceived += 1;
+        if (this.lastSeq !== undefined && seqIsNewer(frame.seq, this.lastSeq)) {
+            const missing = ((frame.seq - this.lastSeq + SEQ_MODULUS) % SEQ_MODULUS) - 1;
+            if (missing <= MAX_COUNTED_SEQ_GAP) {
+                this.stats.framesLost += missing;
+            }
+        }
+        this.lastSeq = frame.seq;
+    }
+}
+
 /** The canvas is sized to the first decoded picture; until then it is this size. */
 const INITIAL_CANVAS_WIDTH = 320;
 const INITIAL_CANVAS_HEIGHT = 240;
@@ -25,6 +52,8 @@ export class RelayReceiver {
     readonly stream: MediaStream;
     private readonly audioFrames = new FrameReassembler();
     private readonly videoFrames = new FrameReassembler();
+    private readonly audioCounter = new ReceiveCounter();
+    private readonly videoCounter = new ReceiveCounter();
     private readonly audio: AudioPlayer;
     private readonly video: VideoPlayer | undefined;
 
@@ -50,10 +79,14 @@ export class RelayReceiver {
         if (!fragment) {
             return;
         }
-        const frame = (fragment.kind === KIND_AUDIO ? this.audioFrames : this.videoFrames).push(fragment);
+        const isAudio = fragment.kind === KIND_AUDIO;
+        const counter = isAudio ? this.audioCounter : this.videoCounter;
+        counter.fragment(payload.length);
+        const frame = (isAudio ? this.audioFrames : this.videoFrames).push(fragment);
         if (!frame) {
             return;
         }
+        counter.frame(frame);
         if (frame.kind === KIND_AUDIO) {
             this.audio.push(frame);
         } else {
@@ -61,6 +94,14 @@ export class RelayReceiver {
         }
     }
 
+    /** A snapshot of what has been received from this peer - see `RelayReceiveDiagnostics`. */
+    diagnostics(): RelayReceiveDiagnostics {
+        return {
+            audio: { ...this.audioCounter.stats, ...this.audio.stats() },
+            video: { ...this.videoCounter.stats },
+        };
+    }
+
     /** Releases the decoders and ends the stream's tracks. */
     close(): void {
         this.audio.close();

package/apps/shared/relay/RelaySender.ts

@@ -2,6 +2,7 @@
 // Copyright (C) 2026 Jean-Philippe Steinmetz. All rights reserved.
 // SPDX-License-Identifier: MPL-2.0
 ///////////////////////////////////////////////////////////////////////////////
+import type { RelaySendDiagnostics, RelaySendStats } from "../webrtc/types.js";
 import { AudioSender } from "./AudioSender.js";
 import { DEFAULT_MESSAGE_BYTES, fragmentFrame, type FrameKind, KIND_AUDIO, KIND_VIDEO } from "./frames.js";
 import type { RelayEnv } from "./relayEnv.js";
@@ -15,6 +16,11 @@ const SEQ_MODULUS = 0x10000;
  * otherwise treat the restarted stream as older than what it has already seen. */
 export class FramePublisher {
     private readonly seqs: Record<FrameKind, number> = { [KIND_AUDIO]: 0, [KIND_VIDEO]: 0 };
+    /** What happened to each kind's frames - for the diagnostics panel. */
+    readonly stats: Record<FrameKind, RelaySendStats> = {
+        [KIND_AUDIO]: { framesSent: 0, framesDropped: 0, bytesSent: 0 },
+        [KIND_VIDEO]: { framesSent: 0, framesDropped: 0, bytesSent: 0 },
+    };
 
     /** `send` returns whether one message was accepted by the socket. */
     /** `maxMessageBytes` is the largest message the socket may send right now (it changes when the server's `ready`
@@ -29,15 +35,20 @@ export class FramePublisher {
     publish: PublishFrame = (kind, keyFrame, data, timestampMs) => {
         const seq = this.seqs[kind];
         this.seqs[kind] = (seq + 1) % SEQ_MODULUS;
+        const stats = this.stats[kind];
         const fragments = fragmentFrame(kind, keyFrame, seq, timestampMs, data, this.maxMessageBytes());
         if (fragments.length === 0) {
+            stats.framesDropped += 1;
             return false;
         }
         for (const fragment of fragments) {
             if (!this.send(fragment)) {
+                stats.framesDropped += 1;
                 return false;
             }
+            stats.bytesSent += fragment.length;
         }
+        stats.framesSent += 1;
         return true;
     };
 }
@@ -52,15 +63,26 @@ export interface RelaySenderOptions {
 
 /** The publishing half of the relay: the two capture paths plus the frame numbering they share. */
 export class RelaySender {
+    private readonly publisher: FramePublisher;
     private readonly audio: AudioSender;
     private readonly video: VideoSender;
 
     constructor(options: RelaySenderOptions) {
-        const deps = { env: options.env, publish: new FramePublisher(options.send, options.maxMessageBytes).publish, canSend: options.canSend };
+        this.publisher = new FramePublisher(options.send, options.maxMessageBytes);
+        const deps = { env: options.env, publish: this.publisher.publish, canSend: options.canSend };
         this.audio = new AudioSender(deps);
         this.video = new VideoSender(deps);
     }
 
+    /** A snapshot of the sending counters - see `RelaySendDiagnostics`. */
+    diagnostics(): RelaySendDiagnostics {
+        return {
+            ...this.audio.captureStats(),
+            audio: { ...this.publisher.stats[KIND_AUDIO] },
+            video: { ...this.publisher.stats[KIND_VIDEO] },
+        };
+    }
+
     /** Starts or stops encoding whatever tracks are set. Stopping releases the encoders and audio nodes. */
     setActive(active: boolean): void {
         this.audio.setActive(active);

package/apps/shared/relay/RelayTransport.ts

@@ -17,6 +17,7 @@
  * negotiation, because both ends are this same code.
  */
 import { apiOrigin } from "@rapidmx/web-client/lib/util/api.js";
+import type { RelayDiagnostics } from "../webrtc/types.js";
 import { PLAYBACK_SAMPLE_RATE } from "./AudioPlayer.js";
 import { resumeAudioContext } from "./audioResume.js";
 import { RelayClient } from "./RelayClient.js";
@@ -39,6 +40,9 @@ export interface RelayTransport {
     /** Same semantics as `MeshConnectionManager.setLocalTrack`: null = send nothing for that kind. Safe to call
      * before or after `setSending`. */
     setLocalTrack(kind: "audio" | "video", track: MediaStreamTrack | null): void;
+    /** The sending counters (shared by every peer) plus what has been received from `peerId`, for the diagnostics
+     * panel - cumulative, so a caller wanting a rate keeps the previous sample. */
+    diagnostics(peerId: string): RelayDiagnostics;
     /** Closes the socket, all coders, streams and timers. Idempotent. */
     close(): void;
 }
@@ -54,7 +58,8 @@ export interface RelayTransportOptions {
 }
 
 /** The relay WebSocket's URL for a meeting: this deployment's origin (the API origin when the UI is served from a
- * different one, else the page's own), `http` becoming `ws` - the same derivation `pushUrl()` uses for `/push`.
+ * different one, else the page's own), `http` becoming `ws` - the same derivation `signalingUrl()` uses for the
+ * signaling socket.
  * `undefined` when there is no origin at all (not running in a browser). */
 export function relayUrl(meetingUid: string): string | undefined {
     const origin = apiOrigin() || (typeof window !== "undefined" ? window.location.origin : "");
@@ -68,6 +73,16 @@ const UNSUPPORTED_TRANSPORT: RelayTransport = {
     stopReceivingFrom: () => undefined,
     setSending: () => undefined,
     setLocalTrack: () => undefined,
+    diagnostics: () => ({
+        send: {
+            audioCapturedMs: 0,
+            audioCaptureWallMs: 0,
+            audioSilentMs: 0,
+            audioEncoderSkippedMs: 0,
+            audio: { framesSent: 0, framesDropped: 0, bytesSent: 0 },
+            video: { framesSent: 0, framesDropped: 0, bytesSent: 0 },
+        },
+    }),
     close: () => undefined,
 };
 
@@ -90,6 +105,7 @@ class WebSocketRelayTransport implements RelayTransport {
             peerId,
             createSocket: (target) => env.createSocket(target),
             random: () => env.random(),
+            now: () => env.now(),
             onMedia: (sender, payload) => this.receivers.get(sender)?.handleMedia(payload),
         });
         this.sender = new RelaySender({
@@ -140,6 +156,10 @@ class WebSocketRelayTransport implements RelayTransport {
         }
     }
 
+    diagnostics(peerId: string): RelayDiagnostics {
+        return { roundTripMs: this.client.roundTripMs, send: this.sender.diagnostics(), receive: this.receivers.get(peerId)?.diagnostics() };
+    }
+
     close(): void {
         if (this.closed) {
             return;

package/apps/shared/relay/SilenceMeter.ts

@@ -0,0 +1,59 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz. All rights reserved.
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+
+/** A sample this close to zero counts as silent: about -80 dBFS, well under the noise floor of any real microphone
+ * (even through noise suppression), so only digital silence - a zero-filled block - falls below it. */
+export const SILENCE_THRESHOLD = 1e-4;
+/** A run of silent samples counts only once it lasts this long, so a waveform merely crossing zero never does. */
+export const MIN_SILENT_RUN_SECONDS = 0.005;
+
+/**
+ * Measures how much of a PCM stream is digital silence, for the relay's diagnostics. A live microphone always carries
+ * some noise, so stretches of exact (or near-exact) zero mean the audio was lost or zero-filled somewhere on its way,
+ * not that the room went quiet. Runs are tracked across `feed()` calls, so a gap that straddles two blocks counts in
+ * full.
+ */
+export class SilenceMeter {
+    private totalSeconds = 0;
+    private silentSeconds = 0;
+    private run = 0;
+    private runRate = 0;
+
+    /** Adds one block of `sampleRate` Hz samples. */
+    feed(samples: Float32Array, sampleRate: number): void {
+        if (sampleRate !== this.runRate) {
+            this.endRun();
+            this.runRate = sampleRate;
+        }
+        for (const sample of samples) {
+            if (Math.abs(sample) < SILENCE_THRESHOLD) {
+                this.run += 1;
+            } else if (this.run > 0) {
+                this.endRun();
+            }
+        }
+        this.totalSeconds += samples.length / sampleRate;
+    }
+
+    /** Milliseconds of audio fed so far. */
+    get totalMs(): number {
+        return this.totalSeconds * 1000;
+    }
+
+    /** Milliseconds of it that were silent - including a silent run still in progress once it is long enough. */
+    get silentMs(): number {
+        return (this.silentSeconds + this.runSeconds(this.run)) * 1000;
+    }
+
+    private runSeconds(run: number): number {
+        const seconds = this.runRate > 0 ? run / this.runRate : 0;
+        return seconds >= MIN_SILENT_RUN_SECONDS ? seconds : 0;
+    }
+
+    private endRun(): void {
+        this.silentSeconds += this.runSeconds(this.run);
+        this.run = 0;
+    }
+}

package/apps/shared/relay/relayEnv.ts

@@ -134,7 +134,7 @@ export interface VideoElementLike {
     pause(): void;
 }
 
-/** The subset of `WebSocket` the relay client uses (the same seam shape `GuestSignalingClient`'s `PushSocket` has). */
+/** The subset of `WebSocket` the relay client uses (the same seam shape `SignalingClient`'s `SignalingSocket` has). */
 export interface RelaySocket {
     readyState: number;
     /** Bytes queued by `send()` that the browser has not yet handed to the network - the backpressure signal. */

package/apps/shared/signaling/SignalingClient.ts

@@ -0,0 +1,335 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz. All rights reserved.
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * The `SignalingChannel` (`../webrtc/types.js`) of a call: one WebSocket to this plugin's own signaling route
+ * (`BaseVideoMeetingRoute.signal()`, `wss://<origin>/api/mail/video-meetings/signal/<meetingUid>`), carrying every
+ * `SignalMessage` both ways - see the backend's `SignalingHub` for the protocol this speaks:
+ *
+ * - Once the socket opens, it says `{"op":"hello","v":1,"peer":<this tab's peer id>}`; the server answers
+ * `{"op":"ready","v":1,"maxMessageBytes":N}` and `connect()` resolves.
+ * - `send()` writes `{"op":"signal","data":<message>}`. The server stamps `from`/`peer` itself, and delivers a message
+ * with `to` to that peer only - so unlike the shared `/push` channel this replaced, nobody receives offers, answers or
+ * ICE candidates meant for someone else, and the client never sees its own messages echoed back.
+ * - A message the server delivers arrives as `{"op":"signal","data":...}` and is handed to every `onMessage()` listener.
+ * - A `ping` every `SIGNALING_KEEPALIVE_MS` keeps proxies from closing an idle socket.
+ *
+ * ## Authentication
+ *
+ * A browser `WebSocket` cannot send an `Authorization` header, so the upgrade is authenticated by the `jwt` cookie.
+ * For a guest (`token` given - `VideoMeetingJoinResult.authenticated` is `false`) this client sets that cookie to the
+ * guest token right before connecting (`applyAuthCookie()`), and expires it on `close()`; the media relay's own
+ * socket (`../relay/RelayClient.ts`) then authenticates with the same cookie. For a caller already signed in to RapidMX
+ * (`token` omitted) it writes nothing: a script cannot overwrite the real `HttpOnly` session cookie anyway, and that
+ * session is the identity `join()` granted.
+ *
+ * ## Losing the connection
+ *
+ * A socket that drops after `connect()` resolved is reopened with jittered exponential backoff, says `hello` again
+ * and carries on; whatever was sent meanwhile is held (up to `SIGNALING_MAX_QUEUED`, oldest dropped first) and sent
+ * once the new socket is ready. A close with 1008 is the server refusing the socket - no grant, the meeting ended,
+ * the participant was removed - and is final: before `connect()` resolved it rejects `connect()`, after that it
+ * calls `onClosed` with the server's reason. (The one 1008 that is not final, "Replaced.", only ever reaches a socket
+ * this client has already let go of.)
+ */
+import { apiOrigin } from "@rapidmx/web-client/lib/util/api.js";
+import type { SignalMessage, SignalingChannel } from "../webrtc/types.js";
+
+/** The version of the signaling wire protocol this client speaks - `SignalingHub`'s `SIGNALING_PROTOCOL_VERSION`. */
+export const SIGNALING_PROTOCOL_VERSION = 1;
+
+/** The first reconnect waits about this long, doubling on each further failure up to `SIGNALING_BACKOFF_MAX_MS`. */
+export const SIGNALING_BACKOFF_BASE_MS = 1_000;
+export const SIGNALING_BACKOFF_MAX_MS = 30_000;
+
+/** How often an idle socket is pinged. */
+export const SIGNALING_KEEPALIVE_MS = 25_000;
+
+/** The most messages held while the socket is not ready. */
+export const SIGNALING_MAX_QUEUED = 256;
+
+/** What the server allows per message until it says otherwise in `ready` - its smallest possible limit. */
+export const SIGNALING_DEFAULT_MAX_MESSAGE_BYTES: number = 16 * 1024;
+
+/** The reason the server closes the socket with once the participant is removed from the meeting - `SignalingHub`'s
+ * `SIGNALING_EVICTED_REASON` (`apps/` cannot import from the backend's `src/`, so this mirrors it). */
+export const SIGNALING_EVICTED_REASON = "Removed from the meeting.";
+
+/** The subset of the browser's `WebSocket` this client uses, so a test's fake can be a plain object. */
+export interface SignalingSocket {
+    readyState: number;
+    send(data: string): void;
+    close(code?: number, reason?: string): void;
+    onopen: ((event: unknown) => void) | null;
+    onmessage: ((event: { data: unknown }) => void) | null;
+    onclose: ((event: { code?: number; reason?: string }) => void) | null;
+    onerror: ((event: unknown) => void) | null;
+}
+
+export type SignalingSocketFactory = (url: string) => SignalingSocket;
+
+const SOCKET_OPEN = 1;
+
+/** The cookie name `JWTStrategyOptions.cookieName` defaults to (and this deployment always uses). */
+const AUTH_COOKIE_NAME = "jwt";
+
+/** The signaling WebSocket's URL for a meeting - the same origin derivation as the relay's `relayUrl()`. `undefined`
+ * when there is no origin at all (not running in a browser). */
+export function signalingUrl(meetingUid: string): string | undefined {
+    const origin = apiOrigin() || (typeof window !== "undefined" ? window.location.origin : "");
+    return origin ? `${origin.replace(/^http/i, "ws")}/api/mail/video-meetings/signal/${encodeURIComponent(meetingUid)}` : undefined;
+}
+
+function defaultSocketFactory(): SignalingSocketFactory | undefined {
+    return typeof WebSocket === "undefined" ? undefined : (url) => new WebSocket(url) as unknown as SignalingSocket;
+}
+
+export interface SignalingClientOptions {
+    /** The meeting's uid. */
+    meetingUid: string;
+    /** This tab's peer id (`<uid>~<random>` - see `_CallView.tsx`'s `newPeerId()`), announced in `hello`. */
+    peerId: string;
+    /** The guest JWT from `VideoMeetingJoinResult.token`; omitted for a caller already signed in - see this module's
+     * doc comment on authentication. */
+    token?: string;
+    /** Called once when the server closes the socket for good after `connect()` resolved, with its reason. */
+    onClosed?: (reason: string) => void;
+    /** Overrides `signalingUrl(meetingUid)`. */
+    url?: string;
+    createSocket?: SignalingSocketFactory;
+    /** Overrides `document`, for a test - see `applyAuthCookie()`. */
+    documentRef?: Pick<Document, "cookie"> & { location?: Pick<Location, "protocol"> };
+    random?: () => number;
+}
+
+export class SignalingClient implements SignalingChannel {
+    private socket: SignalingSocket | undefined;
+    private ready = false;
+    private closed = false;
+    private everReady = false;
+    private attempt = 0;
+    private reconnectTimer: ReturnType<typeof setTimeout> | undefined;
+    private keepaliveTimer: ReturnType<typeof setInterval> | undefined;
+    private cookieApplied = false;
+    private maxBytes: number = SIGNALING_DEFAULT_MAX_MESSAGE_BYTES;
+    private readonly queue: string[] = [];
+    private readonly listeners = new Set<(message: SignalMessage) => void>();
+    private pendingConnect: { resolve: () => void; reject: (err: Error) => void } | undefined;
+
+    constructor(private readonly options: SignalingClientOptions) {}
+
+    /** The largest message (the whole `signal` envelope, in bytes) the server accepts - what its `ready` said. */
+    get maxMessageBytes(): number {
+        return this.maxBytes;
+    }
+
+    /** Opens the socket and resolves once the server is ready; rejects when the server refuses it, or there is no way
+     * to open one at all (no `WebSocket`, no origin). Calling it on a closed client rejects at once. */
+    connect(): Promise<void> {
+        if (this.closed) {
+            return Promise.reject(new Error("This signaling client has already been closed."));
+        }
+        return new Promise<void>((resolve, reject) => {
+            this.pendingConnect = { resolve, reject };
+            this.openSocket();
+        });
+    }
+
+    /** Closes the socket, stops reconnecting and clears the guest auth cookie this client applied - idempotent. */
+    close(): void {
+        if (this.closed) {
+            return;
+        }
+        this.closed = true;
+        this.ready = false;
+        clearTimeout(this.reconnectTimer);
+        this.stopKeepalive();
+        const socket = this.socket;
+        this.socket = undefined;
+        if (socket) {
+            socket.onopen = socket.onmessage = socket.onclose = socket.onerror = null;
+            try {
+                socket.close(1000, "closing");
+            } catch {
+                // Already gone.
+            }
+        }
+        this.clearAuthCookie();
+        this.listeners.clear();
+        this.queue.length = 0;
+        this.pendingConnect?.reject(new Error("Closed before the signaling channel connected."));
+        this.pendingConnect = undefined;
+    }
+
+    onMessage(handler: (message: SignalMessage) => void): () => void {
+        this.listeners.add(handler);
+        return () => this.listeners.delete(handler);
+    }
+
+    /** Sends `message` now, or once the socket is ready again - see this module's doc comment. A no-op once closed. */
+    send(message: SignalMessage): void {
+        if (this.closed) {
+            return;
+        }
+        const text = JSON.stringify({ op: "signal", data: message });
+        // Straight out only when nothing is waiting, so a message never overtakes one queued before it.
+        if (this.ready && this.queue.length === 0 && this.write(text)) {
+            return;
+        }
+        if (this.queue.length >= SIGNALING_MAX_QUEUED) {
+            this.queue.shift();
+        }
+        this.queue.push(text);
+    }
+
+    private openSocket(): void {
+        const url = this.options.url ?? signalingUrl(this.options.meetingUid);
+        const createSocket = this.options.createSocket ?? defaultSocketFactory();
+        if (!url || !createSocket) {
+            this.fail(new Error("This browser (or this page's connection) doesn't support the signaling channel."));
+            return;
+        }
+        this.applyAuthCookie();
+        let socket: SignalingSocket;
+        try {
+            socket = createSocket(url);
+        } catch {
+            this.scheduleReconnect();
+            return;
+        }
+        this.socket = socket;
+        socket.onopen = () => this.write(JSON.stringify({ op: "hello", v: SIGNALING_PROTOCOL_VERSION, peer: this.options.peerId }));
+        socket.onmessage = (event) => this.handleFrame(event.data);
+        socket.onclose = (event) => {
+            if (this.socket !== socket) {
+                return;
+            }
+            this.socket = undefined;
+            this.ready = false;
+            this.stopKeepalive();
+            if (event?.code === 1008) {
+                this.refused(event.reason || "The meeting refused the connection.");
+                return;
+            }
+            this.scheduleReconnect();
+        };
+        // An error is always followed by a close, which decides what happens next.
+        socket.onerror = () => undefined;
+    }
+
+    private handleFrame(raw: unknown): void {
+        if (typeof raw !== "string") {
+            return;
+        }
+        let frame: { op?: unknown; data?: unknown; maxMessageBytes?: unknown };
+        try {
+            const parsed: unknown = JSON.parse(raw);
+            if (!parsed || typeof parsed !== "object") {
+                return;
+            }
+            frame = parsed;
+        } catch {
+            return;
+        }
+        if (frame.op === "ready") {
+            this.handleReady(frame.maxMessageBytes);
+        } else if (frame.op === "signal" && frame.data && typeof frame.data === "object") {
+            for (const listener of [...this.listeners]) {
+                listener(frame.data as SignalMessage);
+            }
+        }
+    }
+
+    private handleReady(maxMessageBytes: unknown): void {
+        if (typeof maxMessageBytes === "number" && Number.isFinite(maxMessageBytes) && maxMessageBytes > 0) {
+            this.maxBytes = maxMessageBytes;
+        }
+        this.ready = true;
+        this.everReady = true;
+        this.attempt = 0;
+        this.startKeepalive();
+        while (this.queue.length > 0 && this.write(this.queue[0])) {
+            this.queue.shift();
+        }
+        this.pendingConnect?.resolve();
+        this.pendingConnect = undefined;
+    }
+
+    /** Writes `text` to the open socket; `false` when there is none or it threw. */
+    private write(text: string): boolean {
+        const socket = this.socket;
+        if (!socket || socket.readyState !== SOCKET_OPEN) {
+            return false;
+        }
+        try {
+            socket.send(text);
+            return true;
+        } catch {
+            return false;
+        }
+    }
+
+    private startKeepalive(): void {
+        this.stopKeepalive();
+        this.keepaliveTimer = setInterval(() => this.write(JSON.stringify({ op: "ping", t: Date.now() })), SIGNALING_KEEPALIVE_MS);
+    }
+
+    private stopKeepalive(): void {
+        clearInterval(this.keepaliveTimer);
+        this.keepaliveTimer = undefined;
+    }
+
+    private scheduleReconnect(): void {
+        if (this.closed) {
+            return;
+        }
+        const ceiling = Math.min(SIGNALING_BACKOFF_MAX_MS, SIGNALING_BACKOFF_BASE_MS * 2 ** Math.min(this.attempt, 10));
+        const delay = ceiling / 2 + ((this.options.random ?? Math.random)() * ceiling) / 2;
+        this.attempt += 1;
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = undefined;
+            this.openSocket();
+        }, delay);
+    }
+
+    /** The server closed the socket for good - see this module's doc comment. */
+    private refused(reason: string): void {
+        if (this.pendingConnect) {
+            this.fail(new Error(reason));
+            return;
+        }
+        if (this.everReady) {
+            this.options.onClosed?.(reason);
+        }
+    }
+
+    private fail(err: Error): void {
+        this.pendingConnect?.reject(err);
+        this.pendingConnect = undefined;
+    }
+
+    /** Sets the `jwt` cookie to the guest `token`, so the browser attaches it to the upgrade this client is about to
+     * open - see this module's doc comment. A no-op without a token or a document. */
+    private applyAuthCookie(): void {
+        if (!this.options.token) {
+            return;
+        }
+        const doc = this.options.documentRef ?? (typeof document === "undefined" ? undefined : document);
+        if (!doc) {
+            return;
+        }
+        this.cookieApplied = true;
+        const secure = (doc.location ?? (typeof location === "undefined" ? undefined : location))?.protocol === "https:" ? "; Secure" : "";
+        doc.cookie = `${AUTH_COOKIE_NAME}=${encodeURIComponent(this.options.token)}; path=/; SameSite=Lax${secure}`;
+    }
+
+    /** Expires the cookie `applyAuthCookie()` set; a no-op when it set none. */
+    private clearAuthCookie(): void {
+        if (!this.cookieApplied) {
+            return;
+        }
+        const doc = this.options.documentRef ?? (typeof document === "undefined" ? undefined : document);
+        doc!.cookie = `${AUTH_COOKIE_NAME}=; path=/; Max-Age=0`;
+    }
+}