@rapidmx/meet-plugin 0.9.3 → 0.11.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

@@ -138,6 +138,10 @@ function combineErrors(audio: MediaAccessError | null, video: MediaAccessError |
 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. */
@@ -145,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);
@@ -186,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);
         }
@@ -204,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(

package/apps/shared/webrtc/MeshConnectionManager.ts

@@ -62,6 +62,28 @@
  *
  * 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.
+ *
+ * ## Talking stick (`talking-stick`)
+ *
+ * One exclusive "floor" - at most one participant may be unmuted at a time, host-assigned - but unlike presenter,
+ * there is no claim race to resolve: only the host's own client ever calls `setTalkingStick()` (same trust level as
+ * `sendMuteRequest()`/`sendKick()` - nothing here checks that), so the manager carries no state of its own and
+ * simply relays the latest message it sees as `talking-stick-changed`, applying it to itself too via an immediate
+ * local emit (the same "optimistic, no round trip" shape `claimPresenter()`/`releasePresenter()` use). A holder who
+ * leaves the call is not specially reassigned - every other participant's existing `participant-left` handling
+ * already drops them from the roster, and "the stick's holder is no longer in the call" is simply "nobody is holder
+ * right now" without any manager needing to say so, until the host picks someone (or themselves) again. There is no
+ * backend route or persisted field for this at all: like `mute-request`/`kicked`, it only matters while people are
+ * actually in the call together.
+ *
  * ## 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 +137,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 +155,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 +186,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 +254,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 +318,30 @@ 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 });
+    }
+
+    /** Turns talking-stick mode on (naming `holder`, the initial speaker) or off (`active: false`, `holder`
+     * omitted), or hands an already-active stick to a different `holder` - see this module's doc comment on why
+     * there is no collision to resolve here, unlike presenter. Broadcasts and applies locally at once, trusting
+     * there is only ever one sender; the caller (`_CallView.tsx`) is responsible for only offering this to the
+     * host. */
+    setTalkingStick(active: boolean, holder?: string): void {
+        this.send({ kind: "talking-stick", active, holder });
+        this.emit({ type: "talking-stick-changed", active, holder });
+    }
+
     private sendHello(): void {
         this.send({ kind: "hello", name: this.options.selfName, state: this.localState });
     }
@@ -345,6 +402,15 @@ 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;
+            case "talking-stick":
+                this.emit({ type: "talking-stick-changed", active: message.active === true, holder: typeof message.holder === "string" ? message.holder : undefined });
+                return;
         }
     }
 
@@ -408,6 +474,7 @@ export class MeshConnectionManager {
             return;
         }
         this.clearTimers(peer);
+        this.stopDiagnosticsPolling(peer);
         peer.pc.close();
         this.peers.delete(uid);
         if (peer.transport === "websocket") {
@@ -440,6 +507,7 @@ export class MeshConnectionManager {
             transport: "connecting",
             connectTimer: undefined,
             disconnectTimer: undefined,
+            diagnosticsTimer: undefined,
         };
         this.orphanCandidates.delete(uid);
         this.peers.set(uid, peer);
@@ -484,9 +552,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 +563,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 +623,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 +770,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,

package/apps/shared/webrtc/types.ts

@@ -28,10 +28,18 @@ export const REACTION_EMOJIS = ["👍", "👏", "❤️", "🎉", "😂", "😮"
  * 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.
  *
- * `hello`/`bye`/`presenter-claim`/`presenter-release`/`state`/`reaction` are broadcast (`to` left unset - every
- * participant is relevant); `offer`/`answer`/`ice-candidate` 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.
+ * `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.
+ *
+ * `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
+ * nothing on the wire distinguishes a genuine host's message from any other participant's, since this client
+ * protocol has no host identity of its own to check against server-side. `kicked` is paired with the sender also
+ * revoking the recipient's server-side channel grant (`BaseVideoMeetingRoute.revokeChannelGrant()`), which is
+ * enforced and does not depend on the recipient's client cooperating; `talking-stick` has no server-side
+ * counterpart at all (see this module's doc comment on why it is purely an in-call runtime signal).
  */
 export interface SignalMessage {
     type: "video-meeting-signal";
@@ -45,7 +53,10 @@ export interface SignalMessage {
         | "presenter-release"
         | "state"
         | "reaction"
-        | "relay-fallback";
+        | "relay-fallback"
+        | "mute-request"
+        | "kicked"
+        | "talking-stick";
     /** 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
@@ -64,6 +75,11 @@ export interface SignalMessage {
     state?: ParticipantState;
     /** `reaction` only - one of `REACTION_EMOJIS`. */
     emoji?: string;
+    /** `talking-stick` only - whether talking-stick mode is currently on. */
+    active?: boolean;
+    /** `talking-stick` only - the peer id (`MeshParticipant.uid`/this tab's own id) currently holding the stick.
+     * Absent when `active` is `false`, or when nobody holds it yet. */
+    holder?: string;
     /** `offer`/`answer` only. */
     sdp?: RTCSessionDescriptionInit;
     /** `ice-candidate` only. */
@@ -81,6 +97,28 @@ export interface SignalingChannel {
     onMessage(handler: (message: SignalMessage) => void): () => void;
 }
 
+/** One kind's RTP stream stats, as of one sample - cumulative counters (`bytesSent`/`bytesReceived`), not a rate,
+ * since a single `getStats()` snapshot has no "since when" to divide by; a caller wanting a bitrate keeps the
+ * previous sample itself and divides the difference by the elapsed time (see `MeshConnectionManager`'s poller).
+ * `undefined` for anything this browser (or this stream's direction - an audio-only connection reports nothing for
+ * video, and vice versa) doesn't report. */
+export interface RtpStreamDiagnostics {
+    packetsLost?: number;
+    /** Seconds. */
+    jitter?: number;
+    bytesSent?: number;
+    bytesReceived?: number;
+}
+
+/** One point-in-time sample of a connection's own quality stats, for the diagnostics panel. */
+export interface ConnectionDiagnostics {
+    /** Seconds - the selected candidate pair's own current round-trip time. `undefined` when this browser doesn't
+     * report one (a connection still connecting, or simply not supported). */
+    roundTripTimeSeconds?: number;
+    audio: RtpStreamDiagnostics;
+    video: RtpStreamDiagnostics;
+}
+
 /** 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,
  * switching a device or sharing a screen only ever replaces the track a sender sends - no renegotiation. A real
@@ -115,17 +153,24 @@ export interface RTCPeerConnectionLike {
     connectionState: string;
     /** Which path the connected pair is using - read from the selected candidate pair once `connectionState` is
      * `connected`. `"unknown"` when the browser does not report one (treated as direct by the caller). */
-    connectionType(): Promise<"p2p" | "turn" | "unknown">;
+    connectionType(): Promise<"p2p" | "turn" | "turn-tcp" | "unknown">;
+    /** One point-in-time sample of this connection's own quality stats, for the diagnostics panel - polled
+     * periodically and independently of `connectionType()` (see `MeshConnectionManager`'s doc comment). */
+    collectDiagnostics(): Promise<ConnectionDiagnostics>;
 }
 
 /** Which of the three media paths a participant's audio and video currently take, in the order they are tried:
  *
  * - `"p2p"`: a direct peer-to-peer WebRTC connection, the preferred path.
  * - `"turn"`: still WebRTC, but relayed through the TURN server, for a participant a direct path cannot reach.
+ * - `"turn-tcp"`: the same, but the relay hop itself is TCP (or `turns:`, TLS being TCP-based too) rather than UDP -
+ * a network that blocks UDP outright. TCP's reliable, ordered delivery means one lost or delayed packet stalls
+ * everything queued behind it instead of just being dropped, so this can sound like pauses rather than the clicks
+ * plain packet loss would - worth telling apart from ordinary `"turn"` for exactly that reason.
  * - `"websocket"`: not WebRTC at all - encoded frames proxied by this server over a WebSocket (see
  * `apps/shared/relay/`), the last resort when neither of the above connects.
  * - `"connecting"`: no path established yet. `"failed"`: every path this browser can try has failed. */
-export type MediaTransport = "connecting" | "p2p" | "turn" | "websocket" | "failed";
+export type MediaTransport = "connecting" | "p2p" | "turn" | "turn-tcp" | "websocket" | "failed";
 
 /** What `MeshConnectionManager` needs from the WebSocket media relay (`apps/shared/relay/RelayTransport.ts` implements
  * it) - declared here so the mesh, and its tests, depend on the shape alone. */
@@ -151,6 +196,10 @@ export interface MeshParticipant extends ParticipantState {
     name: string;
     /** 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). */
+    diagnostics?: ConnectionDiagnostics;
 }
 
 export type MeshEvent =
@@ -160,4 +209,14 @@ export type MeshEvent =
     | { type: "remote-stream"; uid: string; stream: MediaStream }
     | { type: "hand-raised"; uid: string; name: string }
     | { type: "reaction"; uid: string; name: string; emoji: string }
-    | { type: "presenter-changed"; uid: string | undefined };
+    | { type: "presenter-changed"; uid: string | undefined }
+    /** Someone (implicitly the host, on the client's own say-so - see `SignalMessage`'s doc comment) asked the local
+     * participant to mute. The caller (`_CallView.tsx`) mutes only if currently unmuted; this never unmutes anyone. */
+    | { type: "mute-requested" }
+    /** The local participant was removed from the call. The caller tears down the mesh and shows a distinct
+     * "removed by the host" state rather than the ordinary "you left" one. */
+    | { type: "kicked" }
+    /** Talking-stick mode turned on or off, or the stick changed hands - see this module's doc comment and
+     * `MeshConnectionManager.setTalkingStick()`. `holder` is the peer id now holding it; absent while `active` is
+     * `false`, or (transiently) if whoever held it has since left the call. */
+    | { type: "talking-stick-changed"; active: boolean; holder?: string };

package/dist/apps/meet/[token].d.ts

@@ -1,7 +1,10 @@
 /**
  * The public join/lobby/in-call page, `GET /meet/:token` - resolves an invitee's join token or a public meeting's
  * slug (`BaseVideoMeetingRoute.join()`, both shapes accepted identically - see `_meetApi.ts`), then walks through
- * `loading` -> `lobby` -> `in-call` -> `ended`.
+ * `loading` -> (`password`, only when a password is required) -> (`admission-request` then `waiting`, only when
+ * the meeting has a waiting room - see that phase's own render branch) -> `lobby` -> `in-call` -> `ended`. A
+ * waiting room takes over the entire gate (asking for a password too, on the same form) rather than stacking
+ * after a separate password screen - see `BaseVideoMeetingRoute.join()`'s own doc comment for why.
  *
  * ## Session-based name prefill - NOT implemented, and why
  *