@rapidmx/meet-plugin 0.2.0 → 0.3.0

package/dist/apps/shared/media/useLocalMedia.js

@@ -0,0 +1,259 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz. All rights reserved.
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * The local participant's camera and microphone, owned by one component for the whole visit (`apps/meet/[token].tsx`)
+ * and handed to both the lobby and the call - so the tracks the lobby previews are the very tracks the call sends.
+ * (The lobby used to own its stream and stop it when it unmounted, which is exactly when the call starts using it:
+ * everyone who joined had dead tracks.) Every track is stopped once, when the owner unmounts or `release()` is
+ * called.
+ *
+ * - **Permission**: `requestAccess()` asks for the camera and microphone in one browser prompt, and falls back to
+ * asking for each on its own if that fails for any reason other than an outright denial - a machine with no camera
+ * still gets its microphone. It is safe to call again (a "try again" button is a user gesture, which some browsers
+ * require before they will prompt at all), and the per-kind `status` says what is and isn't working.
+ * - **Mute**: the microphone track is kept and disabled (`micEnabled`), so unmuting is instant. If there is no
+ * microphone track yet, unmuting asks for one.
+ * - **Camera**: turning the camera off stops its track (the camera light goes out and the device is released);
+ * turning it on asks for a new one.
+ * - **Devices**: `selectDevice()` swaps in another camera or microphone; `devicechange` refreshes the lists.
+ * - **Level**: `audioLevel` (0-5) follows the microphone while it is unmuted, for the "your audio is being sent"
+ * indicator.
+ *
+ * Nothing here runs during SSR: browser APIs are only touched from effects and event handlers.
+ */
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { defaultMediaDevices, isMediaDevicesSupported, listDevices, requestUserMedia, } from "./deviceMedia.js";
+import { startLevelMeter } from "./levelMeter.js";
+const AUDIO_CONSTRAINTS = { echoCancellation: true, noiseSuppression: true, autoGainControl: true };
+const VIDEO_CONSTRAINTS = { facingMode: "user", width: { ideal: 1280 }, height: { ideal: 720 } };
+/** The mean deviation (the level meter's 0-100 scale) that fills the whole indicator - ordinary speech sits well
+ * below full scale. */
+const LEVEL_FULL_SCALE = 20;
+export const AUDIO_LEVEL_STEPS = 5;
+function statusFor(error) {
+    switch (error.kind) {
+        case "permission-denied":
+            return "denied";
+        case "not-found":
+            return "unavailable";
+        default:
+            return "error";
+    }
+}
+export function useLocalMedia() {
+    const [supported, setSupported] = useState(true);
+    const [requesting, setRequesting] = useState(false);
+    const [error, setError] = useState(null);
+    const [tracks, setTracks] = useState({ audio: null, video: null });
+    const [status, setStatus] = useState({ audio: "pending", video: "pending" });
+    const [micEnabled, setMicEnabled] = useState(true);
+    const [devices, setDevices] = useState({ cameras: [], microphones: [] });
+    const [audioLevel, setAudioLevel] = useState(0);
+    const tracksRef = useRef({ audio: null, video: null });
+    const micEnabledRef = useRef(true);
+    const mountedRef = useRef(true);
+    const refreshDevices = useCallback(async () => {
+        const list = await listDevices();
+        if (list.ok && mountedRef.current) {
+            setDevices(list.value);
+        }
+    }, []);
+    /** Makes `track` the current track of its kind, stopping whatever it replaces - or stops it at once if the
+     * owner has already gone away (a request that resolved after unmount). */
+    const adoptTrack = useCallback((track) => {
+        const kind = track.kind;
+        if (!mountedRef.current) {
+            track.stop();
+            return;
+        }
+        const previous = tracksRef.current[kind];
+        if (previous && previous !== track) {
+            previous.onended = null;
+            previous.stop();
+        }
+        if (kind === "audio") {
+            track.enabled = micEnabledRef.current;
+        }
+        track.onended = () => {
+            // The device went away (unplugged, or the browser revoked permission).
+            if (tracksRef.current[kind] === track) {
+                tracksRef.current = { ...tracksRef.current, [kind]: null };
+                setTracks(tracksRef.current);
+                setStatus((prev) => ({ ...prev, [kind]: "unavailable" }));
+            }
+        };
+        tracksRef.current = { ...tracksRef.current, [kind]: track };
+        setTracks(tracksRef.current);
+        setStatus((prev) => ({ ...prev, [kind]: "live" }));
+    }, []);
+    const adoptStream = useCallback((stream) => {
+        for (const track of stream.getTracks()) {
+            adoptTrack(track);
+        }
+    }, [adoptTrack]);
+    /** Asks for one kind on its own - a specific device when `deviceId` is given. */
+    const acquire = useCallback(async (kind, deviceId) => {
+        const base = kind === "audio" ? AUDIO_CONSTRAINTS : VIDEO_CONSTRAINTS;
+        const constraint = deviceId ? { ...base, deviceId: { exact: deviceId } } : base;
+        const result = await requestUserMedia({ [kind]: constraint });
+        if (!result.ok) {
+            if (mountedRef.current) {
+                setError(result.error);
+                setStatus((prev) => ({ ...prev, [kind]: statusFor(result.error) }));
+            }
+            return false;
+        }
+        adoptStream(result.value);
+        if (mountedRef.current) {
+            setError(null);
+        }
+        return true;
+    }, [adoptStream]);
+    /** Asks for the camera and the microphone in a single prompt. */
+    const acquireBoth = useCallback(async () => {
+        const both = await requestUserMedia({ audio: AUDIO_CONSTRAINTS, video: VIDEO_CONSTRAINTS });
+        if (both.ok) {
+            adoptStream(both.value);
+        }
+        else if (both.error.kind === "permission-denied") {
+            if (mountedRef.current) {
+                setError(both.error);
+                setStatus({ audio: "denied", video: "denied" });
+            }
+        }
+        else {
+            // No camera, no microphone, or the two together couldn't be satisfied: ask for each on its own, so one
+            // missing device doesn't cost the participant the other.
+            await acquire("audio");
+            await acquire("video");
+        }
+    }, [acquire, adoptStream]);
+    const requestAccess = useCallback(async (kind) => {
+        if (!isMediaDevicesSupported()) {
+            setSupported(false);
+            return;
+        }
+        setRequesting(true);
+        setError(null);
+        await (kind ? acquire(kind) : acquireBoth());
+        await refreshDevices();
+        if (mountedRef.current) {
+            setRequesting(false);
+        }
+    }, [acquire, acquireBoth, refreshDevices]);
+    const toggleMic = useCallback(async () => {
+        const track = tracksRef.current.audio;
+        if (!track) {
+            micEnabledRef.current = true;
+            setMicEnabled(true);
+            await acquire("audio");
+            await refreshDevices();
+            return;
+        }
+        const next = !micEnabledRef.current;
+        micEnabledRef.current = next;
+        track.enabled = next;
+        setMicEnabled(next);
+    }, [acquire, refreshDevices]);
+    const toggleCamera = useCallback(async () => {
+        const track = tracksRef.current.video;
+        if (!track) {
+            await acquire("video");
+            await refreshDevices();
+            return;
+        }
+        track.onended = null;
+        track.stop();
+        tracksRef.current = { ...tracksRef.current, video: null };
+        setTracks(tracksRef.current);
+        setStatus((prev) => ({ ...prev, video: "off" }));
+    }, [acquire, refreshDevices]);
+    const selectDevice = useCallback(async (kind, deviceId) => {
+        if (kind === "video") {
+            // Some phones can't open a second camera while the first is still running.
+            const current = tracksRef.current.video;
+            if (current) {
+                current.onended = null;
+                current.stop();
+                tracksRef.current = { ...tracksRef.current, video: null };
+                setTracks(tracksRef.current);
+            }
+        }
+        await acquire(kind, deviceId);
+        await refreshDevices();
+    }, [acquire, refreshDevices]);
+    const release = useCallback(() => {
+        for (const track of Object.values(tracksRef.current)) {
+            if (track) {
+                track.onended = null;
+                track.stop();
+            }
+        }
+        tracksRef.current = { audio: null, video: null };
+        setTracks(tracksRef.current);
+        setStatus({ audio: "pending", video: "pending" });
+    }, []);
+    // Stops everything when the owner goes away.
+    useEffect(() => {
+        mountedRef.current = true;
+        return () => {
+            mountedRef.current = false;
+            for (const track of Object.values(tracksRef.current)) {
+                track?.stop();
+            }
+            tracksRef.current = { audio: null, video: null };
+        };
+    }, []);
+    // Keeps the device lists current as devices are plugged in and out.
+    useEffect(() => {
+        const devicesApi = defaultMediaDevices();
+        if (!devicesApi?.addEventListener) {
+            return;
+        }
+        const onChange = () => void refreshDevices();
+        devicesApi.addEventListener("devicechange", onChange);
+        return () => devicesApi.removeEventListener("devicechange", onChange);
+    }, [refreshDevices]);
+    // The "your audio is being sent" level: follows the microphone while it is live and unmuted.
+    useEffect(() => {
+        if (!tracks.audio || !micEnabled) {
+            setAudioLevel(0);
+            return;
+        }
+        const handle = startLevelMeter(new MediaStream([tracks.audio]), (level) => {
+            const step = Math.round(Math.min(1, level / LEVEL_FULL_SCALE) * AUDIO_LEVEL_STEPS);
+            setAudioLevel((prev) => (prev === step ? prev : step));
+        });
+        return () => {
+            handle?.stop();
+            setAudioLevel(0);
+        };
+    }, [tracks.audio, micEnabled]);
+    const videoStream = useMemo(() => (tracks.video ? new MediaStream([tracks.video]) : null), [tracks.video]);
+    const selectedDeviceIds = useMemo(() => ({
+        audio: tracks.audio?.getSettings?.().deviceId,
+        video: tracks.video?.getSettings?.().deviceId,
+    }), [tracks.audio, tracks.video]);
+    return {
+        supported,
+        requesting,
+        error,
+        audioTrack: tracks.audio,
+        videoTrack: tracks.video,
+        videoStream,
+        micEnabled,
+        micOn: !!tracks.audio && micEnabled,
+        cameraOn: !!tracks.video,
+        status,
+        devices,
+        selectedDeviceIds,
+        audioLevel,
+        requestAccess,
+        toggleMic,
+        toggleCamera,
+        selectDevice,
+        release,
+    };
+}

package/dist/apps/shared/push/GuestSignalingClient.js

@@ -150,6 +150,8 @@ export class GuestSignalingClient {
             method: "POST",
             headers,
             body: JSON.stringify(message),
+            // Lets a `bye` sent as the page unloads still go out.
+            keepalive: true,
         }).catch(() => {
             // Best-effort - see this method's doc comment.
         });

package/dist/apps/shared/webrtc/MeshConnectionManager.d.ts

@@ -11,6 +11,20 @@
  * both sides independently compute the same answer with no coordination round trip, and exactly one side ever
  * calls `createOffer()` for a given pair.
  *
+ * ## Media: two permanent transceivers, tracks swapped in and out
+ *
+ * Every connection carries one send-and-receive audio transceiver and one send-and-receive video transceiver,
+ * whether or not the local participant has a microphone or camera to send yet. The offerer adds them before its
+ * offer; the answerer takes the ones the offer created (`claimTransceivers()`) - a browser does not match an offer's
+ * m-lines to transceivers the answerer added itself, so adding them up front on both sides leaves the answerer
+ * sending nothing at all. A participant who declined permission, has no camera, or turns the camera on halfway
+ * through therefore still negotiates both directions from the first offer, and later `setLocalTrack()` calls just
+ * `replaceTrack()` on the existing senders - never a renegotiation. (Attaching tracks once at connection creation,
+ * as this manager used to, meant a participant with nothing to send at that moment negotiated no media in either
+ * direction, for the whole call.)
+ * The remote side's tracks are collected into one `MediaStream` per peer (`remote-stream` events), rather than
+ * read from `event.streams[0]`: a transceiver whose sender has no track yet announces no stream to the far end.
+ *
  * ## Join announcement and roster discovery
  *
  * The channel has no history (a push event published while a socket was down is never replayed - see
@@ -22,6 +36,17 @@
  * roster regardless of join order. This is naturally bounded (each participant echoes at most once per peer it
  * ever discovers) rather than a risk of runaway flooding.
  *
+ * Each message is its own `POST`, so nothing guarantees they arrive in the order they were sent. Two consequences
+ * are handled here: an `offer` that beats its sender's `hello` creates the peer under a placeholder name that the
+ * `hello` then replaces (`participant-updated`), and an ICE candidate that beats its offer is held until the peer
+ * exists rather than dropped.
+ *
+ * ## Participant state, hands and reactions
+ *
+ * What each participant is sending (`audioOn`/`videoOn`) and whether their hand is up travels in `hello` and in a
+ * `state` message on every change (`setLocalState()`), because a remote track gives no dependable signal that its
+ * sender stopped. `reaction` messages carry one emoji from `REACTION_EMOJIS`; anything else is ignored.
+ *
  * ## Presenter (single-writer screen share)
  *
  * `presenter-claim` is only ever sent locally when `presenterUid` is unset (`claimPresenter()` refuses otherwise).
@@ -31,29 +56,35 @@
  * smaller uid wins, and the losing claimant self-revokes (stops its own share locally and sends
  * `presenter-release`) once it observes the winning claim. See `handlePresenterClaim()`.
  *
- * ## Presentation mode's screen share
- *
- * Sharing a screen never adds a second video track or renegotiates a connection - `replaceLocalVideoTrack()`
- * simply swaps each peer connection's existing outgoing video `RTCRtpSender`'s track (`sender.replaceTrack()`),
- * the same track object already flowing to everyone from the moment they joined. Stopping a share replaces it
- * back to the camera track the same way.
+ * Sharing a screen is `setLocalTrack("video", screenTrack)`; stopping is `setLocalTrack("video", cameraTrack)`.
  */
-import type { MeshEvent, MeshParticipant, RTCPeerConnectionFactory, SignalingChannel } from "./types.js";
+import { type MeshEvent, type MeshParticipant, type ParticipantState, type RTCPeerConnectionFactory, type SignalingChannel } from "./types.js";
 /** The lexicographically smaller uid is always the offerer for that pair - see this module's doc comment. */
 export declare function isOfferer(selfUid: string, peerUid: string): boolean;
+type MediaKind = "audio" | "video";
 export interface MeshConnectionManagerOptions {
     selfUid: string;
     selfName: string;
     iceServers: RTCIceServer[];
     channel: SignalingChannel;
     createPeerConnection: RTCPeerConnectionFactory;
-    /** The local camera/microphone stream, attached to every new peer connection as it's created. */
-    localStream: MediaStream;
+    /** The tracks to send from the start - either may be absent (no permission, no device) and supplied or
+     * replaced later with `setLocalTrack()`. */
+    localAudioTrack?: MediaStreamTrack | null;
+    localVideoTrack?: MediaStreamTrack | null;
+    /** What to announce at first - defaults to "sending whatever tracks were given, hand down". */
+    localState?: Partial<ParticipantState>;
+    /** Builds the (initially empty) stream one peer's incoming tracks are gathered into. Defaults to
+     * `new MediaStream()`; a test supplies a fake. */
+    createMediaStream?: () => MediaStream;
 }
 export declare class MeshConnectionManager {
     private readonly options;
     private readonly peers;
     private readonly listeners;
+    private readonly orphanCandidates;
+    private readonly localTracks;
+    private localState;
     private unsubscribe;
     private started;
     private stopped;
@@ -65,15 +96,18 @@ export declare class MeshConnectionManager {
     /** Subscribes to the channel and announces this participant. Idempotent - a second call is a no-op. */
     start(): void;
     /** Announces departure, closes every peer connection and unsubscribes - idempotent, and safe to call whether
-     * or not `start()` ever ran. Never removes the camera/microphone indicator itself - stopping `localStream`'s
-     * own tracks is the caller's job (see `deviceMedia.ts`'s `stopStream()`), since this manager never owns that
-     * stream's lifecycle, only attaches it. */
+     * or not `start()` ever ran. Never removes the camera/microphone indicator itself - stopping the local
+     * tracks is the caller's job (see `deviceMedia.ts`'s `stopStream()`), since this manager never owns their
+     * lifecycle, only sends them. */
     stop(): void;
-    /** Swaps every peer connection's outgoing video track (presentation mode) - see this module's doc comment.
-     * `track` is `null` to stop sending video at all (never used by this plugin's UI today, which always has a
-     * camera-or-screen track to fall back to, but kept correct since `RTCRtpSender.replaceTrack()` itself allows
-     * it). */
-    replaceLocalVideoTrack(track: MediaStreamTrack | null): void;
+    /** Sets the track sent as `kind` (`null` to send nothing) on every connection, now and for every peer that
+     * joins later - see this module's doc comment. */
+    setLocalTrack(kind: MediaKind, track: MediaStreamTrack | null): void;
+    /** Updates what this participant announces (`audioOn`/`videoOn`/`handRaised`) and tells everyone if anything
+     * actually changed. Before `start()` it only records the state, which `hello` then carries. */
+    setLocalState(partial: Partial<ParticipantState>): void;
+    /** Sends one emoji to everyone. Returns `false`, sending nothing, for an emoji outside `REACTION_EMOJIS`. */
+    sendReaction(emoji: string): boolean;
     /** Claims presenter status for the local participant. Refuses (returns `false`, sends nothing) when someone
      * else already presents - the caller (`_CallView.tsx`) uses this to disable its own "share screen" control
      * rather than let a claim silently do nothing. */
@@ -85,6 +119,11 @@ export declare class MeshConnectionManager {
     private emit;
     private handleMessage;
     private handleHello;
+    private handleState;
+    private handleReaction;
+    /** Applies a newly learned name and/or state to `peer`, emitting `participant-updated` (and `hand-raised` on a
+     * hand going up) only when something actually changed. */
+    private updatePeer;
     private handleBye;
     private createPeer;
     private initiateOffer;
@@ -95,3 +134,4 @@ export declare class MeshConnectionManager {
     private handlePresenterClaim;
     private handlePresenterRelease;
 }
+export {};