@rapidmx/meet-plugin 0.2.0 → 0.3.1

package/dist/apps/shared/webrtc/MeshConnectionManager.js

@@ -1,17 +1,95 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz. All rights reserved.
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Full-mesh WebRTC connection management: one direct `RTCPeerConnection` per other participant, signaled entirely
+ * over the meeting's own push channel (`SignalingChannel` - see `types.ts`) as this plugin's Phase 2
+ * `.claude/NOTES.md` entry lays out. Pure state machine, no JSX/DOM rendering - `apps/meet/_CallView.tsx` owns one
+ * instance per call and mirrors its events into React state.
+ *
+ * ## Who calls whom
+ *
+ * On learning of another participant (via `hello`), a peer connection for that pair is created by whichever side
+ * has the lexicographically smaller uid (`isOfferer()`) - a well-known, deterministic, race-free rule for a mesh:
+ * 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
+ * `@rapidmx/react-shared`'s `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
+ * first time it becomes aware of that peer - so within one extra round trip everyone converges on the same full
+ * 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).
+ * A claim is applied optimistically and locally at once; every recipient (including the claimant) applies the
+ * *first* claim it sees. If two claims genuinely race (both sent before either claimant heard the other's), every
+ * participant converges on the same winner by resolving the collision deterministically: the lexicographically
+ * 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()`.
+ *
+ * Sharing a screen is `setLocalTrack("video", screenTrack)`; stopping is `setLocalTrack("video", cameraTrack)`.
+ */
+import { REACTION_EMOJIS, } from "./types.js";
 /** The lexicographically smaller uid is always the offerer for that pair - see this module's doc comment. */
-export function isOfferer(selfUid, peerUid) {
-    return selfUid < peerUid;
+export function isOfferer(selfId, peerId) {
+    return selfId < peerId;
 }
+/** How many peers' worth of early ICE candidates are held, and how many candidates per peer - bounds the memory a
+ * misbehaving participant could make this hold for peers that never materialize. */
+const MAX_ORPHAN_PEERS = 32;
+const MAX_ORPHAN_CANDIDATES = 64;
 export class MeshConnectionManager {
     constructor(options) {
         this.options = options;
         this.peers = new Map();
         this.listeners = new Set();
+        this.orphanCandidates = new Map();
         this.started = false;
         this.stopped = false;
+        this.selfId = options.peerId ?? options.selfUid;
+        this.localTracks = { audio: options.localAudioTrack ?? null, video: options.localVideoTrack ?? null };
+        this.localState = {
+            audioOn: !!options.localAudioTrack,
+            videoOn: !!options.localVideoTrack,
+            handRaised: false,
+            ...options.localState,
+        };
     }
     get participants() {
-        return [...this.peers.values()].map((peer) => ({ uid: peer.uid, name: peer.name }));
+        return [...this.peers.values()].map((peer) => toParticipant(peer));
     }
     get presenterUid() {
         return this.currentPresenterUid;
@@ -30,9 +108,9 @@ export class MeshConnectionManager {
         this.sendHello();
     }
     /** 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() {
         if (this.stopped) {
             return;
@@ -47,33 +125,52 @@ export class MeshConnectionManager {
             peer.pc.close();
         }
         this.peers.clear();
+        this.orphanCandidates.clear();
         this.listeners.clear();
     }
-    /** 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) {
+    /** 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, track) {
+        this.localTracks[kind] = track;
         for (const peer of this.peers.values()) {
-            const sender = peer.pc.getSenders().find((s) => s.track?.kind === "video");
-            void sender?.replaceTrack(track);
+            void peer.senders[kind]?.replaceTrack(track);
+        }
+    }
+    /** 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) {
+        const next = { ...this.localState, ...partial };
+        if (sameState(next, this.localState)) {
+            return;
+        }
+        this.localState = next;
+        if (this.started && !this.stopped) {
+            this.send({ kind: "state", state: next });
         }
     }
+    /** Sends one emoji to everyone. Returns `false`, sending nothing, for an emoji outside `REACTION_EMOJIS`. */
+    sendReaction(emoji) {
+        if (!isReactionEmoji(emoji)) {
+            return false;
+        }
+        this.send({ kind: "reaction", emoji });
+        return true;
+    }
     /** 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. */
     claimPresenter() {
-        if (this.currentPresenterUid !== undefined && this.currentPresenterUid !== this.options.selfUid) {
+        if (this.currentPresenterUid !== undefined && this.currentPresenterUid !== this.selfId) {
             return false;
         }
-        this.currentPresenterUid = this.options.selfUid;
+        this.currentPresenterUid = this.selfId;
         this.send({ kind: "presenter-claim" });
         this.emit({ type: "presenter-changed", uid: this.currentPresenterUid });
         return true;
     }
     /** Releases presenter status - a no-op unless the local participant currently holds it. */
     releasePresenter() {
-        if (this.currentPresenterUid !== this.options.selfUid) {
+        if (this.currentPresenterUid !== this.selfId) {
             return;
         }
         this.currentPresenterUid = undefined;
@@ -81,21 +178,29 @@ export class MeshConnectionManager {
         this.emit({ type: "presenter-changed", uid: undefined });
     }
     sendHello() {
-        this.send({ kind: "hello", name: this.options.selfName });
+        this.send({ kind: "hello", name: this.options.selfName, state: this.localState });
     }
     send(partial) {
-        this.options.channel.send({ type: "video-meeting-signal", from: this.options.selfUid, ...partial });
+        this.options.channel.send({ type: "video-meeting-signal", from: this.options.selfUid, peer: this.selfId, ...partial });
     }
     emit(event) {
         for (const listener of [...this.listeners]) {
             listener(event);
         }
     }
-    handleMessage(message) {
-        if (message.type !== "video-meeting-signal" || message.from === this.options.selfUid) {
+    handleMessage(raw) {
+        if (raw.type !== "video-meeting-signal") {
             return;
         }
-        if (message.to !== undefined && message.to !== this.options.selfUid) {
+        // From here on `from` is the sender's peer id - see `SignalMessage.peer`.
+        if (raw.peer !== undefined && raw.peer !== raw.from && !raw.peer.startsWith(`${raw.from}~`)) {
+            return;
+        }
+        const message = { ...raw, from: raw.peer ?? raw.from };
+        if (message.from === this.selfId) {
+            return;
+        }
+        if (message.to !== undefined && message.to !== this.selfId) {
             return;
         }
         switch (message.kind) {
@@ -120,23 +225,65 @@ export class MeshConnectionManager {
             case "presenter-release":
                 this.handlePresenterRelease(message.from);
                 return;
+            case "state":
+                this.handleState(message);
+                return;
+            case "reaction":
+                this.handleReaction(message);
+                return;
         }
     }
     handleHello(message) {
-        if (this.peers.has(message.from)) {
+        const known = this.peers.get(message.from);
+        if (known) {
+            // An offer that beat this hello created the peer under a placeholder name - fill in the real one.
+            this.updatePeer(known, message.name, message.state);
             return;
         }
-        const name = message.name ?? message.from;
-        const peer = this.createPeer(message.from, name);
-        this.emit({ type: "participant-joined", participant: { uid: peer.uid, name: peer.name } });
+        const offerer = isOfferer(this.selfId, message.from);
+        const peer = this.createPeer(message.from, message.name ?? message.from, message.state, offerer);
+        this.emit({ type: "participant-joined", participant: toParticipant(peer) });
         // Let a newcomer who couldn't have seen our own original `hello` learn about us too - see this module's
         // doc comment on roster discovery.
         this.sendHello();
-        if (isOfferer(this.options.selfUid, message.from)) {
+        if (offerer) {
             void this.initiateOffer(peer);
         }
     }
+    handleState(message) {
+        const peer = this.peers.get(message.from);
+        if (peer) {
+            this.updatePeer(peer, undefined, message.state);
+        }
+    }
+    handleReaction(message) {
+        const peer = this.peers.get(message.from);
+        if (peer && isReactionEmoji(message.emoji)) {
+            this.emit({ type: "reaction", uid: peer.uid, name: peer.name, emoji: message.emoji });
+        }
+    }
+    /** 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. */
+    updatePeer(peer, name, state) {
+        const nextName = name ?? peer.name;
+        const next = state ? sanitizeState(state) : undefined;
+        const handWentUp = !!next && next.handRaised && !peer.handRaised;
+        if (nextName === peer.name && (!next || sameState(next, peer))) {
+            return;
+        }
+        peer.name = nextName;
+        if (next) {
+            peer.audioOn = next.audioOn;
+            peer.videoOn = next.videoOn;
+            peer.handRaised = next.handRaised;
+        }
+        this.emit({ type: "participant-updated", participant: toParticipant(peer) });
+        if (handWentUp) {
+            this.emit({ type: "hand-raised", uid: peer.uid, name: peer.name });
+        }
+    }
     handleBye(uid) {
+        this.orphanCandidates.delete(uid);
         const peer = this.peers.get(uid);
         if (!peer) {
             return;
@@ -149,23 +296,35 @@ export class MeshConnectionManager {
             this.emit({ type: "presenter-changed", uid: undefined });
         }
     }
-    createPeer(uid, name) {
+    createPeer(uid, name, state, offerer) {
         const pc = this.options.createPeerConnection({ iceServers: this.options.iceServers });
-        const peer = { uid, name, pc, remoteDescriptionSet: false, pendingCandidates: [] };
+        const peer = {
+            uid,
+            name,
+            ...(state ? sanitizeState(state) : { audioOn: false, videoOn: false, handRaised: false }),
+            pc,
+            senders: offerer
+                ? {
+                    audio: pc.addTransceiver("audio", this.localTracks.audio).sender,
+                    video: pc.addTransceiver("video", this.localTracks.video).sender,
+                }
+                : {},
+            remoteStream: (this.options.createMediaStream ?? (() => new MediaStream()))(),
+            remoteDescriptionSet: false,
+            pendingCandidates: this.orphanCandidates.get(uid) ?? [],
+        };
+        this.orphanCandidates.delete(uid);
         this.peers.set(uid, peer);
-        for (const track of this.options.localStream.getTracks()) {
-            pc.addTrack(track, this.options.localStream);
-        }
         pc.onicecandidate = (event) => {
             if (event.candidate) {
                 this.send({ kind: "ice-candidate", to: uid, candidate: event.candidate });
             }
         };
         pc.ontrack = (event) => {
-            const stream = event.streams[0];
-            if (stream) {
-                this.emit({ type: "remote-stream", uid, stream });
+            if (!peer.remoteStream.getTracks().includes(event.track)) {
+                peer.remoteStream.addTrack(event.track);
             }
+            this.emit({ type: "remote-stream", uid, stream: peer.remoteStream });
         };
         pc.onconnectionstatechange = () => {
             if (pc.connectionState === "failed" || pc.connectionState === "closed") {
@@ -186,12 +345,23 @@ export class MeshConnectionManager {
         let peer = this.peers.get(message.from);
         const isNew = !peer;
         if (!peer) {
-            peer = this.createPeer(message.from, message.from);
+            peer = this.createPeer(message.from, message.from, undefined, false);
         }
         await peer.pc.setRemoteDescription(message.sdp);
         this.flushPendingCandidates(peer);
+        if (!peer.senders.audio && !peer.senders.video) {
+            // The answerer's half of the media setup - see this module's doc comment.
+            peer.senders = peer.pc.claimTransceivers();
+            for (const kind of ["audio", "video"]) {
+                const track = this.localTracks[kind];
+                if (track) {
+                    await peer.senders[kind]?.replaceTrack(track);
+                }
+            }
+        }
         if (isNew) {
-            this.emit({ type: "participant-joined", participant: { uid: peer.uid, name: peer.name } });
+            this.emit({ type: "participant-joined", participant: toParticipant(peer) });
+            this.sendHello();
         }
         const answer = await peer.pc.createAnswer();
         await peer.pc.setLocalDescription(answer);
@@ -211,10 +381,17 @@ export class MeshConnectionManager {
         }
         const peer = this.peers.get(message.from);
         if (!peer) {
-            // No connection tracked for this peer yet (a candidate that raced ahead of its own offer/answer) -
-            // nothing to buffer it against, and one lost trickle-ICE candidate does not by itself break a
-            // connection (there are normally several). See this module's known-limitations note in the Phase 2
-            // report.
+            // A candidate that raced ahead of its own offer (each message is a separate `POST`) - hold it for
+            // the peer to claim when it is created. Bounded, see `MAX_ORPHAN_PEERS`.
+            const held = this.orphanCandidates.get(message.from);
+            if (held) {
+                if (held.length < MAX_ORPHAN_CANDIDATES) {
+                    held.push(message.candidate);
+                }
+            }
+            else if (this.orphanCandidates.size < MAX_ORPHAN_PEERS) {
+                this.orphanCandidates.set(message.from, [message.candidate]);
+            }
             return;
         }
         if (!peer.remoteDescriptionSet) {
@@ -243,12 +420,12 @@ export class MeshConnectionManager {
         // Collision: a claim from someone other than the presenter we already recorded. Resolve deterministically
         // - see this module's doc comment - so every participant converges on the same winner. When the
         // already-recorded presenter has the smaller uid, it wins and nothing changes here - including when that
-        // presenter is `this.options.selfUid` itself, whose own optimistic claim simply stays in place.
+        // presenter is this participant itself, whose own optimistic claim simply stays in place.
         if (from < this.currentPresenterUid) {
             const loser = this.currentPresenterUid;
             this.currentPresenterUid = from;
             this.emit({ type: "presenter-changed", uid: from });
-            if (loser === this.options.selfUid) {
+            if (loser === this.selfId) {
                 this.send({ kind: "presenter-release" });
             }
         }
@@ -260,3 +437,16 @@ export class MeshConnectionManager {
         }
     }
 }
+function toParticipant(peer) {
+    return { uid: peer.uid, name: peer.name, audioOn: peer.audioOn, videoOn: peer.videoOn, handRaised: peer.handRaised };
+}
+function sameState(a, b) {
+    return a.audioOn === b.audioOn && a.videoOn === b.videoOn && a.handRaised === b.handRaised;
+}
+/** Copies only the three booleans out of a received state, coerced - a message off the wire is untrusted. */
+function sanitizeState(state) {
+    return { audioOn: state.audioOn === true, videoOn: state.videoOn === true, handRaised: state.handRaised === true };
+}
+function isReactionEmoji(emoji) {
+    return REACTION_EMOJIS.includes(emoji);
+}

package/dist/apps/shared/webrtc/realPeerConnection.js

@@ -1,8 +1,21 @@
 export const createBrowserPeerConnection = (config) => {
     const pc = new RTCPeerConnection(config);
     const like = {
-        addTrack: (track, stream) => pc.addTrack(track, stream),
-        getSenders: () => pc.getSenders(),
+        addTransceiver: (kind, track) => {
+            const { sender } = pc.addTransceiver(track ?? kind, { direction: "sendrecv" });
+            return { sender };
+        },
+        claimTransceivers: () => {
+            const senders = {};
+            for (const transceiver of pc.getTransceivers()) {
+                const kind = transceiver.receiver.track.kind;
+                if (!senders[kind]) {
+                    transceiver.direction = "sendrecv";
+                    senders[kind] = transceiver.sender;
+                }
+            }
+            return senders;
+        },
         createOffer: () => pc.createOffer(),
         createAnswer: () => pc.createAnswer(),
         setLocalDescription: (description) => pc.setLocalDescription(description),
@@ -20,7 +33,7 @@ export const createBrowserPeerConnection = (config) => {
     // `like` - a level of indirection needed because `like`'s own handler properties are reassigned *after* this
     // adapter object is constructed and returned (see `MeshConnectionManager.createPeer()`).
     pc.onicecandidate = (event) => like.onicecandidate?.({ candidate: event.candidate ? event.candidate.toJSON() : null });
-    pc.ontrack = (event) => like.ontrack?.({ streams: event.streams });
+    pc.ontrack = (event) => like.ontrack?.({ track: event.track });
     pc.onconnectionstatechange = () => like.onconnectionstatechange?.();
     return like;
 };

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

@@ -2,6 +2,18 @@
  * kept in their own module so a test can depend on the shapes alone. `GuestSignalingClient` itself now also serves
  * an already-authenticated real caller (`VideoMeetingJoinResult.authenticated`), not only a synthetic guest - see
  * its own doc comment. */
+/** What a participant is sending, and whether their hand is up. Announced in `hello` and re-sent as a `state`
+ * message on every change, so a tile can show a muted microphone, an avatar for a camera that is off, and a raised
+ * hand without inspecting the media itself (the far end of a `replaceTrack(null)` gives no dependable signal that
+ * the track stopped). */
+export interface ParticipantState {
+    audioOn: boolean;
+    videoOn: boolean;
+    handRaised: boolean;
+}
+/** The emoji a participant can send during a call. A received `reaction` outside this list is ignored, so an
+ * arbitrary string from another participant is never rendered. */
+export declare const REACTION_EMOJIS: readonly ["👍", "👏", "❤️", "🎉", "😂", "😮", "😢", "👋"];
 /**
  * One WebRTC signaling message, published as the JSON body of `POST /push/:meetingUid` (`BasePushRoute.send()`)
  * and received back over `/push`'s WebSocket, exactly as `BaseVideoMeetingRoute`'s doc comment describes ("SDP
@@ -9,22 +21,32 @@
  * literal so a listener on the meeting's channel (which will also see other frame shapes if this server ever
  * grows other push consumers) can cheaply recognize and skip anything that isn't one of these.
  *
- * `hello`/`bye`/`presenter-claim`/`presenter-release` are broadcast (`to` left unset - every participant is
- * relevant); `offer`/`answer`/`ice-candidate` are point-to-point (`to` is the intended peer's uid) - a recipient
- * that isn't `to` (when set) ignores the message, since a channel's pub/sub fans every message out to every
- * subscriber, sender included.
+ * `hello`/`bye`/`presenter-claim`/`presenter-release`/`state`/`reaction` are broadcast (`to` left unset - every
+ * participant is relevant); `offer`/`answer`/`ice-candidate` are point-to-point (`to` is the intended peer's uid) -
+ * a recipient that isn't `to` (when set) ignores the message, since a channel's pub/sub fans every message out to
+ * every subscriber, sender included.
  */
 export interface SignalMessage {
     type: "video-meeting-signal";
-    kind: "hello" | "bye" | "offer" | "answer" | "ice-candidate" | "presenter-claim" | "presenter-release";
-    /** The sender's uid - the real, already-authenticated caller's own uid when `join()` returned
-     * `authenticated: true`, else the `guest:<random>` uid `BaseVideoMeetingRoute.join()` minted (either way, see
-     * `VideoMeetingJoinResult.selfUid`). */
+    kind: "hello" | "bye" | "offer" | "answer" | "ice-candidate" | "presenter-claim" | "presenter-release" | "state" | "reaction";
+    /** 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
+     * exactly that uid. */
     from: string;
+    /** Which of the sender's tabs or devices this is: `<from>~<random>`. The same account joining from two devices is
+     * two participants, not one that ignores its own messages. A `peer` that doesn't start with `<from>~` is
+     * 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`). */
     to?: string;
     /** `hello` only - the display name the sender chose in the lobby. */
     name?: string;
+    /** `hello` and `state` - what the sender is currently sending and whether their hand is up. */
+    state?: ParticipantState;
+    /** `reaction` only - one of `REACTION_EMOJIS`. */
+    emoji?: string;
     /** `offer`/`answer` only. */
     sdp?: RTCSessionDescriptionInit;
     /** `ice-candidate` only. */
@@ -40,9 +62,10 @@ export interface SignalingChannel {
      * rather than relying on the transport to). Returns the function that stops listening. */
     onMessage(handler: (message: SignalMessage) => void): () => void;
 }
-/** The subset of `RTCRtpSender` `MeshConnectionManager.replaceLocalVideoTrack()` uses (presentation mode - see
- * this plugin's Phase 2 `.claude/NOTES.md` entry: sharing replaces the outgoing camera track rather than adding a
- * second video track, so no renegotiation is ever needed). A real `RTCRtpSender` already satisfies this shape. */
+/** The subset of `RTCRtpSender` `MeshConnectionManager.setLocalTrack()` uses. Every connection carries one audio and
+ * one video sender for its whole life (see `MeshConnectionManager`'s doc comment), so turning a camera on or off,
+ * switching a device or sharing a screen only ever replaces the track a sender sends - no renegotiation. A real
+ * `RTCRtpSender` already satisfies this shape. */
 export interface RTCRtpSenderLike {
     track: MediaStreamTrack | null;
     replaceTrack(track: MediaStreamTrack | null): Promise<void>;
@@ -52,8 +75,16 @@ export interface RTCRtpSenderLike {
  * properties (`RTCPeerConnection`'s own `on*` style) rather than `addEventListener`, matching the browser API
  * this stands in for and keeping a test fake to the bare minimum. */
 export interface RTCPeerConnectionLike {
-    addTrack(track: MediaStreamTrack, stream: MediaStream): RTCRtpSenderLike;
-    getSenders(): RTCRtpSenderLike[];
+    /** The offerer's side: adds a send-and-receive transceiver for `kind`, sending `track` when there is one and
+     * nothing until `replaceTrack()` supplies it otherwise. */
+    addTransceiver(kind: "audio" | "video", track: MediaStreamTrack | null): {
+        sender: RTCRtpSenderLike;
+    };
+    /** The answerer's side: once the remote offer is applied, turns the transceivers that offer created into
+     * send-and-receive ones and returns their senders by kind. (A browser only matches an offer's m-lines to
+     * transceivers it created for the offer itself - one the answerer added up front with `addTransceiver()` is left
+     * unused, and everything the answerer sends is silently lost.) */
+    claimTransceivers(): Partial<Record<"audio" | "video", RTCRtpSenderLike>>;
     createOffer(): Promise<RTCSessionDescriptionInit>;
     createAnswer(): Promise<RTCSessionDescriptionInit>;
     setLocalDescription(description: RTCSessionDescriptionInit): Promise<void>;
@@ -64,7 +95,7 @@ export interface RTCPeerConnectionLike {
         candidate: RTCIceCandidateInit | null;
     }) => void) | null;
     ontrack: ((event: {
-        streams: readonly MediaStream[];
+        track: MediaStreamTrack;
     }) => void) | null;
     onconnectionstatechange: (() => void) | null;
     connectionState: string;
@@ -74,13 +105,16 @@ export type RTCPeerConnectionFactory = (config: {
 }) => RTCPeerConnectionLike;
 /** One other participant currently known to be in the call - `MeshConnectionManager.participants` never includes
  * the local participant themselves (the UI already knows its own name/uid without asking the manager). */
-export interface MeshParticipant {
+export interface MeshParticipant extends ParticipantState {
     uid: string;
     name: string;
 }
 export type MeshEvent = {
     type: "participant-joined";
     participant: MeshParticipant;
+} | {
+    type: "participant-updated";
+    participant: MeshParticipant;
 } | {
     type: "participant-left";
     uid: string;
@@ -88,6 +122,15 @@ export type MeshEvent = {
     type: "remote-stream";
     uid: string;
     stream: MediaStream;
+} | {
+    type: "hand-raised";
+    uid: string;
+    name: string;
+} | {
+    type: "reaction";
+    uid: string;
+    name: string;
+    emoji: string;
 } | {
     type: "presenter-changed";
     uid: string | undefined;

package/dist/apps/shared/webrtc/types.js

@@ -6,4 +6,6 @@
  * kept in their own module so a test can depend on the shapes alone. `GuestSignalingClient` itself now also serves
  * an already-authenticated real caller (`VideoMeetingJoinResult.authenticated`), not only a synthetic guest - see
  * its own doc comment. */
-export {};
+/** The emoji a participant can send during a call. A received `reaction` outside this list is ignored, so an
+ * arbitrary string from another participant is never rendered. */
+export const REACTION_EMOJIS = ["👍", "👏", "❤️", "🎉", "😂", "😮", "😢", "👋"];