@rapidmx/meet-plugin 0.6.0 → 0.8.1

package/apps/shared/webrtc/MeshConnectionManager.ts

@@ -32,7 +32,7 @@
  * ## Join announcement and roster discovery
  *
  * The channel has no history (a push event published while a socket was down is never replayed - see
- * `@rapidmx/react-shared`'s `pushClient.ts` doc comment for the identical guarantee on the mail push channel this
+ * `@rapidmx/web-client`'s `lib/mail/pushClient.ts` doc comment for the identical guarantee on the mail push channel this
  * one shares its transport with), so a newcomer's `hello` would only reach participants who happened to already be
  * subscribed *and* who joined before them - never the other way around. Every participant who learns of a
  * genuinely new peer (from any message, not just `hello`) therefore echoes its own `hello` right back, once, the
@@ -61,14 +61,37 @@
  * `presenter-release`) once it observes the winning claim. See `handlePresenterClaim()`.
  *
  * Sharing a screen is `setLocalTrack("video", screenTrack)`; stopping is `setLocalTrack("video", cameraTrack)`.
+ *
+ * ## Three media paths, tried in order
+ *
+ * Each pair of participants reaches for the best path that works, and `MeshParticipant.transport` says which one it
+ * got:
+ *
+ * 1. **Direct peer-to-peer** (`"p2p"`). The `RTCPeerConnection` is given the STUN servers and the TURN server
+ * together, and ICE ranks a direct pair above a relayed one, so this is what a pair gets whenever it can.
+ * 2. **Relayed through the TURN server** (`"turn"`). The same connection, on the relay candidate ICE falls back to
+ * when the direct pairs fail - a participant behind a symmetric NAT or a firewall that blocks direct UDP. Which of
+ * the two ICE picked is read from the selected candidate pair once connected (`RTCPeerConnectionLike.connectionType()`).
+ * 3. **Proxied by this server over a WebSocket** (`"websocket"`, `apps/shared/relay/`). For a participant whose
+ * network lets nothing but ordinary HTTPS out, neither of the above ever connects. A pair whose connection has not
+ * come up within `connectTimeoutMs`, has failed, or has stayed `disconnected` for `disconnectedGraceMs` gives up
+ * on WebRTC and switches to it, telling the other side with a `relay-fallback` message so both switch even when
+ * only one of them noticed. Nothing is renegotiated - the pair simply stops using the `RTCPeerConnection` - and the
+ * relay's stream replaces the one WebRTC would have filled (a `remote-stream` event again). When the relay is
+ * unavailable (turned off by the operator, or a browser without WebCodecs) the pair is marked `"failed"` and stays
+ * in the roster, rather than the participant vanishing with no explanation as it used to.
+ *
+ * A pair never moves back up: once on the relay it stays there for the rest of the call.
  */
 import {
+    type MediaTransport,
     type MeshEvent,
     type MeshParticipant,
     type ParticipantState,
     type RTCPeerConnectionFactory,
     type RTCPeerConnectionLike,
     type RTCRtpSenderLike,
+    type RelayTransportLike,
     type SignalMessage,
     type SignalingChannel,
     REACTION_EMOJIS,
@@ -84,6 +107,14 @@ export function isOfferer(selfId: string, peerId: string): boolean {
 const MAX_ORPHAN_PEERS = 32;
 const MAX_ORPHAN_CANDIDATES = 64;
 
+/** How long a connection may stay in `connecting` before the pair gives up on WebRTC. ICE with an unreachable TURN
+ * server can take the better part of a minute to report `failed`; a person waiting on a call will not. It is still long
+ * enough for a slow TURN allocation and a few round trips of signaling. */
+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;
+
 type MediaKind = "audio" | "video";
 
 interface PeerState extends MeshParticipant {
@@ -93,6 +124,10 @@ interface PeerState extends MeshParticipant {
     remoteStream: MediaStream;
     remoteDescriptionSet: boolean;
     pendingCandidates: RTCIceCandidateInit[];
+    /** Gives up on WebRTC when the connection is still `connecting` after `connectTimeoutMs`. */
+    connectTimer: ReturnType<typeof setTimeout> | undefined;
+    /** Gives up on WebRTC when the connection has stayed `disconnected` for `disconnectedGraceMs`. */
+    disconnectTimer: ReturnType<typeof setTimeout> | undefined;
 }
 
 export interface MeshConnectionManagerOptions {
@@ -114,6 +149,13 @@ export interface MeshConnectionManagerOptions {
     /** Builds the (initially empty) stream one peer's incoming tracks are gathered into. Defaults to
      * `new MediaStream()`; a test supplies a fake. */
     createMediaStream?: () => MediaStream;
+    /** The WebSocket media relay, the last-resort path - see this module's doc comment. Leave unset when the
+     * operator has turned it off; without one a pair WebRTC cannot connect is marked `"failed"`. */
+    relay?: RelayTransportLike;
+    /** Defaults to `DEFAULT_CONNECT_TIMEOUT_MS`. */
+    connectTimeoutMs?: number;
+    /** Defaults to `DEFAULT_DISCONNECTED_GRACE_MS`. */
+    disconnectedGraceMs?: number;
 }
 
 export class MeshConnectionManager {
@@ -137,6 +179,8 @@ export class MeshConnectionManager {
             handRaised: false,
             ...options.localState,
         };
+        options.relay?.setLocalTrack("audio", this.localTracks.audio);
+        options.relay?.setLocalTrack("video", this.localTracks.video);
     }
 
     get participants(): MeshParticipant[] {
@@ -177,11 +221,13 @@ export class MeshConnectionManager {
         this.unsubscribe?.();
         this.unsubscribe = undefined;
         for (const peer of this.peers.values()) {
+            this.clearTimers(peer);
             peer.pc.close();
         }
         this.peers.clear();
         this.orphanCandidates.clear();
         this.listeners.clear();
+        this.options.relay?.close();
     }
 
     /** Sets the track sent as `kind` (`null` to send nothing) on every connection, now and for every peer that
@@ -191,6 +237,7 @@ export class MeshConnectionManager {
         for (const peer of this.peers.values()) {
             void peer.senders[kind]?.replaceTrack(track);
         }
+        this.options.relay?.setLocalTrack(kind, track);
     }
 
     /** Updates what this participant announces (`audioOn`/`videoOn`/`handRaised`) and tells everyone if anything
@@ -295,6 +342,9 @@ export class MeshConnectionManager {
             case "reaction":
                 this.handleReaction(message);
                 return;
+            case "relay-fallback":
+                this.handleRelayFallback(message.from);
+                return;
         }
     }
 
@@ -357,8 +407,13 @@ export class MeshConnectionManager {
         if (!peer) {
             return;
         }
+        this.clearTimers(peer);
         peer.pc.close();
         this.peers.delete(uid);
+        if (peer.transport === "websocket") {
+            this.options.relay?.stopReceivingFrom(uid);
+            this.syncRelaySending();
+        }
         this.emit({ type: "participant-left", uid });
         if (this.currentPresenterUid === uid) {
             this.currentPresenterUid = undefined;
@@ -382,6 +437,9 @@ export class MeshConnectionManager {
             remoteStream: (this.options.createMediaStream ?? (() => new MediaStream()))(),
             remoteDescriptionSet: false,
             pendingCandidates: this.orphanCandidates.get(uid) ?? [],
+            transport: "connecting",
+            connectTimer: undefined,
+            disconnectTimer: undefined,
         };
         this.orphanCandidates.delete(uid);
         this.peers.set(uid, peer);
@@ -396,14 +454,108 @@ export class MeshConnectionManager {
             }
             this.emit({ type: "remote-stream", uid, stream: peer.remoteStream });
         };
-        pc.onconnectionstatechange = () => {
-            if (pc.connectionState === "failed" || pc.connectionState === "closed") {
-                this.handleBye(uid);
-            }
-        };
+        pc.onconnectionstatechange = () => this.handleConnectionState(peer);
+        // Cleared the moment the connection comes up, so this only ever fires for a pair still waiting on WebRTC.
+        peer.connectTimer = setTimeout(() => this.fallBack(peer), this.options.connectTimeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS);
         return peer;
     }
 
+    /** Reacts to the peer connection's state: notes which path a connected pair got, and gives up on WebRTC for a
+     * pair that failed or stays disconnected - see `fallBack()`. Ignores a pair that already left WebRTC. */
+    private handleConnectionState(peer: PeerState): void {
+        if (peer.transport === "websocket" || this.peers.get(peer.uid) !== peer) {
+            return;
+        }
+        switch (peer.pc.connectionState) {
+            case "connected":
+                this.clearTimers(peer);
+                void this.detectTransport(peer);
+                return;
+            case "disconnected":
+                // ICE often recovers from this on its own, so it is only given up on after a grace period.
+                peer.disconnectTimer ??= setTimeout(() => this.fallBack(peer), this.options.disconnectedGraceMs ?? DEFAULT_DISCONNECTED_GRACE_MS);
+                return;
+            case "failed":
+                this.fallBack(peer);
+                return;
+            case "closed":
+                this.handleBye(peer.uid);
+                return;
+        }
+    }
+
+    /** Records whether a connected pair is direct or relayed through TURN, from the candidate pair ICE selected. */
+    private async detectTransport(peer: PeerState): Promise<void> {
+        let type: "p2p" | "turn" | "unknown";
+        try {
+            type = await peer.pc.connectionType();
+        } catch {
+            type = "unknown";
+        }
+        // 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");
+        }
+    }
+
+    private setTransport(peer: PeerState, transport: MediaTransport): void {
+        if (peer.transport !== transport) {
+            peer.transport = transport;
+            this.emit({ type: "participant-updated", participant: toParticipant(peer) });
+        }
+    }
+
+    private clearTimers(peer: PeerState): void {
+        clearTimeout(peer.connectTimer);
+        clearTimeout(peer.disconnectTimer);
+        peer.connectTimer = undefined;
+        peer.disconnectTimer = undefined;
+    }
+
+    /**
+     * Gives up on WebRTC for `peer` and moves the pair to the WebSocket relay (the third path - see this module's doc
+     * comment), or marks it `"failed"` when there is no relay to move to. `notify` tells the other side, which may not
+     * have noticed yet; a pair told by the other side does not tell it back.
+     */
+    private fallBack(peer: PeerState, notify = true): void {
+        if (peer.transport === "websocket" || this.peers.get(peer.uid) !== peer) {
+            return;
+        }
+        this.clearTimers(peer);
+        const relay = this.options.relay;
+        if (!relay?.supported) {
+            this.setTransport(peer, "failed");
+            return;
+        }
+        // Stop listening to the dead connection before closing it, so closing it cannot be mistaken for the peer leaving.
+        peer.pc.onconnectionstatechange = null;
+        peer.pc.onicecandidate = null;
+        peer.pc.ontrack = null;
+        peer.pc.close();
+        peer.transport = "websocket";
+        relay.receiveFrom(peer.uid, (stream) => {
+            peer.remoteStream = stream;
+            this.emit({ type: "remote-stream", uid: peer.uid, stream });
+        });
+        this.syncRelaySending();
+        this.emit({ type: "participant-updated", participant: toParticipant(peer) });
+        if (notify) {
+            this.send({ kind: "relay-fallback", to: peer.uid });
+        }
+    }
+
+    private handleRelayFallback(from: string): void {
+        const peer = this.peers.get(from);
+        if (peer) {
+            this.fallBack(peer, false);
+        }
+    }
+
+    /** The relay only encodes and uploads the local media while at least one pair is actually using it. */
+    private syncRelaySending(): void {
+        this.options.relay?.setSending([...this.peers.values()].some((peer) => peer.transport === "websocket"));
+    }
+
     private async initiateOffer(peer: PeerState): Promise<void> {
         const offer = await peer.pc.createOffer();
         await peer.pc.setLocalDescription(offer);
@@ -515,7 +667,7 @@ export class MeshConnectionManager {
 }
 
 function toParticipant(peer: PeerState): MeshParticipant {
-    return { uid: peer.uid, name: peer.name, audioOn: peer.audioOn, videoOn: peer.videoOn, handRaised: peer.handRaised };
+    return { uid: peer.uid, name: peer.name, audioOn: peer.audioOn, videoOn: peer.videoOn, handRaised: peer.handRaised, transport: peer.transport };
 }
 
 function sameState(a: ParticipantState, b: ParticipantState): boolean {

package/apps/shared/webrtc/realPeerConnection.ts

@@ -9,6 +9,27 @@
  * exist at all - it would only throw if actually *called* outside a browser. */
 import type { RTCPeerConnectionFactory, RTCPeerConnectionLike } 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.
+ */
+export async function selectedConnectionType(pc: Pick<RTCPeerConnection, "getStats">): Promise<"p2p" | "turn" | "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);
+    const pair =
+        (transport ? reports.get(String(transport.selectedCandidatePairId)) : undefined) ??
+        [...reports.values()].find((report) => report.type === "candidate-pair" && (report.selected || (report.nominated && report.state === "succeeded")));
+    if (!pair) {
+        return "unknown";
+    }
+    const local = reports.get(String(pair.localCandidateId));
+    const remote = reports.get(String(pair.remoteCandidateId));
+    return local?.candidateType === "relay" || remote?.candidateType === "relay" ? "turn" : "p2p";
+}
+
 export const createBrowserPeerConnection: RTCPeerConnectionFactory = (config) => {
     const pc = new RTCPeerConnection(config);
     const like: RTCPeerConnectionLike = {
@@ -33,6 +54,7 @@ export const createBrowserPeerConnection: RTCPeerConnectionFactory = (config) =>
         setRemoteDescription: (description) => pc.setRemoteDescription(description),
         addIceCandidate: (candidate) => pc.addIceCandidate(candidate),
         close: () => pc.close(),
+        connectionType: () => selectedConnectionType(pc),
         onicecandidate: null,
         ontrack: null,
         onconnectionstatechange: null,

package/apps/shared/webrtc/types.ts

@@ -44,7 +44,8 @@ export interface SignalMessage {
         | "presenter-claim"
         | "presenter-release"
         | "state"
-        | "reaction";
+        | "reaction"
+        | "relay-fallback";
     /** 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
@@ -55,7 +56,7 @@ export interface SignalMessage {
      * ignored, so it can't name someone else's tab. Absent from a sender that predates it (the participant is then
      * identified by `from`). */
     peer?: string;
-    /** Set only on a point-to-point message (`offer`/`answer`/`ice-candidate`). */
+    /** Set only on a point-to-point message (`offer`/`answer`/`ice-candidate`/`relay-fallback`). */
     to?: string;
     /** `hello` only - the display name the sender chose in the lobby. */
     name?: string;
@@ -112,6 +113,33 @@ export interface RTCPeerConnectionLike {
     ontrack: ((event: { track: MediaStreamTrack }) => void) | null;
     onconnectionstatechange: (() => void) | null;
     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">;
+}
+
+/** 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.
+ * - `"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";
+
+/** 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. */
+export interface RelayTransportLike {
+    /** `false` when this browser cannot do it (no WebSocket, no WebCodecs) - the mesh then never falls back to it. */
+    readonly supported: boolean;
+    /** Starts receiving `peerId`'s media. `onStream` is given the `MediaStream` that plays it. */
+    receiveFrom(peerId: string, onStream: (stream: MediaStream) => void): void;
+    stopReceivingFrom(peerId: string): void;
+    /** Starts or stops publishing the local tracks to the relay. */
+    setSending(active: boolean): void;
+    /** Same as `MeshConnectionManager.setLocalTrack()` - `null` sends nothing for that kind. */
+    setLocalTrack(kind: "audio" | "video", track: MediaStreamTrack | null): void;
+    close(): void;
 }
 
 export type RTCPeerConnectionFactory = (config: { iceServers: RTCIceServer[] }) => RTCPeerConnectionLike;
@@ -121,6 +149,8 @@ export type RTCPeerConnectionFactory = (config: { iceServers: RTCIceServer[] })
 export interface MeshParticipant extends ParticipantState {
     uid: string;
     name: string;
+    /** How this participant's media currently reaches the local one - see `MediaTransport`. */
+    transport: MediaTransport;
 }
 
 export type MeshEvent =

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

@@ -6,14 +6,14 @@
  * ## Session-based name prefill - NOT implemented, and why
  *
  * The spec asks this page to prefill the name field from `Profile.givenName` when the visiting browser already
- * holds a RapidMX session (investigating `@rapidmx/react-shared`'s `profileApi.ts`/`session.ts` was part of this
- * plugin's Phase 2 work). That turned out not to be wireable from here: `profileApi.ts`'s `getMyProfile()` needs
+ * holds a RapidMX session (investigating `@rapidmx/web-client`'s `lib/profileApi.ts`/`lib/session.ts` was part of
+ * this plugin's Phase 2 work). That turned out not to be wireable from here: `profileApi.ts`'s `getMyProfile()` needs
  * an `authServerUrl` to call auth-server (a *different* origin) with, and `session.ts`'s own doc comment confirms
  * `userUid`/`authServerUrl` are supplied only via server-side `fetchProps` on the `www`/admin console hosts
  * (`wwwRoute`/`AdminConsoleRoute` in `@rapidmx/server`) - never on the `public` host this page is mounted on.
  * `PublicPageRoute` (`@rapidmx/server`, this page's actual host route) returns only branding props; it has no
  * concept of the caller's session at all. There is, today, no public-host plugin page anywhere in this codebase
- * that does this, so there was no convention to extend - only two, cross-repo (`@rapidmx/server`/`react-shared`)
+ * that does this, so there was no convention to extend - only two, cross-repo (`@rapidmx/server`/`web-client`)
  * ways to add one (flagged in this plugin's Phase 2 report rather than built here, both out of this frontend-only
  * phase's scope):
  *

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

@@ -11,14 +11,14 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  * ## Session-based name prefill - NOT implemented, and why
  *
  * The spec asks this page to prefill the name field from `Profile.givenName` when the visiting browser already
- * holds a RapidMX session (investigating `@rapidmx/react-shared`'s `profileApi.ts`/`session.ts` was part of this
- * plugin's Phase 2 work). That turned out not to be wireable from here: `profileApi.ts`'s `getMyProfile()` needs
+ * holds a RapidMX session (investigating `@rapidmx/web-client`'s `lib/profileApi.ts`/`lib/session.ts` was part of
+ * this plugin's Phase 2 work). That turned out not to be wireable from here: `profileApi.ts`'s `getMyProfile()` needs
  * an `authServerUrl` to call auth-server (a *different* origin) with, and `session.ts`'s own doc comment confirms
  * `userUid`/`authServerUrl` are supplied only via server-side `fetchProps` on the `www`/admin console hosts
  * (`wwwRoute`/`AdminConsoleRoute` in `@rapidmx/server`) - never on the `public` host this page is mounted on.
  * `PublicPageRoute` (`@rapidmx/server`, this page's actual host route) returns only branding props; it has no
  * concept of the caller's session at all. There is, today, no public-host plugin page anywhere in this codebase
- * that does this, so there was no convention to extend - only two, cross-repo (`@rapidmx/server`/`react-shared`)
+ * that does this, so there was no convention to extend - only two, cross-repo (`@rapidmx/server`/`web-client`)
  * ways to add one (flagged in this plugin's Phase 2 report rather than built here, both out of this frontend-only
  * phase's scope):
  *
@@ -31,10 +31,10 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  * invitees have no RapidMX account at all), just never prefilled even for a mailbox owner testing their own link.
  */
 import React, { useState } from "react";
-import useBranding from "@rapidmx/react-shared/branding/useBranding.js";
-import { ApiRequestError } from "@rapidmx/react-shared/util/api.js";
-import Button from "@rapidmx/react-shared/components/buttons/Button.js";
-import Alert from "@rapidmx/react-shared/components/feedback/Alert.js";
+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 { MeetCard, MeetPageShell } from "./_MeetChrome.js";
 import { useLocalMedia } from "../shared/media/useLocalMedia.js";
 import MeetLobby from "./_MeetLobby.js";
@@ -49,10 +49,10 @@ export default function MeetJoinPage({ params }) {
  * window instead (see `_CallView.tsx`). */
 function MeetJoinContent({ token, branding }) {
     const [phase, setPhase] = useState("loading");
-    const [joinResult, setJoinResult] = useState(null);
     const [name, setName] = useState("");
     const [loadError, setLoadError] = useState(null);
-    const media = useLocalMedia();
+    const [joinResult, setJoinResult] = useState(null);
+    const media = useLocalMedia({ effectsAssetsUrl: joinResult?.effectsAssetsUrl });
     const { release } = media;
     React.useEffect(() => {
         let cancelled = false;
@@ -93,7 +93,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, media: media, onLeave: handleLeave }));
+            token: joinResult.token, selfUid: joinResult.selfUid, selfName: name, meetingTitle: joinResult.meeting.title, iceServers: joinResult.iceServers, relayEnabled: joinResult.relayEnabled, media: media, onLeave: handleLeave }));
     }
     let content;
     if (phase === "loading") {

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

@@ -2,7 +2,8 @@
  * The in-call control bar, fixed to the bottom of the call (`_CallView.tsx` lays it out below the tiles, never over
  * them). Its menus open upward, centered on the whole bar on a phone (where the bar wraps onto two rows and a menu
  * hung from its own button would run off the edge) and from their own button on a wider window: microphone and camera (each a mute/unmute or on/off button next to a menu that picks the device), share
- * screen, reactions, raise hand, grid/focus and leave.
+ * screen, reactions, raise hand, grid/focus and leave. The effects button opens the video filter picker
+ * (`_EffectsPanel.tsx`) and lights up while any filter is on.
  *
  * The microphone button shows a live level while it is unmuted - bars that move with the sound the microphone is
  * picking up, so a participant can see their audio is being sent - and the camera button shows a green dot while a

package/dist/apps/meet/_CallControls.js

@@ -7,15 +7,18 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  * The in-call control bar, fixed to the bottom of the call (`_CallView.tsx` lays it out below the tiles, never over
  * them). Its menus open upward, centered on the whole bar on a phone (where the bar wraps onto two rows and a menu
  * hung from its own button would run off the edge) and from their own button on a wider window: microphone and camera (each a mute/unmute or on/off button next to a menu that picks the device), share
- * screen, reactions, raise hand, grid/focus and leave.
+ * screen, reactions, raise hand, grid/focus and leave. The effects button opens the video filter picker
+ * (`_EffectsPanel.tsx`) and lights up while any filter is on.
  *
  * The microphone button shows a live level while it is unmuted - bars that move with the sound the microphone is
  * picking up, so a participant can see their audio is being sent - and the camera button shows a green dot while a
  * camera is sending. Both are driven by `LocalMedia` (`apps/shared/media/useLocalMedia.ts`).
  */
 import { useEffect, useRef, useState } from "react";
+import { filtersActive } from "../shared/media/filters/filterTypes.js";
 import { REACTION_EMOJIS } from "../shared/webrtc/types.js";
-import { ChevronUpIcon, EmojiIcon, FocusIcon, GridIcon, HandIcon, LeaveIcon, MicIcon, MicOffIcon, ScreenShareIcon, VideoIcon, VideoOffIcon, } from "./_icons.js";
+import EffectsPanel from "./_EffectsPanel.js";
+import { ChevronUpIcon, EffectsIcon, EmojiIcon, FocusIcon, GridIcon, HandIcon, LeaveIcon, MicIcon, MicOffIcon, ScreenShareIcon, VideoIcon, VideoOffIcon, } from "./_icons.js";
 const BUTTON = "flex items-center justify-center h-12 rounded-full transition-colors focus:outline-none focus-visible:ring-2 focus-visible:ring-white/80";
 const NEUTRAL = "bg-[#3c4043] text-white hover:bg-[#4b4f53]";
 const ALERT = "bg-[#f9dedc] text-[#8c1d18] hover:bg-[#f2c4c0]";
@@ -53,7 +56,7 @@ export default function CallControls({ media, isPresenting, presentingElsewhereN
     function toggleMenu(menu) {
         setOpenMenu((prev) => (prev === menu ? null : menu));
     }
-    return (_jsxs("div", { ref: barRef, className: "relative flex flex-wrap items-center justify-center gap-2 px-3", role: "toolbar", "aria-label": "Call controls", children: [_jsxs("div", { className: "sm:relative flex items-stretch gap-px", children: [_jsx("button", { type: "button", className: `${BUTTON} w-9 rounded-r-none ${media.micOn ? NEUTRAL : ALERT}`, "aria-label": "Choose microphone", "aria-haspopup": "menu", "aria-expanded": openMenu === "audio", onClick: () => toggleMenu("audio"), children: _jsx(ChevronUpIcon, {}) }), _jsxs("button", { type: "button", className: `${BUTTON} min-w-14 gap-1.5 px-3 rounded-l-none ${media.micOn ? NEUTRAL : ALERT}`, "aria-label": media.micOn ? "Mute microphone" : "Unmute microphone", "aria-pressed": !media.micOn, onClick: () => void media.toggleMic(), children: [media.micOn && _jsx(LevelBars, { level: media.audioLevel }), media.micOn ? _jsx(MicIcon, {}) : _jsx(MicOffIcon, {})] }), openMenu === "audio" && _jsx(DeviceMenu, { kind: "audio", media: media, onClose: () => setOpenMenu(null) })] }), _jsxs("div", { className: "sm:relative flex items-stretch gap-px", children: [_jsx("button", { type: "button", className: `${BUTTON} w-9 rounded-r-none ${media.cameraOn ? NEUTRAL : ALERT}`, "aria-label": "Choose camera", "aria-haspopup": "menu", "aria-expanded": openMenu === "video", onClick: () => toggleMenu("video"), children: _jsx(ChevronUpIcon, {}) }), _jsxs("button", { type: "button", className: `${BUTTON} relative min-w-14 px-3 rounded-l-none ${media.cameraOn ? NEUTRAL : ALERT}`, "aria-label": media.cameraOn ? "Turn off camera" : "Turn on camera", "aria-pressed": !media.cameraOn, onClick: () => void media.toggleCamera(), children: [media.cameraOn ? _jsx(VideoIcon, {}) : _jsx(VideoOffIcon, {}), media.cameraOn && (_jsx("span", { className: "absolute top-2 right-2 w-2 h-2 rounded-full bg-[#34a853] animate-pulse", "data-testid": "camera-live", title: "Your camera is sending" }))] }), openMenu === "video" && _jsx(DeviceMenu, { kind: "video", media: media, onClose: () => setOpenMenu(null) })] }), _jsx("button", { type: "button", className: `${BUTTON} w-12 ${isPresenting ? ACTIVE : NEUTRAL} disabled:opacity-40 disabled:cursor-not-allowed`, "aria-label": isPresenting ? "Stop sharing" : "Share screen", "aria-pressed": isPresenting, disabled: shareDisabled, title: shareDisabled ? `${presentingElsewhereName} is presenting - stop their share to present yourself.` : undefined, onClick: onToggleShare, children: _jsx(ScreenShareIcon, {}) }), _jsxs("div", { className: "sm:relative", children: [_jsx("button", { type: "button", className: `${BUTTON} w-12 ${NEUTRAL}`, "aria-label": "Send a reaction", "aria-haspopup": "menu", "aria-expanded": openMenu === "emoji", onClick: () => toggleMenu("emoji"), children: _jsx(EmojiIcon, {}) }), openMenu === "emoji" && (_jsx("div", { role: "menu", "aria-label": "Reactions", className: "absolute bottom-full mb-3 left-1/2 -translate-x-1/2 w-max grid grid-cols-4 gap-1 p-2 rounded-2xl bg-[#2b2d30] shadow-xl", children: REACTION_EMOJIS.map((emoji) => (_jsx("button", { type: "button", role: "menuitem", className: "w-11 h-11 rounded-lg text-2xl hover:bg-white/10 focus:outline-none focus-visible:ring-2 focus-visible:ring-white/80", "aria-label": `Send ${emoji}`, onClick: () => {
+    return (_jsxs("div", { ref: barRef, className: "relative flex flex-wrap items-center justify-center gap-2 px-3", role: "toolbar", "aria-label": "Call controls", children: [_jsxs("div", { className: "sm:relative flex items-stretch gap-px", children: [_jsx("button", { type: "button", className: `${BUTTON} w-9 rounded-r-none ${media.micOn ? NEUTRAL : ALERT}`, "aria-label": "Choose microphone", "aria-haspopup": "menu", "aria-expanded": openMenu === "audio", onClick: () => toggleMenu("audio"), children: _jsx(ChevronUpIcon, {}) }), _jsxs("button", { type: "button", className: `${BUTTON} min-w-14 gap-1.5 px-3 rounded-l-none ${media.micOn ? NEUTRAL : ALERT}`, "aria-label": media.micOn ? "Mute microphone" : "Unmute microphone", "aria-pressed": !media.micOn, onClick: () => void media.toggleMic(), children: [media.micOn && _jsx(LevelBars, { level: media.audioLevel }), media.micOn ? _jsx(MicIcon, {}) : _jsx(MicOffIcon, {})] }), openMenu === "audio" && _jsx(DeviceMenu, { kind: "audio", media: media, onClose: () => setOpenMenu(null) })] }), _jsxs("div", { className: "sm:relative flex items-stretch gap-px", children: [_jsx("button", { type: "button", className: `${BUTTON} w-9 rounded-r-none ${media.cameraOn ? NEUTRAL : ALERT}`, "aria-label": "Choose camera", "aria-haspopup": "menu", "aria-expanded": openMenu === "video", onClick: () => toggleMenu("video"), children: _jsx(ChevronUpIcon, {}) }), _jsxs("button", { type: "button", className: `${BUTTON} relative min-w-14 px-3 rounded-l-none ${media.cameraOn ? NEUTRAL : ALERT}`, "aria-label": media.cameraOn ? "Turn off camera" : "Turn on camera", "aria-pressed": !media.cameraOn, onClick: () => void media.toggleCamera(), children: [media.cameraOn ? _jsx(VideoIcon, {}) : _jsx(VideoOffIcon, {}), media.cameraOn && (_jsx("span", { className: "absolute top-2 right-2 w-2 h-2 rounded-full bg-[#34a853] animate-pulse", "data-testid": "camera-live", title: "Your camera is sending" }))] }), openMenu === "video" && _jsx(DeviceMenu, { kind: "video", media: media, onClose: () => setOpenMenu(null) })] }), _jsxs("div", { className: "sm:relative", children: [_jsx("button", { type: "button", className: `${BUTTON} w-12 ${filtersActive(media.filters) ? ACTIVE : NEUTRAL}`, "aria-label": "Video effects", "aria-haspopup": "dialog", "aria-expanded": openMenu === "effects", onClick: () => toggleMenu("effects"), children: _jsx(EffectsIcon, {}) }), openMenu === "effects" && (_jsx("div", { role: "dialog", "aria-label": "Video effects", className: "absolute bottom-full mb-3 left-1/2 -translate-x-1/2 w-96 max-w-[calc(100vw-1rem)] max-h-[60vh] overflow-y-auto p-3 rounded-2xl bg-[#2b2d30] text-white shadow-xl", children: _jsx(EffectsPanel, { media: media, tone: "dark" }) }))] }), _jsx("button", { type: "button", className: `${BUTTON} w-12 ${isPresenting ? ACTIVE : NEUTRAL} disabled:opacity-40 disabled:cursor-not-allowed`, "aria-label": isPresenting ? "Stop sharing" : "Share screen", "aria-pressed": isPresenting, disabled: shareDisabled, title: shareDisabled ? `${presentingElsewhereName} is presenting - stop their share to present yourself.` : undefined, onClick: onToggleShare, children: _jsx(ScreenShareIcon, {}) }), _jsxs("div", { className: "sm:relative", children: [_jsx("button", { type: "button", className: `${BUTTON} w-12 ${NEUTRAL}`, "aria-label": "Send a reaction", "aria-haspopup": "menu", "aria-expanded": openMenu === "emoji", onClick: () => toggleMenu("emoji"), children: _jsx(EmojiIcon, {}) }), openMenu === "emoji" && (_jsx("div", { role: "menu", "aria-label": "Reactions", className: "absolute bottom-full mb-3 left-1/2 -translate-x-1/2 w-max grid grid-cols-4 gap-1 p-2 rounded-2xl bg-[#2b2d30] shadow-xl", children: REACTION_EMOJIS.map((emoji) => (_jsx("button", { type: "button", role: "menuitem", className: "w-11 h-11 rounded-lg text-2xl hover:bg-white/10 focus:outline-none focus-visible:ring-2 focus-visible:ring-white/80", "aria-label": `Send ${emoji}`, onClick: () => {
                                 onReaction(emoji);
                                 setOpenMenu(null);
                             }, children: emoji }, emoji))) }))] }), _jsx("button", { type: "button", className: `${BUTTON} w-12 ${handRaised ? ACTIVE : NEUTRAL}`, "aria-label": handRaised ? "Lower hand" : "Raise hand", "aria-pressed": handRaised, onClick: onToggleHand, children: _jsx(HandIcon, {}) }), _jsx("button", { type: "button", className: `${BUTTON} w-12 ${NEUTRAL}`, "aria-label": viewMode === "grid" ? "Switch to focused view" : "Switch to grid view", onClick: onToggleViewMode, children: viewMode === "grid" ? _jsx(FocusIcon, {}) : _jsx(GridIcon, {}) }), _jsx("button", { type: "button", className: `${BUTTON} w-16 bg-[#d93025] text-white hover:bg-[#b3261e]`, "aria-label": "Leave call", onClick: onLeave, children: _jsx(LeaveIcon, {}) })] }));

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

@@ -42,6 +42,9 @@ export interface CallViewProps {
     selfName: string;
     meetingTitle: string;
     iceServers: RTCIceServer[];
+    /** Whether the server offers the WebSocket media relay, the last-resort path for a participant neither a direct
+     * connection nor the TURN server can reach - `VideoMeetingJoinResult.relayEnabled`. Off when absent. */
+    relayEnabled?: boolean;
     /** The camera and microphone, owned by the page (`[token].tsx`) - the lobby's tracks carried into the call. */
     media: LocalMedia;
     onLeave: () => void;
@@ -58,4 +61,4 @@ export declare function computeMainUid(options: {
  * from two devices - or two tabs - is two participants rather than one that ignores itself. It travels as the
  * `peer` of each message; `from` stays the exact authenticated uid, which the server requires. */
 export declare function newPeerId(selfUid: string): string;
-export default function CallView({ channel, token, selfUid, selfName, meetingTitle, iceServers, media, onLeave }: CallViewProps): React.JSX.Element;
+export default function CallView({ channel, token, selfUid, selfName, meetingTitle, iceServers, relayEnabled, media, onLeave }: CallViewProps): React.JSX.Element;

package/dist/apps/meet/_CallView.js

@@ -42,6 +42,7 @@ import { startLevelMeter } from "../shared/media/levelMeter.js";
 import { requestDisplayMedia, stopStream } from "../shared/media/deviceMedia.js";
 import { createBrowserPeerConnection } from "../shared/webrtc/realPeerConnection.js";
 import { MeshConnectionManager } from "../shared/webrtc/MeshConnectionManager.js";
+import { createRelayTransport } from "../shared/relay/RelayTransport.js";
 import { GuestSignalingClient } from "../shared/push/GuestSignalingClient.js";
 import CallControls from "./_CallControls.js";
 import ParticipantTile from "./_ParticipantTile.js";
@@ -69,7 +70,7 @@ export function computeMainUid(options) {
 export function newPeerId(selfUid) {
     return `${selfUid}~${globalThis.crypto?.randomUUID?.() ?? Math.random().toString(36).slice(2)}`;
 }
-export default function CallView({ channel, token, selfUid, selfName, meetingTitle, iceServers, media, onLeave }) {
+export default function CallView({ channel, token, selfUid, selfName, meetingTitle, iceServers, relayEnabled, media, onLeave }) {
     const [peerId] = useState(() => newPeerId(selfUid));
     const [connectError, setConnectError] = useState(null);
     const [participants, setParticipants] = useState([]);
@@ -85,6 +86,7 @@ export default function CallView({ channel, token, selfUid, selfName, meetingTit
     const [announcement, setAnnouncement] = useState("");
     const [audioBlocked, setAudioBlocked] = useState(false);
     const [audioNonce, setAudioNonce] = useState(0);
+    const [signalingReady, setSignalingReady] = useState(false);
     const managerRef = useRef(null);
     const screenStreamRef = useRef(null);
     const levelMetersRef = useRef({});
@@ -110,6 +112,7 @@ export default function CallView({ channel, token, selfUid, selfName, meetingTit
             iceServers,
             channel: client,
             createPeerConnection: createBrowserPeerConnection,
+            relay: relayEnabled ? createRelay(channel, peerId) : undefined,
             localAudioTrack: media.audioTrack,
             localVideoTrack: media.videoTrack,
             localState: { audioOn: media.micOn, videoOn: media.cameraOn },
@@ -162,6 +165,7 @@ export default function CallView({ channel, token, selfUid, selfName, meetingTit
             .then(() => {
             if (!cancelled) {
                 manager.start();
+                setSignalingReady(true);
             }
         })
             .catch((err) => {
@@ -266,8 +270,15 @@ export default function CallView({ channel, token, selfUid, selfName, meetingTit
     const presenterName = presenterUid ? (presenterUid === peerId ? selfName : (participants.find((p) => p.uid === presenterUid)?.name ?? "Someone")) : undefined;
     const raisedNames = [...(handRaised ? ["You"] : []), ...participants.filter((p) => p.handRaised).map((p) => p.name)];
     const alone = participants.length === 0;
-    const remoteTile = (p, className) => (_jsx(ParticipantTile, { name: p.name, stream: remoteStreams[p.uid] ?? null, cameraOff: !p.videoOn, micMuted: !p.audioOn, handRaised: p.handRaised, isFocused: mainUid === p.uid, contain: presenterUid === p.uid, className: className, onClick: () => togglePin(p.uid) }, p.uid));
-    const selfTile = (className) => (_jsx(ParticipantTile, { name: selfName, stream: media.videoStream, isLocal: true, cameraOff: !media.cameraOn, micMuted: !media.micOn, handRaised: handRaised, className: className }));
+    // This participant has no working link yet: the signaling channel is still opening, or there is someone in the call
+    // and every connection to them is still being made. Once any one is up (or nobody else is here) it is not shown,
+    // so someone already in the call is not told they are "connecting" each time a newcomer arrives.
+    const selfConnecting = !connectError && (!signalingReady || (!alone && participants.every((p) => p.transport === "connecting")));
+    const remoteTile = (p, className) => (_jsx(ParticipantTile, { name: p.name, stream: remoteStreams[p.uid] ?? null, cameraOff: !p.videoOn, micMuted: !p.audioOn, handRaised: p.handRaised, transport: p.transport, status: p.transport === "connecting" ? "Awaiting connection…" : undefined, isFocused: mainUid === p.uid, contain: presenterUid === p.uid, className: className, onClick: () => togglePin(p.uid) }, p.uid));
+    const selfTile = (className) => (_jsx(ParticipantTile, { name: selfName, stream: media.videoStream, isLocal: true, cameraOff: !media.cameraOn, micMuted: !media.micOn, handRaised: handRaised, status: selfConnecting ? "Connecting…" : undefined, 
+        // A custom background is a fixed picture, not a live reflection - mirroring it would show it backwards
+        // to no one but the participant themselves (see `_ParticipantTile.tsx`'s doc comment).
+        mirrored: media.filters.background !== "image", className: className }));
     const mainParticipant = participants.find((p) => p.uid === mainUid);
     const thumbnails = participants.filter((p) => p.uid !== mainUid);
     let stage;
@@ -297,6 +308,12 @@ function RemoteAudio({ stream, onBlocked }) {
     }, [stream, onBlocked]);
     return _jsx("audio", { ref: audioRef, autoPlay: true, "data-testid": "remote-audio" });
 }
+/** The WebSocket media relay for this call, or `undefined` when this browser cannot run it (no WebCodecs) - the
+ * mesh then never falls back to it, and says so by marking an unreachable participant `"failed"`. */
+function createRelay(meetingUid, peerId) {
+    const relay = createRelayTransport({ meetingUid, peerId });
+    return relay.supported ? relay : undefined;
+}
 function stopLevelMeter(ref, uid) {
     ref.current[uid]?.stop();
     delete ref.current[uid];

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

@@ -0,0 +1,17 @@
+/**
+ * The picker for the video filters (`apps/shared/media/filters/`): a background, a colour effect and a face accessory,
+ * each one of a short list, chosen independently so they combine. Shared by the lobby (on the page's light theme) and
+ * the in-call control bar (on its dark one) - `tone` picks the colours, nothing else differs.
+ *
+ * The background can also be a picture from the participant's own device: choosing "Custom image" with none picked yet
+ * opens the file picker, and once one is picked "Change image" is offered beside the options. The picture is read and
+ * kept in the browser (`filters/backgroundImage.ts`) - it is never uploaded.
+ */
+import React from "react";
+import type { LocalMedia } from "../shared/media/useLocalMedia.js";
+export type EffectsTone = "light" | "dark";
+export interface EffectsPanelProps {
+    media: LocalMedia;
+    tone: EffectsTone;
+}
+export default function EffectsPanel({ media, tone }: EffectsPanelProps): React.JSX.Element;