@rapidmx/meet-plugin 0.14.1 → 0.16.0

package/dist/apps/shared/webrtc/MeshConnectionManager.js

@@ -4,7 +4,7 @@
 ///////////////////////////////////////////////////////////////////////////////
 /**
  * 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.
  *
@@ -31,17 +31,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.
  *
@@ -558,7 +558,11 @@ export class MeshConnectionManager {
     async pollDiagnostics(peer) {
         let diagnostics;
         try {
-            diagnostics = await peer.pc.collectDiagnostics();
+            const relay = this.options.relay;
+            diagnostics =
+                peer.transport === "websocket" && relay?.diagnostics
+                    ? fromRelayDiagnostics(relay.diagnostics(peer.uid))
+                    : await peer.pc.collectDiagnostics();
         }
         catch {
             // Leaves whatever was last polled in place rather than blanking a momentary failure.
@@ -636,6 +640,9 @@ export class MeshConnectionManager {
         });
         this.syncRelaySending();
         this.emit({ type: "participant-updated", participant: toParticipant(peer) });
+        if (relay.diagnostics) {
+            this.startDiagnosticsPolling(peer);
+        }
         if (notify) {
             this.send({ kind: "relay-fallback", to: peer.uid });
         }
@@ -739,7 +746,7 @@ export class MeshConnectionManager {
         }
         const peer = this.peers.get(message.from);
         if (!peer) {
-            // A candidate that raced ahead of its own offer (each message is a separate `POST`) - hold it for
+            // A candidate that raced ahead of its own offer (see this module's doc comment on ordering) - hold it for
             // the peer to claim when it is created. Bounded, see `MAX_ORPHAN_PEERS`.
             const held = this.orphanCandidates.get(message.from);
             if (held) {
@@ -806,6 +813,18 @@ function toParticipant(peer) {
         diagnostics: peer.diagnostics,
     };
 }
+/** A relayed pair's diagnostics: the relay's own counters, with the part that maps onto RTP stats (round trip, frames
+ * lost, bytes each way) also filled into the ordinary fields, so the panel's ordinary rows show it too. The round trip
+ * is to the relay server, not to the peer - see `RelayDiagnostics.roundTripMs`. */
+function fromRelayDiagnostics(relay) {
+    const { send, receive } = relay;
+    return {
+        roundTripTimeSeconds: relay.roundTripMs === undefined ? undefined : relay.roundTripMs / 1000,
+        audio: { packetsLost: receive?.audio.framesLost, bytesSent: send.audio.bytesSent, bytesReceived: receive?.audio.bytesReceived },
+        video: { packetsLost: receive?.video.framesLost, bytesSent: send.video.bytesSent, bytesReceived: receive?.video.bytesReceived },
+        relay,
+    };
+}
 function sameState(a, b) {
     return a.audioOn === b.audioOn && a.videoOn === b.videoOn && a.handRaised === b.handRaised;
 }

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

@@ -1,7 +1,6 @@
-/** Shared types for `MeshConnectionManager.ts` and its signaling transport (`apps/shared/push/GuestSignalingClient.ts`) -
- * kept in their own module so a test can depend on the shapes alone. `GuestSignalingClient` itself now also serves
- * an already-authenticated real caller (`VideoMeetingJoinResult.authenticated`), not only a synthetic guest - see
- * its own doc comment. */
+/** Shared types for `MeshConnectionManager.ts` and its signaling transport (`apps/shared/signaling/SignalingClient.ts`) -
+ * kept in their own module so a test can depend on the shapes alone. `SignalingClient` serves both a guest and an
+ * already-authenticated real caller (`VideoMeetingJoinResult.authenticated`) - see its own doc comment. */
 /** What a participant is sending, and whether their hand is up. Announced in `hello` and re-sent as a `state`
  * message on every change, so a tile can show a muted microphone, an avatar for a camera that is off, and a raised
  * hand without inspecting the media itself (the far end of a `replaceTrack(null)` gives no dependable signal that
@@ -29,16 +28,19 @@ export declare const REACTION_EMOJIS: readonly ["👍", "👏", "❤️", "🎉"
  * every other participant has chosen for their own tab. */
 export type TransportMode = "auto" | "p2p" | "relay" | "websocket";
 /**
- * One WebRTC signaling message, published as the JSON body of `POST /push/:meetingUid` (`BasePushRoute.send()`)
- * and received back over `/push`'s WebSocket, exactly as `BaseVideoMeetingRoute`'s doc comment describes ("SDP
- * offers/answers and ICE candidates are ordinary `NotificationUtils.sendMessage()` payloads"). `type` is a fixed
- * literal so a listener on the meeting's channel (which will also see other frame shapes if this server ever
- * grows other push consumers) can cheaply recognize and skip anything that isn't one of these.
+ * One WebRTC signaling message, sent as the `data` of a `{"op":"signal"}` frame over the meeting's own signaling
+ * WebSocket (`apps/shared/signaling/SignalingClient.ts`, served by `BaseVideoMeetingRoute.signal()` and the backend's
+ * `SignalingHub`) and delivered to the other participants the same way. `type` is a fixed literal so a listener can
+ * cheaply recognize and skip anything that isn't one of these.
+ *
+ * `chat`/`whiteboard` (see `../collab/CollabSession.ts`) are broadcast like `reaction`.
  *
  * `hello`/`bye`/`presenter-claim`/`presenter-release`/`state`/`reaction`/`talking-stick` are broadcast (`to` left
- * unset - every participant is relevant); `offer`/`answer`/`ice-candidate`/`mute-request`/`kicked` are
- * point-to-point (`to` is the intended peer's uid) - a recipient that isn't `to` (when set) ignores the message,
- * since a channel's pub/sub fans every message out to every subscriber, sender included.
+ * unset - every other participant receives it); `offer`/`answer`/`ice-candidate`/`mute-request`/`kicked` are
+ * point-to-point (`to` is the intended peer's id) - the server delivers one only to the socket of that peer, so
+ * nobody else ever sees it. The sender never receives its own messages back either. (A recipient still ignores a
+ * message whose `to` isn't itself, and its own messages - harmless with this transport, and kept so
+ * `MeshConnectionManager` does not depend on how its transport routes.)
  *
  * `mute-request`/`kicked`/`talking-stick` are host moderation signals (see `MeshConnectionManager`'s doc comment) -
  * purely cooperative, like every other message here: the recipient's own client decides whether to honor one, and
@@ -56,16 +58,17 @@ export type TransportMode = "auto" | "p2p" | "relay" | "websocket";
  */
 export interface SignalMessage {
     type: "video-meeting-signal";
-    kind: "hello" | "bye" | "offer" | "answer" | "ice-candidate" | "presenter-claim" | "presenter-release" | "state" | "reaction" | "relay-fallback" | "mute-request" | "kicked" | "talking-stick" | "restart-connection";
+    kind: "hello" | "bye" | "offer" | "answer" | "ice-candidate" | "presenter-claim" | "presenter-release" | "state" | "reaction" | "relay-fallback" | "mute-request" | "kicked" | "talking-stick" | "restart-connection" | "chat" | "whiteboard" | "collab-sync-request" | "collab-sync" | "whiteboard-cursor";
     /** The sender's authenticated uid - the real caller's own uid when `join()` returned `authenticated: true`, else
-     * the `guest:<random>` uid `BaseVideoMeetingRoute.join()` minted. The server refuses a published message whose
-     * `from` isn't the authenticated caller's uid (it stops one participant speaking as another), so this must be
-     * exactly that uid. */
+     * the `guest:<random>` uid `BaseVideoMeetingRoute.join()` minted. The server overwrites whatever the sender put
+     * here with the uid its signaling socket authenticated as (it stops one participant speaking as another), so a
+     * received message's `from` is always that uid. */
     from: string;
     /** Which of the sender's tabs or devices this is: `<from>~<random>`. The same account joining from two devices is
-     * two participants, not one that ignores its own messages. A `peer` that doesn't start with `<from>~` is
-     * ignored, so it can't name someone else's tab. Absent from a sender that predates it (the participant is then
-     * identified by `from`). */
+     * two participants, not one that ignores its own messages. The server overwrites it with the peer id the sender's
+     * socket announced in its `hello` (which must be `<from>` or start with `<from>~`), so every received message
+     * carries one; a received `peer` that is neither is still ignored, so it can't name someone else's tab, and one
+     * that is absent identifies the participant by `from`. */
     peer?: string;
     /** Set only on a point-to-point message (`offer`/`answer`/`ice-candidate`/`relay-fallback`). */
     to?: string;
@@ -84,15 +87,26 @@ export interface SignalMessage {
     sdp?: RTCSessionDescriptionInit;
     /** `ice-candidate` only. */
     candidate?: RTCIceCandidateInit;
+    /** `chat` only - a `ChatPayload` (`../collab/protocol.ts`), validated by `parseChat()` before use. Typed `unknown`
+     * since it is another participant's input until then; the same goes for the next two. */
+    chat?: unknown;
+    /** `whiteboard` only - a `WhiteboardOp`, validated by `parseWhiteboardOp()`. */
+    whiteboard?: unknown;
+    /** `collab-sync` only - one `SyncPayload` part of a newcomer's catch-up, validated by `parseSync()`. `collab-sync`
+     * and `collab-sync-request` are point-to-point (`to` set) - see `CollabSession`'s doc comment. */
+    sync?: unknown;
+    /** `whiteboard-cursor` only - a `CursorPayload`, validated by `parseCursor()`; broadcast, never stored. */
+    cursor?: unknown;
 }
 /** What `MeshConnectionManager` needs from a signaling transport - implemented by
- * `apps/shared/push/GuestSignalingClient.ts` for a real call, and by an in-memory fake for `MeshConnectionManager`'s own
- * tests (see `test/webrtc/MeshConnectionManager.test.ts`), which never opens a real network connection. */
+ * `apps/shared/signaling/SignalingClient.ts` for a real call, and by an in-memory fake for `MeshConnectionManager`'s own
+ * tests (see `test/apps/shared/webrtc/MeshConnectionManager.test.ts`), which never opens a real network connection. */
 export interface SignalingChannel {
     send(message: SignalMessage): void;
-    /** Calls `handler` with every message received on the channel (including, per the pub/sub fan-out this
-     * transport is built on, this same client's own sends - `MeshConnectionManager` filters those out itself
-     * rather than relying on the transport to). Returns the function that stops listening. */
+    /** Calls `handler` with every message received on the channel. `SignalingClient` never delivers this client's own
+     * sends, nor a `to`-addressed message meant for another peer, but `MeshConnectionManager` filters both out itself
+     * rather than relying on the transport to (its tests' fake echoes everything to everyone). Returns the function
+     * that stops listening. */
     onMessage(handler: (message: SignalMessage) => void): () => void;
 }
 /** One kind's RTP stream stats, as of one sample - cumulative counters (`bytesSent`/`bytesReceived`), not a rate,
@@ -114,6 +128,66 @@ export interface ConnectionDiagnostics {
     roundTripTimeSeconds?: number;
     audio: RtpStreamDiagnostics;
     video: RtpStreamDiagnostics;
+    /** The WebSocket relay's own counters, present only for a `"websocket"` pair - `audio`/`video` then carry the
+     * subset of them that maps onto RTP stats (frames lost, bytes each way). */
+    relay?: RelayDiagnostics;
+}
+/** What the relay's sending half did with one kind of frame, cumulative since the relay transport was created. */
+export interface RelaySendStats {
+    framesSent: number;
+    /** Frames encoded but not sent: the socket was not ready, backed up, or refused a fragment. */
+    framesDropped: number;
+    bytesSent: number;
+}
+/** What the relay's sending half has done, cumulative since the relay transport was created. It is per browser, not
+ * per peer: every relayed peer receives the same stream. */
+export interface RelaySendDiagnostics {
+    /** Milliseconds of microphone audio the capture path delivered, against `audioCaptureWallMs` - the wall-clock time
+     * it was capturing for. Well short of it means capture is losing whole blocks. */
+    audioCapturedMs: number;
+    audioCaptureWallMs: number;
+    /** How much of `audioCapturedMs` was digital silence (see `SilenceMeter`) - a live microphone always has some
+     * noise, so a large share means the capture path is handing the encoder zero-filled blocks. */
+    audioSilentMs: number;
+    /** Milliseconds of captured audio not encoded because the encoder was too far behind. */
+    audioEncoderSkippedMs: number;
+    audio: RelaySendStats;
+    video: RelaySendStats;
+}
+/** What the relay's receiving half got of one kind of frame from one peer, cumulative. */
+export interface RelayReceiveStats {
+    framesReceived: number;
+    /** Frames the sequence numbers say never arrived complete - dropped by the sender, the server or in transit. */
+    framesLost: number;
+    bytesReceived: number;
+}
+/** What the relay's receiving half has done with one peer's media, cumulative since it started receiving from them. */
+export interface RelayReceiveDiagnostics {
+    audio: RelayReceiveStats & {
+        /** Milliseconds of decoded audio scheduled for playback. */
+        playedMs: number;
+        /** How much of `playedMs` was digital silence - silence that arrived inside the packets, i.e. the sender sent
+         * it, as opposed to `gapMs`. */
+        silentMs: number;
+        /** Times playback ran dry and restarted, and the total silence that inserted. */
+        gaps: number;
+        gapMs: number;
+        /** Packets dropped on arrival because the decoder was backed up or playback was already too far ahead. */
+        droppedLate: number;
+        /** How far ahead of the clock audio is scheduled right now - the receive buffer's current depth. */
+        bufferedMs: number;
+    };
+    video: RelayReceiveStats;
+}
+/** One sample of the relay's counters for one peer. */
+export interface RelayDiagnostics {
+    /** The latest round trip from this browser to the relay server, in milliseconds - not to the peer: the relay has
+     * no direct path between the two, and each end only knows its own leg. `undefined` before the first pong, or for
+     * a server too old to answer pings. */
+    roundTripMs?: number;
+    send: RelaySendDiagnostics;
+    /** `undefined` when nothing is being received from this peer. */
+    receive?: RelayReceiveDiagnostics;
 }
 /** The subset of `RTCRtpSender` `MeshConnectionManager.setLocalTrack()` uses. Every connection carries one audio and
  * one video sender for its whole life (see `MeshConnectionManager`'s doc comment), so turning a camera on or off,
@@ -183,6 +257,9 @@ export interface RelayTransportLike {
     setSending(active: boolean): void;
     /** Same as `MeshConnectionManager.setLocalTrack()` - `null` sends nothing for that kind. */
     setLocalTrack(kind: "audio" | "video", track: MediaStreamTrack | null): void;
+    /** The relay's counters as they stand for `peerId`, for the diagnostics panel. Optional so a test's fake relay
+     * needn't provide it; the mesh then shows nothing for a relayed pair. */
+    diagnostics?(peerId: string): RelayDiagnostics;
     close(): void;
 }
 /** `iceTransportPolicy` mirrors the real `RTCConfiguration` field of the same name - `"relay"` forces ICE to use
@@ -200,8 +277,9 @@ export interface MeshParticipant extends ParticipantState {
     /** How this participant's media currently reaches the local one - see `MediaTransport`. */
     transport: MediaTransport;
     /** This connection's most recently polled quality stats, for the diagnostics panel - `undefined` until the
-     * first poll completes (shortly after `transport` first leaves `"connecting"`), and never present at all for
-     * a `"websocket"`-relayed participant (there is no `RTCPeerConnection` to poll). */
+     * first poll completes (shortly after `transport` first leaves `"connecting"`, or the pair moves to the relay).
+     * For a `"websocket"`-relayed participant they come from the relay's own counters (`relay`) rather than an
+     * `RTCPeerConnection`. */
     diagnostics?: ConnectionDiagnostics;
 }
 export type MeshEvent = {

package/dist/apps/shared/webrtc/types.js

@@ -2,10 +2,9 @@
 // Copyright (C) 2026 Jean-Philippe Steinmetz. All rights reserved.
 // SPDX-License-Identifier: MPL-2.0
 ///////////////////////////////////////////////////////////////////////////////
-/** Shared types for `MeshConnectionManager.ts` and its signaling transport (`apps/shared/push/GuestSignalingClient.ts`) -
- * kept in their own module so a test can depend on the shapes alone. `GuestSignalingClient` itself now also serves
- * an already-authenticated real caller (`VideoMeetingJoinResult.authenticated`), not only a synthetic guest - see
- * its own doc comment. */
+/** Shared types for `MeshConnectionManager.ts` and its signaling transport (`apps/shared/signaling/SignalingClient.ts`) -
+ * kept in their own module so a test can depend on the shapes alone. `SignalingClient` serves both a guest and an
+ * already-authenticated real caller (`VideoMeetingJoinResult.authenticated`) - see its own doc comment. */
 /** The emoji a participant can send during a call. A received `reaction` outside this list is ignored, so an
  * arbitrary string from another participant is never rendered. */
 export const REACTION_EMOJIS = ["👍", "👏", "❤️", "🎉", "😂", "😮", "😢", "👋"];