@rapidmx/meet-plugin 0.1.0

package/apps/meet/_CallView.tsx

@@ -0,0 +1,338 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz. All rights reserved.
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * The in-call view: connects the full-mesh `MeshConnectionManager` to the meeting's signaling channel
+ * (`GuestSignalingClient`), mirrors its events into React state, and renders the grid/focused/presentation
+ * layouts - see `apps/shared/webrtc/MeshConnectionManager.ts`'s doc comment for the who-calls-whom and
+ * single-presenter rules this view relies on rather than re-deciding. These reusable, non-UI modules live under
+ * `apps/shared/` rather than this plugin's backend `src/` - `tsconfig.apps.json` builds `apps/` as its own
+ * program rooted at `apps/`, which cannot reference files outside it (`TS6059`), matching `booking-plugin`'s own
+ * identical `apps/shared/` convention for reusable frontend-only code.
+ *
+ * ## Layout precedence
+ *
+ * `computeMainUid()` decides who is shown large, in this order: an active presenter always wins (presentation
+ * mode, forcing a focused-like layout regardless of `viewMode`); otherwise a manually pinned participant; else the
+ * auto-detected active speaker (silently ignored while presenting, so it never fights the presenter for the main
+ * slot); else, in focus mode with nobody yet speaking, the first other participant - so focus mode never shows an
+ * empty main slot once someone else has joined.
+ */
+import React, { useEffect, useRef, useState } from "react";
+import { pickActiveSpeaker } from "../shared/media/activeSpeaker.js";
+import { startLevelMeter, type LevelMeterHandle } from "../shared/media/levelMeter.js";
+import { requestDisplayMedia, setTracksEnabled, stopStream } from "../shared/media/deviceMedia.js";
+import { createBrowserPeerConnection } from "../shared/webrtc/realPeerConnection.js";
+import { MeshConnectionManager } from "../shared/webrtc/MeshConnectionManager.js";
+import type { MeshParticipant } from "../shared/webrtc/types.js";
+import { GuestSignalingClient } from "../shared/push/GuestSignalingClient.js";
+import Alert from "@rapidmx/react-shared/components/feedback/Alert.js";
+import CallControls, { type CallViewMode } from "./_CallControls.js";
+import ParticipantTile from "./_ParticipantTile.js";
+
+export interface CallViewProps {
+    channel: string;
+    /** Omitted when the caller already authenticated as a real RapidMX identity in `join()` - there is then no
+     * guest token to hand `GuestSignalingClient`, which relies entirely on the browser's own already-existing
+     * `jwt` session cookie instead (see its own doc comment). */
+    token?: string;
+    selfUid: string;
+    selfName: string;
+    iceServers: RTCIceServer[];
+    initialStream: MediaStream;
+    initialMicOn: boolean;
+    initialCameraOn: boolean;
+    onLeave: () => void;
+}
+
+/** Who is shown large - see this module's doc comment. `undefined` when nobody but the local participant has
+ * joined yet (the grid/focus toggle still works, there's just nobody else to focus on). */
+export function computeMainUid(options: {
+    presenterUid?: string;
+    pinnedUid?: string;
+    activeSpeakerUid?: string;
+    otherUids: readonly string[];
+}): string | undefined {
+    if (options.presenterUid) {
+        return options.presenterUid;
+    }
+    if (options.pinnedUid) {
+        return options.pinnedUid;
+    }
+    if (options.activeSpeakerUid) {
+        return options.activeSpeakerUid;
+    }
+    return options.otherUids[0];
+}
+
+export default function CallView({
+    channel,
+    token,
+    selfUid,
+    selfName,
+    iceServers,
+    initialStream,
+    initialMicOn,
+    initialCameraOn,
+    onLeave,
+}: CallViewProps) {
+    const [connectError, setConnectError] = useState<string | null>(null);
+    const [participants, setParticipants] = useState<MeshParticipant[]>([]);
+    const [remoteStreams, setRemoteStreams] = useState<Record<string, MediaStream>>({});
+    const [levels, setLevels] = useState<Record<string, number>>({});
+    const [presenterUid, setPresenterUid] = useState<string | undefined>(undefined);
+    const [micOn, setMicOn] = useState(initialMicOn);
+    const [cameraOn, setCameraOn] = useState(initialCameraOn);
+    const [isPresenting, setIsPresenting] = useState(false);
+    const [viewMode, setViewMode] = useState<CallViewMode>("grid");
+    const [pinnedUid, setPinnedUid] = useState<string | undefined>(undefined);
+    const [activeSpeakerUid, setActiveSpeakerUid] = useState<string | undefined>(undefined);
+
+    const managerRef = useRef<MeshConnectionManager | null>(null);
+    const clientRef = useRef<GuestSignalingClient | null>(null);
+    const localStreamRef = useRef(initialStream);
+    const screenStreamRef = useRef<MediaStream | null>(null);
+    const cameraTrackRef = useRef<MediaStreamTrack | null>(initialStream.getVideoTracks()[0] ?? null);
+    const levelMetersRef = useRef<Record<string, LevelMeterHandle>>({});
+    const isPresentingRef = useRef(false);
+
+    useEffect(() => {
+        let cancelled = false;
+        const client = new GuestSignalingClient({ channel, token });
+        clientRef.current = client;
+        const manager = new MeshConnectionManager({
+            selfUid,
+            selfName,
+            iceServers,
+            channel: client,
+            createPeerConnection: createBrowserPeerConnection,
+            localStream: localStreamRef.current,
+        });
+        managerRef.current = manager;
+
+        const unsubscribe = manager.onEvent((event) => {
+            switch (event.type) {
+                case "participant-joined":
+                    setParticipants((prev) => [...prev.filter((p) => p.uid !== event.participant.uid), event.participant]);
+                    return;
+                case "participant-left":
+                    setParticipants((prev) => prev.filter((p) => p.uid !== event.uid));
+                    setRemoteStreams((prev) => {
+                        const { [event.uid]: _removed, ...rest } = prev;
+                        return rest;
+                    });
+                    stopLevelMeter(levelMetersRef, event.uid);
+                    setLevels((prev) => {
+                        const { [event.uid]: _removed, ...rest } = prev;
+                        return rest;
+                    });
+                    setPinnedUid((prev) => (prev === event.uid ? undefined : prev));
+                    return;
+                case "remote-stream":
+                    setRemoteStreams((prev) => ({ ...prev, [event.uid]: event.stream }));
+                    startTrackingLevel(levelMetersRef, event.uid, event.stream, (level) =>
+                        setLevels((prev) => ({ ...prev, [event.uid]: level })),
+                    );
+                    return;
+                case "presenter-changed":
+                    setPresenterUid(event.uid);
+                    if (event.uid !== selfUid && isPresentingRef.current) {
+                        // Lost a presenter-claim collision (see `MeshConnectionManager`'s doc comment) - stop our
+                        // own capture without re-sending a release the manager already handled internally.
+                        stopLocalPresentation(false);
+                    }
+                    return;
+            }
+        });
+
+        client
+            .connect()
+            .then(() => {
+                if (!cancelled) {
+                    manager.start();
+                }
+            })
+            .catch((err: Error) => {
+                if (!cancelled) {
+                    setConnectError(err.message);
+                }
+            });
+
+        return () => {
+            cancelled = true;
+            unsubscribe();
+            manager.stop();
+            client.close();
+            for (const handle of Object.values(levelMetersRef.current)) {
+                handle.stop();
+            }
+            levelMetersRef.current = {};
+            stopStream(localStreamRef.current);
+            stopStream(screenStreamRef.current);
+        };
+        // Deliberately runs once - the call's identity (channel/token/selfUid) never changes for the life of this
+        // component; a real identity change is a new call, which unmounts/remounts this view from `[token].tsx`.
+    }, []);
+
+    useEffect(() => {
+        if (!presenterUid) {
+            setActiveSpeakerUid((prev) => pickActiveSpeaker(levels, prev));
+        }
+    }, [levels, presenterUid]);
+
+    function stopLocalPresentation(alsoRelease: boolean): void {
+        isPresentingRef.current = false;
+        setIsPresenting(false);
+        if (alsoRelease) {
+            managerRef.current?.releasePresenter();
+        }
+        stopStream(screenStreamRef.current);
+        screenStreamRef.current = null;
+        // Restores the camera track as the outgoing video sender - its own `enabled` flag (toggled by
+        // `handleToggleCamera`, untouched by presenting) already governs whether it actually sends frames, so
+        // this is correct whether or not the camera happens to be off right now.
+        managerRef.current?.replaceLocalVideoTrack(cameraTrackRef.current);
+    }
+
+    async function handleToggleShare() {
+        if (isPresenting) {
+            stopLocalPresentation(true);
+            return;
+        }
+        const result = await requestDisplayMedia();
+        if (!result.ok) {
+            setConnectError(result.error.message);
+            return;
+        }
+        const claimed = managerRef.current?.claimPresenter() ?? false;
+        if (!claimed) {
+            stopStream(result.value);
+            return;
+        }
+        screenStreamRef.current = result.value;
+        const [screenTrack] = result.value.getVideoTracks();
+        managerRef.current?.replaceLocalVideoTrack(screenTrack);
+        isPresentingRef.current = true;
+        setIsPresenting(true);
+        screenTrack.onended = () => stopLocalPresentation(true);
+    }
+
+    function handleToggleMic() {
+        setMicOn((prev) => {
+            const next = !prev;
+            setTracksEnabled(localStreamRef.current, "audio", next);
+            return next;
+        });
+    }
+
+    function handleToggleCamera() {
+        setCameraOn((prev) => {
+            const next = !prev;
+            // Just the track's own `enabled` flag (see `deviceMedia.ts`'s `setTracksEnabled()` doc comment) -
+            // whether that track is actually the one being sent (camera) or has been swapped out for a screen
+            // share (`replaceLocalVideoTrack()`) is an orthogonal concern this toggle never touches.
+            setTracksEnabled(localStreamRef.current, "video", next);
+            return next;
+        });
+    }
+
+    function handleLeave() {
+        onLeave();
+    }
+
+    function togglePin(uid: string) {
+        setPinnedUid((prev) => (prev === uid ? undefined : uid));
+    }
+
+    const otherUids = participants.map((p) => p.uid);
+    const showFocusLayout = !!presenterUid || viewMode === "focus";
+    const mainUid = showFocusLayout ? computeMainUid({ presenterUid, pinnedUid, activeSpeakerUid, otherUids }) : undefined;
+    const presenterName = presenterUid ? (presenterUid === selfUid ? selfName : (participants.find((p) => p.uid === presenterUid)?.name ?? "Someone")) : undefined;
+
+    const localTile = (
+        <ParticipantTile
+            key="__self"
+            name={selfName}
+            stream={isPresenting ? null : localStreamRef.current}
+            isLocal
+            cameraOff={!cameraOn && !isPresenting}
+            micMuted={!micOn}
+            isFocused={mainUid === selfUid}
+            onClick={() => togglePin(selfUid)}
+        />
+    );
+
+    const remoteTiles = participants.map((p) => (
+        <ParticipantTile
+            key={p.uid}
+            name={p.name}
+            stream={remoteStreams[p.uid] ?? null}
+            cameraOff={!remoteStreams[p.uid]}
+            isFocused={mainUid === p.uid}
+            onClick={() => togglePin(p.uid)}
+        />
+    ));
+
+    const allTiles = [localTile, ...remoteTiles];
+    // The presenter's own screen content is rendered from their local capture, not their (replaced) outgoing
+    // video sender - `mainStream` picks whichever is right for `mainUid`.
+    const mainStream =
+        mainUid === selfUid ? (isPresenting ? screenStreamRef.current : localStreamRef.current) : mainUid ? (remoteStreams[mainUid] ?? null) : null;
+    const mainName = mainUid === selfUid ? selfName : (participants.find((p) => p.uid === mainUid)?.name ?? "");
+    const thumbnailTiles = showFocusLayout ? allTiles.filter((tile) => tile.key !== (mainUid === selfUid ? "__self" : mainUid)) : allTiles;
+
+    return (
+        <div className="min-h-screen flex flex-col bg-surface-alt">
+            {connectError && <Alert>{connectError}</Alert>}
+            <div className="flex-1 p-3 flex flex-col gap-3 min-h-0">
+                {showFocusLayout && mainUid ? (
+                    <>
+                        <div className="flex-1 min-h-0">
+                            <ParticipantTile name={mainName} stream={mainStream} isLocal={mainUid === selfUid} isFocused className="h-full" />
+                        </div>
+                        <div className="flex gap-2 overflow-x-auto h-24 shrink-0">
+                            {thumbnailTiles.map((tile) => (
+                                <div key={tile.key} className="w-32 shrink-0">
+                                    {tile}
+                                </div>
+                            ))}
+                        </div>
+                    </>
+                ) : (
+                    <div className="flex-1 grid gap-2 [grid-template-columns:repeat(auto-fit,minmax(180px,1fr))]">{allTiles}</div>
+                )}
+            </div>
+            <CallControls
+                micOn={micOn}
+                onToggleMic={handleToggleMic}
+                cameraOn={cameraOn}
+                onToggleCamera={handleToggleCamera}
+                isPresenting={isPresenting}
+                presentingElsewhereName={presenterUid && presenterUid !== selfUid ? presenterName : undefined}
+                onToggleShare={handleToggleShare}
+                viewMode={viewMode}
+                onToggleViewMode={() => setViewMode((prev) => (prev === "grid" ? "focus" : "grid"))}
+                onLeave={handleLeave}
+            />
+        </div>
+    );
+}
+
+function stopLevelMeter(ref: React.MutableRefObject<Record<string, LevelMeterHandle>>, uid: string): void {
+    ref.current[uid]?.stop();
+    delete ref.current[uid];
+}
+
+function startTrackingLevel(
+    ref: React.MutableRefObject<Record<string, LevelMeterHandle>>,
+    uid: string,
+    stream: MediaStream,
+    onLevel: (level: number) => void,
+): void {
+    stopLevelMeter(ref, uid);
+    const handle = startLevelMeter(stream, onLevel);
+    if (handle) {
+        ref.current[uid] = handle;
+    }
+}

package/apps/meet/_MeetChrome.tsx

@@ -0,0 +1,30 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz. All rights reserved.
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/** The frame shared by every page in this app: the deployment's branding header/footer around a centered card, the
+ * same `booking-plugin`'s `_BookingChrome.tsx` shell-component pattern this plugin's Phase 2 spec calls for. Not a
+ * page itself: `_`-prefixed files in `apps/` aren't routed. */
+import React, { PropsWithChildren } from "react";
+import { Branding } from "@rapidmx/react-shared/branding/brandingApi.js";
+import { BrandingFooter, BrandingHeader } from "@rapidmx/web-client/shared/components/layout/BrandingChrome.js";
+
+export function MeetPageShell({ branding, children }: PropsWithChildren<{ branding: Branding | null }>) {
+    return (
+        <div className="min-h-screen flex flex-col">
+            <BrandingHeader branding={branding} />
+            <main className="flex-1 bg-surface-alt px-4 py-6 sm:py-10">{children}</main>
+            <BrandingFooter branding={branding} />
+        </div>
+    );
+}
+
+/** The white card the lobby (and the "meeting not found" state) is drawn in - the in-call view (`_CallView.tsx`)
+ * deliberately does NOT use this: a video call wants the full viewport, not a centered card. */
+export function MeetCard({ maxWidth = "max-w-2xl", children }: PropsWithChildren<{ maxWidth?: string }>) {
+    return (
+        <div className={`mx-auto w-full ${maxWidth} overflow-hidden rounded-lg border border-border bg-surface shadow-sm p-6 sm:p-10`}>
+            {children}
+        </div>
+    );
+}

package/apps/meet/_MeetLobby.tsx

@@ -0,0 +1,223 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz. All rights reserved.
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * The join/lobby step: name entry, device preview and pickers, mute/camera-off starting preferences, and the
+ * "Join" button. Per this plugin's Phase 2 spec, the name field is always editable - it is only ever *prefilled*
+ * when a session is genuinely known (see this component's `initialName` prop and `[token].tsx`'s own doc comment
+ * on why that never actually happens on this page today).
+ *
+ * Device support/permission errors (`navigator.mediaDevices` missing entirely - e.g. a non-HTTPS context in some
+ * browsers - a denied prompt, or no camera/microphone at all) are shown as a plain message rather than crashing;
+ * joining is still allowed with no local media in that case (a signaling-only participant - see this plugin's
+ * Phase 2 report's known-limitations note on why that participant's peer connections can carry no media at all
+ * without this design's simpler, renegotiation-free mesh needing to grow one).
+ */
+import React, { useEffect, useRef, useState } from "react";
+import Alert from "@rapidmx/react-shared/components/feedback/Alert.js";
+import Button from "@rapidmx/react-shared/components/buttons/Button.js";
+import FormField from "@rapidmx/react-shared/components/forms/FormField.js";
+import {
+    type DeviceLists,
+    type MediaAccessError,
+    isMediaDevicesSupported,
+    listDevices,
+    requestUserMedia,
+    setTracksEnabled,
+    stopStream,
+} from "../shared/media/deviceMedia.js";
+import type { PublicVideoMeeting } from "./_meetApi.js";
+
+const INPUT_CLASS =
+    "w-full text-base py-2.5 px-3.5 border border-border rounded-md bg-surface text-text focus:outline-none focus:border-primary";
+
+export interface JoinPreferences {
+    name: string;
+    micOn: boolean;
+    cameraOn: boolean;
+    /** Never `null` - an empty `MediaStream` when no device access was ever obtained, so the call view always has
+     * a stream to work with. */
+    stream: MediaStream;
+}
+
+export interface MeetLobbyProps {
+    meeting: PublicVideoMeeting;
+    /** Prefilled from `Profile.givenName` when a session was detected - still always editable. */
+    initialName?: string;
+    onJoin: (preferences: JoinPreferences) => void;
+}
+
+export default function MeetLobby({ meeting, initialName, onJoin }: MeetLobbyProps) {
+    const [name, setName] = useState(initialName ?? "");
+    const [micOn, setMicOn] = useState(true);
+    const [cameraOn, setCameraOn] = useState(true);
+    const [stream, setStream] = useState<MediaStream | null>(null);
+    const [devices, setDevices] = useState<DeviceLists>({ cameras: [], microphones: [] });
+    const [error, setError] = useState<MediaAccessError | null>(null);
+    const [supported, setSupported] = useState(true);
+    const videoRef = useRef<HTMLVideoElement>(null);
+
+    // Requests device access once, on mount - never re-requested just because `micOn`/`cameraOn` toggle (those
+    // toggles disable/enable the already-granted tracks instead, see `handleToggleMic`/`handleToggleCamera`).
+    useEffect(() => {
+        let cancelled = false;
+        if (!isMediaDevicesSupported()) {
+            setSupported(false);
+            return;
+        }
+        void requestUserMedia({ audio: true, video: true }).then(async (result) => {
+            if (cancelled) {
+                return;
+            }
+            if (!result.ok) {
+                setError(result.error);
+                return;
+            }
+            setStream(result.value);
+            const list = await listDevices();
+            if (!cancelled && list.ok) {
+                setDevices(list.value);
+            }
+        });
+        return () => {
+            cancelled = true;
+        };
+        // Intentionally empty deps - see this effect's own comment on why this never re-runs.
+    }, []);
+
+    // Releases the camera/microphone the moment this component unmounts (leaving the lobby without joining, or
+    // transitioning into the call - `[token].tsx` requests its own continuation of these tracks first).
+    useEffect(() => stopOnUnmount(stream), [stream]);
+
+    useEffect(() => {
+        if (videoRef.current) {
+            videoRef.current.srcObject = stream;
+        }
+    }, [stream]);
+
+    function handleToggleMic() {
+        setMicOn((prev) => {
+            const next = !prev;
+            setTracksEnabled(stream, "audio", next);
+            return next;
+        });
+    }
+
+    function handleToggleCamera() {
+        setCameraOn((prev) => {
+            const next = !prev;
+            setTracksEnabled(stream, "video", next);
+            return next;
+        });
+    }
+
+    async function handleSwitchDevice(kind: "audio" | "video", deviceId: string) {
+        const result = await requestUserMedia({ [kind]: { deviceId: { exact: deviceId } }, [kind === "audio" ? "video" : "audio"]: false });
+        if (!result.ok) {
+            setError(result.error);
+            return;
+        }
+        const [newTrack] = kind === "audio" ? result.value.getAudioTracks() : result.value.getVideoTracks();
+        // `stream` is always set by the time this can be called - the device picker this is wired to only ever
+        // renders once `devices` is populated, which itself only happens after an initial successful
+        // `requestUserMedia()` call has already set `stream` (see the mount effect above).
+        if (!newTrack) {
+            return;
+        }
+        const [oldTrack] = kind === "audio" ? stream!.getAudioTracks() : stream!.getVideoTracks();
+        if (oldTrack) {
+            stream!.removeTrack(oldTrack);
+            oldTrack.stop();
+        }
+        newTrack.enabled = kind === "audio" ? micOn : cameraOn;
+        stream!.addTrack(newTrack);
+        // Re-triggers the preview `<video>` binding and any downstream consumer without minting a whole new
+        // `MediaStream` object (the mesh's already-negotiated connections keep the same stream identity).
+        setStream((current) => current);
+    }
+
+    function handleJoin() {
+        onJoin({
+            name: name.trim(),
+            micOn,
+            cameraOn,
+            stream: stream ?? new MediaStream(),
+        });
+    }
+
+    return (
+        <div>
+            <h1 className="text-2xl font-bold tracking-tight">{meeting.title}</h1>
+            {meeting.hostDisplayName && <p className="text-sm text-text-muted mt-1">Hosted by {meeting.hostDisplayName}</p>}
+
+            <div className="mt-6 grid sm:grid-cols-2 gap-6">
+                <div>
+                    <div className="aspect-video bg-black/80 rounded-md overflow-hidden flex items-center justify-center">
+                        {stream && cameraOn ? (
+                            <video ref={videoRef} autoPlay playsInline muted className="w-full h-full object-cover" />
+                        ) : (
+                            <p className="text-white/70 text-sm">{cameraOn ? "No camera preview" : "Camera is off"}</p>
+                        )}
+                    </div>
+                    <div className="flex gap-2 mt-3">
+                        <Button type="button" variant="secondary" className="!w-auto" onClick={handleToggleMic} disabled={!stream}>
+                            {micOn ? "Mute mic" : "Unmute mic"}
+                        </Button>
+                        <Button type="button" variant="secondary" className="!w-auto" onClick={handleToggleCamera} disabled={!stream}>
+                            {cameraOn ? "Turn camera off" : "Turn camera on"}
+                        </Button>
+                    </div>
+                    {!supported && <Alert>This browser (or this page's connection) doesn't support camera/microphone access.</Alert>}
+                    {error && <Alert>{error.message}</Alert>}
+                    {devices.cameras.length > 1 && (
+                        <label className="block text-sm mt-3">
+                            Camera
+                            <select className={`${INPUT_CLASS} mt-1`} onChange={(e) => handleSwitchDevice("video", e.target.value)}>
+                                {devices.cameras.map((d) => (
+                                    <option key={d.deviceId} value={d.deviceId}>
+                                        {d.label || "Camera"}
+                                    </option>
+                                ))}
+                            </select>
+                        </label>
+                    )}
+                    {devices.microphones.length > 1 && (
+                        <label className="block text-sm mt-3">
+                            Microphone
+                            <select className={`${INPUT_CLASS} mt-1`} onChange={(e) => handleSwitchDevice("audio", e.target.value)}>
+                                {devices.microphones.map((d) => (
+                                    <option key={d.deviceId} value={d.deviceId}>
+                                        {d.label || "Microphone"}
+                                    </option>
+                                ))}
+                            </select>
+                        </label>
+                    )}
+                </div>
+
+                <div className="flex flex-col justify-center gap-3">
+                    <FormField label="Your name" htmlFor="meet-name">
+                        <input
+                            id="meet-name"
+                            type="text"
+                            className={INPUT_CLASS}
+                            value={name}
+                            onChange={(e) => setName(e.target.value)}
+                            placeholder="Enter your name"
+                        />
+                    </FormField>
+                    <Button type="button" className="!w-auto" disabled={!name.trim()} onClick={handleJoin}>
+                        Join meeting
+                    </Button>
+                </div>
+            </div>
+        </div>
+    );
+}
+
+/** `useEffect` cleanup helper for stopping a lobby preview stream on unmount/replacement - a named function
+ * (rather than an inline arrow) purely so its intent reads clearly at the call site. */
+function stopOnUnmount(stream: MediaStream | null): () => void {
+    return () => stopStream(stream);
+}

package/apps/meet/_ParticipantTile.tsx

@@ -0,0 +1,66 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz. All rights reserved.
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/** One participant's video tile - used by both the grid and the focused/thumbnail-strip layouts in `_CallView.tsx`.
+ * Renders a placeholder (the participant's initial) instead of a `<video>` element whenever there's no stream or
+ * their camera is off, rather than showing a black/frozen frame. */
+import React, { useEffect, useRef } from "react";
+
+export interface ParticipantTileProps {
+    name: string;
+    stream?: MediaStream | null;
+    /** The local participant's own tile must be `muted` (never plays back its own audio) - a real remote tile
+     * never sets this. */
+    isLocal?: boolean;
+    cameraOff?: boolean;
+    micMuted?: boolean;
+    /** Highlights this tile as the current presenter/focus. */
+    isFocused?: boolean;
+    onClick?: () => void;
+    className?: string;
+}
+
+function initialOf(name: string): string {
+    return (Array.from(name.trim())[0] ?? "?").toUpperCase();
+}
+
+export default function ParticipantTile({ name, stream, isLocal, cameraOff, micMuted, isFocused, onClick, className }: ParticipantTileProps) {
+    const videoRef = useRef<HTMLVideoElement>(null);
+    const showVideo = !!stream && !cameraOff;
+
+    useEffect(() => {
+        if (videoRef.current) {
+            /* v8 ignore next -- unreachable via real usage: the `<video>` element only ever renders at all when
+               `showVideo` (`!!stream && !cameraOff`) is true, so `stream` is always truthy whenever `videoRef.current`
+               is non-null here; the `?? null` exists purely to satisfy `srcObject`'s type, not for a real code path. */
+            videoRef.current.srcObject = stream ?? null;
+        }
+    }, [stream]);
+
+    return (
+        <div
+            className={`relative overflow-hidden rounded-md bg-black/80 flex items-center justify-center min-h-[90px] ${
+                isFocused ? "ring-2 ring-accent" : ""
+            } ${className ?? ""}`}
+            onClick={onClick}
+            role={onClick ? "button" : undefined}
+            tabIndex={onClick ? 0 : undefined}
+        >
+            {showVideo ? (
+                <video ref={videoRef} autoPlay playsInline muted={isLocal} className="w-full h-full object-cover" />
+            ) : (
+                <div className="w-14 h-14 rounded-full bg-primary text-white flex items-center justify-center text-xl font-bold" aria-hidden="true">
+                    {initialOf(name)}
+                </div>
+            )}
+            <div className="absolute bottom-1.5 left-1.5 flex items-center gap-1.5 px-2 py-0.5 rounded bg-black/60 text-white text-xs">
+                {micMuted && <span title="Muted">(muted)</span>}
+                <span>
+                    {name}
+                    {isLocal ? " (you)" : ""}
+                </span>
+            </div>
+        </div>
+    );
+}