@rapidmx/meet-plugin 0.9.2 → 0.10.0

package/apps/shared/media/filters/ScreenTransform.ts

@@ -0,0 +1,148 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz. All rights reserved.
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Rotates and/or flips a screen-share track before it's sent, so everyone - the presenter included, since their own
+ * preview is this same processor's output - sees it the right way round, rather than however the browser's own
+ * window/screen capture happened to hand it back. Window capture in particular has a known, driver/compositor-
+ * dependent history of occasionally returning upside-down or sideways frames for a specific captured window; this
+ * is the presenter's own manual correction for that, not an automatic fix (there's no reliable way to detect it
+ * from pixels alone).
+ *
+ * Reuses `VideoFilterProcessor.ts`'s own shape (a hidden `<video>` playing the source track, a canvas redrawn on a
+ * timer, `captureStream()` exposing the result) but far simpler: no models to load, no per-frame throttling to
+ * worry about, just a transform applied on each draw. Entirely independent of the camera pipeline - `useLocalMedia`'s
+ * filters never see the screen-share track, and this never touches the camera's.
+ */
+
+/** A rotation in degrees clockwise. */
+export type ScreenRotation = 0 | 90 | 180 | 270;
+
+export interface ScreenTransformState {
+    rotation: ScreenRotation;
+    /** Mirrored left-right, applied before the rotation (so "flip, then turn" - the usual photo-editing order). */
+    flipped: boolean;
+}
+
+export const NO_SCREEN_TRANSFORM: ScreenTransformState = { rotation: 0, flipped: false };
+
+/** The next rotation clockwise, wrapping back to 0 after 270. */
+export function rotateClockwise(state: ScreenTransformState): ScreenTransformState {
+    const next: Record<ScreenRotation, ScreenRotation> = { 0: 90, 90: 180, 180: 270, 270: 0 };
+    return { ...state, rotation: next[state.rotation] };
+}
+
+export interface ScreenTransformDeps {
+    createCanvas(): HTMLCanvasElement;
+    createVideo(): HTMLVideoElement;
+    now(): number;
+}
+
+/** Screen share doesn't need the camera's 30fps - matches `VIDEO_FPS`, what the relay's own `VideoSender` already
+ * encodes a shared screen at. */
+const DEFAULT_FRAME_RATE = 15;
+
+const DEFAULT_DEPS: ScreenTransformDeps = {
+    createCanvas: () => document.createElement("canvas"),
+    createVideo: () => document.createElement("video"),
+    now: () => performance.now(),
+};
+
+export interface ScreenTransformOptions {
+    /** The screen-share track. Only ever read - stopping it stays with whoever owns it (`_CallView.tsx`). */
+    source: MediaStreamTrack;
+    state?: ScreenTransformState;
+    frameRate?: number;
+    deps?: Partial<ScreenTransformDeps>;
+}
+
+export class ScreenTransformProcessor {
+    /** The transformed video - what to send in place of the screen track's own. */
+    readonly track: MediaStreamTrack;
+
+    private readonly deps: ScreenTransformDeps;
+    private readonly interval: number;
+    private readonly video: HTMLVideoElement;
+    private readonly canvas: HTMLCanvasElement;
+    private readonly ctx: CanvasRenderingContext2D;
+
+    private state: ScreenTransformState;
+    private stopped = false;
+    private timer: ReturnType<typeof setTimeout> | undefined;
+
+    constructor(options: ScreenTransformOptions) {
+        this.deps = { ...DEFAULT_DEPS, ...options.deps };
+        this.state = options.state ?? NO_SCREEN_TRANSFORM;
+        const frameRate = options.frameRate ?? DEFAULT_FRAME_RATE;
+        this.interval = 1000 / frameRate;
+
+        this.canvas = this.deps.createCanvas();
+        const ctx = this.canvas.getContext("2d");
+        if (!ctx) {
+            throw new Error("This browser can't rotate the shared screen.");
+        }
+        this.ctx = ctx;
+        this.track = this.canvas.captureStream(frameRate).getVideoTracks()[0];
+
+        this.video = this.deps.createVideo();
+        this.video.muted = true;
+        this.video.playsInline = true;
+        this.video.srcObject = new MediaStream([options.source]);
+        void this.video.play().catch(() => undefined);
+
+        this.tick();
+    }
+
+    /** Changes the rotation/flip without interrupting the video. */
+    setState(state: ScreenTransformState): void {
+        this.state = state;
+    }
+
+    stop(): void {
+        this.stopped = true;
+        clearTimeout(this.timer);
+        this.video.pause();
+        this.video.srcObject = null;
+        this.track.stop();
+    }
+
+    private tick = (): void => {
+        if (this.stopped) {
+            return;
+        }
+        const started = this.deps.now();
+        if (this.video.readyState >= 2 && this.video.videoWidth > 0) {
+            this.render();
+        }
+        this.timer = setTimeout(this.tick, Math.max(0, this.interval - (this.deps.now() - started)));
+    };
+
+    private render(): void {
+        const { video, canvas, ctx, state } = this;
+        const sourceWidth = video.videoWidth;
+        const sourceHeight = video.videoHeight;
+        // A quarter turn swaps which way is "wide" - the canvas (and so the track everyone actually receives) must
+        // match, or the picture is squashed into the untransformed aspect ratio.
+        const swapped = state.rotation === 90 || state.rotation === 270;
+        const width = swapped ? sourceHeight : sourceWidth;
+        const height = swapped ? sourceWidth : sourceHeight;
+        if (canvas.width !== width || canvas.height !== height) {
+            canvas.width = width;
+            canvas.height = height;
+        }
+
+        if (state.rotation === 0 && !state.flipped) {
+            ctx.drawImage(video, 0, 0, sourceWidth, sourceHeight);
+            return;
+        }
+        ctx.save();
+        ctx.translate(width / 2, height / 2);
+        ctx.rotate((state.rotation * Math.PI) / 180);
+        if (state.flipped) {
+            ctx.scale(-1, 1);
+        }
+        ctx.drawImage(video, -sourceWidth / 2, -sourceHeight / 2, sourceWidth, sourceHeight);
+        ctx.restore();
+    }
+}

package/apps/shared/media/useLocalMedia.ts

@@ -38,6 +38,7 @@ import {
     defaultMediaDevices,
     isMediaDevicesSupported,
     listDevices,
+    notFoundError,
     requestUserMedia,
 } from "./deviceMedia.js";
 import { startLevelMeter } from "./levelMeter.js";
@@ -115,9 +116,32 @@ function statusFor(error: MediaAccessError): TrackStatus {
     }
 }
 
+/** After asking for the camera and the microphone separately (`acquireBoth()`'s fallback, one at a time rather
+ * than together), the one error to show for both attempts together - naming both devices when both are actually
+ * missing, rather than just whichever of the two happened to be asked about last (which would otherwise say "no
+ * camera" even when the microphone is *also* missing, or say nothing at all when only the microphone is missing,
+ * since the camera's own success would otherwise clear the error the microphone's failure had just set). `null`
+ * when both succeeded. */
+function combineErrors(audio: MediaAccessError | null, video: MediaAccessError | null): MediaAccessError | null {
+    if (!audio || !video) {
+        return audio ?? video;
+    }
+    if (audio.kind === "not-found" && video.kind === "not-found") {
+        return notFoundError(true, true);
+    }
+    // Different reasons - unusual (e.g. permission denied for one, missing hardware for the other). Permission is
+    // the more actionable of the two, so it's what's shown; otherwise there's no single message that honestly
+    // describes both, so this just picks one.
+    return audio.kind === "permission-denied" ? audio : video;
+}
+
 export interface LocalMediaOptions {
     /** Where the filters' models are hosted, when not on the default CDN - see `filters/mlModels.ts`. */
     effectsAssetsUrl?: string;
+    /** The host's `VideoMeeting.forceMuteOnJoin` setting - when `true`, this call's microphone starts muted
+     * regardless of what was remembered from a previous call, overriding (but never overwriting) that preference -
+     * see `ensurePrefs()`. `undefined`/`false` changes nothing. */
+    forceMuteOnJoin?: boolean;
 }
 
 /** `base`, asking for `preferredId` (the device used last time) when there is one - as a preference, not a demand. */
@@ -125,7 +149,7 @@ function preferring(base: MediaTrackConstraints, preferredId?: string): MediaTra
     return preferredId ? { ...base, deviceId: { ideal: preferredId } } : base;
 }
 
-export function useLocalMedia({ effectsAssetsUrl }: LocalMediaOptions = {}): LocalMedia {
+export function useLocalMedia({ effectsAssetsUrl, forceMuteOnJoin }: LocalMediaOptions = {}): LocalMedia {
     const [supported, setSupported] = useState(true);
     const [requesting, setRequesting] = useState(false);
     const [error, setError] = useState<MediaAccessError | null>(null);
@@ -166,7 +190,7 @@ export function useLocalMedia({ effectsAssetsUrl }: LocalMediaOptions = {}): Loc
         }
         const prefs = loadPreferences();
         prefsRef.current = prefs;
-        if (prefs.micEnabled === false) {
+        if (prefs.micEnabled === false || forceMuteOnJoin) {
             micEnabledRef.current = false;
             setMicEnabled(false);
         }
@@ -184,7 +208,7 @@ export function useLocalMedia({ effectsAssetsUrl }: LocalMediaOptions = {}): Loc
             );
         }
         return prefs;
-    }, [applyBackground, applyFilters]);
+    }, [applyBackground, applyFilters, forceMuteOnJoin]);
 
     /** Saves a change to the remembered settings. */
     const remember = useCallback(
@@ -245,7 +269,7 @@ export function useLocalMedia({ effectsAssetsUrl }: LocalMediaOptions = {}): Loc
 
     /** Asks for one kind on its own - a specific device when `deviceId` is given, else the one used last time. */
     const acquire = useCallback(
-        async (kind: MediaKind, deviceId?: string): Promise<boolean> => {
+        async (kind: MediaKind, deviceId?: string): Promise<MediaAccessError | null> => {
             const base = kind === "audio" ? AUDIO_CONSTRAINTS : VIDEO_CONSTRAINTS;
             const prefs = ensurePrefs();
             const constraint: MediaTrackConstraints = deviceId
@@ -257,13 +281,13 @@ export function useLocalMedia({ effectsAssetsUrl }: LocalMediaOptions = {}): Loc
                     setError(result.error);
                     setStatus((prev) => ({ ...prev, [kind]: statusFor(result.error) }));
                 }
-                return false;
+                return result.error;
             }
             adoptStream(result.value);
             if (mountedRef.current) {
                 setError(null);
             }
-            return true;
+            return null;
         },
         [adoptStream, ensurePrefs],
     );
@@ -292,9 +316,13 @@ export function useLocalMedia({ effectsAssetsUrl }: LocalMediaOptions = {}): Loc
             }
         } else {
             // No camera, no microphone, or the two together couldn't be satisfied: ask for each on its own, so one
-            // missing device doesn't cost the participant the other.
-            await acquire("audio");
-            await acquire("video");
+            // missing device doesn't cost the participant the other - then combine what each found into one
+            // message (see `combineErrors()`) rather than showing whichever of the two ran last.
+            const audioError = await acquire("audio");
+            const videoError = await acquire("video");
+            if (mountedRef.current) {
+                setError(combineErrors(audioError, videoError));
+            }
         }
     }, [acquire, adoptStream, ensurePrefs]);
 
@@ -359,7 +387,7 @@ export function useLocalMedia({ effectsAssetsUrl }: LocalMediaOptions = {}): Loc
                     setTracks(tracksRef.current);
                 }
             }
-            if (await acquire(kind, deviceId)) {
+            if ((await acquire(kind, deviceId)) === null) {
                 remember(kind === "audio" ? { microphoneId: deviceId } : { cameraId: deviceId });
             }
             await refreshDevices();

package/apps/shared/relay/AudioPlayer.ts

@@ -16,6 +16,10 @@ export const JITTER_BUFFER_SECONDS = 0.08;
 export const MAX_AHEAD_SECONDS = 0.4;
 /** Skip a packet instead of queueing it when the decoder is this far behind. */
 export const AUDIO_MAX_DECODE_QUEUE = 16;
+/** The length of the fade-in `play()` gives a block that doesn't pick up exactly where the last one left off (the
+ * first block, or the one after a gap) - long enough to mask the click such a discontinuity would otherwise
+ * produce, short enough that it is never heard as an actual fade. */
+export const DISCONTINUITY_FADE_SECONDS = 0.004;
 
 /**
  * Decodes one sender's Opus packets and schedules them for playback into a `MediaStreamAudioDestinationNode`.
@@ -23,8 +27,16 @@ export const AUDIO_MAX_DECODE_QUEUE = 16;
  * Each decoded block is copied into an `AudioBuffer` and started on its own `AudioBufferSourceNode` at
  * `max(currentTime + jitter, nextTime)`, where `nextTime` is when the previous block ends - so consecutive blocks
  * join seamlessly, and after a gap in the stream playback restarts with the jitter buffer's worth of headroom.
- * Opus packets are independently decodable, so a lost packet costs only its own 20 ms and needs no recovery step;
- * the decoder is created lazily and discarded on any error, and replaced by the next packet.
+ * Opus packets are independently decodable, so a lost packet costs only its own 20 ms and needs no recovery step
+ * *in terms of content* - but the shared decoder (reused across packets so it keeps its normal state between them,
+ * not recreated per packet) is never told a packet was skipped, so its internal prediction state no longer matches
+ * what it decodes next. Audibly this can be a click right at that seam, not just silence where the lost packet
+ * would have been - the same is true of the very first block (nothing at all came before it) and of the block
+ * after a stall long enough to need the jitter buffer's full headroom again. `play()` gives exactly those blocks a
+ * few milliseconds' fade-in (`DISCONTINUITY_FADE_SECONDS`) through a `GainNode` to mask it; an ordinary block that
+ * picks up exactly where the last one ended gets none - fading *every* block would itself be audible, a faint
+ * tremolo at the packet rate. The decoder is created lazily and discarded on any error, and replaced by the next
+ * packet.
  */
 export class AudioPlayer {
     private decoder: DecoderLike | undefined;
@@ -97,9 +109,23 @@ export class AudioPlayer {
             buffer.copyToChannel(pcm, 0);
             const source = this.ctx.createBufferSource();
             source.buffer = buffer;
-            source.connect(this.destination);
-            source.onended = () => source.disconnect();
             const start = Math.max(now + JITTER_BUFFER_SECONDS, this.nextTime);
+            if (start > this.nextTime) {
+                // A gap, not a continuation - the decoder's state no longer matches what it's about to decode (see
+                // this class's doc comment), so fade this block in rather than let it start abruptly.
+                const gain = this.ctx.createGain();
+                gain.gain.setValueAtTime(0, start);
+                gain.gain.linearRampToValueAtTime(1, start + DISCONTINUITY_FADE_SECONDS);
+                source.connect(gain);
+                gain.connect(this.destination);
+                source.onended = () => {
+                    source.disconnect();
+                    gain.disconnect();
+                };
+            } else {
+                source.connect(this.destination);
+                source.onended = () => source.disconnect();
+            }
             source.start(start);
             this.nextTime = start + buffer.duration;
         } catch {

package/apps/shared/relay/relayEnv.ts

@@ -74,7 +74,14 @@ export interface ScriptProcessorLike extends AudioNodeLike {
 }
 
 export interface GainLike extends AudioNodeLike {
-    gain: { value: number };
+    gain: {
+        value: number;
+        /** `AudioParam.setValueAtTime()` - used to schedule a fade (`AudioPlayer`'s discontinuity fade-in), not
+         * needed for `AudioSender`'s own static, unscheduled mute (a plain `.value = 0` assignment). */
+        setValueAtTime(value: number, startTime: number): unknown;
+        /** `AudioParam.linearRampToValueAtTime()`. */
+        linearRampToValueAtTime(value: number, endTime: number): unknown;
+    };
 }
 
 export interface AudioBufferLike {

package/apps/shared/webrtc/MeshConnectionManager.ts

@@ -62,6 +62,15 @@
  *
  * Sharing a screen is `setLocalTrack("video", screenTrack)`; stopping is `setLocalTrack("video", cameraTrack)`.
  *
+ * ## Host moderation (`mute-request`, `kicked`)
+ *
+ * `sendMuteRequest()`/`sendKick()` send a point-to-point signal to one peer; the manager itself does not decide who
+ * may send one - a "host" identity exists only in `_CallView.tsx`, which shows the controls that call these
+ * methods to nobody but the host (see `types.ts`'s `SignalMessage` doc comment for why this is cooperative, not
+ * enforced, at the signaling layer). Receiving one emits `mute-requested`/`kicked` for the caller to act on; this
+ * manager takes no action of its own beyond that - it doesn't mute a track or tear itself down, since a kicked
+ * participant's actual departure is `stop()`, which the caller decides to call.
+ *
  * ## Three media paths, tried in order
  *
  * Each pair of participants reaches for the best path that works, and `MeshParticipant.transport` says which one it
@@ -115,6 +124,11 @@ export const DEFAULT_CONNECT_TIMEOUT_MS = 15_000;
 /** How long a connection may stay `disconnected` (ICE lost the path but may still recover) before giving up on it. */
 export const DEFAULT_DISCONNECTED_GRACE_MS = 8_000;
 
+/** How often a connected pair's quality stats (the diagnostics panel) are refreshed - low frequency on purpose:
+ * this is for a participant occasionally checking why a call feels off, not a live chart, and `getStats()` is not
+ * free to call every frame. */
+export const DEFAULT_DIAGNOSTICS_POLL_MS = 3_000;
+
 type MediaKind = "audio" | "video";
 
 interface PeerState extends MeshParticipant {
@@ -128,6 +142,9 @@ 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. */
+    diagnosticsTimer: ReturnType<typeof setInterval> | undefined;
 }
 
 export interface MeshConnectionManagerOptions {
@@ -156,6 +173,8 @@ export interface MeshConnectionManagerOptions {
     connectTimeoutMs?: number;
     /** Defaults to `DEFAULT_DISCONNECTED_GRACE_MS`. */
     disconnectedGraceMs?: number;
+    /** Defaults to `DEFAULT_DIAGNOSTICS_POLL_MS`. */
+    diagnosticsPollMs?: number;
 }
 
 export class MeshConnectionManager {
@@ -222,6 +241,7 @@ export class MeshConnectionManager {
         this.unsubscribe = undefined;
         for (const peer of this.peers.values()) {
             this.clearTimers(peer);
+            this.stopDiagnosticsPolling(peer);
             peer.pc.close();
         }
         this.peers.clear();
@@ -285,6 +305,20 @@ export class MeshConnectionManager {
         this.emit({ type: "presenter-changed", uid: undefined });
     }
 
+    /** Asks `peerUid`'s participant to mute - a cooperative signal (see this module's doc comment on host
+     * moderation), not enforcement. Nothing here checks that the local participant is actually the host; the caller
+     * is responsible for only offering this to one. */
+    sendMuteRequest(peerUid: string): void {
+        this.send({ kind: "mute-request", to: peerUid });
+    }
+
+    /** Tells `peerUid`'s participant they have been removed from the call. Sends only the cooperative signal - it
+     * does not itself revoke `peerUid`'s server-side channel grant (see `BaseVideoMeetingRoute.revokeChannelGrant()`,
+     * which the caller is expected to call alongside this for an enforced removal). */
+    sendKick(peerUid: string): void {
+        this.send({ kind: "kicked", to: peerUid });
+    }
+
     private sendHello(): void {
         this.send({ kind: "hello", name: this.options.selfName, state: this.localState });
     }
@@ -345,6 +379,12 @@ export class MeshConnectionManager {
             case "relay-fallback":
                 this.handleRelayFallback(message.from);
                 return;
+            case "mute-request":
+                this.emit({ type: "mute-requested" });
+                return;
+            case "kicked":
+                this.emit({ type: "kicked" });
+                return;
         }
     }
 
@@ -408,6 +448,7 @@ export class MeshConnectionManager {
             return;
         }
         this.clearTimers(peer);
+        this.stopDiagnosticsPolling(peer);
         peer.pc.close();
         this.peers.delete(uid);
         if (peer.transport === "websocket") {
@@ -440,6 +481,7 @@ export class MeshConnectionManager {
             transport: "connecting",
             connectTimer: undefined,
             disconnectTimer: undefined,
+            diagnosticsTimer: undefined,
         };
         this.orphanCandidates.delete(uid);
         this.peers.set(uid, peer);
@@ -484,9 +526,10 @@ export class MeshConnectionManager {
         }
     }
 
-    /** Records whether a connected pair is direct or relayed through TURN, from the candidate pair ICE selected. */
+    /** Records whether a connected pair is direct, relayed through TURN, or relayed through TURN over TCP (see
+     * `MediaTransport`'s doc comment), from the candidate pair ICE selected. */
     private async detectTransport(peer: PeerState): Promise<void> {
-        let type: "p2p" | "turn" | "unknown";
+        let type: "p2p" | "turn" | "turn-tcp" | "unknown";
         try {
             type = await peer.pc.connectionType();
         } catch {
@@ -494,7 +537,39 @@ export class MeshConnectionManager {
         }
         // The pair may have moved on (fallen back, left, or dropped again) while the stats were being read.
         if (peer.transport !== "websocket" && this.peers.get(peer.uid) === peer && peer.pc.connectionState === "connected") {
-            this.setTransport(peer, type === "turn" ? "turn" : "p2p");
+            this.setTransport(peer, type === "turn" || type === "turn-tcp" ? type : "p2p");
+            this.startDiagnosticsPolling(peer);
+        }
+    }
+
+    /** Idempotent - a pair that reconnects without ever leaving WebRTC (`connected` -> `disconnected` -> `connected`
+     * again) does not get a second timer. */
+    private startDiagnosticsPolling(peer: PeerState): void {
+        if (peer.diagnosticsTimer !== undefined) {
+            return;
+        }
+        const pollMs = this.options.diagnosticsPollMs ?? DEFAULT_DIAGNOSTICS_POLL_MS;
+        peer.diagnosticsTimer = setInterval(() => void this.pollDiagnostics(peer), pollMs);
+        void this.pollDiagnostics(peer); // the first sample doesn't wait a full interval
+    }
+
+    private stopDiagnosticsPolling(peer: PeerState): void {
+        clearInterval(peer.diagnosticsTimer);
+        peer.diagnosticsTimer = undefined;
+    }
+
+    private async pollDiagnostics(peer: PeerState): Promise<void> {
+        let diagnostics: MeshParticipant["diagnostics"];
+        try {
+            diagnostics = await peer.pc.collectDiagnostics();
+        } catch {
+            // Leaves whatever was last polled in place rather than blanking a momentary failure.
+            return;
+        }
+        // The pair may have moved on (fallen back, left, or dropped again) while the stats were being read.
+        if (this.peers.get(peer.uid) === peer && peer.diagnosticsTimer !== undefined) {
+            peer.diagnostics = diagnostics;
+            this.emit({ type: "participant-updated", participant: toParticipant(peer) });
         }
     }
 
@@ -522,6 +597,8 @@ export class MeshConnectionManager {
             return;
         }
         this.clearTimers(peer);
+        this.stopDiagnosticsPolling(peer);
+        peer.diagnostics = undefined;
         const relay = this.options.relay;
         if (!relay?.supported) {
             this.setTransport(peer, "failed");
@@ -667,7 +744,15 @@ export class MeshConnectionManager {
 }
 
 function toParticipant(peer: PeerState): MeshParticipant {
-    return { uid: peer.uid, name: peer.name, audioOn: peer.audioOn, videoOn: peer.videoOn, handRaised: peer.handRaised, transport: peer.transport };
+    return {
+        uid: peer.uid,
+        name: peer.name,
+        audioOn: peer.audioOn,
+        videoOn: peer.videoOn,
+        handRaised: peer.handRaised,
+        transport: peer.transport,
+        diagnostics: peer.diagnostics,
+    };
 }
 
 function sameState(a: ParticipantState, b: ParticipantState): boolean {

package/apps/shared/webrtc/realPeerConnection.ts

@@ -7,15 +7,23 @@
  * this factory's only real caller. `createBrowserPeerConnection` is a plain function value, never invoked at
  * module scope, so importing this file is safe during this plugin's page SSR, where `RTCPeerConnection` does not
  * exist at all - it would only throw if actually *called* outside a browser. */
-import type { RTCPeerConnectionFactory, RTCPeerConnectionLike } from "./types.js";
+import type { ConnectionDiagnostics, RTCPeerConnectionFactory, RTCPeerConnectionLike, RtpStreamDiagnostics } from "./types.js";
 
 /**
- * Whether the pair ICE settled on goes through a TURN relay. The selected pair is found the standard way (the
- * `transport` report's `selectedCandidatePairId`) and, for a browser that does not fill that in, as the succeeded and
- * nominated `candidate-pair`. A relay on *either* end means the media passes through a TURN server, so it counts as
- * `"turn"`; `"unknown"` when no pair is reported at all.
+ * Whether the pair ICE settled on goes through a TURN relay, and - when it's our own end that's relayed - whether
+ * that relay is TCP (`turn-tcp`, meaning `turns:` too, TLS being TCP-based as well) rather than UDP. The selected
+ * pair is found the standard way (the `transport` report's `selectedCandidatePairId`) and, for a browser that does
+ * not fill that in, as the succeeded and nominated `candidate-pair`. A relay on *either* end means the media
+ * passes through a TURN server, so it counts as at least `"turn"`; `"unknown"` when no pair is reported at all.
+ *
+ * The TCP/UDP distinction matters because they fail very differently under loss: UDP just drops the lost packet
+ * (a click), while TCP retransmits it and blocks everything queued behind it until that arrives (a stall) - exactly
+ * the "gaps that feel like latency, not packet loss" a participant on a TCP-relayed connection reports. `relayProtocol`
+ * (`"udp"`/`"tcp"`/`"tls"`) is only ever reported on a *local* relay candidate - there's no equivalent visibility into
+ * how the *remote* peer reaches its own TURN allocation, so a relay on the remote end alone is reported as plain
+ * `"turn"` rather than guessed at.
  */
-export async function selectedConnectionType(pc: Pick<RTCPeerConnection, "getStats">): Promise<"p2p" | "turn" | "unknown"> {
+export async function selectedConnectionType(pc: Pick<RTCPeerConnection, "getStats">): Promise<"p2p" | "turn" | "turn-tcp" | "unknown"> {
     const reports = new Map<string, Record<string, unknown>>();
     (await pc.getStats()).forEach((report: Record<string, unknown>) => reports.set(String(report.id), report));
     const transport = [...reports.values()].find((report) => report.type === "transport" && report.selectedCandidatePairId);
@@ -27,7 +35,38 @@ export async function selectedConnectionType(pc: Pick<RTCPeerConnection, "getSta
     }
     const local = reports.get(String(pair.localCandidateId));
     const remote = reports.get(String(pair.remoteCandidateId));
-    return local?.candidateType === "relay" || remote?.candidateType === "relay" ? "turn" : "p2p";
+    if (local?.candidateType !== "relay" && remote?.candidateType !== "relay") {
+        return "p2p";
+    }
+    const relayProtocol = local?.candidateType === "relay" ? String(local.relayProtocol ?? "") : "";
+    return relayProtocol === "tcp" || relayProtocol === "tls" ? "turn-tcp" : "turn";
+}
+
+function streamDiagnostics(reports: Map<string, Record<string, unknown>>, kind: "audio" | "video"): RtpStreamDiagnostics {
+    const inbound = [...reports.values()].find((report) => report.type === "inbound-rtp" && report.kind === kind);
+    const outbound = [...reports.values()].find((report) => report.type === "outbound-rtp" && report.kind === kind);
+    const num = (value: unknown): number | undefined => (typeof value === "number" ? value : undefined);
+    return {
+        packetsLost: num(inbound?.packetsLost),
+        jitter: num(inbound?.jitter),
+        bytesSent: num(outbound?.bytesSent),
+        bytesReceived: num(inbound?.bytesReceived),
+    };
+}
+
+/** One point-in-time sample of this connection's own quality stats, for the diagnostics panel - a single
+ * `getStats()` walk, independent of (and in addition to) `selectedConnectionType()`'s own call, since this is
+ * polled periodically at a much lower priority than the one-time transport check and there's no value in coupling
+ * the two together. */
+export async function collectDiagnostics(pc: Pick<RTCPeerConnection, "getStats">): Promise<ConnectionDiagnostics> {
+    const reports = new Map<string, Record<string, unknown>>();
+    (await pc.getStats()).forEach((report: Record<string, unknown>) => reports.set(String(report.id), report));
+    const transport = [...reports.values()].find((report) => report.type === "transport" && report.selectedCandidatePairId);
+    const pair =
+        (transport ? reports.get(String(transport.selectedCandidatePairId)) : undefined) ??
+        [...reports.values()].find((report) => report.type === "candidate-pair" && (report.selected || (report.nominated && report.state === "succeeded")));
+    const roundTripTimeSeconds = typeof pair?.currentRoundTripTime === "number" ? pair.currentRoundTripTime : undefined;
+    return { roundTripTimeSeconds, audio: streamDiagnostics(reports, "audio"), video: streamDiagnostics(reports, "video") };
 }
 
 export const createBrowserPeerConnection: RTCPeerConnectionFactory = (config) => {
@@ -55,6 +94,7 @@ export const createBrowserPeerConnection: RTCPeerConnectionFactory = (config) =>
         addIceCandidate: (candidate) => pc.addIceCandidate(candidate),
         close: () => pc.close(),
         connectionType: () => selectedConnectionType(pc),
+        collectDiagnostics: () => collectDiagnostics(pc),
         onicecandidate: null,
         ontrack: null,
         onconnectionstatechange: null,