// Owns the Chime SDK and its observers. NO React - this is what makes the media lifecycle testable
// without jsdom, lets surfaces be pure tile-binding consumers, and makes "the call survives
// navigation" structurally true rather than carefully maintained.
import { loadChimeSdk } from './chimeLoader';
import type { ChimeJoinInfo } from './videoContract';
import { classifyMediaFailure, type MediaFailureReason, type MediaKind } from './mediaFailure';
import { deviceChoices, type DeviceChoice } from './deviceChoices';

/** Task 9 - WHO is on the roster, not just how many. One entry per remote attendee, carrying the
 * SDK's `externalUserId` (its presence callback's THIRD argument) alongside the Chime attendee id it
 * has always tracked. Per the video contract, `externalUserId` IS the participant's stable FHIR
 * reference (`Practitioner/abc`, `Patient/xyz`) - this class only CARRIES it; resolving it to a name
 * or a neutral fallback (and never rendering it raw) is `MeetingParticipantsPanel`'s job, not this
 * one's. `undefined` when the SDK did not supply one for that attendee - the participant is still
 * tracked, just unresolvable beyond the panel's own "Someone" fallback. */
export interface RemoteMeetingParticipant {
    attendeeId: string;
    externalUserId?: string;
}

export interface CallSessionState {
    /** Every tile on screen, the local self-view included. This is the RENDER list. */
    tiles: number[];
    /** The tiles belonging to SOMEBODY ELSE - a strict subset of `tiles`. This is a LAYOUT fact and
 * nothing more.
 *
 * IT IS NOT A PRESENCE SIGNAL, and reading it as one was the Task 9 review's first defect.
 * A patient may join AUDIO-ONLY (this class deliberately degrades rather than refusing a visit
 * with no camera), in which case no remote video tile is ever created; and a patient may turn
 * their camera off mid-visit with a button we ship, which empties this list again. Either way
 * they are IN THE ROOM and talking. Use `remoteAttendees`. */
    remoteTiles: number[];
    /** - attendee id the numeric tile carrying that attendee's video. The link Chime
 * hands us on every tile update (`VideoTileState.boundAttendeeId`) and which this class used to
 * discard, leaving the main stage unable to feature the person who is actually speaking.
 * An absent key means that attendee has NO video tile - which is the camera-off case, not an error. */
    tilesByAttendee: Record<string, number>;
    /** EVERYONE ELSE IN THE MEETING, by Chime attendee id - the truthful "is anybody here yet"
 * signal, and the one "waiting for the patient" is derived from.
 *
 * The ring protocol is gone (Spencer, 2026-08-01): a host who starts a visit is `active` and
 * simply ALONE, so "waiting" is not a phase - it is an EMPTY ROOM in a live meeting. This comes
 * from `realtimeSubscribeToAttendeeIdPresence`, which fires for every attendee already present
 * when you join and then on every arrival and departure, with the local attendee EXCLUDED (see
 * `subscribeToPresence`).
 *
 * Task 9: now DERIVED from `remoteParticipants` below (`.map(p => p.attendeeId)`), kept only so
 * no existing consumer of the plain id list has to change. `remoteParticipants` is the one source
 * of truth. */
    remoteAttendees: string[];
    /** Task 9 - see `RemoteMeetingParticipant`. Same roster as `remoteAttendees`, one entry per
 * attendee, carrying `externalUserId` alongside the attendee id. */
    remoteParticipants: RemoteMeetingParticipant[];
    muted: boolean;
    /** Whether the local camera is CURRENTLY published. Never true without `cameraAvailable`:
 * claiming a camera we do not have inverts the toggle and shows everyone else a black tile. */
    cameraOn: boolean;
    /** Whether a camera was actually acquired for this meeting (present, permitted, not in use by
 * another app). False audio-only. */
    cameraAvailable: boolean;
    /** Whether a microphone was actually acquired. False this participant can hear but not speak. */
    micAvailable: boolean;
    /** - WHY it is unavailable. Absent when the device works.
 * Four distinct causes used to render one sentence telling the user to change a browser
 * permission; two of them sent people to a setting that was not the problem, and on an insecure
 * origin the browser had already refused to ask, so that setting was greyed out. */
    micFailure?: MediaFailureReason;
    cameraFailure?: MediaFailureReason;
    /** - WHICH device this visit is currently using, so the picker shows the live choice
 * rather than guessing at it. Absent until one has been selected. */
    micDeviceId?: string;
    cameraDeviceId?: string;
    /** THE SILENT-CALL FLAG. Chime mixes EVERY remote participant into one dedicated <audio>
 * element; false means remote audio has nowhere to play and this participant hears NOBODY,
 * while the call itself looks perfectly healthy. */
    audioOutputBound: boolean;
    /** HAS ANYBODY ELSE EVER BEEN IN THIS MEETING? Found by the first real browser call (Spencer,
 * 2026-08-02): the patient LEFT and the practitioner was told nothing at all, because "nobody has
 * arrived yet" and "they hung up" are the SAME observable state - empty roster, no remote tiles.
 * This flag is the only thing that separates them. Latches true for the life of the meeting; the
 * reset lives in `idleState()`, so one visit's departure can never colour the next one. */
    everRemote: boolean;
    /** Task 3 - WHO is talking, so a narrow-window layout can collapse the grid to a single tile
 * without guessing which one. Resolves as: the most-recent REMOTE SDK-reported speaker else the
 * first entry of `remoteParticipants` else `undefined`.
 *
 * - NEVER the local participant. "The last attendee who spoke and is not me": Chime's
 * detector reports the local attendee too, and featuring them on a collapsed main stage would put
 * the viewer's own face where their self-view inset already shows it. Guarded at the WRITE site
 * (`subscribeToActiveSpeaker`), not here - see that method for why.
 *
 * NEVER an empty tile. "Nobody is speaking" and "the video is broken" must not render
 * alike - two of the six defects the first real browser calls found were exactly that shape (a
 * self-view tile that never arrived, and camera-off reading as "waiting"). `emit()` derives this
 * from `this.state.activeSpeakerAttendeeId` - written ONLY when the SDK reports an actual REMOTE
 * speaker, so silence is a no-op, never a clear - falling back to `remoteParticipants[0]`,
 * Task 9's one source of truth for the roster, rather than a second synchronized list. See
 * `subscribeToActiveSpeaker`.
 *
 * MAY NAME AN ATTENDEE WHO HAS LEFT. "Never a clear" above means exactly that: departure is not
 * a write, so a stale id can outlive the person it names indefinitely. No consumer today is
 * harmed by that (`VideoTileGrid`'s `speaker` layout re-validates against `remoteParticipants`
 * before trusting it - fix round 1), but nothing here stops a future consumer from
 * reading this field's definedness as presence, which is exactly the bug that fix closed. */
    activeSpeakerAttendeeId: string | undefined;
    /** Remote attendees whose microphone carries speech right now. The active speaker is held through silence; this is not. */
    speakingAttendeeIds: string[];
}

/** A fresh idle state. A function, not a shared constant: `setMuted`/`setCameraOn` mutate
 * `this.state` in place, and a shared literal would carry one call's mute into the next. */
const idleState = (): CallSessionState => ({
    tiles: [],
    remoteTiles: [],
    tilesByAttendee: {},
    remoteAttendees: [],
    remoteParticipants: [],
    muted: false,
    cameraOn: false,
    cameraAvailable: false,
    micAvailable: false,
    audioOutputBound: false,
    everRemote: false,
    activeSpeakerAttendeeId: undefined,
    speakingAttendeeIds: [],
});

interface AcquiredMedia {
    micAvailable: boolean;
    cameraAvailable: boolean;
    /** - WHY it is unavailable, so the surface can say something true. Absent when it works. */
    micFailure?: MediaFailureReason;
    cameraFailure?: MediaFailureReason;
    /** Which device was actually chosen, so the picker shows the live selection rather than guessing. */
    micDeviceId?: string;
    cameraDeviceId?: string;
    audioOutputBound: boolean;
}

/** Picks the first device of a kind and selects it on the facade, reporting whether one was
 * actually acquired.
 *
 * NEVER THROWS. A denied camera, a denied mic, a device already held by another app, or simply
 * no such hardware must not fail the join: a telehealth visit that refuses to connect because the
 * laptop has no webcam is a worse outcome than an audio-only one. An EMPTY LIST is not an error
 * either - it means the device does not exist. */
async function selectFirstInput(
    list: () => Promise<Array<{ deviceId?: string }> | undefined>,
    select: (deviceId: string) => Promise<unknown>,
    kind: MediaKind,
    isCurrent: () => boolean = () => true,
): Promise<{ available: boolean; failure?: MediaFailureReason; deviceId?: string }> {
    // - IT NOW REPORTS *WHY*, NOT JUST *WHETHER*. This function's own doc already listed
    // four causes it swallows - denied, busy, absent, no hardware - and every one of them rendered the
    // same sentence telling the user to change a browser permission. Two of the four sent them to a
    // setting that was not the problem, and on an insecure origin (2026-08-15) the browser had already
    // refused to even ask, so the control they were pointed at was greyed out.
    // It still NEVER THROWS. A telehealth visit that refuses to connect because a laptop has no
    // webcam is a worse outcome than an audio-only one; the reason is for the copy, not for a refusal.
    const secureContext = typeof window === 'undefined' ? true : window.isSecureContext !== false;
    try {
        const devices = await list();
        // A join retired while the list was read selects nothing: selecting would acquire the device.
        if (!isCurrent()) return { available: false };
        const deviceId = devices?.[0]?.deviceId;
        if (!deviceId) {
            const failure = classifyMediaFailure({ secureContext, deviceCount: 0 });
            console.warn(`[video] no ${kind} on this device (${failure}) — joining without one`);
            return { available: false, failure };
        }
        await select(deviceId);
        // - reported so the picker can show what the visit is ACTUALLY using. Without it the
        // menu would have to guess, and its best guess is `devices[0]` - the very assumption this card
        // exists to remove.
        return { available: true, deviceId };
    } catch (e) {
        const failure = classifyMediaFailure({ secureContext, error: e }) ?? 'unknown';
        console.warn(`[video] could not use the ${kind} (${failure}) — joining without one`, e);
        return { available: false, failure };
    }
}

/** Chime's device enumeration is NOT a plain enumeration, and its default behaviour can leave a
 * perfectly good microphone looking like it does not exist.
 *
 * Read off the installed build (amazon-chime-sdk-js@3.32.0), not from memory:
 * `listAudioInputDevices()` `listDevicesOfKind` `updateDeviceInfoCacheFromBrowser()`
 * (`DefaultDeviceController.js:668`). If ANY enumerated device has an empty label - which is what
 * a browser reports before permission is granted - the SDK calls its `deviceLabelTrigger` to force
 * a prompt. The DEFAULT trigger (same file, line 40) is
 * `getUserMedia({ audio: true, video: true })` - BOTH KINDS IN ONE REQUEST. If that rejects the
 * SDK logs it, swallows it, and returns the label-less enumeration, in which browsers report
 * `deviceId: ''`.
 *
 * So on a machine with a microphone and NO WEBCAM, Chrome rejects the combined request outright
 * (`NotFoundError`, without even prompting). The mic comes back with `deviceId: ''`,
 * `selectFirstInput` reads that as "there is no microphone", `startAudioInput` is never called,
 * microphone permission is never requested - and that user CANNOT BE HEARD, on every join,
 * forever. Same shape for anyone who refuses the combined prompt on a first-ever join.
 *
 * DO NOT "SIMPLIFY" THIS BACK TO ONE REQUEST. Audio+video must be tried FIRST: an audio-only
 * request grants the microphone but never labels a camera, so collapsing it to that would cost
 * every user their video. The audio-only call is the FALLBACK, for the machine that cannot
 * satisfy the combined one. Installed BEFORE the first `list*` call - the first enumeration is
 * the one that decides whether we ever get a microphone id, so installing it afterwards is too
 * late. */
/** How long to wait for the user to answer a permission prompt before giving up on it.
 *
 * Generous on purpose. This is not a network timeout - it is a HUMAN one, and a clinician reading a
 * chart while the prompt sits in the corner is the ordinary case. Too short and we pre-empt a grant
 * that was coming; too long and we are the hang this exists to fix. */
const PERMISSION_PROMPT_TIMEOUT_MS = 25_000;

/** - AN UNANSWERED PERMISSION PROMPT IS NOT AN ERROR, AND THAT IS THE ENTIRE BUG.
 *
 * `getUserMedia` REJECTS when permission is denied, when there is no device, or when the device is
 * busy - all of which the trigger's `catch` already handles by degrading to audio-only. But when the
 * user simply IGNORES the prompt, the promise **never settles at all**. The `catch` cannot fire for a
 * promise that never resolves or rejects, so the trigger awaited forever and the join never completed:
 * the practitioner sat on "Connecting..." indefinitely, with no error, no timeout and nothing changing.
 * Measured live in run 3 at ~3 minutes and still hung - while the patient client on the SAME
 * run hit `NotReadableError` and degraded correctly. An ERRORED permission degraded; an IGNORED one hung.
 *
 * Rejecting on timeout means the SDK falls back to a LABEL-LESS enumeration, in which browsers
 * report `deviceId: ''` - and per this file's own header that reads as "no microphone". So the user
 * joins degraded. That is a deliberate trade, not an oversight: `cameraAvailable`/`micAvailable` go
 * false and `CallControls` already tells them so, which is a RECOVERABLE state. "Connecting..." forever
 * is not.
 */
function awaitPermission(request: Promise<MediaStream>, label: string): Promise<MediaStream> {
    let timedOut = false;

    return new Promise<MediaStream>((resolve, reject) => {
        const timer = setTimeout(() => {
            timedOut = true;
            console.warn(
                `[video] the ${label} permission prompt was not answered within `
                + `${PERMISSION_PROMPT_TIMEOUT_MS}ms — joining without it rather than waiting forever`,
            );
            reject(new Error(`permission prompt (${label}) was not answered`));
        }, PERMISSION_PROMPT_TIMEOUT_MS);

        request.then(
            (stream) => {
                clearTimeout(timer);
                if (timedOut) {
                    // THE USER ANSWERED AFTER WE GAVE UP, and this branch is not tidiness. An
                    // orphaned stream nobody is consuming leaves the CAMERA LIGHT ON with the meeting
                    // not using it - which a patient reads as "the app is still watching me". This file
                    // already treats that as a trust defect in a healthcare product (see releaseMedia).
                    stopTracks(stream);
                    return;
                }
                resolve(stream);
            },
            (e) => {
                clearTimeout(timer);
                // Already rejected by the timeout - reporting the late error too would be noise.
                if (!timedOut) reject(e);
            },
        );
    });
}

function stopTracks(stream: MediaStream): void {
    (stream.getTracks?.() ?? []).forEach((track) => {
        try { track.stop(); } catch { /* a track we cannot stop is not worth failing over */ }
    });
}

function installDeviceLabelTrigger(av: any, isCurrent: () => boolean = () => true): void {
    // A prompt cannot be withdrawn once shown; a grant that answers a retired join is released, not kept.
    const kept = (stream: MediaStream): MediaStream => {
        if (isCurrent()) return stream;
        stopTracks(stream);
        throw new Error('the join was retired while its permission prompt was open');
    };
    try {
        av.setDeviceLabelTrigger(async (): Promise<MediaStream> => {
            let both: MediaStream;
            try {
                both = await awaitPermission(
                    navigator.mediaDevices.getUserMedia({ audio: true, video: true }),
                    'camera and microphone',
                );
            } catch (e) {
                // A retired join asks for nothing more: the fallback would be a second prompt.
                if (!isCurrent()) throw e;
                console.warn('[video] audio+video permission failed — falling back to audio-only', e);
                // BOUNDED TOO, and for the same reason rather than by symmetry: if the combined
                // prompt timed out because it was ignored, this one is about to be ignored as well.
                // An unbounded fallback would simply move the hang one line down.
                return kept(await awaitPermission(
                    navigator.mediaDevices.getUserMedia({ audio: true }),
                    'microphone',
                ));
            }
            return kept(both);
        });
    } catch (e) {
        // Never fatal to the join: without a trigger we are exactly where we were before this
        // existed, which is degraded, not broken.
        console.warn('[video] could not install the device-label trigger', e);
    }
}

/** `av.stop()` ends the SESSION; it does NOT release the input devices. Without this the camera
 * light stays on and the mic stays hot after a telehealth visit ends - which a patient reads as
 * "the app is still watching me". That is a trust defect in a healthcare product, not untidiness.
 *
 * Each release is guarded on its own: a failure letting go of the MIC must never be the reason the
 * CAMERA stays lit. And nothing here throws, so it is safe to call from a `finally` that is still
 * propagating someone else's error. */
async function releaseMedia(av: any): Promise<void> {
    try { await av.stopAudioInput(); } catch (e) { console.warn('[video] failed to release the microphone', e); }
    try { await av.stopVideoInput(); } catch (e) { console.warn('[video] failed to release the camera', e); }
}

/** The SDK's `RealtimeSubscribeToAttendeeIdPresenceCallback`, transcribed from the installed
 * amazon-chime-sdk-js@3.32.0 (`build/realtimecontroller/RealtimeSubscribeToAttendeeIdPresenceCallback.d.ts`)
 * rather than imported: this file must not pull the SDK's types into the eager bundle, which is the
 * whole reason `chimeLoader` exists.
 *
 * `dropped` distinguishes "left" from "could not rejoin after a reconnect" - both arrive with
 * `present: false`, and for our purposes both mean GONE. */
type PresenceCallback = (
    attendeeId: string,
    present: boolean,
    externalUserId?: string,
    dropped?: boolean,
    posInFrame?: unknown,
) => void;

/** The SDK's `ActiveSpeakerDetectorFacade` callback, transcribed from the installed
 * amazon-chime-sdk-js@3.32.0 (`build/activespeakerdetector/ActiveSpeakerDetectorFacade.d.ts`) rather
 * than imported - same reason as `PresenceCallback`: this file must not pull the SDK's types into
 * the eager bundle.
 *
 * Sorted MOST-ACTIVE-FIRST by the detector's own policy (verified against the installed build,
 * `DefaultActiveSpeakerDetector.updateActiveSpeakers`, which sorts descending by score before
 * calling back) - index 0 IS "who is talking right now", not a roster to interpret. An empty array
 * means the SDK currently hears nobody. */
type ActiveSpeakerCallback = (activeSpeakers: string[]) => void;

type SdkLoader = typeof loadChimeSdk;

/** Whether the caller still owns the opening a pending join was started for. */
export type AdmissionOwner = () => boolean;

/** A join whose owner retired before it was admitted: nothing was adopted, started or published. */
export class JoinRetired extends Error {
    constructor() {
        super('the join was retired before it was admitted');
        this.name = 'JoinRetired';
    }
}

type VolumeCallback = (attendeeId: string, volume: number | null, muted: boolean | null) => void;

// Chime reports 0 to 1; anything above a breath counts as speech.
const SPEAKING_VOLUME = 0.05;

export type VolumeReading = { volume: number | null; muted: boolean | null };

/**
 * Folds one volume reading into who is speaking; true when that changed. Chime sends null for a value
 * that has not changed, so each reading merges into the last one known for that attendee.
 */
export function recordVolume(
    state: CallSessionState,
    readings: Map<string, VolumeReading>,
    attendeeId: string,
    volume: number | null,
    muted: boolean | null,
): boolean {
    const last = readings.get(attendeeId);
    const reading = { volume: volume ?? last?.volume ?? null, muted: muted ?? last?.muted ?? null };
    readings.set(attendeeId, reading);
    const speaking = !reading.muted && reading.volume !== null && reading.volume > SPEAKING_VOLUME;
    const was = state.speakingAttendeeIds.includes(attendeeId);
    const others = state.speakingAttendeeIds.filter((id) => id !== attendeeId);
    state.speakingAttendeeIds = speaking ? [...others, attendeeId] : others;
    return speaking !== was;
}

export class ChimeCallSession {
    // No `session` field: `DefaultMeetingSession` exists only to hand us its `audioVideo` facade,
    // and holding a second write-only reference to it is dead state (tsc's noUnusedLocals says so
    // now that join() reads the facade off a local). `this.av` IS the meeting, for every purpose
    // this class has.
    private av: any = null;
    private observer: any = null;
    // The presence callback currently registered on `this.av`, held for exactly one reason: the SDK
    // unsubscribes BY CALLBACK IDENTITY, so nothing else can take it off again. Null whenever no
    // subscription is live - including the meetings where we deliberately never subscribed.
    private presenceHandler: PresenceCallback | null = null;
    // Same reasoning as `presenceHandler`, for the active-speaker subscription Task 3 adds - the SDK
    // unsubscribes BY CALLBACK IDENTITY there too.
    private activeSpeakerHandler: ActiveSpeakerCallback | null = null;
    private volumeHandlers = new Map<string, VolumeCallback>();
    private volumeReadings = new Map<string, VolumeReading>();
    private audioEl: HTMLAudioElement | null = null;
    // The facade whose stream audioEl plays now. No facade's SDK is ever given audioEl itself: each binds
    // a private element of its own, because the SDK keeps writing that element after its own awaits (on
    // Chromium, setSinkId's completion restores the stream it captured) and nothing can recall such a write.
    private outputOwner: any = null;
    /** Releases a facade's devices, then its private output; the shared element clears only for its owner. */
    private async releaseFacade(av: any): Promise<void> {
        await releaseMedia(av);
        // An element already unbound or torn down has nothing left to release.
        try { av.unbindAudioElement(); } catch { /* nothing to release */ }
        if (this.outputOwner === av) this.outputOwner = null;
    }
    /** Binds `av` to a private, muted element. The SDK writes only that one; a write reaches the shared
     * element, synchronously and unchanged, only while `av` still owns the output and the element is the same. */
    private async bindOutput(av: any, shared: HTMLAudioElement): Promise<void> {
        const own = shared.ownerDocument.createElement('audio');
        own.muted = true;
        let stream: MediaProvider | null = null;
        Object.defineProperty(own, 'srcObject', {
            configurable: true,
            get: () => stream,
            set: (value: MediaProvider | null) => {
                stream = value;
                if (this.outputOwner === av && this.audioEl === shared) shared.srcObject = value;
            },
        });
        this.outputOwner = av;
        shared.srcObject = null;
        // The SDK's bind sets autoplay only on the element it is given; the audible one needs it as well, or a
        // freshly mounted provider holds the call's stream without ever playing it.
        shared.autoplay = true;
        await av.bindAudioElement(own);
    }
    private state: CallSessionState = idleState();
    private subscribers = new Set<(s: CallSessionState) => void>();
    // Which element is CURRENTLY bound for each tile. This exists because the SDK's unbind is keyed
    // by TILE ID, not by element - see `unbindTile`.
    private boundElements = new Map<number, HTMLVideoElement>();
    // Identifies the join that owns this object. See `join`.
    private joinToken: object | null = null;

    // The loader is injected so tests can supply a fake SDK with no jsdom and no media APIs.
    constructor(private readonly load: SdkLoader = loadChimeSdk) {}

    /** Hand over the element Chime plays every remote participant through.
 *
 * The provider owns it, not a surface component, and that is load-bearing: `VideoTileGrid`
 * returns `null` at zero tiles, so an element living there would be unmounted - and the call
 * silenced - the moment both cameras went off in a 1:1. Stored rather than bound here because
 * `bindAudioElement` needs a live facade; the binding happens inside `join()`. */
    setAudioElement(el: HTMLAudioElement | null): void {
        this.audioEl = el;
    }

    subscribe(cb: (s: CallSessionState) => void): () => void {
        this.subscribers.add(cb);
        return () => { this.subscribers.delete(cb); };
    }

    /** Every subscriber runs inside its own try/catch, and that is not defensive habit - it is
 * load-bearing. `emit()` runs ARBITRARY consumer code (a React setState after unmount, a
 * surface with a bug) and it is called from `leave()`'s `finally`, from `join()`, from the
 * tile observer and from both toggles. A subscriber throwing out of here would abort whatever
 * teardown it happened to be sequenced inside - and, in `leave()`, would also REPLACE the
 * error already in flight out of the try block. One broken consumer must not be able to
 * corrupt this class's own state machine, nor silence every OTHER subscriber behind it in the
 * Set. Logged, never swallowed silently. */
    private emit(): void {
        // EVERY array is copied, not just `tiles`: a subscriber holding on to a snapshot must not be
        // able to see a later mutation of any of them - and `remoteAttendees` is the one a surface
        // derives "waiting for the patient" from, so a shared reference there is a UI that changes
        // without a re-render.
        const snapshot = {
            ...this.state,
            tiles: [...this.state.tiles],
            remoteTiles: [...this.state.remoteTiles],
            // BELT-AND-BRACES, AND PROVEN SO RATHER THAN ASSUMED. Mutating this line away does NOT
            // redden any test: every write path above (`videoTileDidUpdate`, `videoTileWasRemoved`,
            // `seedExistingTiles`) rebuilds `tilesByAttendee` as a NEW object, so a subscriber's
            // captured reference is already safe without this copy. Kept because it is the same shape
            // as every sibling collection here, and it becomes load-bearing the instant a future write
            // path mutates the map in place instead of rebuilding it. A test for this line was written
            //, found vacuous by mutation, and deleted - do not re-add one without first
            // making it fail.
            tilesByAttendee: { ...this.state.tilesByAttendee },
            remoteAttendees: [...this.state.remoteAttendees],
            remoteParticipants: [...this.state.remoteParticipants],
            speakingAttendeeIds: [...this.state.speakingAttendeeIds],
            // Task 3 - DERIVED here, not maintained as a second synchronized field.
            // `this.state.activeSpeakerAttendeeId` is written ONLY when the SDK reports an actual
            // speaker (see `subscribeToActiveSpeaker`); falling back to the first entry of
            // `remoteParticipants` - Task 9's one source of truth for the roster - is what keeps this
            // "never an empty tile" even before anybody has spoken.
            activeSpeakerAttendeeId: this.state.activeSpeakerAttendeeId ?? this.state.remoteParticipants[0]?.attendeeId,
        };
        this.subscribers.forEach((cb) => {
            try {
                cb(snapshot);
            } catch (e) {
                console.error('[video] a call-state subscriber threw — continuing', e);
            }
        });
    }

    /**
     * With an owner, a pending join is admitted only while its own token and that owner both still hold:
     * it resolves with a handle for a qualified leave, and rejects with JoinRetired when it was not.
     */
    join(info: ChimeJoinInfo): Promise<void>;
    join(info: ChimeJoinInfo, owner: AdmissionOwner): Promise<object>;
    async join(info: ChimeJoinInfo, owner?: AdmissionOwner): Promise<object | void> {
        const retired = (): void => { if (owner) throw new JoinRetired(); };
        // Before touching the old facade or the token: a retired attempt must not stop a successor.
        if (owner && !owner()) return retired();
        // A second join() before an intervening leave() must not orphan the first meeting: its
        // observer would still be registered and start() already called, with no reference left
        // to end it (a real cost leak - Chime bills per attendee-minute). Auto-leave rather than
        // throw or no-op: the reconnect path legitimately rejoins the same meeting, so a throw
        // would break a normal flow, and a silent no-op would leave the caller believing it had
        // joined when it had not.
        if (this.av) await this.leave();
        if (owner && !owner()) return retired();

        // Whoever set this token last owns the object. Everything below awaits - the SDK chunk, and
        // then DEVICE PERMISSION, which can sit on a browser prompt for as long as the user ignores
        // it - and both a second join() and a leave() can land inside that window. An older
        // continuation waking up in there must release what it took and stop, rather than start() a
        // meeting nothing holds a reference to (billed, unreachable) or overwrite the newer join's
        // facade with its own. `leave()` clears the token for the same reason.
        const token = {};
        this.joinToken = token;
        const current = () => this.joinToken === token && (!owner || owner());
        // Clears only its own token, so a retired attempt never cancels a newer join.
        const release = (): void => {
            if (this.joinToken === token) this.joinToken = null;
            return retired();
        };

        let sdk: Awaited<ReturnType<SdkLoader>>;
        try {
            sdk = await this.load();
        } catch (e) {
            if (!current()) return release();
            throw e;
        }
        // Cancelled while the lazy SDK chunk was still in flight. The cheapest bail there is:
        // nothing has been constructed, no meeting object exists, and - the point - NO PERMISSION
        // PROMPT HAS BEEN SHOWN, so there is nothing to release and nobody to bother. Without this
        // check, a user who backs out during the chunk load is still asked for their camera a
        // moment later.
        if (!current()) return release();

        const logger = new sdk.ConsoleLogger('akashic-video', sdk.LogLevel.WARN);
        const deviceController = new sdk.DefaultDeviceController(logger);
        const configuration = new sdk.MeetingSessionConfiguration(info.Meeting, info.Attendee);
        const session = new sdk.DefaultMeetingSession(configuration, logger, deviceController);
        const av = session.audioVideo;

        // Chime v3 order, and it is not arbitrary: select the inputs and bind the output element
        // BEFORE start(). Nothing below this line existed until 2026-08-01 - join() built the
        // meeting, added the tile observer, called start(), and stopped. The meeting connected, the
        // tiles rendered, the UI looked entirely healthy, and the call was SILENT in both
        // directions with a permanently blank local tile.
        const media = await this.acquireMedia(av, current);

        if (media === null || !current()) {
            // Superseded while we waited - either mid-acquisition (`null`) or during the bind.
            // Release on the LOCAL facade only - `this.av` may already belong to the join that
            // replaced us, and stomping it is the bug this guard prevents.
            await this.releaseFacade(av);
            return release();
        }

        this.av = av;
        // Symmetric with leave(). bindTile records an element whether or not a facade is live, so a
        // surface unmounting after the last call ended can leave this map dirty - and a stale
        // element matching a REUSED tile id would then unbind a live tile of a meeting it was never
        // part of, the exact hazard the element check exists to prevent.
        this.boundElements.clear();
        this.state = {
            ...idleState(),
            micAvailable: media.micAvailable,
            cameraAvailable: media.cameraAvailable,
            micFailure: media.micFailure,
            cameraFailure: media.cameraFailure,
            micDeviceId: media.micDeviceId,
            cameraDeviceId: media.cameraDeviceId,
            audioOutputBound: media.audioOutputBound,
            // HONEST, not aspirational. This used to initialise `true` while no camera had been
            // selected at all, so the button rendered "on", its first click called
            // stopLocalVideoTile(), and the user had to press it twice to turn on a camera the app
            // had already told them was running.
            cameraOn: media.cameraAvailable,
        };

        this.observer = {
            // The parameter is a `VideoTileState`. It used to be typed `{ tileId: number }` and
            // everything else thrown away - including `localTile`, which is the only thing that can
            // tell "I am alone in this meeting" from "somebody joined".
            videoTileDidUpdate: (tile: { tileId: number | null; localTile?: boolean; boundAttendeeId?: string }) => {
                if (tile?.tileId == null) return;
                const known = this.state.tiles.includes(tile.tileId);
                // Chime can announce a remote tile before binding it to an attendee, so a later update
                // may be the first to say whose it is.
                const bindsNow = tile.localTile === false && !!tile.boundAttendeeId
                    && this.state.tilesByAttendee[tile.boundAttendeeId] !== tile.tileId;
                if (known && !bindsNow) return;
                // Only a POSITIVE "not local" makes a tile remote, and the direction of that
                // default is deliberate. The SDK always sets this boolean (VideoTileState.localTile
                // is not optional), so `undefined` should never arrive - but if it ever did,
                // mis-filing the LOCAL tile as remote would tell a practitioner sitting alone that
                // their patient had joined, and they would start talking to nobody. A stale
                // "waiting for the patient" is the far cheaper wrong answer.
                if (tile.localTile === false) {
                    if (!known) {
                        this.state.remoteTiles = [...this.state.remoteTiles, tile.tileId];
                        this.state.everRemote = true;
                    }
                    //. Inside the SAME `localTile === false` branch on purpose: the map must
                    // never contain the local tile, or the main stage can feature the viewer's own face.
                    if (bindsNow && tile.boundAttendeeId) {
                        this.state.tilesByAttendee = {
                            ...this.state.tilesByAttendee,
                            [tile.boundAttendeeId]: tile.tileId,
                        };
                    }
                }
                if (!known) this.state.tiles = [...this.state.tiles, tile.tileId];
                this.emit();
            },
            videoTileWasRemoved: (tileId: number) => {
                // BOTH collections, unconditionally. A removed tile that stayed in `remoteTiles`
                // would latch "somebody is here" on forever: the patient drops off and the
                // practitioner is never told they are alone again.
                this.state.tiles = this.state.tiles.filter((t) => t !== tileId);
                this.state.remoteTiles = this.state.remoteTiles.filter((t) => t !== tileId);
                //. A stale mapping outlives the stream it names, so the main stage would
                // feature a frozen frame of somebody who has gone.
                this.state.tilesByAttendee = Object.fromEntries(
                    Object.entries(this.state.tilesByAttendee).filter(([, id]) => id !== tileId),
                );
                this.emit();
            },
        };
        av.addObserver(this.observer);
        // Before start(), so no arrival can land in the gap. See the method - this is the signal
        // "waiting for the patient" is actually derived from.
        this.subscribeToPresence(av, info);
        // Task 3 - same "before start()" reasoning: nothing about who is speaking should be missed
        // in the gap between the meeting starting and this subscription landing.
        this.subscribeToActiveSpeaker(av, sdk);
        av.start();
        // `startVideoInput` only SELECTED the camera; this is what publishes it to the meeting.
        // Guarded, because publishing with no camera behind it is the blank-tile defect: everyone
        // else sees a black rectangle that claims this participant's camera is on.
        if (media.cameraAvailable) av.startLocalVideoTile();
        // THE MISSING SELF-VIEW (Spencer, browser round 2, 2026-08-02): the user saw exactly ONE
        // video box - the other person, never themselves. Local video is started inside `acquireMedia`
        // ABOVE, which runs before `addObserver`, so the SDK creates the local tile while nobody is
        // listening and never re-fires for a tile whose state has not changed. The camera published
        // (which is why the REMOTE side saw you fine) while our own state never learned the tile
        // existed.
        //
        // Deliberately NOT fixed by moving `addObserver` earlier: that would leave the observer live
        // during the concurrency-guard window above, so an abandoned join could feed tiles into a
        // session the user has already left. Reading the SDK's own tile list once, here, is correct for
        // BOTH orderings and stays correct if the SDK changes when it creates the tile.
        this.seedExistingTiles(av);
        this.emit();
        return owner ? token : undefined;
    }

    /** Adopt any tile the SDK already has that our observer never saw. Idempotent - anything already
 * known is skipped, so this can never double-count what `videoTileDidUpdate` delivered. */
    private seedExistingTiles(av: any): void {
        try {
            for (const tile of av.getAllVideoTiles?.() ?? []) {
                const state = tile?.state?.();
                if (!state || state.tileId == null) continue;
                if (this.state.tiles.includes(state.tileId)) continue;
                // Same rule as the observer: only a POSITIVE "not local" makes a tile remote, so a
                // mis-typed local tile can never claim somebody else is in the room.
                if (state.localTile === false) {
                    this.state.remoteTiles = [...this.state.remoteTiles, state.tileId];
                    this.state.everRemote = true;
                    if (state.boundAttendeeId) {
                        this.state.tilesByAttendee = {
                            ...this.state.tilesByAttendee,
                            [state.boundAttendeeId]: state.tileId,
                        };
                    }
                }
                this.state.tiles = [...this.state.tiles, state.tileId];
            }
        } catch (e) {
            // Never fatal: a self-view is worth having, but not worth failing a working call over.
            console.warn('[video] could not read existing video tiles — self-view may be missing', e);
        }
    }

    /** Track WHO ELSE IS IN THE ROOM, which is what "waiting for the patient" actually means.
 *
 * THE TASK 9 REVIEW'S FIRST DEFECT, in one sentence: tiles are not presence. A patient who
 * joins audio-only never produces a remote tile, so a tile-derived "waiting" stood for the whole
 * visit while they were talking - and a practitioner could reasonably hang up believing nobody
 * showed. `realtimeSubscribeToAttendeeIdPresence` is the SDK's answer: it fires once for every
 * attendee already present when you join, then on every arrival and departure.
 *
 * WITHOUT OUR OWN ATTENDEE ID THERE IS NO SAFE ANSWER, so we take the cheap wrong one and
 * do not track presence at all. The SDK reports the LOCAL attendee through this callback too;
 * with nothing to exclude, the practitioner's own arrival would file as a remote attendee and
 * the pane would say the patient was here for a room they are alone in. A stale "waiting" is
 * visible and harmless; a stale "not waiting" is a doctor talking to an empty room. Same
 * direction `videoTileDidUpdate` picks for `localTile`.
 *
 * Never fatal to the join, exactly like `installDeviceLabelTrigger`: an SDK without this API
 * degrades to a permanent "waiting", which is a great deal better than no telehealth at all. */
    private subscribeToPresence(av: any, info: ChimeJoinInfo): void {
        const selfAttendeeId = (info.Attendee as { AttendeeId?: string } | null | undefined)?.AttendeeId;
        if (!selfAttendeeId) {
            console.warn('[video] the join info carried no AttendeeId — presence is not tracked for this meeting');
            return;
        }

        // Task 9: widened to capture `externalUserId`, the SDK's THIRD presence-callback argument -
        // previously received and thrown away. Per the video contract it IS the participant's stable
        // FHIR reference; this class only carries it, never resolves or renders it (see
        // `RemoteMeetingParticipant`).
        const handler: PresenceCallback = (attendeeId, present, externalUserId) => {
            if (!attendeeId || attendeeId === selfAttendeeId) return;
            const known = this.state.remoteParticipants.some((p) => p.attendeeId === attendeeId);
            // The SDK re-announces the whole roster on a reconnect, so both directions check what is
            // already known and skip a redundant `emit()` - otherwise every reconnect re-renders every
            // video surface for no change.
            //
            // This guard is an OPTIMISATION, not the safety property. What actually keeps a
            // duplicate from latching "not waiting" is that the removal below uses `filter`, which
            // drops EVERY occurrence - so one departure empties the list no matter how many times an
            // id got in. Deleting this guard leaves the suite green (verified by mutation); replacing
            // `filter` with a remove-first would not, and would strand a practitioner believing their
            // patient is still in the room.
            if (present) {
                if (known) return;
                this.state.remoteParticipants = [...this.state.remoteParticipants, { attendeeId, externalUserId }];
                this.watchVolume(av, attendeeId);
                // Latched, and never cleared while the meeting lives. The departure branch below
                // empties the roster; THIS is what still tells "they left" from "nobody came".
                this.state.everRemote = true;
            } else {
                if (!known) return;
                this.state.remoteParticipants = this.state.remoteParticipants.filter((p) => p.attendeeId !== attendeeId);
                this.unwatchVolume(av, attendeeId);
            }
            // Task 9: DERIVED, not maintained in parallel - `remoteParticipants` is the one source of
            // truth, so `remoteAttendees` can never disagree with it.
            this.state.remoteAttendees = this.state.remoteParticipants.map((p) => p.attendeeId);
            this.emit();
        };

        try {
            av.realtimeSubscribeToAttendeeIdPresence(handler);
            // Recorded only on success: the unsubscribe in leave() is keyed on this being non-null,
            // and calling it for a subscription that never happened is how a teardown throws.
            this.presenceHandler = handler;
        } catch (e) {
            console.warn('[video] could not subscribe to attendee presence — "waiting for the patient" may stay on', e);
        }
    }

    /** Track WHO IS TALKING, so a narrow-window layout can collapse to a single tile without
 * guessing which one - see `CallSessionState.activeSpeakerAttendeeId`.
 *
 * Only WRITES `this.state.activeSpeakerAttendeeId` when the SDK reports an actual REMOTE speaker
 * ( - see the guard inside the handler); the fallback to the first remote participant
 * when nobody has (yet) is computed in `emit()`, off `remoteParticipants` - Task 9's one source
 * of truth for the roster - rather than duplicated here. An empty `activeSpeakers` array means
 * the SDK currently hears silence, which is deliberately a no-op: "nobody is speaking right now"
 * must not be read as "clear the last known speaker", or a momentary pause between sentences
 * would flicker a collapsed layout back to an empty tile.
 *
 * Never fatal to the join, same posture as `subscribeToPresence` and `installDeviceLabelTrigger`:
 * an SDK without this API degrades to the roster-only fallback, not a broken telehealth visit.
 *
 * CONSEQUENCE OF THE REMOTE-ONLY GUARD, recorded because it is a real behaviour change and not
 * an obvious one: if presence never populates - a missing attendee id, or
 * `realtimeSubscribeToAttendeeIdPresence` throwing - `remoteParticipants` stays empty forever, so
 * EVERY speaker is now rejected and this field is never written, where before the guard it would
 * have been.
 *
 * CORRECTED ( fix round 2) - this used to call that "the safer direction (no featured
 * attendee rather than a wrong one, and `emit()`'s roster fallback is empty in that state
 * anyway)". True before `speaker` layout existed; WRONG the moment it shipped and
 * stayed wrong through fix round 1. An empty roster left `VideoTileGrid` with NOTHING to feature
 * at the narrow rung - not "no featured attendee" as a cosmetic downgrade, but NO REMOTE VIDEO AT
 * ALL for the rest of the visit, on the phone rung, with the roster provably broken rather than
 * the call actually being audio-only. `VideoTileGrid`'s own degraded-state net (fix round 2, I1)
 * now covers exactly this case by featuring `remoteTiles[0]` directly whenever the roster is
 * empty but a tile still exists, so the guard's remaining, genuinely safe consequence is what this
 * file's posture always intended: a broken presence subscription costs active-speaker SWITCHING,
 * not video itself. */
    private watchVolume(av: any, attendeeId: string): void {
        if (this.volumeHandlers.has(attendeeId)) return;
        const handler: VolumeCallback = (id, volume, muted) => {
            if (recordVolume(this.state, this.volumeReadings, id, volume, muted)) this.emit();
        };
        try {
            av.realtimeSubscribeToVolumeIndicator(attendeeId, handler);
            this.volumeHandlers.set(attendeeId, handler);
        } catch {
            // Without it this participant is not marked speaking; the roster still shows them.
        }
    }

    private unwatchVolume(av: any, attendeeId: string): void {
        const handler = this.volumeHandlers.get(attendeeId);
        this.volumeHandlers.delete(attendeeId);
        this.volumeReadings.delete(attendeeId);
        this.state.speakingAttendeeIds = this.state.speakingAttendeeIds.filter((id) => id !== attendeeId);
        if (!handler) return;
        try {
            av.realtimeUnsubscribeFromVolumeIndicator(attendeeId, handler);
        } catch {
            // A subscription the meeting already dropped needs no unsubscribe.
        }
    }

    private subscribeToActiveSpeaker(av: any, sdk: any): void {
        const handler: ActiveSpeakerCallback = (activeSpeakers) => {
            const speaking = activeSpeakers[0];
            if (!speaking) return;
            // - REMOTE ONLY, AND THE GUARD BELONGS HERE RATHER THAN AT THE RENDER SITE.
            // Chime's detector reports the LOCAL attendee too. Filtering when rendering would be too
            // late: the local speaker would already have overwritten the last remote one, so "hold the
            // previous remote speaker" becomes unimplementable. Guarding the write makes this field's
            // name honest - "the last attendee who spoke and is not me" - instead of requiring every
            // future consumer to re-apply the filter.
            if (!this.state.remoteParticipants.some((p) => p.attendeeId === speaking)) return;
            this.state.activeSpeakerAttendeeId = speaking;
            this.emit();
        };

        try {
            av.subscribeToActiveSpeakerDetector(new sdk.DefaultActiveSpeakerPolicy(), handler);
            // Recorded only on success - same reasoning as `presenceHandler`: unsubscribing a
            // subscription that never happened is how a teardown throws.
            this.activeSpeakerHandler = handler;
        } catch (e) {
            console.warn('[video] could not subscribe to active-speaker detection — the roster fallback still applies', e);
        }
    }

    /** Select the inputs and bind the output element. Never throws - see `selectFirstInput`.
 *
 * Returns `null` when `isCurrent()` has gone false mid-acquisition; the caller releases the
 * facade. Checked BETWEEN the devices rather than only at the end because every step here is
 * a browser permission prompt the user can sit on for minutes: carrying on after the join has
 * been cancelled prompts someone who already backed out and LIGHTS THEIR CAMERA - seconds
 * after they left - only to release it again. */
    private async acquireMedia(av: any, isCurrent: () => boolean): Promise<AcquiredMedia | null> {
        // Before the FIRST enumeration, and that ordering is the whole point - see the function.
        installDeviceLabelTrigger(av, isCurrent);

        const mic = await selectFirstInput(
            () => av.listAudioInputDevices(),
            (deviceId) => av.startAudioInput(deviceId),
            'microphone',
            isCurrent,
        );
        if (!isCurrent()) return null;

        const camera = await selectFirstInput(
            () => av.listVideoInputDevices(),
            (deviceId) => av.startVideoInput(deviceId),
            'camera',
            isCurrent,
        );
        if (!isCurrent()) return null;

        // THE LOUDEST FAILURE ON THIS PATH. Chime mixes every remote participant into this one
        // element and never into the tile <video>s, which are deliberately `muted` - so without the
        // bind you hear nobody, and nothing about the call looks wrong while it happens.
        // console.error and surface it in state; never swallow it. It is still not fatal to the
        // join: losing the speaker is no reason to refuse the visit, and the surface can only tell
        // the user about it if the meeting came up to be told about.
        let audioOutputBound = false;
        try {
            if (!this.audioEl) throw new Error('no audio element was handed to the session');
            await this.bindOutput(av, this.audioEl);
            audioOutputBound = true;
        } catch (e) {
            console.error('[video] could not bind the audio output element — you will hear nobody', e);
        }

        return {
            micAvailable: mic.available,
            cameraAvailable: camera.available,
            micFailure: mic.failure,
            cameraFailure: camera.failure,
            micDeviceId: mic.deviceId,
            cameraDeviceId: camera.deviceId,
            audioOutputBound,
        };
    }

    /** With the handle of an admitted join, leaves only while that join still owns the session. */
    async leave(handle?: object): Promise<void> {
        if (handle && this.joinToken !== handle) return;
        // Before the early return, not after: a join() still waiting on a device prompt must be
        // invalidated even when it has not reached the point of publishing `this.av` yet -
        // otherwise a user who backs out mid-prompt ends up in a live meeting seconds later.
        this.joinToken = null;
        if (!this.av) return;
        const av = this.av;
        const observer = this.observer;
        const presenceHandler = this.presenceHandler;
        const activeSpeakerHandler = this.activeSpeakerHandler;
        try {
            // GUARDED ON ITS OWN, and NOT inside the try below, because the two failures are not
            // equally bad. The SDK unsubscribes by callback identity, so this is the only thing that
            // can take the presence handler off - but a throw here escaping into the block below
            // would skip `av.stop()` and leave the MEETING running. A leaked realtime callback is a
            // reference; a meeting nobody stopped is a bill.
            if (presenceHandler) {
                try {
                    av.realtimeUnsubscribeToAttendeeIdPresence(presenceHandler);
                } catch (e) {
                    console.warn('[video] failed to unsubscribe from attendee presence', e);
                }
            }
            // Task 3 - guarded on its own for the identical reason: this is the only thing that
            // can take the active-speaker callback off, and a throw here must not skip `av.stop()`.
            if (activeSpeakerHandler) {
                try {
                    av.unsubscribeFromActiveSpeakerDetector(activeSpeakerHandler);
                } catch (e) {
                    console.warn('[video] failed to unsubscribe from active-speaker detection', e);
                }
            }
            // Removing the observer is not optional: a leaked observer holds the meeting alive.
            for (const attendeeId of [...this.volumeHandlers.keys()]) this.unwatchVolume(av, attendeeId);
            if (observer) av.removeObserver(observer);
            av.stop();
        } finally {
            // Unconditional: if removeObserver/stop above throws (e.g. a partially-initialised
            // facade because addObserver blew up mid-join), the object must still recover rather
            // than wedge forever with join() unable to re-enter. The error still propagates after
            // this block runs - nothing here swallows it.
            this.observer = null;
            this.presenceHandler = null;
            this.activeSpeakerHandler = null;
            this.av = null;
            // Bindings belong to the meeting that just ended. Carrying them into the next meeting
            // would let a stale element match a REUSED tile id and unbind a live tile of a call it
            // was never part of - the same class of bug the element check exists to prevent.
            this.boundElements.clear();
            this.state = idleState();
            // Unconditional - and ORDERED BEFORE the emit for exactly that reason. A device
            // release that only ran on the happy path would leave the camera light on precisely
            // when teardown went wrong. `emit()` runs ARBITRARY subscriber code, so anything
            // sequenced after it is only as unconditional as every consumer is well-behaved;
            // `emit` now catches per subscriber, but the release must not DEPEND on that staying
            // true. Two independent reasons the camera cannot stay lit is the right number.
            // releaseMedia never throws, so it cannot mask the error still in flight above.
            await this.releaseFacade(av);
            this.emit();
        }
    }

    bindTile(tileId: number, el: HTMLVideoElement): void {
        this.boundElements.set(tileId, el);
        this.av?.bindVideoElement(tileId, el);
    }

    /** Unbind `tileId` - but ONLY if `el` is still the element bound to it.
 *
 * The whole reason this takes an element. `DefaultVideoTileController.unbindVideoElement`
 * is keyed by TILE ID: it tears down whatever element is bound for that id at that moment and,
 * with the SDK's default `cleanUpVideoElement`, pauses it and nulls its `srcObject`. Two video
 * surfaces can be mounted at once (the app renders `CallOverlay` outside `<Routes>` while
 * `EncounterVideoPane` lives inside one), so an unmount cleanup from a surface that has ALREADY
 * been replaced can land after the new surface bound the same tile - and unbinding by id alone
 * at that moment kills the NEW element's stream. Refusing a mismatched element is what makes
 * "a live call moves between the docked and floating surfaces without dropping" true rather
 * than merely intended. */
    unbindTile(tileId: number, el: HTMLVideoElement): void {
        if (this.boundElements.get(tileId) !== el) {
            // Refusing is the CORRECT outcome for a late cleanup from a replaced surface - but a
            // silent refusal is indistinguishable from a wrong one, and the symptom of a wrong one
            // (a frozen frame) is reported by users, not by code. Say so.
            console.warn(`[video] refused to unbind tile ${tileId}: a different element holds it now`);
            return;
        }
        this.boundElements.delete(tileId);
        this.av?.unbindVideoElement(tileId);
    }

    setMuted(muted: boolean): void {
        if (!this.av) return;
        if (muted) this.av.realtimeMuteLocalAudio();
        else this.av.realtimeUnmuteLocalAudio();
        this.state.muted = muted;
        this.emit();
    }

    async setCameraOn(on: boolean): Promise<void> {
        if (!this.av) return;
        if (on) {
            // No camera was acquired for this meeting, so startLocalVideoTile() would publish an
            // EMPTY tile - a black rectangle every other participant reads as "their camera is on".
            // Refuse, say why, and leave the state honest. Offering the user a retry (re-prompting
            // for a camera they denied at join) is the audio-only UX, which is Task 14's.
            if (!this.state.cameraAvailable) {
                console.warn('[video] cannot turn the camera on — no camera was acquired for this meeting');
                return;
            }
            this.av.startLocalVideoTile();
        } else {
            this.av.stopLocalVideoTile();
        }
        this.state.cameraOn = on;
        this.emit();
    }

    /**
 * - the devices this participant can choose between, refreshed from the browser.
 *
 * ASKED FOR ON DEMAND rather than cached at join, and that is not laziness: a headset plugged in
 * mid-visit is exactly the case someone opens this menu for, and a list captured at join would
 * never contain it. It is also when LABELS finally exist - before permission is granted a browser
 * reports them blank.
 */
    async listInputs(): Promise<{ microphones: DeviceChoice[]; cameras: DeviceChoice[] }> {
        if (!this.av) return { microphones: [], cameras: [] };
        // Each kind independently, so a camera enumeration that throws cannot cost the user their
        // microphone menu - which is the device they most often need to change.
        const microphones = await this.av.listAudioInputDevices()
            .then((d: any) => deviceChoices(d, 'microphone'))
            .catch(() => [] as DeviceChoice[]);
        const cameras = await this.av.listVideoInputDevices()
            .then((d: any) => deviceChoices(d, 'camera'))
            .catch(() => [] as DeviceChoice[]);
        return { microphones, cameras };
    }

    /**
 * Switch the visit to a different microphone or camera, WITHOUT rejoining. done-when 1.
 *
 * THE FAILURE PATH IS THE POINT. Picking a second device that is ALSO busy is the ordinary next
 * move for someone whose first one was - so a failed switch must leave the state honest (the new
 * reason, so the copy updates) rather than silently reporting success and leaving them mute with a
 * menu that looks like it worked.
 */
    async selectInput(kind: MediaKind, deviceId: string): Promise<void> {
        if (!this.av || !deviceId) return;
        const secureContext = typeof window === 'undefined' ? true : window.isSecureContext !== false;
        try {
            if (kind === 'microphone') {
                await this.av.startAudioInput(deviceId);
                this.state.micAvailable = true;
                this.state.micFailure = undefined;
                this.state.micDeviceId = deviceId;
            } else {
                await this.av.startVideoInput(deviceId);
                this.state.cameraAvailable = true;
                this.state.cameraFailure = undefined;
                this.state.cameraDeviceId = deviceId;
                // ⛔ Do NOT auto-start the tile. Choosing which camera to use is not the same act as
                // turning the camera on, and publishing video someone had deliberately switched off is
                // the one mistake on this surface that other people in the room can see.
            }
        } catch (error) {
            const failure = classifyMediaFailure({ secureContext, error }) ?? 'unknown';
            console.warn(`[video] could not switch the ${kind} (${failure})`, error);
            if (kind === 'microphone') {
                this.state.micAvailable = false;
                this.state.micFailure = failure;
            } else {
                this.state.cameraAvailable = false;
                this.state.cameraFailure = failure;
                // A camera that failed to start is not on, whatever the toggle said a moment ago.
                this.state.cameraOn = false;
            }
        }
        this.emit();
    }
}