@rapidmx/meet-plugin 0.14.1 → 0.16.0

package/dist/apps/shared/relay/RelaySender.d.ts

@@ -1,3 +1,5 @@
+import type { RelaySendDiagnostics, RelaySendStats } from "../webrtc/types.js";
+import { type FrameKind } from "./frames.js";
 import type { RelayEnv } from "./relayEnv.js";
 import type { PublishFrame } from "./senderCommon.js";
 /** Numbers and fragments the frames of one sender. The counters belong to the transport rather than to a capture
@@ -7,6 +9,8 @@ export declare class FramePublisher {
     private readonly send;
     private readonly maxMessageBytes;
     private readonly seqs;
+    /** What happened to each kind's frames - for the diagnostics panel. */
+    readonly stats: Record<FrameKind, RelaySendStats>;
     /** `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`
      * announces a limit), so it is read for every frame rather than fixed at construction. */
@@ -24,9 +28,12 @@ export interface RelaySenderOptions {
 }
 /** The publishing half of the relay: the two capture paths plus the frame numbering they share. */
 export declare class RelaySender {
+    private readonly publisher;
     private readonly audio;
     private readonly video;
     constructor(options: RelaySenderOptions);
+    /** A snapshot of the sending counters - see `RelaySendDiagnostics`. */
+    diagnostics(): RelaySendDiagnostics;
     /** Starts or stops encoding whatever tracks are set. Stopping releases the encoders and audio nodes. */
     setActive(active: boolean): void;
     /** `null` sends nothing for that kind. Safe before or after `setActive`. */

package/dist/apps/shared/relay/RelaySender.js

@@ -1,7 +1,3 @@
-///////////////////////////////////////////////////////////////////////////////
-// Copyright (C) 2026 Jean-Philippe Steinmetz. All rights reserved.
-// SPDX-License-Identifier: MPL-2.0
-///////////////////////////////////////////////////////////////////////////////
 import { AudioSender } from "./AudioSender.js";
 import { DEFAULT_MESSAGE_BYTES, fragmentFrame, KIND_AUDIO, KIND_VIDEO } from "./frames.js";
 import { VideoSender } from "./VideoSender.js";
@@ -17,20 +13,30 @@ export class FramePublisher {
         this.send = send;
         this.maxMessageBytes = maxMessageBytes;
         this.seqs = { [KIND_AUDIO]: 0, [KIND_VIDEO]: 0 };
+        /** What happened to each kind's frames - for the diagnostics panel. */
+        this.stats = {
+            [KIND_AUDIO]: { framesSent: 0, framesDropped: 0, bytesSent: 0 },
+            [KIND_VIDEO]: { framesSent: 0, framesDropped: 0, bytesSent: 0 },
+        };
         /** Fragments and sends one frame, stopping at the first fragment the socket refuses (the rest could not be
          * used without it). Returns whether the whole frame went out. */
         this.publish = (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;
         };
     }
@@ -38,10 +44,19 @@ export class FramePublisher {
 /** The publishing half of the relay: the two capture paths plus the frame numbering they share. */
 export class RelaySender {
     constructor(options) {
-        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() {
+        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) {
         this.audio.setActive(active);

package/dist/apps/shared/relay/RelayTransport.d.ts

@@ -1,3 +1,4 @@
+import type { RelayDiagnostics } from "../webrtc/types.js";
 import { type RelayEnv } from "./relayEnv.js";
 export interface RelayTransport {
     /** false when this browser lacks WebSocket, AudioEncoder/AudioDecoder/VideoEncoder/VideoDecoder, VideoFrame,
@@ -14,6 +15,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;
 }
@@ -27,7 +31,8 @@ export interface RelayTransportOptions {
     env?: RelayEnv;
 }
 /** 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 declare function relayUrl(meetingUid: string): string | undefined;
 /**

package/dist/apps/shared/relay/RelayTransport.js

@@ -24,7 +24,8 @@ import { detectRelayEnv } from "./relayEnv.js";
 import { RelayReceiver } from "./RelayReceiver.js";
 import { RelaySender } from "./RelaySender.js";
 /** 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) {
     const origin = apiOrigin() || (typeof window !== "undefined" ? window.location.origin : "");
@@ -37,6 +38,16 @@ const UNSUPPORTED_TRANSPORT = {
     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,
 };
 class WebSocketRelayTransport {
@@ -50,6 +61,7 @@ class WebSocketRelayTransport {
             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({
@@ -95,6 +107,9 @@ class WebSocketRelayTransport {
             this.sender.setTrack(kind, track);
         }
     }
+    diagnostics(peerId) {
+        return { roundTripMs: this.client.roundTripMs, send: this.sender.diagnostics(), receive: this.receivers.get(peerId)?.diagnostics() };
+    }
     close() {
         if (this.closed) {
             return;

package/dist/apps/shared/relay/SilenceMeter.d.ts

@@ -0,0 +1,25 @@
+/** 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 declare const SILENCE_THRESHOLD = 0.0001;
+/** A run of silent samples counts only once it lasts this long, so a waveform merely crossing zero never does. */
+export declare 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 declare class SilenceMeter {
+    private totalSeconds;
+    private silentSeconds;
+    private run;
+    private runRate;
+    /** Adds one block of `sampleRate` Hz samples. */
+    feed(samples: Float32Array, sampleRate: number): void;
+    /** Milliseconds of audio fed so far. */
+    get totalMs(): number;
+    /** Milliseconds of it that were silent - including a silent run still in progress once it is long enough. */
+    get silentMs(): number;
+    private runSeconds;
+    private endRun;
+}

package/dist/apps/shared/relay/SilenceMeter.js

@@ -0,0 +1,55 @@
+///////////////////////////////////////////////////////////////////////////////
+// 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 {
+    constructor() {
+        this.totalSeconds = 0;
+        this.silentSeconds = 0;
+        this.run = 0;
+        this.runRate = 0;
+    }
+    /** Adds one block of `sampleRate` Hz samples. */
+    feed(samples, sampleRate) {
+        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() {
+        return this.totalSeconds * 1000;
+    }
+    /** Milliseconds of it that were silent - including a silent run still in progress once it is long enough. */
+    get silentMs() {
+        return (this.silentSeconds + this.runSeconds(this.run)) * 1000;
+    }
+    runSeconds(run) {
+        const seconds = this.runRate > 0 ? run / this.runRate : 0;
+        return seconds >= MIN_SILENT_RUN_SECONDS ? seconds : 0;
+    }
+    endRun() {
+        this.silentSeconds += this.runSeconds(this.run);
+        this.run = 0;
+    }
+}

package/dist/apps/shared/relay/relayEnv.d.ts

@@ -122,7 +122,7 @@ export interface VideoElementLike {
     play(): Promise<void> | undefined;
     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/dist/apps/shared/signaling/SignalingClient.d.ts

@@ -0,0 +1,95 @@
+import type { SignalMessage, SignalingChannel } from "../webrtc/types.js";
+/** The version of the signaling wire protocol this client speaks - `SignalingHub`'s `SIGNALING_PROTOCOL_VERSION`. */
+export declare const SIGNALING_PROTOCOL_VERSION = 1;
+/** The first reconnect waits about this long, doubling on each further failure up to `SIGNALING_BACKOFF_MAX_MS`. */
+export declare const SIGNALING_BACKOFF_BASE_MS = 1000;
+export declare const SIGNALING_BACKOFF_MAX_MS = 30000;
+/** How often an idle socket is pinged. */
+export declare const SIGNALING_KEEPALIVE_MS = 25000;
+/** The most messages held while the socket is not ready. */
+export declare const SIGNALING_MAX_QUEUED = 256;
+/** What the server allows per message until it says otherwise in `ready` - its smallest possible limit. */
+export declare const SIGNALING_DEFAULT_MAX_MESSAGE_BYTES: number;
+/** 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 declare 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;
+/** 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 declare function signalingUrl(meetingUid: string): string | undefined;
+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 declare class SignalingClient implements SignalingChannel {
+    private readonly options;
+    private socket;
+    private ready;
+    private closed;
+    private everReady;
+    private attempt;
+    private reconnectTimer;
+    private keepaliveTimer;
+    private cookieApplied;
+    private maxBytes;
+    private readonly queue;
+    private readonly listeners;
+    private pendingConnect;
+    constructor(options: SignalingClientOptions);
+    /** The largest message (the whole `signal` envelope, in bytes) the server accepts - what its `ready` said. */
+    get maxMessageBytes(): number;
+    /** 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>;
+    /** Closes the socket, stops reconnecting and clears the guest auth cookie this client applied - idempotent. */
+    close(): void;
+    onMessage(handler: (message: SignalMessage) => void): () => void;
+    /** 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;
+    private openSocket;
+    private handleFrame;
+    private handleReady;
+    /** Writes `text` to the open socket; `false` when there is none or it threw. */
+    private write;
+    private startKeepalive;
+    private stopKeepalive;
+    private scheduleReconnect;
+    /** The server closed the socket for good - see this module's doc comment. */
+    private refused;
+    private fail;
+    /** 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;
+    /** Expires the cookie `applyAuthCookie()` set; a no-op when it set none. */
+    private clearAuthCookie;
+}

package/dist/apps/shared/signaling/SignalingClient.js

@@ -0,0 +1,278 @@
+///////////////////////////////////////////////////////////////////////////////
+// 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";
+/** 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 = 1000;
+export const SIGNALING_BACKOFF_MAX_MS = 30000;
+/** How often an idle socket is pinged. */
+export const SIGNALING_KEEPALIVE_MS = 25000;
+/** 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 = 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.";
+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) {
+    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() {
+    return typeof WebSocket === "undefined" ? undefined : (url) => new WebSocket(url);
+}
+export class SignalingClient {
+    constructor(options) {
+        this.options = options;
+        this.ready = false;
+        this.closed = false;
+        this.everReady = false;
+        this.attempt = 0;
+        this.cookieApplied = false;
+        this.maxBytes = SIGNALING_DEFAULT_MAX_MESSAGE_BYTES;
+        this.queue = [];
+        this.listeners = new Set();
+    }
+    /** The largest message (the whole `signal` envelope, in bytes) the server accepts - what its `ready` said. */
+    get maxMessageBytes() {
+        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() {
+        if (this.closed) {
+            return Promise.reject(new Error("This signaling client has already been closed."));
+        }
+        return new Promise((resolve, reject) => {
+            this.pendingConnect = { resolve, reject };
+            this.openSocket();
+        });
+    }
+    /** Closes the socket, stops reconnecting and clears the guest auth cookie this client applied - idempotent. */
+    close() {
+        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) {
+        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) {
+        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);
+    }
+    openSocket() {
+        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;
+        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;
+    }
+    handleFrame(raw) {
+        if (typeof raw !== "string") {
+            return;
+        }
+        let frame;
+        try {
+            const parsed = 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);
+            }
+        }
+    }
+    handleReady(maxMessageBytes) {
+        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. */
+    write(text) {
+        const socket = this.socket;
+        if (!socket || socket.readyState !== SOCKET_OPEN) {
+            return false;
+        }
+        try {
+            socket.send(text);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    startKeepalive() {
+        this.stopKeepalive();
+        this.keepaliveTimer = setInterval(() => this.write(JSON.stringify({ op: "ping", t: Date.now() })), SIGNALING_KEEPALIVE_MS);
+    }
+    stopKeepalive() {
+        clearInterval(this.keepaliveTimer);
+        this.keepaliveTimer = undefined;
+    }
+    scheduleReconnect() {
+        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. */
+    refused(reason) {
+        if (this.pendingConnect) {
+            this.fail(new Error(reason));
+            return;
+        }
+        if (this.everReady) {
+            this.options.onClosed?.(reason);
+        }
+    }
+    fail(err) {
+        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. */
+    applyAuthCookie() {
+        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. */
+    clearAuthCookie() {
+        if (!this.cookieApplied) {
+            return;
+        }
+        const doc = this.options.documentRef ?? (typeof document === "undefined" ? undefined : document);
+        doc.cookie = `${AUTH_COOKIE_NAME}=; path=/; Max-Age=0`;
+    }
+}

package/dist/apps/shared/webrtc/MeshConnectionManager.d.ts

@@ -1,6 +1,6 @@
 /**
  * Full-mesh WebRTC connection management: one direct `RTCPeerConnection` per other participant, signaled entirely
- * over the meeting's own push channel (`SignalingChannel` - see `types.ts`) as this plugin's Phase 2
+ * over the meeting's own signaling channel (`SignalingChannel` - see `types.ts`) as this plugin's Phase 2
  * `.claude/NOTES.md` entry lays out. Pure state machine, no JSX/DOM rendering - `apps/meet/_CallView.tsx` owns one
  * instance per call and mirrors its events into React state.
  *
@@ -27,17 +27,17 @@
  *
  * ## Join announcement and roster discovery
  *
- * The channel has no history (a push event published while a socket was down is never replayed - see
- * `@rapidmx/web-client`'s `lib/mail/pushClient.ts` doc comment for the identical guarantee on the mail push channel this
- * one shares its transport with), so a newcomer's `hello` would only reach participants who happened to already be
- * subscribed *and* who joined before them - never the other way around. Every participant who learns of a
+ * The channel has no history (the server delivers a message only to the sockets connected at that moment, and never
+ * replays one to a socket that connects later - see the backend's `SignalingHub`), so a newcomer's `hello` would only
+ * reach participants who happened to already be connected *and* who joined before them - never the other way around. Every participant who learns of a
  * genuinely new peer (from any message, not just `hello`) therefore echoes its own `hello` right back, once, the
  * first time it becomes aware of that peer - so within one extra round trip everyone converges on the same full
  * roster regardless of join order. This is naturally bounded (each participant echoes at most once per peer it
  * ever discovers) rather than a risk of runaway flooding.
  *
- * Each message is its own `POST`, so nothing guarantees they arrive in the order they were sent. Two consequences
- * are handled here: an `offer` that beats its sender's `hello` creates the peer under a placeholder name that the
+ * Nothing in `SignalingChannel` itself promises that messages arrive in the order they were sent (one socket keeps
+ * one sender's messages in order today, but the transport this replaced sent each message as its own `POST`, and
+ * this manager does not depend on which transport it has). Two consequences are handled here: an `offer` that beats its sender's `hello` creates the peer under a placeholder name that the
  * `hello` then replaces (`participant-updated`), and an ICE candidate that beats its offer is held until the peer
  * exists rather than dropped.
  *