@rapidmx/meet-plugin 0.5.0 → 0.8.0

package/apps/shared/relay/relayEnv.ts

@@ -0,0 +1,230 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz. All rights reserved.
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Every browser API the relay tier touches, gathered behind one injectable object.
+ *
+ * WebCodecs, Web Audio and canvas capture are exactly the surfaces jsdom does not have, and the sender and
+ * receiver need a lot of them at once, so instead of patching a dozen globals in each test (and reading `globalThis`
+ * all over the implementation) the code takes a `RelayEnv` and `detectRelayEnv()` builds the real one. The interfaces
+ * here are deliberately the narrowest structural subset the relay actually calls - they are satisfied by the real
+ * browser objects, and small enough that a test's fake is a few lines.
+ */
+
+/** The half of an encoded chunk (`EncodedAudioChunk`/`EncodedVideoChunk`) an encoder's output callback reads. */
+export interface EncodedChunkLike {
+    readonly type: "key" | "delta";
+    /** Microseconds, as given to the encoder. */
+    readonly timestamp: number;
+    readonly byteLength: number;
+    copyTo(destination: Uint8Array): void;
+}
+
+export interface CoderInit<T> {
+    output: (output: T, metadata?: unknown) => void;
+    error: (error: Error) => void;
+}
+
+/** `AudioData`. */
+export interface AudioDataLike {
+    readonly numberOfFrames: number;
+    readonly sampleRate: number;
+    copyTo(destination: Float32Array, options: { planeIndex: number; format?: string }): void;
+    close(): void;
+}
+
+export interface AudioDataInit {
+    format: "f32-planar";
+    sampleRate: number;
+    numberOfFrames: number;
+    numberOfChannels: number;
+    timestamp: number;
+    data: Float32Array;
+}
+
+/** `VideoFrame`. */
+export interface VideoFrameLike {
+    readonly displayWidth: number;
+    readonly displayHeight: number;
+    close(): void;
+}
+
+export interface EncoderLike<TInput, TOptions = undefined> {
+    readonly encodeQueueSize: number;
+    configure(config: Record<string, unknown>): void;
+    encode(input: TInput, options?: TOptions): void;
+    close(): void;
+}
+
+export interface DecoderLike {
+    readonly decodeQueueSize: number;
+    configure(config: Record<string, unknown>): void;
+    decode(chunk: unknown): void;
+    close(): void;
+}
+
+export interface AudioNodeLike {
+    connect(destination: unknown): unknown;
+    disconnect(): void;
+}
+
+export interface ScriptProcessorLike extends AudioNodeLike {
+    onaudioprocess: ((event: { inputBuffer: { getChannelData(channel: number): Float32Array } }) => void) | null;
+}
+
+export interface GainLike extends AudioNodeLike {
+    gain: { value: number };
+}
+
+export interface AudioBufferLike {
+    copyToChannel(source: Float32Array, channel: number): void;
+    readonly duration: number;
+}
+
+export interface BufferSourceLike extends AudioNodeLike {
+    buffer: AudioBufferLike | null;
+    onended: (() => void) | null;
+    start(when?: number): void;
+}
+
+export interface AudioContextLike {
+    readonly state: string;
+    readonly currentTime: number;
+    readonly destination: unknown;
+    createMediaStreamSource(stream: MediaStream): AudioNodeLike;
+    createScriptProcessor(bufferSize: number, inputChannels: number, outputChannels: number): ScriptProcessorLike;
+    createGain(): GainLike;
+    createMediaStreamDestination(): { readonly stream: MediaStream };
+    createBuffer(channels: number, length: number, sampleRate: number): AudioBufferLike;
+    createBufferSource(): BufferSourceLike;
+    resume(): Promise<void>;
+    close(): Promise<void>;
+}
+
+export interface CanvasContextLike {
+    drawImage(source: unknown, dx: number, dy: number, dw?: number, dh?: number): void;
+}
+
+/** A hidden `<canvas>`. */
+export interface CanvasLike {
+    width: number;
+    height: number;
+    getContext(type: "2d"): CanvasContextLike | null;
+    captureStream(frameRate: number): MediaStream;
+}
+
+/** A hidden `<video>`. */
+export interface VideoElementLike {
+    muted: boolean;
+    autoplay: boolean;
+    playsInline: boolean;
+    srcObject: unknown;
+    readonly readyState: number;
+    readonly videoWidth: number;
+    readonly videoHeight: number;
+    play(): Promise<void> | undefined;
+    pause(): void;
+}
+
+/** The subset of `WebSocket` the relay client uses (the same seam shape `GuestSignalingClient`'s `PushSocket` has). */
+export interface RelaySocket {
+    readyState: number;
+    /** Bytes queued by `send()` that the browser has not yet handed to the network - the backpressure signal. */
+    readonly bufferedAmount: number;
+    binaryType: string;
+    send(data: string | Uint8Array): void;
+    close(code?: number, reason?: string): void;
+    onopen: ((event: unknown) => void) | null;
+    onmessage: ((event: { data: unknown }) => void) | null;
+    onclose: ((event: unknown) => void) | null;
+    onerror: ((event: unknown) => void) | null;
+}
+
+/** What `resumeAudioContext()` needs from `document`. */
+export interface EventTargetLike {
+    addEventListener(type: string, listener: () => void, options?: boolean): void;
+    removeEventListener(type: string, listener: () => void, options?: boolean): void;
+}
+
+export interface RelayEnv {
+    createSocket(url: string): RelaySocket;
+    /** `new AudioContext({ sampleRate })`. */
+    createAudioContext(sampleRate: number): AudioContextLike;
+    createMediaStream(tracks: MediaStreamTrack[]): MediaStream;
+    createVideoElement(): VideoElementLike;
+    createCanvas(): CanvasLike;
+    createAudioEncoder(init: CoderInit<EncodedChunkLike>): EncoderLike<AudioDataLike>;
+    createAudioDecoder(init: CoderInit<AudioDataLike>): DecoderLike;
+    createVideoEncoder(init: CoderInit<EncodedChunkLike>): EncoderLike<VideoFrameLike, { keyFrame: boolean }>;
+    createVideoDecoder(init: CoderInit<VideoFrameLike>): DecoderLike;
+    createAudioData(init: AudioDataInit): AudioDataLike;
+    /** `new VideoFrame(canvas, { timestamp })`. */
+    createVideoFrame(canvas: CanvasLike, timestampUs: number): VideoFrameLike;
+    createEncodedAudioChunk(init: { type: "key" | "delta"; timestamp: number; data: Uint8Array }): unknown;
+    createEncodedVideoChunk(init: { type: "key" | "delta"; timestamp: number; data: Uint8Array }): unknown;
+    document: EventTargetLike;
+    setInterval(callback: () => void, ms: number): unknown;
+    clearInterval(handle: unknown): void;
+    /** A monotonic clock in milliseconds (`performance.now()`). */
+    now(): number;
+    random(): number;
+}
+
+/** The names of the globals `detectRelayEnv()` requires, in one place so the check and the tests agree. */
+export const REQUIRED_GLOBALS = [
+    "WebSocket",
+    "AudioEncoder",
+    "AudioDecoder",
+    "VideoEncoder",
+    "VideoDecoder",
+    "AudioData",
+    "VideoFrame",
+    "EncodedAudioChunk",
+    "EncodedVideoChunk",
+    "AudioContext",
+    "MediaStream",
+    "HTMLCanvasElement",
+    "document",
+] as const;
+
+/**
+ * Builds the real environment from the browser's globals, or returns `undefined` when this browser lacks any
+ * piece of it (no WebSocket, no WebCodecs, no `AudioContext`, no `canvas.captureStream`, or not a browser at all).
+ * The relay codecs are fixed (Opus and VP8), so there is nothing useful to do with a partial environment - the
+ * mesh simply never falls back to the relay on such a browser.
+ */
+export function detectRelayEnv(): RelayEnv | undefined {
+    const scope = globalThis as unknown as Record<string, unknown>;
+    for (const name of REQUIRED_GLOBALS) {
+        if (typeof scope[name] === "undefined") {
+            return undefined;
+        }
+    }
+    if (typeof HTMLCanvasElement.prototype.captureStream !== "function") {
+        return undefined;
+    }
+    // Each factory resolves its constructor when called (not once here) so the environment follows whatever the page
+    // has at that moment, and so a test can stub a constructor after detection.
+    const construct = (name: string, ...args: unknown[]): never => new (scope[name] as new (...a: unknown[]) => never)(...args);
+    return {
+        createSocket: (url) => construct("WebSocket", url),
+        createAudioContext: (sampleRate) => construct("AudioContext", { sampleRate }),
+        createMediaStream: (tracks) => construct("MediaStream", tracks),
+        createVideoElement: () => document.createElement("video"),
+        createCanvas: () => document.createElement("canvas"),
+        createAudioEncoder: (init) => construct("AudioEncoder", init),
+        createAudioDecoder: (init) => construct("AudioDecoder", init),
+        createVideoEncoder: (init) => construct("VideoEncoder", init),
+        createVideoDecoder: (init) => construct("VideoDecoder", init),
+        createAudioData: (init) => construct("AudioData", init),
+        createVideoFrame: (canvas, timestamp) => construct("VideoFrame", canvas, { timestamp }),
+        createEncodedAudioChunk: (init) => construct("EncodedAudioChunk", init),
+        createEncodedVideoChunk: (init) => construct("EncodedVideoChunk", init),
+        document,
+        setInterval: (callback, ms) => globalThis.setInterval(callback, ms),
+        clearInterval: (handle) => globalThis.clearInterval(handle as ReturnType<typeof setInterval>),
+        now: () => performance.now(),
+        random: () => Math.random(),
+    };
+}

package/apps/shared/relay/senderCommon.ts

@@ -0,0 +1,30 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz. All rights reserved.
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import type { FrameKind } from "./frames.js";
+import type { RelayEnv } from "./relayEnv.js";
+
+/** Hands one encoded frame to the transport. `timestampMs` is on the `env.now()` clock. Returns whether every
+ * fragment of it was accepted by the socket - `false` means it was dropped (not ready, or backed up), which for
+ * video means the receiver will need a fresh key frame. */
+export type PublishFrame = (kind: FrameKind, keyFrame: boolean, data: Uint8Array, timestampMs: number) => boolean;
+
+/** What `AudioSender` and `VideoSender` are given. */
+export interface SenderDeps {
+    env: RelayEnv;
+    publish: PublishFrame;
+    /** Whether a frame encoded now could actually be sent. Encoding while the socket is down or still handshaking
+     * would burn CPU on frames that are then dropped, so the senders idle instead. */
+    canSend: () => boolean;
+}
+
+/** Closes an encoder/decoder, ignoring the `InvalidStateError` a browser throws for one that is already closed
+ * (which is what a coder that reported an error is). */
+export function safeClose(coder: { close(): void } | undefined): void {
+    try {
+        coder?.close();
+    } catch {
+        // Already closed.
+    }
+}

package/apps/shared/webrtc/MeshConnectionManager.ts

@@ -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].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