@rapidmx/meet-plugin 0.1.0

package/dist/apps/settings-video-conferencing/_PersonalRoomCard.js

@@ -0,0 +1,77 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { useEffect, useState } from "react";
+import { ApiRequestError } from "@rapidmx/react-shared/util/api.js";
+import { createVideoMeeting, updateVideoMeeting } from "@rapidmx/react-shared/videoconf/videoMeetingsApi.js";
+import Alert from "@rapidmx/react-shared/components/feedback/Alert.js";
+import Button from "@rapidmx/react-shared/components/buttons/Button.js";
+const INPUT_CLASS = "w-full text-sm py-2.5 px-3 border border-border rounded-sm bg-surface text-text focus:outline-none focus:border-primary";
+/** The title a freshly created personal room starts with - editable afterward like any other meeting's title. */
+export const PERSONAL_ROOM_TITLE = "Personal Meeting Room";
+/**
+ * The "get and manage your own persistent public link" card - see this plugin's `.claude/NOTES.md` Phase 4 entry
+ * for why a personal room is simply the mailbox's own oldest non-cancelled `PUBLIC` `VideoMeeting`, not a distinct
+ * model concept. Offers to create one when there is none, and otherwise shows its (editable) title and its
+ * shareable link, exactly as `create()`/`findById()` compute it server-side.
+ */
+export default function PersonalRoomCard({ mailboxUid, room, onCreated, onRenamed }) {
+    const [titleDraft, setTitleDraft] = useState(room?.title ?? "");
+    const [creating, setCreating] = useState(false);
+    const [saving, setSaving] = useState(false);
+    const [copied, setCopied] = useState(false);
+    const [error, setError] = useState(null);
+    // Reset the draft whenever the identified room itself changes (freshly created, or renamed elsewhere) - not
+    // on every parent re-render, so an in-progress edit here survives an unrelated state update on the page (e.g.
+    // cancelling a different meeting in the list below).
+    useEffect(() => {
+        setTitleDraft(room?.title ?? "");
+    }, [room?.uid, room?.title]);
+    async function handleCreate() {
+        setCreating(true);
+        setError(null);
+        try {
+            const result = await createVideoMeeting({ mailboxUid, title: PERSONAL_ROOM_TITLE, visibility: "public" });
+            onCreated({ ...result.meeting, publicJoinUrl: result.publicJoinUrl });
+        }
+        catch (err) {
+            setError(err instanceof ApiRequestError ? err.message : "Could not create your personal room.");
+        }
+        finally {
+            setCreating(false);
+        }
+    }
+    async function handleRename(e) {
+        e.preventDefault();
+        const trimmed = titleDraft.trim();
+        if (!room || !trimmed || trimmed === room.title) {
+            return;
+        }
+        setSaving(true);
+        setError(null);
+        try {
+            const updated = await updateVideoMeeting(room.uid, { title: trimmed });
+            onRenamed(room.uid, updated.title);
+        }
+        catch (err) {
+            setError(err instanceof ApiRequestError ? err.message : "Could not rename your personal room.");
+        }
+        finally {
+            setSaving(false);
+        }
+    }
+    async function handleCopy(url) {
+        try {
+            await navigator.clipboard.writeText(url);
+            setError(null);
+            setCopied(true);
+            setTimeout(() => setCopied(false), 2000);
+        }
+        catch {
+            setError("Could not copy the link. Copy it by hand instead.");
+        }
+    }
+    return (_jsxs("section", { "aria-label": "Your personal room", className: "border border-border rounded-md p-5 mb-6", children: [_jsx("h2", { className: "text-sm font-bold", children: "Your personal room" }), _jsx("p", { className: "text-sm text-text-muted mb-3", children: "A permanent link you can share any time - anyone with it can join, no account needed on their end." }), error && _jsx(Alert, { children: error }), !room ? (_jsx(Button, { type: "button", className: "!w-auto", loading: creating, disabled: creating, onClick: handleCreate, children: "Create my personal room" })) : (_jsxs("div", { className: "flex flex-col gap-3", children: [_jsxs("form", { onSubmit: handleRename, className: "flex items-end gap-2", children: [_jsxs("label", { className: "flex-1 flex flex-col gap-1", children: [_jsx("span", { className: "text-xs text-text-muted", children: "Room name" }), _jsx("input", { type: "text", className: INPUT_CLASS, value: titleDraft, onChange: (e) => setTitleDraft(e.target.value) })] }), _jsx(Button, { type: "submit", variant: "secondary", className: "!w-auto shrink-0", loading: saving, disabled: saving || !titleDraft.trim() || titleDraft.trim() === room.title, children: "Save" })] }), room.publicJoinUrl ? (_jsxs("div", { className: "flex items-center gap-2", children: [_jsx("code", { className: "flex-1 text-xs bg-surface-alt border border-border rounded-sm py-2 px-3 overflow-x-auto whitespace-nowrap", children: room.publicJoinUrl }), _jsx(Button, { type: "button", variant: "secondary", className: "!w-auto shrink-0", onClick: () => handleCopy(room.publicJoinUrl), children: copied ? "Copied" : "Copy" })] })) : (_jsx("p", { className: "text-sm text-text-muted", children: "No public join page URL is configured for this deployment yet - ask an administrator to set one in the Video Conferencing plugin's settings before sharing this room." }))] }))] }));
+}

package/dist/apps/settings-video-conferencing/_layout.d.ts

@@ -0,0 +1,16 @@
+import React, { PropsWithChildren } from "react";
+import { Branding } from "@rapidmx/react-shared/branding/brandingApi.js";
+export interface LayoutProps {
+    /**
+     * Supplied by the server's `WwwRoute` `fetchProps()`, which every `www` plugin app's route extends. This file
+     * is a copy of `@rapidmx/web-client`'s `apps/www/_layout.tsx` (mirroring `booking-plugin`'s own
+     * `apps/settings-booking-types/_layout.tsx` exactly), since every app directory needs its own layout.
+     * `@rapidrest/react` spreads the same merged page props onto this layout as onto the page it wraps, so it
+     * renders correctly server-side on the very first byte of the response: no client-side flash from the stock
+     * defaults below, and a crawler reading the raw HTML sees the real branding too. `undefined` only on the
+     * framework's unwrapped `_500` fallback path, which doesn't receive props at all - falling back to the stock
+     * defaults there is acceptable.
+     */
+    branding?: Branding;
+}
+export default function Layout({ children, branding }: PropsWithChildren<LayoutProps>): React.JSX.Element;

package/dist/apps/settings-video-conferencing/_layout.js

@@ -0,0 +1,8 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { CUSTOM_STYLESHEET_LINK_ID } from "@rapidmx/react-shared/branding/useBranding.js";
+export default function Layout({ children, branding }) {
+    const title = branding?.title || branding?.companyName ? `${branding?.title || branding?.companyName}: Mail` : "RapidMX: Mail";
+    const iconHref = branding?.iconUrl || branding?.logoUrl || "/images/logo.svg";
+    const stylesheetHref = branding?.stylesheetUrl;
+    return (_jsxs("html", { lang: "en", children: [_jsxs("head", { children: [_jsx("meta", { charSet: "utf-8" }), _jsx("meta", { name: "viewport", content: "width=device-width, initial-scale=1" }), _jsx("title", { children: title }), _jsx("link", { rel: "icon", type: "image/svg+xml", href: iconHref }), _jsx("link", { rel: "alternate icon", href: "/favicon.ico" }), _jsx("link", { rel: "preconnect", href: "https://fonts.googleapis.com" }), _jsx("link", { rel: "preconnect", href: "https://fonts.gstatic.com", crossOrigin: "anonymous" }), _jsx("link", { rel: "stylesheet", href: "https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700;800&display=swap" }), stylesheetHref && _jsx("link", { rel: "stylesheet", href: stylesheetHref, id: CUSTOM_STYLESHEET_LINK_ID })] }), _jsx("body", { children: children })] }));
+}

package/dist/apps/settings-video-conferencing/index.d.ts

@@ -0,0 +1,16 @@
+import React from "react";
+import { VideoMeetingDetail } from "@rapidmx/react-shared/videoconf/videoMeetingsApi.js";
+import { SettingsShellProps } from "@rapidmx/web-client/shared/components/settings/layout/SettingsShell.js";
+export type SettingsVideoConferencingPageProps = Omit<SettingsShellProps, "active">;
+export default function SettingsVideoConferencingPage(props: SettingsVideoConferencingPageProps): React.JSX.Element;
+/**
+ * Picks a mailbox's "personal room" out of `listVideoMeetings()`'s results: the oldest still-active (non-cancelled)
+ * `PUBLIC` meeting. `BaseVideoMeetingRoute` has no field or route naming a "personal room" as a concept distinct
+ * from any other public meeting a mailbox happens to have - a public meeting IS just a `VideoMeeting` with
+ * `visibility: "public"` (see this plugin's `.claude/NOTES.md` Phase 4 entry for the full reasoning behind this
+ * convention, and why no backend addition was needed to support it). Oldest-first keeps the identification stable
+ * across reloads, regardless of when in the list a later public meeting (created some other way, e.g. directly
+ * through the API) happens to land; skipping a cancelled one means cancelling today's room and creating a new one
+ * always finds the fresh one on the next load, never a dead link.
+ */
+export declare function findPersonalRoom(meetings: VideoMeetingDetail[]): VideoMeetingDetail | undefined;

package/dist/apps/settings-video-conferencing/index.js

@@ -0,0 +1,92 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { useEffect, useState } from "react";
+import { ApiRequestError } from "@rapidmx/react-shared/util/api.js";
+import { listVideoMeetings, updateVideoMeeting } from "@rapidmx/react-shared/videoconf/videoMeetingsApi.js";
+import SettingsShell, { useSettingsShell } from "@rapidmx/web-client/shared/components/settings/layout/SettingsShell.js";
+import Alert from "@rapidmx/react-shared/components/feedback/Alert.js";
+import PersonalRoomCard from "./_PersonalRoomCard.js";
+/** However many of a mailbox's meetings this page ever needs to see at once - generous enough that a real user's
+ * whole history fits in one request (this is a personal settings page, not a paged archive), matching
+ * `SettingsShell`'s own `listMailboxes({ limit: 100 })` precedent for "large enough not to page in practice". */
+const LIST_LIMIT = 200;
+const STATUS_LABELS = {
+    scheduled: "Scheduled",
+    active: "In progress",
+    ended: "Ended",
+    cancelled: "Cancelled",
+};
+export default function SettingsVideoConferencingPage(props) {
+    return (_jsx(SettingsShell, { ...props, active: "video-conferencing", children: _jsx(VideoConferencingSettingsContent, {}) }));
+}
+/**
+ * Picks a mailbox's "personal room" out of `listVideoMeetings()`'s results: the oldest still-active (non-cancelled)
+ * `PUBLIC` meeting. `BaseVideoMeetingRoute` has no field or route naming a "personal room" as a concept distinct
+ * from any other public meeting a mailbox happens to have - a public meeting IS just a `VideoMeeting` with
+ * `visibility: "public"` (see this plugin's `.claude/NOTES.md` Phase 4 entry for the full reasoning behind this
+ * convention, and why no backend addition was needed to support it). Oldest-first keeps the identification stable
+ * across reloads, regardless of when in the list a later public meeting (created some other way, e.g. directly
+ * through the API) happens to land; skipping a cancelled one means cancelling today's room and creating a new one
+ * always finds the fresh one on the next load, never a dead link.
+ */
+export function findPersonalRoom(meetings) {
+    return meetings
+        .filter((m) => m.visibility === "public" && m.status !== "cancelled")
+        .sort((a, b) => new Date(a.dateCreated).getTime() - new Date(b.dateCreated).getTime())[0];
+}
+function VideoConferencingSettingsContent() {
+    const { mailboxUid } = useSettingsShell();
+    const [meetings, setMeetings] = useState([]);
+    const [loading, setLoading] = useState(true);
+    const [loadError, setLoadError] = useState(null);
+    const [copiedUid, setCopiedUid] = useState(null);
+    const [cancellingUid, setCancellingUid] = useState(null);
+    const [actionError, setActionError] = useState(null);
+    // `SettingsShell` only ever renders its children once `mailboxUid` has resolved - same established non-null
+    // pattern as `booking-plugin`'s own settings pages.
+    useEffect(() => {
+        setLoading(true);
+        setLoadError(null);
+        listVideoMeetings(mailboxUid, { limit: LIST_LIMIT })
+            .then(setMeetings)
+            .catch((err) => setLoadError(err instanceof ApiRequestError ? err.message : "Could not load your video meetings."))
+            .finally(() => setLoading(false));
+    }, [mailboxUid]);
+    const personalRoom = findPersonalRoom(meetings);
+    // Every other meeting worth showing here: any other public meeting, or a private one with a linked calendar
+    // event (the calendar compose hook's own meetings - Phase 3). A private, calendar-less meeting is an artifact
+    // of this plugin's own API used directly (e.g. testing), not something a real user created through this page
+    // or a calendar invite, so it's left out. The personal room itself is surfaced above instead of repeated here.
+    const otherMeetings = meetings
+        .filter((m) => m.uid !== personalRoom?.uid && (m.visibility === "public" || !!m.calendarEventUid))
+        .sort((a, b) => new Date(b.dateCreated).getTime() - new Date(a.dateCreated).getTime());
+    async function handleCopy(url, uid) {
+        try {
+            await navigator.clipboard.writeText(url);
+            setActionError(null);
+            setCopiedUid(uid);
+            setTimeout(() => setCopiedUid((current) => (current === uid ? null : current)), 2000);
+        }
+        catch {
+            setActionError("Could not copy the link. Copy it by hand instead.");
+        }
+    }
+    async function handleCancel(uid) {
+        setCancellingUid(uid);
+        setActionError(null);
+        try {
+            const updated = await updateVideoMeeting(uid, { status: "cancelled" });
+            setMeetings((current) => current.map((m) => (m.uid === uid ? { ...m, status: updated.status } : m)));
+        }
+        catch (err) {
+            setActionError(err instanceof ApiRequestError ? err.message : "Could not cancel this meeting.");
+        }
+        finally {
+            setCancellingUid(null);
+        }
+    }
+    return (_jsx("div", { className: "flex-1 min-w-0 overflow-y-auto p-6", children: _jsxs("div", { className: "max-w-4xl", children: [_jsx("h1", { className: "text-lg font-bold tracking-tight mb-1", children: "Video Conferencing" }), _jsx("p", { className: "text-sm text-text-muted mb-5", children: "Your personal meeting room, and every video meeting created for you - from a calendar invite or directly here." }), loadError && _jsx(Alert, { children: loadError }), actionError && _jsx(Alert, { children: actionError }), loading ? (_jsx("p", { className: "text-sm text-text-muted", children: "Loading\u2026" })) : (_jsxs(_Fragment, { children: [_jsx(PersonalRoomCard, { mailboxUid: mailboxUid, room: personalRoom, onCreated: (meeting) => setMeetings((current) => [meeting, ...current]), onRenamed: (uid, title) => setMeetings((current) => current.map((m) => (m.uid === uid ? { ...m, title } : m))) }), _jsx("h2", { className: "text-sm font-bold mb-2", children: "Meetings" }), otherMeetings.length === 0 ? (_jsx("p", { className: "text-sm text-text-muted", children: "No other meetings yet." })) : (_jsx("div", { className: "overflow-x-auto", children: _jsxs("table", { className: "w-full text-sm border-collapse", children: [_jsx("thead", { children: _jsx("tr", { children: ["Title", "Visibility", "Status", "Created", ""].map((h) => (_jsx("th", { className: "text-left text-xs uppercase tracking-wide text-text-muted py-2 px-2.5 border-b border-border", children: h }, h))) }) }), _jsx("tbody", { children: otherMeetings.map((meeting) => (_jsxs("tr", { children: [_jsx("td", { className: "py-2.5 px-2.5 border-b border-border", children: meeting.title }), _jsx("td", { className: "py-2.5 px-2.5 border-b border-border capitalize", children: meeting.visibility }), _jsx("td", { className: "py-2.5 px-2.5 border-b border-border", children: STATUS_LABELS[meeting.status] ?? meeting.status }), _jsx("td", { className: "py-2.5 px-2.5 border-b border-border whitespace-nowrap", children: new Date(meeting.dateCreated).toLocaleString() }), _jsxs("td", { className: "py-2.5 px-2.5 border-b border-border text-right whitespace-nowrap", children: [meeting.visibility === "public" && meeting.publicJoinUrl && (_jsx("button", { type: "button", "aria-label": `Copy link to ${meeting.title}`, className: "text-primary-dark hover:underline font-medium mr-4", onClick: () => handleCopy(meeting.publicJoinUrl, meeting.uid), children: copiedUid === meeting.uid ? "Copied" : "Copy link" })), meeting.status === "scheduled" && (_jsx("button", { type: "button", "aria-label": `Cancel ${meeting.title}`, className: "text-danger hover:underline font-medium disabled:opacity-55", disabled: cancellingUid === meeting.uid, onClick: () => handleCancel(meeting.uid), children: cancellingUid === meeting.uid ? "Cancelling…" : "Cancel" }))] })] }, meeting.uid))) })] }) }))] }))] }) }));
+}

package/dist/apps/shared/media/activeSpeaker.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Pure active-speaker selection logic, decoupled from `levelMeter.ts`'s `AnalyserNode` wiring so it can be unit
+ * tested with plain numbers - no `AudioContext`/DOM at all. A simple volume-threshold heuristic, as this plugin's
+ * Phase 2 `.claude/NOTES.md` entry calls for ("this doesn't need to be sophisticated"): the loudest participant
+ * currently above `threshold` becomes the pick; below threshold, the previous pick is kept rather than falling
+ * back to nobody, so the focused tile doesn't flicker to a blank state during a brief pause in speech.
+ */
+/** 0-100 (`levelMeter.ts`'s own output range). Chosen empirically as "clearly speaking" vs. room noise/silence -
+ * not derived from any spec, and the easiest constant to retune later. */
+export declare const DEFAULT_ACTIVE_SPEAKER_THRESHOLD = 12;
+/**
+ * Picks who should be auto-focused, given every remote participant's current audio level (local participant
+ * excluded by the caller - see `_CallView.tsx`, which never lets "yourself" be the auto-detected speaker).
+ *
+ * @param levels uid -> level (0-100), one entry per participant currently being measured.
+ * @param current The currently auto-focused uid, if any - kept when no one is clearly above `threshold`, and used
+ * to break an exact tie (staying on the current speaker rather than jittering to another equally-loud one).
+ * @param threshold See `DEFAULT_ACTIVE_SPEAKER_THRESHOLD`.
+ */
+export declare function pickActiveSpeaker(levels: Readonly<Record<string, number>>, current: string | undefined, threshold?: number): string | undefined;

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

@@ -0,0 +1,39 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz. All rights reserved.
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Pure active-speaker selection logic, decoupled from `levelMeter.ts`'s `AnalyserNode` wiring so it can be unit
+ * tested with plain numbers - no `AudioContext`/DOM at all. A simple volume-threshold heuristic, as this plugin's
+ * Phase 2 `.claude/NOTES.md` entry calls for ("this doesn't need to be sophisticated"): the loudest participant
+ * currently above `threshold` becomes the pick; below threshold, the previous pick is kept rather than falling
+ * back to nobody, so the focused tile doesn't flicker to a blank state during a brief pause in speech.
+ */
+/** 0-100 (`levelMeter.ts`'s own output range). Chosen empirically as "clearly speaking" vs. room noise/silence -
+ * not derived from any spec, and the easiest constant to retune later. */
+export const DEFAULT_ACTIVE_SPEAKER_THRESHOLD = 12;
+/**
+ * Picks who should be auto-focused, given every remote participant's current audio level (local participant
+ * excluded by the caller - see `_CallView.tsx`, which never lets "yourself" be the auto-detected speaker).
+ *
+ * @param levels uid -> level (0-100), one entry per participant currently being measured.
+ * @param current The currently auto-focused uid, if any - kept when no one is clearly above `threshold`, and used
+ * to break an exact tie (staying on the current speaker rather than jittering to another equally-loud one).
+ * @param threshold See `DEFAULT_ACTIVE_SPEAKER_THRESHOLD`.
+ */
+export function pickActiveSpeaker(levels, current, threshold = DEFAULT_ACTIVE_SPEAKER_THRESHOLD) {
+    let best;
+    let bestLevel = threshold;
+    for (const [uid, level] of Object.entries(levels)) {
+        if (level > bestLevel || (level === bestLevel && uid === current)) {
+            best = uid;
+            bestLevel = level;
+        }
+    }
+    if (best) {
+        return best;
+    }
+    // Nobody is clearly above threshold: keep the current pick only if they're still a measured participant
+    // (they may have left), otherwise there's no reasonable pick at all.
+    return current && current in levels ? current : undefined;
+}

package/dist/apps/shared/media/deviceMedia.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Thin, dependency-injectable wrappers over `navigator.mediaDevices` - `enumerateDevices()`/`getUserMedia()`/
+ * `getDisplayMedia()` - used by both the join/lobby page's device preview and the in-call view's mute/camera/share
+ * controls (see this plugin's Phase 2 `.claude/NOTES.md` entry). Kept under `src/` rather than `apps/meet/` because
+ * it is pure logic with no JSX, reused by more than one page/component.
+ *
+ * Every function accepts an optional `MediaDevicesLike` so a test can inject a fake without a real browser; the
+ * real `navigator.mediaDevices` is used by default, resolved lazily inside each function (never at module scope)
+ * so importing this module is safe during this plugin's page SSR, where no browser globals exist at all.
+ *
+ * Nothing here ever throws: every browser-API call is wrapped in `classifyMediaError()` and returned as a
+ * discriminated `{ ok: false, error }` result, so a caller (a React component) never needs a try/catch of its own.
+ */
+/** The subset of `MediaDevices` this module calls - what a test's fake implements. */
+export interface MediaDevicesLike {
+    enumerateDevices?: () => Promise<MediaDeviceInfo[]>;
+    getUserMedia?: (constraints: MediaStreamConstraints) => Promise<MediaStream>;
+    getDisplayMedia?: (constraints?: DisplayMediaStreamOptions) => Promise<MediaStream>;
+}
+export type MediaAccessErrorKind = "unsupported" | "permission-denied" | "not-found" | "unknown";
+export interface MediaAccessError {
+    kind: MediaAccessErrorKind;
+    /** Already a complete, user-facing sentence - a caller shows this directly, no further mapping needed. */
+    message: string;
+}
+export type MediaResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: MediaAccessError;
+};
+/** `navigator.mediaDevices`, or `undefined` where there is none (SSR, a non-HTTPS/insecure context in some
+ * browsers, or a very old browser) - resolved lazily so this is safe to call from module code executed under SSR,
+ * where `navigator` itself does not exist. */
+export declare function defaultMediaDevices(): MediaDevicesLike | undefined;
+/** Whether `devices.getUserMedia` is actually callable - the one capability every caller here needs at minimum. */
+export declare function isMediaDevicesSupported(devices?: MediaDevicesLike | undefined): boolean;
+/** Maps a `getUserMedia()`/`getDisplayMedia()`/`enumerateDevices()` rejection to a friendly, already-complete
+ * message - the handful of `DOMException` names a browser actually raises for these calls, matched by name rather
+ * than `instanceof DOMException` (a test's fake rejection need not be a real `DOMException`). */
+export declare function classifyMediaError(err: unknown): MediaAccessError;
+export interface DeviceLists {
+    cameras: MediaDeviceInfo[];
+    microphones: MediaDeviceInfo[];
+}
+/**
+ * Lists the available camera/microphone devices. Labels are only populated once permission has been granted (a
+ * browser rule, not something this function can work around) - a caller wanting labeled devices should call
+ * `requestUserMedia()` first, then this again.
+ */
+export declare function listDevices(devices?: MediaDevicesLike | undefined): Promise<MediaResult<DeviceLists>>;
+/** Requests camera/microphone access. `constraints` lets the caller ask for a specific `deviceId` (device
+ * switching) or disable a track kind entirely (e.g. `{ video: false, audio: true }` for a mic-only preview). */
+export declare function requestUserMedia(constraints: MediaStreamConstraints, devices?: MediaDevicesLike | undefined): Promise<MediaResult<MediaStream>>;
+/** Requests a screen/window/tab share via the browser's own picker. Audio is never requested (this design shares
+ * camera-equivalent video only - see this plugin's Phase 2 `.claude/NOTES.md` entry on presentation mode). */
+export declare function requestDisplayMedia(devices?: MediaDevicesLike | undefined): Promise<MediaResult<MediaStream>>;
+/** Stops every track of `stream` (releasing the camera/microphone/screen-share indicator) - tolerates `undefined`/
+ * `null` so a caller never needs its own guard. */
+export declare function stopStream(stream: MediaStream | undefined | null): void;
+/** Enables/disables every track of `stream` matching `kind`, for the mute/camera-off toggles - tracks are kept
+ * (not stopped/removed), matching every mainstream video-call app's "mute" behavior: instant, reversible, and
+ * without re-requesting `getUserMedia()` or renegotiating the `RTCPeerConnection`. */
+export declare function setTracksEnabled(stream: MediaStream | undefined | null, kind: "audio" | "video", enabled: boolean): void;

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

@@ -0,0 +1,110 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz. All rights reserved.
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Thin, dependency-injectable wrappers over `navigator.mediaDevices` - `enumerateDevices()`/`getUserMedia()`/
+ * `getDisplayMedia()` - used by both the join/lobby page's device preview and the in-call view's mute/camera/share
+ * controls (see this plugin's Phase 2 `.claude/NOTES.md` entry). Kept under `src/` rather than `apps/meet/` because
+ * it is pure logic with no JSX, reused by more than one page/component.
+ *
+ * Every function accepts an optional `MediaDevicesLike` so a test can inject a fake without a real browser; the
+ * real `navigator.mediaDevices` is used by default, resolved lazily inside each function (never at module scope)
+ * so importing this module is safe during this plugin's page SSR, where no browser globals exist at all.
+ *
+ * Nothing here ever throws: every browser-API call is wrapped in `classifyMediaError()` and returned as a
+ * discriminated `{ ok: false, error }` result, so a caller (a React component) never needs a try/catch of its own.
+ */
+/** `navigator.mediaDevices`, or `undefined` where there is none (SSR, a non-HTTPS/insecure context in some
+ * browsers, or a very old browser) - resolved lazily so this is safe to call from module code executed under SSR,
+ * where `navigator` itself does not exist. */
+export function defaultMediaDevices() {
+    return typeof navigator === "undefined" ? undefined : (navigator.mediaDevices);
+}
+/** Whether `devices.getUserMedia` is actually callable - the one capability every caller here needs at minimum. */
+export function isMediaDevicesSupported(devices = defaultMediaDevices()) {
+    return typeof devices?.getUserMedia === "function";
+}
+const UNSUPPORTED_ERROR = {
+    kind: "unsupported",
+    message: "This browser (or this page's connection) doesn't support camera/microphone access. Try a modern browser over HTTPS.",
+};
+/** Maps a `getUserMedia()`/`getDisplayMedia()`/`enumerateDevices()` rejection to a friendly, already-complete
+ * message - the handful of `DOMException` names a browser actually raises for these calls, matched by name rather
+ * than `instanceof DOMException` (a test's fake rejection need not be a real `DOMException`). */
+export function classifyMediaError(err) {
+    const name = err instanceof Error ? err.name : "";
+    switch (name) {
+        case "NotAllowedError":
+        case "SecurityError":
+            return { kind: "permission-denied", message: "Camera/microphone access was denied. Allow access in your browser and try again." };
+        case "NotFoundError":
+        case "OverconstrainedError":
+            return { kind: "not-found", message: "No camera or microphone was found on this device." };
+        default:
+            return { kind: "unknown", message: "Could not access your camera or microphone. Please try again." };
+    }
+}
+/**
+ * Lists the available camera/microphone devices. Labels are only populated once permission has been granted (a
+ * browser rule, not something this function can work around) - a caller wanting labeled devices should call
+ * `requestUserMedia()` first, then this again.
+ */
+export async function listDevices(devices = defaultMediaDevices()) {
+    if (!devices?.enumerateDevices) {
+        return { ok: false, error: UNSUPPORTED_ERROR };
+    }
+    try {
+        const all = await devices.enumerateDevices();
+        return {
+            ok: true,
+            value: {
+                cameras: all.filter((d) => d.kind === "videoinput"),
+                microphones: all.filter((d) => d.kind === "audioinput"),
+            },
+        };
+    }
+    catch (err) {
+        return { ok: false, error: classifyMediaError(err) };
+    }
+}
+/** Requests camera/microphone access. `constraints` lets the caller ask for a specific `deviceId` (device
+ * switching) or disable a track kind entirely (e.g. `{ video: false, audio: true }` for a mic-only preview). */
+export async function requestUserMedia(constraints, devices = defaultMediaDevices()) {
+    if (!devices?.getUserMedia) {
+        return { ok: false, error: UNSUPPORTED_ERROR };
+    }
+    try {
+        return { ok: true, value: await devices.getUserMedia(constraints) };
+    }
+    catch (err) {
+        return { ok: false, error: classifyMediaError(err) };
+    }
+}
+/** Requests a screen/window/tab share via the browser's own picker. Audio is never requested (this design shares
+ * camera-equivalent video only - see this plugin's Phase 2 `.claude/NOTES.md` entry on presentation mode). */
+export async function requestDisplayMedia(devices = defaultMediaDevices()) {
+    if (!devices?.getDisplayMedia) {
+        return { ok: false, error: UNSUPPORTED_ERROR };
+    }
+    try {
+        return { ok: true, value: await devices.getDisplayMedia({ video: true, audio: false }) };
+    }
+    catch (err) {
+        return { ok: false, error: classifyMediaError(err) };
+    }
+}
+/** Stops every track of `stream` (releasing the camera/microphone/screen-share indicator) - tolerates `undefined`/
+ * `null` so a caller never needs its own guard. */
+export function stopStream(stream) {
+    stream?.getTracks().forEach((track) => track.stop());
+}
+/** Enables/disables every track of `stream` matching `kind`, for the mute/camera-off toggles - tracks are kept
+ * (not stopped/removed), matching every mainstream video-call app's "mute" behavior: instant, reversible, and
+ * without re-requesting `getUserMedia()` or renegotiating the `RTCPeerConnection`. */
+export function setTracksEnabled(stream, kind, enabled) {
+    const tracks = kind === "audio" ? (stream?.getAudioTracks() ?? []) : (stream?.getVideoTracks() ?? []);
+    for (const track of tracks) {
+        track.enabled = enabled;
+    }
+}

package/dist/apps/shared/media/levelMeter.d.ts

@@ -0,0 +1,40 @@
+/**
+ * `Web Audio API` `AnalyserNode` wiring for a per-track volume meter - the browser-glue half of active-speaker
+ * detection; `activeSpeaker.ts` holds the actual selection logic as plain, DOM-free functions over the numbers
+ * this module produces. Every browser constructor is behind an injectable factory, so a test never needs a real
+ * `AudioContext`.
+ */
+/** The subset of `AnalyserNode` this module uses - what a test's fake implements. */
+export interface AnalyserNodeLike {
+    fftSize: number;
+    getByteTimeDomainData(array: Uint8Array): void;
+}
+/** The subset of `AudioContext` this module uses. */
+export interface AudioContextLike {
+    createAnalyser(): AnalyserNodeLike;
+    createMediaStreamSource(stream: MediaStream): {
+        connect(node: AnalyserNodeLike): void;
+    };
+    close(): Promise<void> | void;
+}
+export type AudioContextFactory = () => AudioContextLike;
+/** The real `AudioContext`/`webkitAudioContext` constructor, or `undefined` where there is none (SSR, a browser
+ * with no Web Audio support). Resolved lazily - never at module scope - so importing this module is SSR-safe. */
+export declare function defaultAudioContextFactory(): AudioContextFactory | undefined;
+export interface LevelMeterHandle {
+    /** Stops polling and releases the `AudioContext` - idempotent. */
+    stop(): void;
+}
+/** How often the meter samples and reports a level, in milliseconds. Fast enough to feel responsive for
+ * active-speaker switching without generating excessive React state churn. */
+export declare const DEFAULT_LEVEL_METER_INTERVAL_MS = 200;
+/**
+ * Starts reporting `stream`'s audio level (0-100, a simple mean-absolute-deviation-from-silence over each sample
+ * window - not true RMS/dBFS, deliberately: this is a threshold heuristic, not a metering instrument) to `onLevel`
+ * every `intervalMs`. Returns `undefined` (nothing started) when there is no usable `AudioContext` or `stream` has
+ * no audio track to measure - a caller treats that the same as "can't tell, don't auto-switch on this stream".
+ */
+export declare function startLevelMeter(stream: MediaStream, onLevel: (level: number) => void, options?: {
+    factory?: AudioContextFactory;
+    intervalMs?: number;
+}): LevelMeterHandle | undefined;

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

@@ -0,0 +1,61 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz. All rights reserved.
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * `Web Audio API` `AnalyserNode` wiring for a per-track volume meter - the browser-glue half of active-speaker
+ * detection; `activeSpeaker.ts` holds the actual selection logic as plain, DOM-free functions over the numbers
+ * this module produces. Every browser constructor is behind an injectable factory, so a test never needs a real
+ * `AudioContext`.
+ */
+/** The real `AudioContext`/`webkitAudioContext` constructor, or `undefined` where there is none (SSR, a browser
+ * with no Web Audio support). Resolved lazily - never at module scope - so importing this module is SSR-safe. */
+export function defaultAudioContextFactory() {
+    if (typeof window === "undefined") {
+        return undefined;
+    }
+    const Ctor = window.AudioContext ??
+        window.webkitAudioContext;
+    return Ctor ? () => new Ctor() : undefined;
+}
+/** How often the meter samples and reports a level, in milliseconds. Fast enough to feel responsive for
+ * active-speaker switching without generating excessive React state churn. */
+export const DEFAULT_LEVEL_METER_INTERVAL_MS = 200;
+/**
+ * Starts reporting `stream`'s audio level (0-100, a simple mean-absolute-deviation-from-silence over each sample
+ * window - not true RMS/dBFS, deliberately: this is a threshold heuristic, not a metering instrument) to `onLevel`
+ * every `intervalMs`. Returns `undefined` (nothing started) when there is no usable `AudioContext` or `stream` has
+ * no audio track to measure - a caller treats that the same as "can't tell, don't auto-switch on this stream".
+ */
+export function startLevelMeter(stream, onLevel, options = {}) {
+    const factory = options.factory ?? defaultAudioContextFactory();
+    if (!factory || stream.getAudioTracks().length === 0) {
+        return undefined;
+    }
+    const context = factory();
+    const analyser = context.createAnalyser();
+    analyser.fftSize = 512;
+    context.createMediaStreamSource(stream).connect(analyser);
+    const buffer = new Uint8Array(analyser.fftSize);
+    const timer = setInterval(() => {
+        analyser.getByteTimeDomainData(buffer);
+        let sum = 0;
+        for (let i = 0; i < buffer.length; i++) {
+            sum += Math.abs(buffer[i] - 128);
+        }
+        // The maximum possible mean deviation from the 128 midpoint is 128 (a square wave at full scale) -
+        // normalized to a friendlier 0-100 range, matching `activeSpeaker.ts`'s `DEFAULT_ACTIVE_SPEAKER_THRESHOLD`.
+        onLevel(Math.min(100, (sum / buffer.length / 128) * 100));
+    }, options.intervalMs ?? DEFAULT_LEVEL_METER_INTERVAL_MS);
+    let stopped = false;
+    return {
+        stop: () => {
+            if (stopped) {
+                return;
+            }
+            stopped = true;
+            clearInterval(timer);
+            void context.close();
+        },
+    };
+}