@rapidmx/meet-plugin 0.1.0

package/apps/shared/webrtc/MeshConnectionManager.ts

@@ -0,0 +1,350 @@
+///////////////////////////////////////////////////////////////////////////////
+// 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.
+ *
+ * ## 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.
+ *
+ * ## 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()`.
+ *
+ * ## 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.
+ */
+import type { MeshEvent, MeshParticipant, RTCPeerConnectionFactory, RTCPeerConnectionLike, SignalMessage, SignalingChannel } from "./types.js";
+
+/** The lexicographically smaller uid is always the offerer for that pair - see this module's doc comment. */
+export function isOfferer(selfUid: string, peerUid: string): boolean {
+    return selfUid < peerUid;
+}
+
+interface PeerState {
+    uid: string;
+    name: string;
+    pc: RTCPeerConnectionLike;
+    remoteDescriptionSet: boolean;
+    pendingCandidates: RTCIceCandidateInit[];
+}
+
+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;
+}
+
+export class MeshConnectionManager {
+    private readonly peers = new Map<string, PeerState>();
+    private readonly listeners = new Set<(event: MeshEvent) => void>();
+    private unsubscribe: (() => void) | undefined;
+    private started = false;
+    private stopped = false;
+    private currentPresenterUid: string | undefined;
+
+    constructor(private readonly options: MeshConnectionManagerOptions) {}
+
+    get participants(): MeshParticipant[] {
+        return [...this.peers.values()].map((peer) => ({ uid: peer.uid, name: peer.name }));
+    }
+
+    get presenterUid(): string | undefined {
+        return this.currentPresenterUid;
+    }
+
+    onEvent(listener: (event: MeshEvent) => void): () => void {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+
+    /** Subscribes to the channel and announces this participant. Idempotent - a second call is a no-op. */
+    start(): void {
+        if (this.started) {
+            return;
+        }
+        this.started = true;
+        this.unsubscribe = this.options.channel.onMessage((message) => this.handleMessage(message));
+        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. */
+    stop(): void {
+        if (this.stopped) {
+            return;
+        }
+        this.stopped = true;
+        if (this.started) {
+            this.send({ kind: "bye" });
+        }
+        this.unsubscribe?.();
+        this.unsubscribe = undefined;
+        for (const peer of this.peers.values()) {
+            peer.pc.close();
+        }
+        this.peers.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: MediaStreamTrack | null): void {
+        for (const peer of this.peers.values()) {
+            const sender = peer.pc.getSenders().find((s) => s.track?.kind === "video");
+            void sender?.replaceTrack(track);
+        }
+    }
+
+    /** 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(): boolean {
+        if (this.currentPresenterUid !== undefined && this.currentPresenterUid !== this.options.selfUid) {
+            return false;
+        }
+        this.currentPresenterUid = this.options.selfUid;
+        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(): void {
+        if (this.currentPresenterUid !== this.options.selfUid) {
+            return;
+        }
+        this.currentPresenterUid = undefined;
+        this.send({ kind: "presenter-release" });
+        this.emit({ type: "presenter-changed", uid: undefined });
+    }
+
+    private sendHello(): void {
+        this.send({ kind: "hello", name: this.options.selfName });
+    }
+
+    private send(partial: Omit<SignalMessage, "type" | "from">): void {
+        this.options.channel.send({ type: "video-meeting-signal", from: this.options.selfUid, ...partial });
+    }
+
+    private emit(event: MeshEvent): void {
+        for (const listener of [...this.listeners]) {
+            listener(event);
+        }
+    }
+
+    private handleMessage(message: SignalMessage): void {
+        if (message.type !== "video-meeting-signal" || message.from === this.options.selfUid) {
+            return;
+        }
+        if (message.to !== undefined && message.to !== this.options.selfUid) {
+            return;
+        }
+        switch (message.kind) {
+            case "hello":
+                this.handleHello(message);
+                return;
+            case "bye":
+                this.handleBye(message.from);
+                return;
+            case "offer":
+                void this.handleOffer(message);
+                return;
+            case "answer":
+                void this.handleAnswer(message);
+                return;
+            case "ice-candidate":
+                void this.handleIceCandidate(message);
+                return;
+            case "presenter-claim":
+                this.handlePresenterClaim(message.from);
+                return;
+            case "presenter-release":
+                this.handlePresenterRelease(message.from);
+                return;
+        }
+    }
+
+    private handleHello(message: SignalMessage): void {
+        if (this.peers.has(message.from)) {
+            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 } });
+        // 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)) {
+            void this.initiateOffer(peer);
+        }
+    }
+
+    private handleBye(uid: string): void {
+        const peer = this.peers.get(uid);
+        if (!peer) {
+            return;
+        }
+        peer.pc.close();
+        this.peers.delete(uid);
+        this.emit({ type: "participant-left", uid });
+        if (this.currentPresenterUid === uid) {
+            this.currentPresenterUid = undefined;
+            this.emit({ type: "presenter-changed", uid: undefined });
+        }
+    }
+
+    private createPeer(uid: string, name: string): PeerState {
+        const pc = this.options.createPeerConnection({ iceServers: this.options.iceServers });
+        const peer: PeerState = { uid, name, pc, remoteDescriptionSet: false, pendingCandidates: [] };
+        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 });
+            }
+        };
+        pc.onconnectionstatechange = () => {
+            if (pc.connectionState === "failed" || pc.connectionState === "closed") {
+                this.handleBye(uid);
+            }
+        };
+        return peer;
+    }
+
+    private async initiateOffer(peer: PeerState): Promise<void> {
+        const offer = await peer.pc.createOffer();
+        await peer.pc.setLocalDescription(offer);
+        this.send({ kind: "offer", to: peer.uid, sdp: offer });
+    }
+
+    private async handleOffer(message: SignalMessage): Promise<void> {
+        if (!message.sdp) {
+            return;
+        }
+        let peer = this.peers.get(message.from);
+        const isNew = !peer;
+        if (!peer) {
+            peer = this.createPeer(message.from, message.from);
+        }
+        await peer.pc.setRemoteDescription(message.sdp);
+        this.flushPendingCandidates(peer);
+        if (isNew) {
+            this.emit({ type: "participant-joined", participant: { uid: peer.uid, name: peer.name } });
+        }
+        const answer = await peer.pc.createAnswer();
+        await peer.pc.setLocalDescription(answer);
+        this.send({ kind: "answer", to: peer.uid, sdp: answer });
+    }
+
+    private async handleAnswer(message: SignalMessage): Promise<void> {
+        const peer = this.peers.get(message.from);
+        if (!peer || !message.sdp) {
+            return;
+        }
+        await peer.pc.setRemoteDescription(message.sdp);
+        this.flushPendingCandidates(peer);
+    }
+
+    private async handleIceCandidate(message: SignalMessage): Promise<void> {
+        if (!message.candidate) {
+            return;
+        }
+        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.
+            return;
+        }
+        if (!peer.remoteDescriptionSet) {
+            peer.pendingCandidates.push(message.candidate);
+            return;
+        }
+        await peer.pc.addIceCandidate(message.candidate);
+    }
+
+    private flushPendingCandidates(peer: PeerState): void {
+        peer.remoteDescriptionSet = true;
+        const pending = peer.pendingCandidates;
+        peer.pendingCandidates = [];
+        for (const candidate of pending) {
+            void peer.pc.addIceCandidate(candidate);
+        }
+    }
+
+    private handlePresenterClaim(from: string): void {
+        if (this.currentPresenterUid === undefined) {
+            this.currentPresenterUid = from;
+            this.emit({ type: "presenter-changed", uid: from });
+            return;
+        }
+        if (this.currentPresenterUid === from) {
+            return;
+        }
+        // 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.
+        if (from < this.currentPresenterUid) {
+            const loser = this.currentPresenterUid;
+            this.currentPresenterUid = from;
+            this.emit({ type: "presenter-changed", uid: from });
+            if (loser === this.options.selfUid) {
+                this.send({ kind: "presenter-release" });
+            }
+        }
+    }
+
+    private handlePresenterRelease(from: string): void {
+        if (this.currentPresenterUid === from) {
+            this.currentPresenterUid = undefined;
+            this.emit({ type: "presenter-changed", uid: undefined });
+        }
+    }
+}

package/apps/shared/webrtc/realPeerConnection.ts

@@ -0,0 +1,37 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz. All rights reserved.
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/** Adapts the real browser `RTCPeerConnection` to `RTCPeerConnectionLike` (`types.ts`) - `MeshConnectionManager`'s
+ * own tests never use this (they inject a fake `RTCPeerConnectionLike` directly); `apps/meet/_CallView.tsx` is
+ * this factory's only real caller. `createBrowserPeerConnection` is a plain function value, never invoked at
+ * module scope, so importing this file is safe during this plugin's page SSR, where `RTCPeerConnection` does not
+ * exist at all - it would only throw if actually *called* outside a browser. */
+import type { RTCPeerConnectionFactory, RTCPeerConnectionLike } from "./types.js";
+
+export const createBrowserPeerConnection: RTCPeerConnectionFactory = (config) => {
+    const pc = new RTCPeerConnection(config);
+    const like: RTCPeerConnectionLike = {
+        addTrack: (track, stream) => pc.addTrack(track, stream),
+        getSenders: () => pc.getSenders(),
+        createOffer: () => pc.createOffer(),
+        createAnswer: () => pc.createAnswer(),
+        setLocalDescription: (description) => pc.setLocalDescription(description),
+        setRemoteDescription: (description) => pc.setRemoteDescription(description),
+        addIceCandidate: (candidate) => pc.addIceCandidate(candidate),
+        close: () => pc.close(),
+        onicecandidate: null,
+        ontrack: null,
+        onconnectionstatechange: null,
+        get connectionState() {
+            return pc.connectionState;
+        },
+    };
+    // Forwards the real browser events to whatever handler `MeshConnectionManager` has currently assigned on
+    // `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.onconnectionstatechange = () => like.onconnectionstatechange?.();
+    return like;
+};

package/apps/shared/webrtc/types.ts

@@ -0,0 +1,90 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz. All rights reserved.
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/** Shared types for `MeshConnectionManager.ts` and its signaling transport (`apps/shared/push/GuestSignalingClient.ts`) -
+ * 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. */
+
+/**
+ * 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
+ * offers/answers and ICE candidates are ordinary `NotificationUtils.sendMessage()` payloads"). `type` is a fixed
+ * 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.
+ */
+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`). */
+    from: 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;
+    /** `offer`/`answer` only. */
+    sdp?: RTCSessionDescriptionInit;
+    /** `ice-candidate` only. */
+    candidate?: RTCIceCandidateInit;
+}
+
+/** What `MeshConnectionManager` needs from a signaling transport - implemented by
+ * `apps/shared/push/GuestSignalingClient.ts` for a real call, and by an in-memory fake for `MeshConnectionManager`'s own
+ * tests (see `test/webrtc/MeshConnectionManager.test.ts`), which never opens a real network connection. */
+export interface SignalingChannel {
+    send(message: SignalMessage): void;
+    /** Calls `handler` with every message received on the channel (including, per the pub/sub fan-out this
+     * transport is built on, this same client's own sends - `MeshConnectionManager` filters those out itself
+     * 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. */
+export interface RTCRtpSenderLike {
+    track: MediaStreamTrack | null;
+    replaceTrack(track: MediaStreamTrack | null): Promise<void>;
+}
+
+/** The subset of `RTCPeerConnection` `MeshConnectionManager` uses - what a test's fake implements, and what
+ * `apps/shared/webrtc/realPeerConnection.ts` adapts the real browser constructor to. Event handlers are plain settable
+ * 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[];
+    createOffer(): Promise<RTCSessionDescriptionInit>;
+    createAnswer(): Promise<RTCSessionDescriptionInit>;
+    setLocalDescription(description: RTCSessionDescriptionInit): Promise<void>;
+    setRemoteDescription(description: RTCSessionDescriptionInit): Promise<void>;
+    addIceCandidate(candidate: RTCIceCandidateInit): Promise<void>;
+    close(): void;
+    onicecandidate: ((event: { candidate: RTCIceCandidateInit | null }) => void) | null;
+    ontrack: ((event: { streams: readonly MediaStream[] }) => void) | null;
+    onconnectionstatechange: (() => void) | null;
+    connectionState: string;
+}
+
+export type RTCPeerConnectionFactory = (config: { iceServers: RTCIceServer[] }) => 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 {
+    uid: string;
+    name: string;
+}
+
+export type MeshEvent =
+    | { type: "participant-joined"; participant: MeshParticipant }
+    | { type: "participant-left"; uid: string }
+    | { type: "remote-stream"; uid: string; stream: MediaStream }
+    | { type: "presenter-changed"; uid: string | undefined };

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

@@ -0,0 +1,33 @@
+/**
+ * The public join/lobby/in-call page, `GET /meet/:token` - resolves an invitee's join token or a public meeting's
+ * slug (`BaseVideoMeetingRoute.join()`, both shapes accepted identically - see `_meetApi.ts`), then walks through
+ * `loading` -> `lobby` -> `in-call` -> `ended`.
+ *
+ * ## 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
+ * 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`)
+ * 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):
+ *
+ * 1. Have `PublicPageRoute.fetchProps()` check the incoming `jwt` cookie itself (the way `wwwRoute` already does)
+ * and pass `userUid`/`authServerUrl` through like the `www`/admin hosts do.
+ * 2. Add a small authenticated "who am I" endpoint on this server's own origin (no `authServerUrl` needed at all),
+ * which this page could call with `apiFetch()` the same way any other same-origin authenticated call works.
+ *
+ * Per the spec, the name field is always left empty and editable instead - correct for the common case (most
+ * invitees have no RapidMX account at all), just never prefilled even for a mailbox owner testing their own link.
+ */
+import React from "react";
+export default function MeetJoinPage({ params }: {
+    params: {
+        token: string;
+    };
+}): React.JSX.Element;

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

@@ -0,0 +1,101 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz. All rights reserved.
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * The public join/lobby/in-call page, `GET /meet/:token` - resolves an invitee's join token or a public meeting's
+ * slug (`BaseVideoMeetingRoute.join()`, both shapes accepted identically - see `_meetApi.ts`), then walks through
+ * `loading` -> `lobby` -> `in-call` -> `ended`.
+ *
+ * ## 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
+ * 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`)
+ * 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):
+ *
+ * 1. Have `PublicPageRoute.fetchProps()` check the incoming `jwt` cookie itself (the way `wwwRoute` already does)
+ * and pass `userUid`/`authServerUrl` through like the `www`/admin hosts do.
+ * 2. Add a small authenticated "who am I" endpoint on this server's own origin (no `authServerUrl` needed at all),
+ * which this page could call with `apiFetch()` the same way any other same-origin authenticated call works.
+ *
+ * Per the spec, the name field is always left empty and editable instead - correct for the common case (most
+ * 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 Alert from "@rapidmx/react-shared/components/feedback/Alert.js";
+import { MeetCard, MeetPageShell } from "./_MeetChrome.js";
+import { default as MeetLobby } from "./_MeetLobby.js";
+import CallView from "./_CallView.js";
+import { joinMeeting } from "./_meetApi.js";
+export default function MeetJoinPage({ params }) {
+    const { branding } = useBranding();
+    return (_jsx(MeetPageShell, { branding: branding, children: _jsx(MeetJoinContent, { token: params.token }) }));
+}
+function MeetJoinContent({ token }) {
+    const [phase, setPhase] = useState("loading");
+    const [joinResult, setJoinResult] = useState(null);
+    const [preferences, setPreferences] = useState(null);
+    const [loadError, setLoadError] = useState(null);
+    React.useEffect(() => {
+        let cancelled = false;
+        joinMeeting(token)
+            .then((result) => {
+            if (!cancelled) {
+                setJoinResult(result);
+                setPhase("lobby");
+            }
+        })
+            .catch((err) => {
+            if (cancelled) {
+                return;
+            }
+            if (err instanceof ApiRequestError && err.status === 404) {
+                setPhase("not-found");
+                return;
+            }
+            setLoadError(err instanceof ApiRequestError ? err.message : "Could not load this meeting.");
+            setPhase("not-found");
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, [token]);
+    function handleJoin(prefs) {
+        setPreferences(prefs);
+        setPhase("in-call");
+    }
+    function handleLeave() {
+        setPhase("ended");
+    }
+    if (phase === "loading") {
+        return (_jsx(MeetCard, { children: _jsx("p", { className: "text-base text-text-muted", children: "Loading\u2026" }) }));
+    }
+    if (phase === "not-found") {
+        return (_jsx(MeetCard, { children: _jsx(Alert, { children: loadError ?? "This meeting link isn't valid." }) }));
+    }
+    if (phase === "ended") {
+        return (_jsxs(MeetCard, { children: [_jsx("h1", { className: "text-xl font-bold tracking-tight mb-2", children: "You left the meeting" }), _jsx("p", { className: "text-base text-text-muted", children: "You can close this page now." })] }));
+    }
+    if (phase === "in-call" && joinResult && preferences) {
+        return (_jsx(CallView, { channel: joinResult.meeting.uid, 
+            // `token` is present only for the common anonymous case (`authenticated: false`) - when the
+            // caller's own existing session already authenticated them (`authenticated: true`), there is no
+            // 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: preferences.name, iceServers: joinResult.iceServers, initialStream: preferences.stream, initialMicOn: preferences.micOn, initialCameraOn: preferences.cameraOn, onLeave: handleLeave }));
+    }
+    // phase === "lobby" (join Result is always set by then - see the effect above).
+    return (_jsx(MeetCard, { maxWidth: "max-w-4xl", children: _jsx(MeetLobby, { meeting: joinResult.meeting, onJoin: handleJoin }) }));
+}

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

@@ -0,0 +1,18 @@
+/** The in-call bottom control bar: mute/unmute, camera on/off, share screen, grid/focus toggle, leave. Deliberately
+ * minimal per this plugin's Phase 2 spec ("no chat, no recording, no reactions"). */
+import React from "react";
+export type CallViewMode = "grid" | "focus";
+export interface CallControlsProps {
+    micOn: boolean;
+    onToggleMic: () => void;
+    cameraOn: boolean;
+    onToggleCamera: () => void;
+    isPresenting: boolean;
+    /** Someone else is presenting - the share button is disabled and explains why. */
+    presentingElsewhereName?: string;
+    onToggleShare: () => void;
+    viewMode: CallViewMode;
+    onToggleViewMode: () => void;
+    onLeave: () => void;
+}
+export default function CallControls({ micOn, onToggleMic, cameraOn, onToggleCamera, isPresenting, presentingElsewhereName, onToggleShare, viewMode, onToggleViewMode, onLeave, }: CallControlsProps): React.JSX.Element;

package/dist/apps/meet/_CallControls.js

@@ -0,0 +1,6 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import Button from "@rapidmx/react-shared/components/buttons/Button.js";
+export default function CallControls({ micOn, onToggleMic, cameraOn, onToggleCamera, isPresenting, presentingElsewhereName, onToggleShare, viewMode, onToggleViewMode, onLeave, }) {
+    const shareDisabled = !isPresenting && !!presentingElsewhereName;
+    return (_jsxs("div", { className: "flex flex-wrap items-center justify-center gap-2 py-3 px-4 bg-surface border-t border-border", children: [_jsx(Button, { type: "button", variant: "secondary", className: "!w-auto", onClick: onToggleMic, children: micOn ? "Mute" : "Unmute" }), _jsx(Button, { type: "button", variant: "secondary", className: "!w-auto", onClick: onToggleCamera, children: cameraOn ? "Turn camera off" : "Turn camera on" }), _jsx(Button, { type: "button", variant: "secondary", className: "!w-auto", disabled: shareDisabled, title: shareDisabled ? `${presentingElsewhereName} is presenting - stop their share to present yourself.` : undefined, onClick: onToggleShare, children: isPresenting ? "Stop sharing" : "Share screen" }), _jsx(Button, { type: "button", variant: "secondary", className: "!w-auto", onClick: onToggleViewMode, children: viewMode === "grid" ? "Focused view" : "Grid view" }), _jsx(Button, { type: "button", className: "!w-auto !bg-none !bg-danger !border-danger hover:!bg-danger", onClick: onLeave, children: "Leave" })] }));
+}