@rapidmx/meet-plugin 0.9.3 → 0.10.0

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,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,

package/apps/shared/webrtc/types.ts

@@ -29,9 +29,16 @@ export const REACTION_EMOJIS = ["👍", "👏", "❤️", "🎉", "😂", "😮"
  * 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.
+ * 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` 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.
  */
 export interface SignalMessage {
     type: "video-meeting-signal";
@@ -45,7 +52,9 @@ export interface SignalMessage {
         | "presenter-release"
         | "state"
         | "reaction"
-        | "relay-fallback";
+        | "relay-fallback"
+        | "mute-request"
+        | "kicked";
     /** 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
@@ -81,6 +90,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 +146,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 +189,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 +202,10 @@ 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" };

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
  *

package/dist/apps/meet/[token].js

@@ -6,7 +6,10 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 /**
  * 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
  *
@@ -35,11 +38,15 @@ import useBranding from "@rapidmx/web-client/lib/branding/useBranding.js";
 import { ApiRequestError } from "@rapidmx/web-client/lib/util/api.js";
 import Button from "@rapidmx/web-client/lib/components/buttons/Button.js";
 import Alert from "@rapidmx/web-client/lib/components/feedback/Alert.js";
+import FormField from "@rapidmx/web-client/lib/components/forms/FormField.js";
 import { MeetCard, MeetPageShell } from "./_MeetChrome.js";
 import { useLocalMedia } from "../shared/media/useLocalMedia.js";
 import MeetLobby from "./_MeetLobby.js";
 import CallView from "./_CallView.js";
-import { joinMeeting } from "./_meetApi.js";
+import { joinMeeting, pollAdmission, requestAdmission, verifyMeetingPassword, } from "./_meetApi.js";
+const INPUT_CLASS = "w-full text-base py-2.5 px-3.5 border border-border rounded-md bg-surface text-text focus:outline-none focus:border-primary";
+/** How often `MeetJoinContent` polls while in the `"waiting"` phase. */
+const ADMISSION_POLL_MS = 3000;
 export default function MeetJoinPage({ params }) {
     const { branding } = useBranding();
     return _jsx(MeetJoinContent, { token: params.token, branding: branding });
@@ -52,16 +59,48 @@ function MeetJoinContent({ token, branding }) {
     const [name, setName] = useState("");
     const [loadError, setLoadError] = useState(null);
     const [joinResult, setJoinResult] = useState(null);
-    const media = useLocalMedia({ effectsAssetsUrl: joinResult?.effectsAssetsUrl });
+    /** The restricted `PublicVideoMeeting` `joinMeeting()` returned while this meeting required a password - just
+     * enough to show the password prompt's own title/host, since `joinResult` itself stays unset until one is
+     * verified (see `handleSubmitPassword()`). Only read while `phase === "password"`. */
+    const [passwordMeeting, setPasswordMeeting] = useState(null);
+    const [passwordInput, setPasswordInput] = useState("");
+    const [passwordError, setPasswordError] = useState(null);
+    /** The restricted `PublicVideoMeeting` `joinMeeting()`/`requestAdmission()` returned while this meeting has a
+     * waiting room - read on both the `"admission-request"` and `"waiting"` screens. */
+    const [admissionMeeting, setAdmissionMeeting] = useState(null);
+    const [admissionName, setAdmissionName] = useState("");
+    const [admissionPassword, setAdmissionPassword] = useState("");
+    const [admissionError, setAdmissionError] = useState(null);
+    /** The guest token `requestAdmission()` minted, to poll with (`Authorization` header - a guest has no session
+     * cookie of their own). `undefined` for an already-authenticated real caller, whose existing session cookie
+     * already identifies them to `pollAdmission()` with no header needed. */
+    const [pendingGuestToken, setPendingGuestToken] = useState(undefined);
+    /** Set only when the call ended without the participant's own action (currently: kicked by the host) - see
+     * `CallView`'s `onLeave` doc comment. Shown instead of the ordinary "you left" message; also hides "Rejoin
+     * meeting", since a kicked participant's server-side channel grant has just been revoked and a rejoin attempt
+     * would only fail. */
+    const [endedReason, setEndedReason] = useState(undefined);
+    const media = useLocalMedia({ effectsAssetsUrl: joinResult?.effectsAssetsUrl, forceMuteOnJoin: joinResult?.meeting.forceMuteOnJoin });
     const { release } = media;
     React.useEffect(() => {
         let cancelled = false;
         joinMeeting(token)
             .then((result) => {
-            if (!cancelled) {
-                setJoinResult(result);
-                setPhase("lobby");
+            if (cancelled) {
+                return;
+            }
+            if ("requiresAdmission" in result) {
+                setAdmissionMeeting(result.meeting);
+                setPhase("admission-request");
+                return;
             }
+            if ("requiresPassword" in result) {
+                setPasswordMeeting(result.meeting);
+                setPhase("password");
+                return;
+            }
+            setJoinResult(result);
+            setPhase("lobby");
         })
             .catch((err) => {
             if (cancelled) {
@@ -82,8 +121,69 @@ function MeetJoinContent({ token, branding }) {
         setName(joinName);
         setPhase("in-call");
     }
-    function handleLeave() {
+    async function handleSubmitPassword(e) {
+        e.preventDefault();
+        setPasswordError(null);
+        try {
+            const result = await verifyMeetingPassword(token, passwordInput);
+            setJoinResult(result);
+            setPhase("lobby");
+        }
+        catch (err) {
+            setPasswordError(err instanceof ApiRequestError && err.status === 403 ? "Incorrect password." : "Something went wrong. Try again.");
+        }
+    }
+    async function handleRequestAdmission(e) {
+        e.preventDefault();
+        setAdmissionError(null);
+        try {
+            const result = await requestAdmission(token, {
+                name: admissionName.trim(),
+                ...(admissionMeeting?.hasPassword && { password: admissionPassword }),
+            });
+            setName(admissionName.trim());
+            setPendingGuestToken(result.token);
+            setPhase("waiting");
+        }
+        catch (err) {
+            setAdmissionError(err instanceof ApiRequestError && err.status === 403 ? "Incorrect password." : "Something went wrong. Try again.");
+        }
+    }
+    // Polls while waiting for the host to respond - stops as soon as this phase is left, one way or the other.
+    React.useEffect(() => {
+        if (phase !== "waiting") {
+            return;
+        }
+        let cancelled = false;
+        const poll = async () => {
+            try {
+                const result = await pollAdmission(token, pendingGuestToken);
+                if (cancelled || "requiresAdmission" in result) {
+                    return;
+                }
+                setJoinResult(result);
+                setPhase("lobby");
+            }
+            catch (err) {
+                if (cancelled || !(err instanceof ApiRequestError) || err.status !== 403) {
+                    // A transient failure (network blip, server hiccup) - stay on this screen and try again next
+                    // tick, rather than giving up on what might just be one bad request.
+                    return;
+                }
+                setAdmissionError(err.message || "The host did not admit you to this meeting.");
+                setPhase("denied");
+            }
+        };
+        void poll();
+        const interval = setInterval(() => void poll(), ADMISSION_POLL_MS);
+        return () => {
+            cancelled = true;
+            clearInterval(interval);
+        };
+    }, [phase, token, pendingGuestToken]);
+    function handleLeave(reason) {
         release();
+        setEndedReason(reason);
         setPhase("ended");
     }
     if (phase === "in-call" && joinResult) {
@@ -93,7 +193,7 @@ function MeetJoinContent({ token, branding }) {
             // guest token to apply as a cookie at all, and `GuestSignalingClient` relies entirely on the
             // browser's own already-existing `jwt` session cookie instead (see its own doc comment and
             // `VideoMeetingJoinResult`'s doc comment in `_meetApi.ts`).
-            token: joinResult.token, selfUid: joinResult.selfUid, selfName: name, meetingTitle: joinResult.meeting.title, iceServers: joinResult.iceServers, relayEnabled: joinResult.relayEnabled, media: media, onLeave: handleLeave }));
+            token: joinResult.token, selfUid: joinResult.selfUid, selfName: name, meetingTitle: joinResult.meeting.title, iceServers: joinResult.iceServers, relayEnabled: joinResult.relayEnabled, hostUid: joinResult.meeting.hostUid, initialForceMuteOnJoin: !!joinResult.meeting.forceMuteOnJoin, initialHasPassword: !!joinResult.meeting.hasPassword, initialWaitingRoomEnabled: !!joinResult.meeting.waitingRoomEnabled, media: media, onLeave: handleLeave }));
     }
     let content;
     if (phase === "loading") {
@@ -102,8 +202,20 @@ function MeetJoinContent({ token, branding }) {
     else if (phase === "not-found") {
         content = (_jsx(MeetCard, { children: _jsx(Alert, { children: loadError ?? "This meeting link isn't valid." }) }));
     }
+    else if (phase === "password") {
+        content = (_jsxs(MeetCard, { children: [_jsx("h1", { className: "text-2xl font-bold tracking-tight", children: passwordMeeting?.title }), passwordMeeting?.hostDisplayName && _jsxs("p", { className: "text-sm text-text-muted mt-1", children: ["Hosted by ", passwordMeeting.hostDisplayName] }), _jsx("p", { className: "text-base text-text-muted mt-4 mb-3", children: "This meeting requires a password to join." }), _jsxs("form", { onSubmit: (e) => void handleSubmitPassword(e), children: [_jsx(FormField, { label: "Password", htmlFor: "meet-password", children: _jsx("input", { id: "meet-password", type: "password", autoFocus: true, className: INPUT_CLASS, value: passwordInput, onChange: (e) => setPasswordInput(e.target.value) }) }), passwordError && _jsx(Alert, { children: passwordError }), _jsx(Button, { type: "submit", className: "!w-auto mt-3", disabled: !passwordInput, children: "Join meeting" })] })] }));
+    }
+    else if (phase === "admission-request") {
+        content = (_jsxs(MeetCard, { children: [_jsx("h1", { className: "text-2xl font-bold tracking-tight", children: admissionMeeting?.title }), admissionMeeting?.hostDisplayName && _jsxs("p", { className: "text-sm text-text-muted mt-1", children: ["Hosted by ", admissionMeeting.hostDisplayName] }), _jsx("p", { className: "text-base text-text-muted mt-4 mb-3", children: "The host must let you in before you can join." }), _jsxs("form", { onSubmit: (e) => void handleRequestAdmission(e), children: [_jsx(FormField, { label: "Your name", htmlFor: "admission-name", children: _jsx("input", { id: "admission-name", type: "text", autoFocus: true, className: INPUT_CLASS, value: admissionName, onChange: (e) => setAdmissionName(e.target.value) }) }), admissionMeeting?.hasPassword && (_jsx(FormField, { label: "Password", htmlFor: "admission-password", children: _jsx("input", { id: "admission-password", type: "password", className: `${INPUT_CLASS} mt-3`, value: admissionPassword, onChange: (e) => setAdmissionPassword(e.target.value) }) })), admissionError && _jsx(Alert, { children: admissionError }), _jsx(Button, { type: "submit", className: "!w-auto mt-3", disabled: !admissionName.trim() || (!!admissionMeeting?.hasPassword && !admissionPassword), children: "Ask to join" })] })] }));
+    }
+    else if (phase === "waiting") {
+        content = (_jsxs(MeetCard, { children: [_jsx("h1", { className: "text-2xl font-bold tracking-tight", children: admissionMeeting?.title }), _jsx("p", { className: "text-base text-text-muted mt-4", children: "Waiting for the host to let you in\u2026" })] }));
+    }
+    else if (phase === "denied") {
+        content = (_jsx(MeetCard, { children: _jsx(Alert, { children: admissionError ?? "The host did not admit you to this meeting." }) }));
+    }
     else if (phase === "ended") {
-        content = (_jsxs(MeetCard, { children: [_jsx("h1", { className: "text-xl font-bold tracking-tight mb-2", children: "You left the meeting" }), _jsx("p", { className: "text-base text-text-muted mb-4", children: "You can close this page now, or rejoin." }), _jsx(Button, { type: "button", className: "!w-auto", onClick: () => setPhase("lobby"), children: "Rejoin meeting" })] }));
+        content = (_jsxs(MeetCard, { children: [_jsx("h1", { className: "text-xl font-bold tracking-tight mb-2", children: endedReason ? "Removed from the meeting" : "You left the meeting" }), _jsx("p", { className: "text-base text-text-muted mb-4", children: endedReason ?? "You can close this page now, or rejoin." }), !endedReason && (_jsx(Button, { type: "button", className: "!w-auto", onClick: () => setPhase("lobby"), children: "Rejoin meeting" }))] }));
     }
     else {
         // phase === "lobby" (joinResult is always set by then - see the effect above).

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

@@ -10,14 +10,22 @@
  * camera is sending. Both are driven by `LocalMedia` (`apps/shared/media/useLocalMedia.ts`).
  */
 import React from "react";
+import type { ScreenTransformState } from "../shared/media/filters/ScreenTransform.js";
 import type { LocalMedia } from "../shared/media/useLocalMedia.js";
+import { type MeshParticipant } from "../shared/webrtc/types.js";
 export type CallViewMode = "grid" | "focus";
 export interface CallControlsProps {
     media: LocalMedia;
+    selfName: string;
+    participants: MeshParticipant[];
     isPresenting: boolean;
     /** Someone else is presenting - the share button is disabled and explains why. */
     presentingElsewhereName?: string;
     onToggleShare: () => void;
+    /** The current presenter's own rotate/flip correction - shown (and changeable) only while `isPresenting`. */
+    screenTransform: ScreenTransformState;
+    onRotateScreen: () => void;
+    onFlipScreen: () => void;
     handRaised: boolean;
     onToggleHand: () => void;
     onReaction: (emoji: string) => void;
@@ -29,4 +37,4 @@ export interface CallControlsProps {
 export declare function LevelBars({ level }: {
     level: number;
 }): React.JSX.Element;
-export default function CallControls({ media, isPresenting, presentingElsewhereName, onToggleShare, handRaised, onToggleHand, onReaction, viewMode, onToggleViewMode, onLeave, }: CallControlsProps): React.JSX.Element;
+export default function CallControls({ media, selfName, participants, isPresenting, presentingElsewhereName, onToggleShare, screenTransform, onRotateScreen, onFlipScreen, handRaised, onToggleHand, onReaction, viewMode, onToggleViewMode, onLeave, }: CallControlsProps): React.JSX.Element;