@rapidmx/meet-plugin 0.14.1 → 0.15.0

package/apps/shared/relay/RelayClient.ts

@@ -13,6 +13,10 @@
  * older one, which accepts `MAX_MESSAGE_BYTES`). Nothing else may be sent before `ready`.
  * - `{"op":"want","peers":[...]}` REPLACES the set of senders this socket receives from (the server accepts at most
  * `MAX_WANTED_PEERS`). It has to be re-sent after every reconnect, because the server's set dies with the socket.
+ * - `{"op":"ping","t":<this client's clock>}`, every `RELAY_PING_INTERVAL_MS` once ready, is answered with
+ * `{"op":"pong","t":<the same>}`, which times the round trip to the server (`roundTripMs`) - over the same socket as
+ * the media, so it includes whatever the media has queued ahead of it. An older server ignores the ping and the
+ * round trip stays unknown.
  * - A binary message from the client is an opaque payload of at most `maxMessageBytes`. The server forwards it to
  * every socket that wants this sender as `[1 byte N][N bytes UTF-8 sender peer id][payload]`, stamping the sender
  * itself so a peer cannot speak as another.
@@ -48,6 +52,9 @@ export const RELAY_BACKOFF_MAX_MS = 15_000;
 /** How long a socket may take to become `ready` before it is abandoned and retried (a server that accepts the
  * upgrade but never answers the hello would otherwise hang the tier forever). */
 export const RELAY_HANDSHAKE_TIMEOUT_MS = 10_000;
+/** How often a ready socket pings the server to time the round trip - often enough that the diagnostics panel (which
+ * polls every few seconds) always has a recent sample, rarely enough to cost nothing next to the media. */
+export const RELAY_PING_INTERVAL_MS = 2_000;
 
 const SOCKET_OPEN = 1;
 
@@ -56,6 +63,8 @@ export interface RelayClientOptions {
     peerId: string;
     createSocket: (url: string) => RelaySocket;
     random: () => number;
+    /** A monotonic millisecond clock for timing pings. Defaults to `Date.now`. */
+    now?: () => number;
     /** Called with the sender's peer id (as stamped by the server) and the original payload. */
     onMedia: (peerId: string, payload: Uint8Array) => void;
 }
@@ -82,6 +91,8 @@ export class RelayClient {
     private wanted: string[] = [];
     private reconnectTimer: ReturnType<typeof setTimeout> | undefined;
     private handshakeTimer: ReturnType<typeof setTimeout> | undefined;
+    private pingTimer: ReturnType<typeof setInterval> | undefined;
+    private lastRoundTripMs: number | undefined;
     private readonly decoder = new TextDecoder();
 
     constructor(private readonly options: RelayClientOptions) {}
@@ -91,6 +102,12 @@ export class RelayClient {
         return this.isReady;
     }
 
+    /** The most recent ping's round trip to the server, in milliseconds - `undefined` until the first pong on the
+     * current socket (and for good on a server too old to answer pings). */
+    get roundTripMs(): number | undefined {
+        return this.lastRoundTripMs;
+    }
+
     /** The largest message `sendMedia()` will send: what the server announced in `ready` (validated and clamped), or
      * `MAX_MESSAGE_BYTES` before that, without one, and again after every disconnect until the next `ready`. The
      * frame fragmenter sizes its fragments from this. */
@@ -148,6 +165,7 @@ export class RelayClient {
         clearTimeout(this.reconnectTimer);
         clearTimeout(this.handshakeTimer);
         this.reconnectTimer = this.handshakeTimer = undefined;
+        this.stopPinging();
         this.detach();
     }
 
@@ -200,7 +218,15 @@ export class RelayClient {
         } catch {
             return;
         }
-        if (!message || typeof message !== "object" || (message as { op?: unknown }).op !== "ready" || this.isReady) {
+        if (!message || typeof message !== "object") {
+            return;
+        }
+        const op = (message as { op?: unknown }).op;
+        if (op === "pong") {
+            this.handlePong((message as { t?: unknown }).t);
+            return;
+        }
+        if (op !== "ready" || this.isReady) {
             return;
         }
         this.isReady = true;
@@ -213,6 +239,30 @@ export class RelayClient {
         this.handshakeTimer = undefined;
         // The server's wanted set is per socket, so it starts empty on every (re)connect.
         this.sendText({ op: "want", peers: this.wanted });
+        this.pingTimer = setInterval(() => this.sendText({ op: "ping", t: this.now() }), RELAY_PING_INTERVAL_MS);
+    }
+
+    /** Times the round trip of the ping that `t` came back from. Ignored before ready, for a `t` that isn't a number,
+     * or one from the future (nothing this client sent). */
+    private handlePong(t: unknown): void {
+        if (!this.isReady || typeof t !== "number") {
+            return;
+        }
+        const roundTrip = this.now() - t;
+        if (roundTrip >= 0) {
+            this.lastRoundTripMs = roundTrip;
+        }
+    }
+
+    private now(): number {
+        return (this.options.now ?? Date.now)();
+    }
+
+    /** Stops pinging and forgets the last round trip - it described a socket that is gone. */
+    private stopPinging(): void {
+        clearInterval(this.pingTimer);
+        this.pingTimer = undefined;
+        this.lastRoundTripMs = undefined;
     }
 
     private handleClose(socket: RelaySocket): void {
@@ -220,6 +270,7 @@ export class RelayClient {
             return;
         }
         this.isReady = false;
+        this.stopPinging();
         // The next server might be a different one (a rolling upgrade), so the limit is learned afresh.
         this.messageLimit = MAX_MESSAGE_BYTES;
         clearTimeout(this.handshakeTimer);

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;
 }
@@ -68,6 +72,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 +104,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 +155,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/webrtc/MeshConnectionManager.ts

@@ -134,6 +134,7 @@
  * not something a meeting agrees on together.
  */
 import {
+    type ConnectionDiagnostics,
     type MediaTransport,
     type MeshEvent,
     type MeshParticipant,
@@ -141,6 +142,7 @@ import {
     type RTCPeerConnectionFactory,
     type RTCPeerConnectionLike,
     type RTCRtpSenderLike,
+    type RelayDiagnostics,
     type RelayTransportLike,
     type SignalMessage,
     type SignalingChannel,
@@ -184,8 +186,8 @@ interface PeerState extends MeshParticipant {
     connectTimer: ReturnType<typeof setTimeout> | undefined;
     /** Gives up on WebRTC when the connection has stayed `disconnected` for `disconnectedGraceMs`. */
     disconnectTimer: ReturnType<typeof setTimeout> | undefined;
-    /** Refreshes `diagnostics` (`MeshParticipant`) while this pair is on a real `RTCPeerConnection` - started once
-     * it first connects, stopped the moment it leaves WebRTC for the relay or the pair ends. */
+    /** Refreshes `diagnostics` (`MeshParticipant`) - from the `RTCPeerConnection` once it first connects, then (after
+     * a restart in `fallBack()`) from the relay's counters once the pair moves there; stopped when the pair ends. */
     diagnosticsTimer: ReturnType<typeof setInterval> | undefined;
 }
 
@@ -663,7 +665,11 @@ export class MeshConnectionManager {
     private async pollDiagnostics(peer: PeerState): Promise<void> {
         let diagnostics: MeshParticipant["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.
             return;
@@ -744,6 +750,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 });
         }
@@ -925,6 +934,19 @@ function toParticipant(peer: PeerState): MeshParticipant {
     };
 }
 
+/** 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: RelayDiagnostics): ConnectionDiagnostics {
+    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: ParticipantState, b: ParticipantState): boolean {
     return a.audioOn === b.audioOn && a.videoOn === b.videoOn && a.handRaised === b.handRaised;
 }

package/apps/shared/webrtc/types.ts

@@ -139,6 +139,71 @@ 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
@@ -206,6 +271,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;
 }
 
@@ -222,8 +290,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;
 }
 

package/dist/apps/meet/_CallControls.d.ts

@@ -17,8 +17,11 @@
  * their own: "Diagnostics" (`onOpenDiagnostics`) and "Settings" (`onOpenSettings`, host-only) each open their own
  * persistent window/modal in `_CallView.tsx` and close this menu; "Connection method" is a four-way
  * `menuitemradio` group (`TransportMode` - see `MeshConnectionManager.setTransportMode()`'s own doc comment)
- * forcing how *this tab's* media reaches everyone else, independent of what anyone else has chosen. Otherwise an
- * ordinary menu of this bar's own shape (`openMenu`, closes on Escape/outside click like every other one here).
+ * forcing how *this tab's* media reaches everyone else, independent of what anyone else has chosen; "Hide self"/
+ * "Show self" (`selfHidden`/`onToggleSelfHidden`) is the only way to bring the local tile back once hidden from
+ * grid view, where there's no tile left to offer its own "show" control - see `_CallView.tsx`'s doc comment on
+ * where the local tile appears. Otherwise an ordinary menu of this bar's own shape (`openMenu`, closes on
+ * Escape/outside click like every other one here).
  */
 import React from "react";
 import type { ScreenTransformState } from "../shared/media/filters/ScreenTransform.js";
@@ -53,10 +56,14 @@ export interface CallControlsProps {
     onSetTransportMode: (mode: TransportMode) => void;
     onOpenDiagnostics: () => void;
     onOpenSettings: () => void;
+    /** Whether the local tile is currently hidden - the "…" menu's "Hide self"/"Show self" item reflects and
+     * toggles this; see `_CallView.tsx`'s doc comment on where the local tile appears. */
+    selfHidden: boolean;
+    onToggleSelfHidden: () => void;
     onLeave: () => void;
 }
 /** Bars that rise and fall with the microphone's level (0-5) - a flat, dim set while there is no sound. */
 export declare function LevelBars({ level }: {
     level: number;
 }): React.JSX.Element;
-export default function CallControls({ media, participants, isPresenting, presentingElsewhereName, onToggleShare, screenTransform, onRotateScreen, onFlipScreen, handRaised, onToggleHand, onReaction, viewMode, onToggleViewMode, micLocked, isHost, transportMode, onSetTransportMode, onOpenDiagnostics, onOpenSettings, onLeave, }: CallControlsProps): React.JSX.Element;
+export default function CallControls({ media, participants, isPresenting, presentingElsewhereName, onToggleShare, screenTransform, onRotateScreen, onFlipScreen, handRaised, onToggleHand, onReaction, viewMode, onToggleViewMode, micLocked, isHost, transportMode, onSetTransportMode, onOpenDiagnostics, onOpenSettings, selfHidden, onToggleSelfHidden, onLeave, }: CallControlsProps): React.JSX.Element;

package/dist/apps/meet/_CallControls.js

@@ -22,8 +22,11 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
  * their own: "Diagnostics" (`onOpenDiagnostics`) and "Settings" (`onOpenSettings`, host-only) each open their own
  * persistent window/modal in `_CallView.tsx` and close this menu; "Connection method" is a four-way
  * `menuitemradio` group (`TransportMode` - see `MeshConnectionManager.setTransportMode()`'s own doc comment)
- * forcing how *this tab's* media reaches everyone else, independent of what anyone else has chosen. Otherwise an
- * ordinary menu of this bar's own shape (`openMenu`, closes on Escape/outside click like every other one here).
+ * forcing how *this tab's* media reaches everyone else, independent of what anyone else has chosen; "Hide self"/
+ * "Show self" (`selfHidden`/`onToggleSelfHidden`) is the only way to bring the local tile back once hidden from
+ * grid view, where there's no tile left to offer its own "show" control - see `_CallView.tsx`'s doc comment on
+ * where the local tile appears. Otherwise an ordinary menu of this bar's own shape (`openMenu`, closes on
+ * Escape/outside click like every other one here).
  */
 import { useEffect, useRef, useState } from "react";
 import { filtersActive } from "../shared/media/filters/filterTypes.js";
@@ -45,7 +48,7 @@ const ACTIVE = "bg-[#a8c7fa] text-[#062e6f] hover:bg-[#8ab4f8]";
 export function LevelBars({ level }) {
     return (_jsx("span", { className: "flex items-center gap-[2px] h-5", "data-testid": "mic-level", "data-level": level, "aria-hidden": "true", children: [0.6, 1, 0.6].map((weight, i) => (_jsx("span", { className: `w-[3px] rounded-full ${level > 0 ? "bg-[#8ab4f8]" : "bg-white/50"}`, style: { height: `${4 + weight * level * 3}px` } }, i))) }));
 }
-export default function CallControls({ media, participants, isPresenting, presentingElsewhereName, onToggleShare, screenTransform, onRotateScreen, onFlipScreen, handRaised, onToggleHand, onReaction, viewMode, onToggleViewMode, micLocked, isHost, transportMode, onSetTransportMode, onOpenDiagnostics, onOpenSettings, onLeave, }) {
+export default function CallControls({ media, participants, isPresenting, presentingElsewhereName, onToggleShare, screenTransform, onRotateScreen, onFlipScreen, handRaised, onToggleHand, onReaction, viewMode, onToggleViewMode, micLocked, isHost, transportMode, onSetTransportMode, onOpenDiagnostics, onOpenSettings, selfHidden, onToggleSelfHidden, onLeave, }) {
     const [openMenu, setOpenMenu] = useState(null);
     const barRef = useRef(null);
     const shareDisabled = !isPresenting && !!presentingElsewhereName;
@@ -80,7 +83,10 @@ export default function CallControls({ media, participants, isPresenting, presen
                             }, children: emoji }, emoji))) }))] }), _jsx("button", { type: "button", className: `${BUTTON} w-12 ${handRaised ? ACTIVE : NEUTRAL}`, "aria-label": handRaised ? "Lower hand" : "Raise hand", "aria-pressed": handRaised, onClick: onToggleHand, children: _jsx(HandIcon, {}) }), _jsx("button", { type: "button", className: `${BUTTON} w-12 ${NEUTRAL} disabled:opacity-40 disabled:cursor-not-allowed`, "aria-label": viewMode === "grid" ? "Switch to focused view" : "Switch to grid view", disabled: participants.length < 2, title: participants.length < 2 ? "Grid and focused view look the same with only one other participant." : undefined, onClick: onToggleViewMode, children: viewMode === "grid" ? _jsx(FocusIcon, {}) : _jsx(GridIcon, {}) }), _jsxs("div", { className: "sm:relative", children: [_jsx("button", { type: "button", className: `${BUTTON} w-12 ${openMenu === "overflow" ? ACTIVE : NEUTRAL}`, "aria-label": "More options", "aria-haspopup": "menu", "aria-expanded": openMenu === "overflow", onClick: () => toggleMenu("overflow"), children: _jsx(OverflowIcon, {}) }), openMenu === "overflow" && (_jsxs("div", { role: "menu", "aria-label": "More options", className: "absolute bottom-full mb-3 right-0 w-56 max-w-[calc(100vw-1rem)] rounded-2xl bg-[#2b2d30] text-white shadow-xl py-1 text-sm", children: [_jsx("button", { type: "button", role: "menuitem", className: "w-full px-3 py-2 text-left hover:bg-white/10 focus:outline-none focus-visible:ring-2 focus-visible:ring-white/80", onClick: () => {
                                     onOpenDiagnostics();
                                     setOpenMenu(null);
-                                }, children: "Diagnostics" }), _jsx("div", { className: "my-1 border-t border-white/10" }), _jsx("p", { className: "px-3 pt-1 pb-0.5 text-xs font-semibold uppercase tracking-wide text-white/60", children: "Connection method" }), TRANSPORT_MODE_OPTIONS.map(({ mode, label }) => (_jsxs("button", { type: "button", role: "menuitemradio", "aria-checked": transportMode === mode, className: "flex w-full items-center gap-2 px-3 py-2 text-left hover:bg-white/10 focus:outline-none focus-visible:ring-2 focus-visible:ring-white/80", onClick: () => {
+                                }, children: "Diagnostics" }), _jsx("button", { type: "button", role: "menuitem", className: "w-full px-3 py-2 text-left hover:bg-white/10 focus:outline-none focus-visible:ring-2 focus-visible:ring-white/80", onClick: () => {
+                                    onToggleSelfHidden();
+                                    setOpenMenu(null);
+                                }, children: selfHidden ? "Show self" : "Hide self" }), _jsx("div", { className: "my-1 border-t border-white/10" }), _jsx("p", { className: "px-3 pt-1 pb-0.5 text-xs font-semibold uppercase tracking-wide text-white/60", children: "Connection method" }), TRANSPORT_MODE_OPTIONS.map(({ mode, label }) => (_jsxs("button", { type: "button", role: "menuitemradio", "aria-checked": transportMode === mode, className: "flex w-full items-center gap-2 px-3 py-2 text-left hover:bg-white/10 focus:outline-none focus-visible:ring-2 focus-visible:ring-white/80", onClick: () => {
                                     onSetTransportMode(mode);
                                     setOpenMenu(null);
                                 }, children: [_jsx("span", { className: "w-4 text-[#8ab4f8]", "aria-hidden": "true", children: transportMode === mode ? "✓" : "" }), label] }, mode))), isHost && (_jsxs(_Fragment, { children: [_jsx("div", { className: "my-1 border-t border-white/10" }), _jsx("button", { type: "button", role: "menuitem", className: "w-full px-3 py-2 text-left hover:bg-white/10 focus:outline-none focus-visible:ring-2 focus-visible:ring-white/80", onClick: () => {

package/dist/apps/meet/_CallView.d.ts

@@ -11,10 +11,24 @@
  *
  * The call fills the viewport (`fixed inset-0`) as three rows - a slim header, the tiles (which take whatever room
  * is left and never scroll the page), and the control bar pinned to the bottom - instead of being laid out inside
- * the branded page shell, whose header, footer and padding pushed it off the screen. The local participant's own
- * tile is a small tile in the bottom-right corner while anyone else is in the call (above the control bar on a narrower
- * window, and at the top on a phone, where the bar wraps onto a second row), and fills the tile area while they are
- * alone.
+ * the branded page shell, whose header, footer and padding pushed it off the screen.
+ *
+ * ## Where the local tile appears
+ *
+ * In plain grid view (not focus, not presenting), the local tile is an ordinary member of the grid, same size as
+ * everyone else's, rather than a floating corner overlay - so with exactly two participants, the local tile is
+ * genuinely one of the two grid cells, not a small picture-in-picture over the other person's. The floating corner
+ * tile (above the control bar on a narrower window, at the top on a phone, where the bar wraps onto a second row)
+ * is reserved for focus/presentation layouts, where there's already a single large tile the local one would
+ * otherwise compete with for space. Either way, alone in the call, the local tile simply fills the whole stage
+ * (see the `alone` branch of the `stage` computation).
+ *
+ * `selfHidden` (`handleHideSelf()`/`handleToggleSelfHidden()`) removes the local tile from view entirely, wherever
+ * it would otherwise appear - set from the tile's own corner "…" menu (`_ParticipantTile.tsx`'s `onHideSelf`, one
+ * directional: there's no tile left to click "show" on once it's gone) or toggled back on from the navbar's own
+ * "…" menu (`_CallControls.tsx`), which is the only way to re-show it from grid view, where there'd otherwise be
+ * nothing left bearing a "show self" control. Never honored while `alone`: hiding the only tile on screen would
+ * just blank it, so the local tile ignores `selfHidden` there and always shows.
  *
  * ## Who is heard
  *