@appsocom/client 0.0.0-stage → 0.5.0

package/dist/index.js

@@ -0,0 +1,2289 @@
+import "webrtc-adapter";
+import { PartyTracks, getCamera, getMic, getScreenshare, } from "partytracks/client";
+import { BehaviorSubject, Subscription, firstValueFrom, combineLatest, debounceTime, distinctUntilChanged, filter, map, } from "rxjs";
+import { CloseCodes, QUALITY_TO_LAYER, pickLayer, resolveDataSaver, canHost, canPublishAny, claimsPermissions, claimsRole, } from "@appsocom/protocol";
+import { Emitter } from "./emitter.js";
+import { SPEAKER, SpeakerTracker, VoiceActivity, rmsLevel } from "./speaker.js";
+export { SPEAKER, SpeakerTracker, VoiceActivity } from "./speaker.js";
+import { CAMERA_CONSTRAINTS, CAMERA_LAYERS, bytesFromStats, cameraEncodings, mergeEncodings, initialAdaptiveState, initialFallbackState, initialUsageMeter, nextFallbackState, nextUsage, videoAllowList, minQuality, nextAdaptiveState, qualityForHeight, connectionQualityFromSample, sampleFromStats, micBitrateCap, } from "./adaptive.js";
+import { CaptionCapture } from "./captions.js";
+export { qualityForHeight, nextAdaptiveState, initialAdaptiveState, ADAPTIVE, connectionQualityFromSample, FALLBACK, nextFallbackState, initialFallbackState, cameraEncodings, videoAllowList, nextUsage, initialUsageMeter, bytesFromStats, } from "./adaptive.js";
+export { DATA_SAVER_PRESETS, DATA_SAVER_MODES, resolveDataSaver, estimateDataUsage, pickLayer, TYPICAL_BITRATES } from "@appsocom/protocol";
+import { E2EEContext, isEncryptedMessage } from "./e2ee.js";
+export { isE2EESupported, deriveE2EEKeys, createE2EEWorker, e2eeWorkerSource, } from "./e2ee.js";
+import { backgroundEffect, noiseSuppression, } from "./effects.js";
+export * from "./effects.js";
+export { CloseCodes, attendanceToCsv } from "@appsocom/protocol";
+export { runPreflight } from "./preflight.js";
+export const TOKEN_HEADER = "X-SfuKit-Token";
+const TRACK_KINDS = ["audio", "video", "screenVideo", "screenAudio"];
+const DEVICE_RETRIES = 4;
+/** Room keep-alive. No server message for 2.5× this = dead socket. */
+const PING_EVERY_MS = 10_000;
+const DEVICE_RETRY_MS = 1000;
+/** A device that has stayed on this long resets its retry budget. */
+const DEVICE_HEALTHY_MS = 10_000;
+const VIDEO_KINDS = ["video", "screenVideo"];
+/** Join a room. Resolves once you're in, rejects if the token is bad, the room is full, etc. */
+export function joinRoom(options) {
+    const room = new Room(options);
+    return room._start().then(() => room);
+}
+const GROUP_KINDS = {
+    mic: ["audio"],
+    camera: ["video"],
+    screen: ["screenVideo", "screenAudio"],
+};
+export class Room extends Emitter {
+    roomId;
+    userId;
+    /** Your role: "teacher", "student", "observer", or your app's own label. */
+    /** Updated when your app's backend changes it during the call. */
+    role;
+    /** What you may do right now. Updated when a teacher/host changes it. */
+    permissions;
+    /** Room-wide settings (locked, …). */
+    roomState = { locked: false, chat: true, spotlight: [], waitingRoom: false, breakouts: [] };
+    /** Teachers/hosts: who is in the waiting room now, first come first. */
+    waiting = [];
+    /** Room metadata set by your app's backend (same as roomState.metadata). */
+    get metadata() {
+        return this.roomState.metadata;
+    }
+    /** Chat messages you've seen (public history + live, private ones to/from you), oldest first. Last 200. */
+    chat = [];
+    /** True if you may publish anything at all right now. */
+    get canPublish() {
+        return canPublishAny(this.permissions);
+    }
+    /** Your own participant record (id changes after a reconnect). */
+    self = null;
+    /** The recording in progress, or null. See the "recording" event. */
+    recording = null;
+    connectionState = "connecting";
+    /** Raw partytracks objects for advanced use (device lists, transforms…). */
+    media;
+    #opts;
+    #token;
+    #headers;
+    #ws = null;
+    #remotes = new Map();
+    #subs = new Subscription();
+    #localTracks = {};
+    #localState = { micOn: false, cameraOn: false, screenOn: false };
+    #customState;
+    #left = false;
+    /** Pulls wait until partyTracks exists (it needs ICE servers, fetched after the welcome). */
+    #mediaReady = false;
+    /** What the user asked for, so device retries never override "off". */
+    #wanted = { microphone: true, camera: true };
+    #adaptive = initialAdaptiveState();
+    #statsCursor = null;
+    #statsTimer = null;
+    #lastSample = null;
+    #audioOnly = false;
+    #cameraBeforeAudioOnly = true;
+    #cameraEncodings$ = null;
+    /** Layers our camera announces (fewer with a data saver). */
+    #cameraLayers = [...CAMERA_LAYERS];
+    #cameraSending = true;
+    #micEncodings$ = new BehaviorSubject([{}]);
+    /** Latest media peer connection (to adjust our senders' encodings). */
+    #pc = null;
+    #saver = resolveDataSaver("off");
+    #fallback = initialFallbackState();
+    #fallbackOn = true;
+    #keepScreenInFallback = false;
+    /** Remote participant ids, most recent speaker first (data saver: video for speakers only). */
+    #recentSpeakers = [];
+    #videoAllow = null;
+    #usage = initialUsageMeter(Date.now());
+    #myQuality = null;
+    #speakers = new SpeakerTracker();
+    #vad = new VoiceActivity();
+    #speakerTimer = null;
+    #levelTimer = null;
+    #audioCtx = null;
+    #levelSource = null;
+    #lastLevelSentAt = 0;
+    #qualities = new Map();
+    #attempt = 0;
+    #reconnectTimer = null;
+    /** Per device group: the subscriptions that push and watch it. */
+    #deviceSubs = {};
+    #deviceAttempts = {};
+    #broadcasting = { mic: false, camera: false, screen: false };
+    #stateTimer = null;
+    #onWaiting = null;
+    #attendanceWaiters = [];
+    #pingTimer = null;
+    /** Room WebSocket: up, or dropped (and since when). */
+    #signalUp = false;
+    #signalLostAt = null;
+    #lastServerMsgAt = 0;
+    #mediaState = "new";
+    #mediaEverConnected = false;
+    #tokenTimer = null;
+    #onOnline = () => this.#networkChanged("online");
+    #onOffline = () => this.#networkChanged("offline");
+    #onConnChange = () => this.#networkChanged("change");
+    #e2ee = null;
+    /** Encrypted sends finish in order. */
+    #sendChain = Promise.resolve();
+    #files = new Map();
+    #polls = new Map();
+    #lessons = new Map();
+    #myVotes = new Map();
+    #questions = new Map();
+    #myUpvotes = new Set();
+    #captionsState = { on: false };
+    #captionLines = [];
+    #captionLanguage = null;
+    #summary;
+    #capture = null;
+    #micTrack = null;
+    #captionUploads = 0;
+    #localPreview = {};
+    #sinkId = null;
+    #bgOptions = null;
+    #videoTransform = null;
+    #nsOn = false;
+    #audioTransform = null;
+    /** @internal use joinRoom() */
+    constructor(options) {
+        super();
+        this.#opts = { autoPlayAudio: true, reconnect: true, joinTimeoutMs: 15000, ...options };
+        if (options.mode === "audio")
+            this.#opts.video = false;
+        this.#wanted = { microphone: options.audio ?? true, camera: this.#opts.video ?? true };
+        this.#audioOnly = options.mode === "audio";
+        this.#opts.url = options.url.replace(/\/+$/, "");
+        this.#token = options.token;
+        const claims = decodeClaims(options.token);
+        this.#saver = resolveDataSaver(options.dataSaver ?? claims.ds ?? "off");
+        this.#cameraBeforeAudioOnly = this.#wanted.camera;
+        if (this.#saver.settings.audioOnly)
+            this.#wanted.camera = false;
+        const fb = options.audioFallback ?? options.adaptive !== false;
+        this.#fallbackOn = fb !== false;
+        this.#keepScreenInFallback = typeof fb === "object" && !!fb.keepScreenShare;
+        this.#micEncodings$.next(this.#micEncodings());
+        this.#localState = { ...this.#localState, ...this.#lowBandwidthState() };
+        this.roomId = claims.room;
+        this.userId = claims.sub;
+        this.role = claimsRole(claims);
+        this.permissions = claimsPermissions(claims);
+        if (options.e2ee) {
+            this.#e2ee = new E2EEContext(this.roomId, options.e2ee.worker, (type, detail) => this.emit("encryption-error", type, detail));
+            this.#localState.e2ee = true;
+        }
+        else if (claims.e2ee) {
+            throw new Error("this join token requires end-to-end encryption: pass an e2ee key to joinRoom()");
+        }
+        if (options.backgroundEffect)
+            this.#setBackground(options.backgroundEffect === true ? {} : options.backgroundEffect);
+        if (options.noiseSuppression)
+            this.#setNs(options.noiseSuppression === true ? {} : options.noiseSuppression);
+        this.#headers = new Headers({ [TOKEN_HEADER]: this.#token });
+        // partyTracks is created in _start(), once ICE servers are known.
+        this.media = { partyTracks: null, mic: null, camera: null, screen: null };
+    }
+    // ---------------- public API ----------------
+    /** All other participants currently in the room. */
+    get participants() {
+        return [...this.#remotes.values()].map((r) => r.participant);
+    }
+    /** Current remote track for a participant, if any. */
+    getTrack(participantId, kind) {
+        return this.#remotes.get(participantId)?.tracks[kind];
+    }
+    get localState() {
+        return { ...this.#localState };
+    }
+    toggleMic() {
+        this.setMic(!this.#localState.micOn);
+    }
+    setMic(on) {
+        this.#wanted.microphone = on;
+        if (on)
+            this.media.mic?.startBroadcasting();
+        else
+            this.media.mic?.stopBroadcasting();
+    }
+    toggleCamera() {
+        this.setCamera(!this.#localState.cameraOn);
+    }
+    setCamera(on) {
+        if (on && this.#opts.mode === "audio")
+            return; // voice call: no camera
+        this.#wanted.camera = on;
+        if (on)
+            this.media.camera?.startBroadcasting();
+        else
+            this.media.camera?.stopBroadcasting();
+    }
+    /** Must be called from a click/tap handler (browser rule for screen capture). */
+    toggleScreenShare() {
+        this.media.screen?.toggleBroadcasting();
+    }
+    /** Pick a specific mic/camera, e.g. from navigator.mediaDevices.enumerateDevices(). */
+    setMicDevice(device) {
+        this.media.mic?.setPreferredDevice(device);
+    }
+    setCameraDevice(device) {
+        this.media.camera?.setPreferredDevice(device);
+    }
+    /**
+     * Start the camera or mic again from scratch and turn it on. Use it for a
+     * "Try again" button after an "error" saying the device could not start
+     * (blocked, busy in another app, or stuck). Call it from a click/tap so the
+     * browser can ask for permission again.
+     */
+    restartDevice(kind) {
+        if (this.#left || !this.permissions[kind])
+            return;
+        if (kind === "camera" && this.#opts.mode === "audio")
+            return;
+        this.#wanted[kind === "mic" ? "microphone" : "camera"] = true;
+        this.#deviceAttempts[kind] = 0;
+        this.#disableDevice(kind);
+        this.#enableDevice(kind);
+    }
+    /** Your own camera / screen preview track right now (also sent as "local-track" events). */
+    getLocalTrack(kind) {
+        return this.#localPreview[kind] ?? null;
+    }
+    /** Play remote audio through this output device (speakers/headset). Not supported in every browser. */
+    setAudioOutputDevice(deviceId) {
+        this.#sinkId = deviceId;
+        for (const r of this.#remotes.values())
+            for (const el of Object.values(r.audioEls))
+                this.#applySink(el);
+    }
+    get audioOutputDevice() {
+        return this.#sinkId;
+    }
+    #emitLocal(kind, track) {
+        this.#localPreview[kind] = track;
+        this.emit("local-track", kind, track);
+    }
+    #applySink(el) {
+        const e = el;
+        if (e && this.#sinkId !== null && e.setSinkId) {
+            e.setSinkId(this.#sinkId).catch((err) => this.emit("error", new Error(`Could not switch speakers (${String(err)})`)));
+        }
+    }
+    /** Current background effect (null = off). */
+    get backgroundEffect() {
+        return this.#bgOptions;
+    }
+    /** True while RNNoise noise suppression is on. */
+    get noiseSuppression() {
+        return this.#nsOn;
+    }
+    /**
+     * Blur your background (true / { blurRadius }), replace it
+     * ({ backgroundImage: url }), or switch the effect off (false).
+     * Runs on-device with MediaPipe; loaded on first use.
+     */
+    setBackgroundEffect(effect) {
+        const prev = this.#videoTransform;
+        this.#setBackground(effect === true ? {} : effect || null);
+        if (prev)
+            this.media.camera?.removeTransform(prev);
+        if (this.#videoTransform)
+            this.media.camera?.addTransform(this.#videoTransform);
+        this.#emitEffects();
+    }
+    /** Shorthand: setBackgroundEffect(on ? { blurRadius } : false). */
+    setBackgroundBlur(on, blurRadius) {
+        this.setBackgroundEffect(on ? { blurRadius } : false);
+    }
+    /** Switch RNNoise noise suppression on the mic on or off. */
+    setNoiseSuppression(on) {
+        const prev = this.#audioTransform;
+        this.#setNs(on === true ? {} : on || null);
+        if (prev)
+            this.media.mic?.removeTransform(prev);
+        if (this.#audioTransform)
+            this.media.mic?.addTransform(this.#audioTransform);
+        this.#emitEffects();
+    }
+    #setBackground(opts) {
+        this.#bgOptions = opts ? { ...opts } : null;
+        this.#videoTransform = opts
+            ? backgroundEffect({ ...opts, onError: (e) => this.#effectError("Background effect", e, opts.onError) })
+            : null;
+    }
+    #setNs(opts) {
+        this.#nsOn = !!opts;
+        this.#audioTransform = opts
+            ? noiseSuppression({ ...opts, onError: (e) => this.#effectError("Noise suppression", e, opts.onError) })
+            : null;
+    }
+    #effectError(what, e, user) {
+        user?.(e);
+        this.emit("error", new Error(`${what} unavailable, sending the original (${e.message})`));
+    }
+    #emitEffects() {
+        this.emit("effects", { background: this.#bgOptions, noiseSuppression: this.#nsOn });
+    }
+    /** Small app-defined state shared with everyone (hand raised, etc.). Max ~4KB. */
+    setCustomState(custom) {
+        this.#customState = custom;
+        this.#send({ type: "state", state: { custom } });
+    }
+    /**
+     * Teachers/hosts (permissions.moderate): allow or stop a user's mic, camera
+     * or screen share, e.g. { screen: true } to let a student present.
+     * Applies to all their connections and lasts until the room empties.
+     */
+    setPermissions(userId, permissions) {
+        if (!this.permissions.moderate)
+            throw new Error("not allowed to moderate");
+        this.#send({ type: "set-permissions", userId, permissions });
+    }
+    /**
+     * Teachers/hosts: turn off a user's devices (default: mic). They can turn
+     * them back on, unless `lock` is true (that also takes the permission away;
+     * give it back with setPermissions).
+     */
+    mute(userId, devices = ["mic"], options = {}) {
+        this.#moderate({ type: "mute", userId, devices, lock: options.lock });
+    }
+    /** Teachers/hosts: mute everyone who isn't a teacher/host (default: mics). */
+    muteAll(devices = ["mic"], options = {}) {
+        this.#moderate({ type: "mute", userId: "*", devices, lock: options.lock });
+    }
+    /** Teachers/hosts: stop someone's screen share. */
+    stopScreenShare(userId) {
+        this.#moderate({ type: "mute", userId, devices: ["screen"] });
+    }
+    /** Teachers/hosts: remove a user. `ban` keeps them out until the room empties. */
+    remove(userId, options = {}) {
+        this.#moderate({ type: "remove", userId, ban: options.ban });
+    }
+    /** Raise your hand. Raising it again keeps your place in the queue. */
+    raiseHand() {
+        this.#send({ type: "hand", raised: true });
+    }
+    /** Lower your own hand, or (teachers/hosts) someone else's. */
+    lowerHand(userId) {
+        if (!userId || userId === this.userId)
+            this.#send({ type: "hand", raised: false });
+        else
+            this.#moderate({ type: "lower-hand", userId });
+    }
+    /** Teachers/hosts: lower every raised hand. */
+    lowerAllHands() {
+        this.#moderate({ type: "lower-hand", userId: "*" });
+    }
+    /** Everyone with a hand up (you included), first raised first. */
+    get raisedHands() {
+        const all = this.self ? [this.self, ...this.participants] : this.participants;
+        return all.filter((p) => p.handRaisedAt != null).sort((a, b) => a.handRaisedAt - b.handRaisedAt);
+    }
+    /**
+     * Send a chat message to everyone, or privately with { to: userId }.
+     * Students can only message teachers/hosts privately, and can't chat while a
+     * teacher has turned chat off (you get an `error` event).
+     */
+    sendChat(text, options = {}) {
+        this.#send({
+            type: "chat",
+            text,
+            ...(options.to ? { to: options.to } : {}),
+            ...(options.everywhere ? { everywhere: true } : {}),
+        });
+    }
+    /** Teachers/hosts: delete a chat message for everyone. */
+    deleteChat(id) {
+        this.#moderate({ type: "chat-delete", id });
+    }
+    /** Teachers/hosts: turn chat on/off for everyone who isn't a teacher/host. */
+    setChatEnabled(enabled) {
+        this.#moderate({ type: "room", chat: enabled });
+    }
+    /**
+     * Teachers/hosts: put users in the spotlight for everyone (up to 6, in
+     * order; [] clears). Read it from room.roomState.spotlight / "room-state".
+     */
+    setSpotlight(userIds) {
+        this.#moderate({ type: "room", spotlight: userIds });
+    }
+    /**
+     * Teachers/hosts: start breakout rooms. Each group lists userIds; anyone not
+     * listed stays in the main room. Groups get ids "g1", "g2", … (room.roomState.breakouts).
+     */
+    startBreakouts(groups) {
+        this.#moderate({ type: "breakouts", groups });
+    }
+    /** Teachers/hosts: move someone to a group id (null = main room). */
+    moveToGroup(userId, group) {
+        this.#moderate({ type: "move", userId, group });
+    }
+    /** Teachers/hosts: join a breakout group yourself (null = back to the main room). */
+    visitGroup(group) {
+        this.moveToGroup(this.userId, group);
+    }
+    /** Teachers/hosts: end breakouts; everyone returns to the main room. */
+    endBreakouts() {
+        this.#moderate({ type: "end-breakouts" });
+    }
+    /** Your breakout group id, or null in the main room. */
+    get group() {
+        return this.self?.group ?? null;
+    }
+    /** Teachers/hosts: turn the waiting room on/off (off admits everyone waiting). */
+    setWaitingRoom(on) {
+        this.#moderate({ type: "room", waitingRoom: on });
+    }
+    /** Teachers/hosts: let someone in from the waiting room ("*" = everyone). */
+    admit(userId) {
+        this.#moderate({ type: "admit", userId });
+    }
+    /** Teachers/hosts: turn someone in the waiting room away. */
+    deny(userId) {
+        this.#moderate({ type: "deny", userId });
+    }
+    /**
+     * Teachers/hosts: who attended and for how long (this room, last 30 days).
+     * Turn it into a spreadsheet with attendanceToCsv(report).
+     */
+    fetchAttendance(timeoutMs = 10000) {
+        return new Promise((resolve, reject) => {
+            try {
+                this.#moderate({ type: "attendance" });
+            }
+            catch (err) {
+                reject(err);
+                return;
+            }
+            this.#attendanceWaiters.push(resolve);
+            setTimeout(() => {
+                const i = this.#attendanceWaiters.indexOf(resolve);
+                if (i >= 0) {
+                    this.#attendanceWaiters.splice(i, 1);
+                    reject(new Error("attendance request timed out"));
+                }
+            }, timeoutMs);
+        });
+    }
+    /** Teachers/hosts: while locked, only teachers/hosts can join. */
+    lockRoom(locked = true) {
+        this.#moderate({ type: "room", locked });
+    }
+    #moderate(msg) {
+        if (!this.permissions.moderate)
+            throw new Error("not allowed to moderate");
+        this.#send(msg);
+    }
+    /**
+     * Teachers/hosts (permissions.moderate): start recording the room to R2.
+     * Audio only by default; { video: true } records everything with the
+     * recorder bot (the kit must be deployed with it).
+     */
+    startRecording(options = {}) {
+        if (!this.permissions.moderate)
+            throw new Error("not allowed to moderate");
+        this.#send({ type: "start-recording", video: options.video === true });
+    }
+    /** Teachers/hosts (permissions.moderate): stop the recording. */
+    stopRecording() {
+        if (!this.permissions.moderate)
+            throw new Error("not allowed to moderate");
+        this.#send({ type: "stop-recording" });
+    }
+    // ---------------- subscription controls ----------------
+    /**
+     * Start or stop receiving some of a participant's tracks, e.g. stop their
+     * video while their tile is off screen. Stopping really stops the media
+     * (no bandwidth used); starting again pulls it fresh.
+     */
+    setSubscribed(participantId, kinds, on) {
+        const entry = this.#remotes.get(participantId);
+        if (!entry)
+            return;
+        for (const kind of Array.isArray(kinds) ? kinds : [kinds])
+            entry.subscribed[kind] = on;
+        this.#syncPulls(entry);
+    }
+    /** Whether you're set to receive this participant's track kind (if they publish it and you're allowed). */
+    isSubscribed(participantId, kind) {
+        const entry = this.#remotes.get(participantId);
+        return !!entry && this.#wants(entry, kind);
+    }
+    /**
+     * Receive a participant's video only while `el` (their tile) is on screen
+     * and the tab is visible. Video stops 1s after the tile leaves the screen
+     * (`hideDelayMs`) and comes back when it returns. Returns a function that
+     * stops watching (and leaves video on).
+     */
+    observeVisibility(el, participantId, options = {}) {
+        const kinds = options.kinds ?? VIDEO_KINDS;
+        const hideDelay = options.hideDelayMs ?? 1000;
+        let inView = true;
+        let timer = null;
+        const apply = () => {
+            const visible = inView && (typeof document === "undefined" || document.visibilityState !== "hidden");
+            if (timer)
+                clearTimeout(timer);
+            timer = null;
+            if (visible)
+                this.setSubscribed(participantId, kinds, true);
+            else
+                timer = setTimeout(() => this.setSubscribed(participantId, kinds, false), hideDelay);
+        };
+        const io = typeof IntersectionObserver !== "undefined"
+            ? new IntersectionObserver((entries) => {
+                inView = entries.some((e) => e.isIntersecting);
+                apply();
+            })
+            : null;
+        io?.observe(el);
+        const onVis = () => apply();
+        if (typeof document !== "undefined")
+            document.addEventListener("visibilitychange", onVis);
+        return () => {
+            io?.disconnect();
+            if (timer)
+                clearTimeout(timer);
+            if (typeof document !== "undefined")
+                document.removeEventListener("visibilitychange", onVis);
+            this.setSubscribed(participantId, kinds, true);
+        };
+    }
+    /**
+     * Choose who may receive YOUR tracks. Enforced by the server: others only
+     * see (and can only pull) what you allow; anyone who loses access stops
+     * receiving within seconds. Kept until the room empties.
+     *
+     *   room.setTrackPermissions({ allowAll: true });                          // default
+     *   room.setTrackPermissions({ allowAll: false, allow: [{ userId: "t1" }] });
+     *   room.setTrackPermissions({ allowAll: false, allow: [{ userId: "t1", kinds: ["screenVideo"] }] });
+     */
+    setTrackPermissions(permissions) {
+        this.#send({ type: "track-permissions", permissions });
+    }
+    #wants(entry, kind) {
+        const chosen = entry.subscribed[kind];
+        if (chosen !== undefined)
+            return chosen;
+        const auto = this.#opts.autoSubscribe ?? true;
+        if (typeof auto === "boolean")
+            return auto;
+        return VIDEO_KINDS.includes(kind) ? auto.video ?? true : auto.audio ?? true;
+    }
+    /** AI agents currently in the room. */
+    get agents() {
+        return this.participants.filter((p) => p.kind === "agent");
+    }
+    /** Type to an AI agent instead of speaking; it answers out loud. */
+    sendToAgent(agentId, text) {
+        this.#send({ type: "agent-text", agentId, text });
+    }
+    /** AI lessons running in this room (usually one). */
+    get lessons() {
+        return [...this.#lessons.values()];
+    }
+    /** The AI lesson running in this room, if any. */
+    get lesson() {
+        return this.#lessons.values().next().value ?? null;
+    }
+    /** AI participants in the room (agents with a role: contributor, scribe, co-teacher…). */
+    get aiParticipants() {
+        return this.participants.filter((p) => p.kind === "agent" && p.agent?.ai);
+    }
+    /**
+     * "Ask AI": type a question to an AI participant (the alternative to asking
+     * the host or teacher). It answers in the chat, or out loud when its voice is
+     * on. `private`: only you see the answer, in chat. Needs the AI's
+     * directQuestions on unless you're a host. Saying its name in the call works too.
+     */
+    askAI(text, options = {}) {
+        const agentId = options.agentId ?? this.aiParticipants[0]?.id;
+        if (!agentId)
+            throw new Error("no AI participant in this room");
+        this.#send({ type: "ai-ask", agentId, text, ...(options.private ? { private: true } : {}) });
+    }
+    /**
+     * Hosts: steer an AI participant: { action: "pause" | "resume" | "recap" | "minutes" },
+     * { action: "settings", voice, directQuestions, flags, watchPolicy, knowledge },
+     * co-teachers { action: "teach", topic | planId } and { action: "stop-teaching" }.
+     */
+    controlAI(control, agentId = this.aiParticipants[0]?.id) {
+        if (!agentId)
+            throw new Error("no AI participant in this room");
+        this.#send({ type: "ai-control", agentId, control });
+    }
+    /**
+     * Keep yourself out of what AI participants hear (true) or let them hear you
+     * again (false). Your speech and chat are then never handed to the AI.
+     * Shown to everyone as `participant.aiOptOut`.
+     */
+    setAiOptOut(optOut) {
+        this.#send({ type: "ai-opt-out", optOut });
+    }
+    /** Type a question to the AI teacher. Raise your hand (raiseHand) to ask out loud instead. */
+    askLesson(text, lessonId = this.lesson?.lessonId) {
+        if (!lessonId)
+            throw new Error("no lesson in this room");
+        this.#send({ type: "lesson-ask", lessonId, text });
+    }
+    /**
+     * Moderators: steer the AI lesson, e.g. { action: "pause" }, { action: "takeover" }
+     * (you speak, the AI listens and keeps notes), { action: "handback" },
+     * { action: "call-on", userId }, { action: "goto", section: 2 },
+     * { action: "scope", scope: "strict" }, { action: "note", text: "slow down" }.
+     */
+    controlLesson(control, lessonId = this.lesson?.lessonId) {
+        if (!lessonId)
+            throw new Error("no lesson in this room");
+        this.#send({ type: "lesson-control", lessonId, control });
+    }
+    /**
+     * Send an app-level message to everyone else in the room (chat, reactions…),
+     * or with `to` only to those userIds. `topic` travels with it so you can route
+     * messages (e.g. "whiteboard").
+     * With end-to-end encryption on, it's encrypted first (other participants
+     * receive the original `data`; the server sees ciphertext).
+     */
+    send(data, options = {}) {
+        const extra = {
+            ...(options.to ? { to: options.to } : {}),
+            ...(options.topic ? { topic: options.topic } : {}),
+        };
+        const e2ee = this.#e2ee;
+        if (!e2ee)
+            return this.#send({ type: "broadcast", data, ...extra });
+        const encrypted = e2ee.encryptMessage(data);
+        this.#sendChain = this.#sendChain
+            .then(() => encrypted)
+            .then((enc) => this.#send({ type: "broadcast", data: enc, ...extra }))
+            .catch((err) => this.emit("error", err instanceof Error ? err : new Error(String(err))));
+    }
+    /** End-to-end encryption status. `keyIndex` is the key you send with (-1 = off). */
+    get encryption() {
+        return { enabled: Boolean(this.#e2ee), keyIndex: this.#e2ee?.keyIndex ?? -1 };
+    }
+    /**
+     * Add or rotate the end-to-end encryption key. Give every participant the new
+     * key with a new index (0-255). With `use: false` it's only added for
+     * receiving, so you can hand it out first and switch everyone over after.
+     * The last 16 keys are kept for decrypting.
+     */
+    async setEncryptionKey(key, index, options = {}) {
+        if (!this.#e2ee)
+            throw new Error("end-to-end encryption is off for this room (join with the e2ee option)");
+        await this.#e2ee.setKey(key, index, options.use ?? true);
+    }
+    // ---------------- reactions & files ----------------
+    /** Send an emoji reaction to everyone (e.g. "👍"). Max ~10 per 5 seconds. */
+    react(emoji) {
+        this.#send({ type: "reaction", emoji });
+    }
+    /** Files shared in this room, oldest first. They're deleted when the room empties. */
+    get files() {
+        return [...this.#files.values()].sort((a, b) => a.at - b.at);
+    }
+    /**
+     * Share a file with everyone in the room (needs the Worker's STORAGE bucket).
+     * Observers can't share. Max size is the Worker's MAX_FILE_MB (default 25).
+     */
+    async shareFile(file, name = file.name || "file") {
+        const res = await fetch(`${this.#opts.url}/rooms/${encodeURIComponent(this.roomId)}/files`, {
+            method: "POST",
+            headers: {
+                [TOKEN_HEADER]: this.#token,
+                "Content-Type": file.type || "application/octet-stream",
+                "X-File-Name": encodeURIComponent(name),
+            },
+            body: file,
+        });
+        const body = (await res.json().catch(() => ({})));
+        if (!res.ok)
+            throw new Error(body.error ?? `file upload failed (HTTP ${res.status})`);
+        this.#addFile(body);
+        return body;
+    }
+    /** Download a shared file's bytes. */
+    async downloadFile(fileId) {
+        const res = await fetch(this.#fileEndpoint(fileId), { headers: { [TOKEN_HEADER]: this.#token } });
+        if (!res.ok)
+            throw new Error(`download failed (HTTP ${res.status})`);
+        return res.blob();
+    }
+    /**
+     * A link that downloads the file (carries your join token, so don't share it
+     * outside the room). `inline` shows PNG/JPEG/GIF/WebP images instead.
+     */
+    fileUrl(fileId, inline = false) {
+        return `${this.#fileEndpoint(fileId)}?token=${encodeURIComponent(this.#token)}${inline ? "&inline=1" : ""}`;
+    }
+    /** Remove a file you shared (moderators can remove anyone's). */
+    async deleteFile(fileId) {
+        const res = await fetch(this.#fileEndpoint(fileId), { method: "DELETE", headers: { [TOKEN_HEADER]: this.#token } });
+        if (!res.ok && res.status !== 404) {
+            const body = (await res.json().catch(() => ({})));
+            throw new Error(body.error ?? `delete failed (HTTP ${res.status})`);
+        }
+        this.#removeFile(fileId);
+    }
+    // ---------------- polls & Q&A ----------------
+    /** True if you may run polls and moderate Q&A (moderators, or everyone in rooms without roles). */
+    get isHost() {
+        return this.self ? canHost(this.self) : canHost({ role: this.role, permissions: this.permissions });
+    }
+    /** Polls in this room, oldest first. `counts` is empty while results are hidden from you. */
+    get polls() {
+        return [...this.#polls.values()].sort((a, b) => a.at - b.at);
+    }
+    /** Your vote in a poll (option indexes), if you voted. */
+    myVote(pollId) {
+        return this.#myVotes.get(pollId);
+    }
+    /** Hosts: start a poll. */
+    createPoll(poll) {
+        this.#send({ type: "poll-create", poll });
+    }
+    /** Vote, or change your vote. One option index unless the poll allows multiple. */
+    vote(pollId, choices) {
+        this.#send({ type: "poll-vote", pollId, choices: Array.isArray(choices) ? choices : [choices] });
+    }
+    closePoll(pollId) {
+        this.#send({ type: "poll-close", pollId });
+    }
+    deletePoll(pollId) {
+        this.#send({ type: "poll-delete", pollId });
+    }
+    /** Q&A questions, oldest first. Sort by `upvotes` for a "top questions" view. */
+    get questions() {
+        return [...this.#questions.values()].sort((a, b) => a.at - b.at);
+    }
+    /** Did you upvote this question? */
+    hasUpvoted(questionId) {
+        return this.#myUpvotes.has(questionId);
+    }
+    /** `anonymous` hides your name from everyone except hosts. Max 500 characters, 5 a minute. */
+    askQuestion(text, anonymous = false) {
+        this.#send({ type: "question-ask", text, anonymous });
+    }
+    upvoteQuestion(questionId, up = true) {
+        this.#send({ type: "question-upvote", id: questionId, up });
+    }
+    /** Hosts. */
+    markAnswered(questionId, answered = true) {
+        this.#send({ type: "question-answer", id: questionId, answered });
+    }
+    /** Hosts, or your own question. */
+    deleteQuestion(questionId) {
+        this.#send({ type: "question-delete", id: questionId });
+    }
+    // ---------------- captions, transcript, summary ----------------
+    /** Are captions on in this room, and with what settings. */
+    get captions() {
+        return { ...this.#captionsState };
+    }
+    /** Recent caption lines (the last 200 you've seen). Hosts can fetch the full transcript. */
+    get recentCaptions() {
+        return [...this.#captionLines];
+    }
+    /** The latest AI summary of this call, if a host made one. */
+    get summary() {
+        return this.#summary;
+    }
+    /**
+     * Hosts: turn live captions on/off (needs Workers AI on the Worker).
+     * `language` ("en", "fr", …) improves accuracy; `translate` gives English captions for any language.
+     * `server`: transcribe every mic on the server (participants on any SDK get captioned, nobody uploads clips).
+     */
+    setCaptions(on, options = {}) {
+        this.#send({ type: "captions", on, ...options });
+    }
+    /** The language you read captions in ("fr", "ha", …): lines arrive with a translation. null = as spoken. */
+    setCaptionLanguage(language) {
+        this.#captionLanguage = language && /^[a-z]{2,3}$/.test(language) ? language : null;
+        this.#send({ type: "caption-language", language: this.#captionLanguage });
+    }
+    /** The language you asked to read captions in (null = as spoken). */
+    get captionLanguage() {
+        return this.#captionLanguage;
+    }
+    /** Hosts: the whole transcript so far, as JSON lines, plain text or WebVTT. */
+    async getTranscript(format = "json") {
+        const res = await fetch(`${this.#roomEndpoint()}/transcript?format=${format}`, { headers: { [TOKEN_HEADER]: this.#token } });
+        if (!res.ok)
+            throw new Error(`transcript: HTTP ${res.status}`);
+        return format === "json" ? (await res.json()).lines : res.text();
+    }
+    /** Hosts: summarize the transcript so far with AI. Everyone gets the `summary` event. */
+    async summarize(style = "meeting") {
+        const res = await fetch(`${this.#roomEndpoint()}/summary`, {
+            method: "POST",
+            headers: { [TOKEN_HEADER]: this.#token, "Content-Type": "application/json" },
+            body: JSON.stringify({ style }),
+        });
+        const body = (await res.json().catch(() => ({})));
+        if (!res.ok)
+            throw new Error(body.error ?? `summary: HTTP ${res.status}`);
+        return body;
+    }
+    #roomEndpoint() {
+        return `${this.#opts.url}/rooms/${encodeURIComponent(this.roomId)}`;
+    }
+    /** Start/stop transcribing our own mic to match captions + mic state. */
+    #syncCaptions() {
+        const want = !this.#left &&
+            this.#opts.sendCaptions !== false &&
+            this.#captionsState.on &&
+            !this.#captionsState.server &&
+            this.#broadcasting.mic &&
+            this.permissions.mic &&
+            this.#micTrack !== null &&
+            typeof AudioContext !== "undefined";
+        if (want) {
+            this.#capture ??= new CaptionCapture((wav) => this.#sendCaption(wav));
+            void this.#capture.start(this.#micTrack);
+        }
+        else if (this.#capture?.running) {
+            void this.#capture.stop();
+        }
+    }
+    #sendCaption(wav) {
+        if (this.#captionUploads >= 3)
+            return; // network can't keep up: skip rather than lag
+        this.#captionUploads++;
+        fetch(`${this.#roomEndpoint()}/captions`, {
+            method: "POST",
+            headers: { [TOKEN_HEADER]: this.#token, "Content-Type": "audio/wav" },
+            body: wav,
+        })
+            .then(async (res) => {
+            if (!res.ok && res.status !== 409) {
+                const body = (await res.json().catch(() => ({})));
+                this.emit("error", new Error(`captions: ${body.error ?? "HTTP " + res.status}`));
+            }
+        })
+            .catch(() => { })
+            .finally(() => this.#captionUploads--);
+    }
+    #addCaptionLine(line, translation) {
+        if (this.#captionLines.some((l) => l.seq === line.seq))
+            return;
+        this.#captionLines.push(line);
+        if (this.#captionLines.length > 200)
+            this.#captionLines.shift();
+        this.emit("caption", line, translation);
+    }
+    #fileEndpoint(fileId) {
+        return `${this.#opts.url}/rooms/${encodeURIComponent(this.roomId)}/files/${encodeURIComponent(fileId)}`;
+    }
+    #addFile(file) {
+        if (this.#files.has(file.id))
+            return;
+        this.#files.set(file.id, file);
+        this.emit("file-shared", file);
+    }
+    #removeFile(id) {
+        if (this.#files.delete(id))
+            this.emit("file-removed", id);
+    }
+    /** Swap in a fresh token before the current one expires. */
+    updateToken(token) {
+        const claims = decodeClaims(token);
+        if (claims.room !== this.roomId || claims.sub !== this.userId) {
+            throw new Error("new token is for a different room or user");
+        }
+        this.#token = token;
+        this.#headers.set(TOKEN_HEADER, token);
+        this.#send({ type: "token", token }); // the room keeps this connection past the old expiry
+        this.#scheduleTokenWarning(claims.exp);
+    }
+    #scheduleTokenWarning(exp) {
+        if (this.#tokenTimer)
+            clearTimeout(this.#tokenTimer);
+        const ms = exp * 1000 - Date.now() - 60_000;
+        // setTimeout can't take > ~24.8 days; tokens are ≤ 24h anyway.
+        this.#tokenTimer = setTimeout(() => !this.#left && this.emit("token-expiring", exp), Math.max(0, Math.min(ms, 2 ** 31 - 1)));
+    }
+    /**
+     * Choose how much video you want from one participant: "high" | "medium" |
+     * "low" | "off" (audio only for them). Adaptive limits can still lower it.
+     */
+    setVideoQuality(participantId, quality) {
+        const entry = this.#remotes.get(participantId);
+        if (!entry)
+            return;
+        entry.requested = quality;
+        this.#applyQuality(entry);
+    }
+    /**
+     * Keep a participant's received video matched to the size of the element
+     * showing it (ResizeObserver). Returns a function that stops watching.
+     */
+    fitVideoQuality(participantId, el) {
+        if (typeof ResizeObserver === "undefined")
+            return () => { };
+        const update = () => {
+            const h = el.getBoundingClientRect().height * (globalThis.devicePixelRatio || 1);
+            this.setVideoQuality(participantId, qualityForHeight(h));
+        };
+        const ro = new ResizeObserver(update);
+        ro.observe(el);
+        update();
+        return () => ro.disconnect();
+    }
+    /**
+     * Audio-only mode: stop receiving everyone's camera video and turn your own
+     * camera off. Screen shares still come through. Turning it off restores both.
+     */
+    setAudioOnly(on) {
+        if (on === this.#audioOnly || (!on && this.#opts.mode === "audio"))
+            return;
+        const before = this.#chosenAudioOnly();
+        this.#audioOnly = on;
+        this.#afterAudioOnlyChange(before);
+    }
+    /** Audio only by choice: setAudioOnly(true), mode "audio" or the "audio" data saver. See also audioFallback. */
+    get audioOnly() {
+        return this.#chosenAudioOnly();
+    }
+    /**
+     * Data saver for costly or weak mobile data. A preset ("off", "low",
+     * "minimal", "audio") or custom settings, e.g.
+     * `{ base: "low", activeSpeakerVideo: 2 }`. Applies straight away, both to
+     * what you send and what you receive. Your choice is shown to others as
+     * participant.state.dataSaver.
+     */
+    setDataSaver(input) {
+        const next = resolveDataSaver(input);
+        if (this.#left)
+            return;
+        const before = this.#chosenAudioOnly();
+        this.#saver = next;
+        this.#updateMicEncodings();
+        this.#afterAudioOnlyChange(before);
+        this.emit("data-saver", next.mode, { ...next.settings });
+    }
+    /** The current data-saver mode and what it does. */
+    get dataSaver() {
+        return { mode: this.#saver.mode, settings: { ...this.#saver.settings } };
+    }
+    /** True while your connection has fallen back to audio only (see "audio-fallback"). */
+    get audioFallback() {
+        return this.#fallback.active;
+    }
+    /**
+     * Turn the audio-first fallback on or off during the call. Turning it off
+     * while it's active brings video back now.
+     */
+    setAudioFallback(enabled) {
+        this.#fallbackOn = enabled;
+        if (!enabled && this.#fallback.active) {
+            this.#fallback = { ...this.#fallback, active: false, good: 0, lastRecoveredAt: Date.now() };
+            this.#afterFallbackChange();
+        }
+    }
+    /**
+     * Media data used in this call so far (uploaded + downloaded, as measured by
+     * WebRTC), the current rates and a per-hour projection. Updated every
+     * statsIntervalMs; also see the "data-usage" event and estimateDataUsage().
+     */
+    get dataUsage() {
+        return { ...this.#usage.usage };
+    }
+    #chosenAudioOnly() {
+        return this.#audioOnly || this.#saver.settings.audioOnly;
+    }
+    /** Camera on/off around audio-only by choice, then re-apply everything. */
+    #afterAudioOnlyChange(before) {
+        const now = this.#chosenAudioOnly();
+        if (now && !before) {
+            this.#cameraBeforeAudioOnly = this.#wanted.camera;
+            this.setCamera(false);
+        }
+        else if (!now && before && this.#cameraBeforeAudioOnly && this.#opts.mode !== "audio") {
+            this.setCamera(true);
+        }
+        this.#refreshVideoAllow(false);
+        this.#applyAllQualities();
+        this.#updateCameraEncodings();
+        this.#sendLowBandwidthState();
+    }
+    #afterFallbackChange() {
+        if (!this.#fallback.active) {
+            // Come back gently: start low and let the adaptive logic climb.
+            this.#adaptive = { ...initialAdaptiveState(), receiveCap: "low" };
+        }
+        this.#applyAllQualities();
+        this.#updateCameraEncodings();
+        this.#updateMicEncodings();
+        this.#sendLowBandwidthState();
+        this.emit("audio-fallback", this.#fallback.active);
+    }
+    #applyAllQualities() {
+        for (const entry of this.#remotes.values()) {
+            this.#applyQuality(entry);
+            this.#syncPulls(entry);
+        }
+    }
+    #lowBandwidthState() {
+        const mode = this.#saver.mode === "custom" ? "low" : this.#saver.mode;
+        return {
+            audioOnly: this.#chosenAudioOnly() || this.#fallback.active,
+            audioFallback: this.#fallback.active,
+            dataSaver: mode,
+        };
+    }
+    #sendLowBandwidthState() {
+        const next = this.#lowBandwidthState();
+        const cur = this.#localState;
+        if (cur.audioOnly === next.audioOnly && cur.audioFallback === next.audioFallback && cur.dataSaver === next.dataSaver)
+            return;
+        this.#localState = { ...cur, ...next };
+        this.#send({ type: "state", state: next });
+        this.emit("local-state", this.localState);
+    }
+    #micEncodings() {
+        const cap = micBitrateCap(this.#saver.settings.maxAudioBitrate, this.#fallback.active);
+        return [cap > 0 ? { maxBitrate: cap } : {}];
+    }
+    #updateMicEncodings() {
+        const next = this.#micEncodings();
+        if (JSON.stringify(next) !== JSON.stringify(this.#micEncodings$.value))
+            this.#micEncodings$.next(next);
+        this.#syncSenders();
+    }
+    /**
+     * Make our senders match the data saver / fallback / adaptive state. Sets
+     * the parameters directly, keeping the encodings the browser negotiated
+     * (it may drop simulcast layers for small cameras, or have none). Also run
+     * on every stats sample, so a rebuilt connection gets the same settings.
+     */
+    #syncSenders() {
+        const pc = this.#pc;
+        if (!pc || this.#left)
+            return;
+        const s = this.#saver.settings;
+        for (const sender of pc.getSenders()) {
+            const t = sender.track;
+            if (!t)
+                continue;
+            let params;
+            try {
+                params = sender.getParameters();
+            }
+            catch {
+                continue;
+            }
+            const current = params.encodings ?? [];
+            if (!current.length)
+                continue;
+            let planned;
+            if (t.kind === "audio" && this.#micTrack && (t === this.#micTrack || (!!t.label && t.label === this.#micTrack.label))) {
+                planned = this.#micEncodings();
+            }
+            else if (t.kind === "video" && this.#isCameraTrack(t)) {
+                const rids = current.map((e) => e.rid).filter((r) => r === "f" || r === "h" || r === "q");
+                const simulcast = rids.length > 1;
+                const height = t.getSettings?.().height ?? 720;
+                const plan = cameraEncodings(simulcast, s, this.#cameraSending, height, simulcast ? rids : undefined);
+                planned = plan.encodings;
+                if (simulcast)
+                    this.#announceLayers(plan.layers);
+            }
+            else
+                continue;
+            const merged = mergeEncodings(current, planned);
+            if (merged)
+                sender.setParameters({ ...params, encodings: merged }).catch(() => { });
+        }
+    }
+    /** partytracks may hand the sender its own copy of the camera track: match by device label too. */
+    #isCameraTrack(t) {
+        const cam = this.#localPreview.video;
+        if (!cam)
+            return false;
+        if (t === cam)
+            return true;
+        const screen = this.#localPreview.screenVideo;
+        if (screen && (t === screen || t.label === screen.label))
+            return false;
+        return !!t.label && t.label === cam.label;
+    }
+    #announceLayers(layers) {
+        if (layers.join() === this.#cameraLayers.join())
+            return;
+        this.#cameraLayers = layers;
+        const v = this.#localTracks.video;
+        if (v) {
+            v.layers = [...layers];
+            this.#send({ type: "tracks", tracks: { video: v } });
+        }
+    }
+    /** Camera encodings and announced layers from adaptive + fallback + data saver. */
+    #updateCameraEncodings() {
+        const s = this.#saver.settings;
+        const sending = this.#adaptive.sendVideo && !this.#fallback.active && !s.audioOnly && s.maxSendHeight !== 0;
+        const enc$ = this.#cameraEncodings$;
+        const changed = sending !== this.#cameraSending;
+        this.#cameraSending = sending;
+        this.#syncSenders();
+        if (changed) {
+            if (enc$) {
+                this.#localState = { ...this.#localState, videoPaused: !sending };
+                this.#send({ type: "state", state: { videoPaused: !sending } });
+                this.emit("video-paused", null, !sending);
+                this.emit("local-state", this.localState);
+            }
+        }
+    }
+    /**
+     * Data saver with activeSpeakerVideo: work out whose camera video we take.
+     * Re-applies qualities when the set changes (unless `apply` is false).
+     */
+    #refreshVideoAllow(apply = true) {
+        const n = this.#saver.settings.activeSpeakerVideo;
+        const present = [...this.#remotes.keys()];
+        const spot = new Set(this.roomState.spotlight ?? []);
+        const always = [...this.#remotes.values()].filter((e) => spot.has(e.participant.userId)).map((e) => e.participant.id);
+        this.#recentSpeakers = this.#recentSpeakers.filter((id) => this.#remotes.has(id));
+        const next = videoAllowList(n, this.#recentSpeakers, present, always);
+        const same = next === this.#videoAllow || (!!next && !!this.#videoAllow && next.size === this.#videoAllow.size && [...next].every((id) => this.#videoAllow.has(id)));
+        this.#videoAllow = next;
+        if (!same && apply)
+            this.#applyAllQualities();
+        return !same;
+    }
+    /** Highest video quality the adaptive logic currently allows you to receive. */
+    get receiveCap() {
+        return this.#adaptive.receiveCap;
+    }
+    /** Participant ids currently speaking, loudest first (includes room.self.id). */
+    get activeSpeakers() {
+        return this.#speakers.active(Date.now());
+    }
+    /** Connection rating for a participant (use room.self.id for yourself). */
+    getConnectionQuality(participantId) {
+        if (participantId === this.self?.id)
+            return this.#myQuality ?? undefined;
+        return this.#qualities.get(participantId);
+    }
+    /** Latest connection measurement (updated every statsIntervalMs). */
+    get linkStats() {
+        return this.#lastSample;
+    }
+    /** Leave the room, stop camera/mic and clean everything up. */
+    leave(reason = "left") {
+        if (this.#left)
+            return;
+        this.#left = true;
+        if (this.#reconnectTimer)
+            clearTimeout(this.#reconnectTimer);
+        if (this.#pingTimer)
+            clearInterval(this.#pingTimer);
+        if (this.#tokenTimer)
+            clearTimeout(this.#tokenTimer);
+        this.#watchNetwork(false);
+        if (this.#statsTimer)
+            clearInterval(this.#statsTimer);
+        if (this.#speakerTimer)
+            clearInterval(this.#speakerTimer);
+        if (this.#levelTimer)
+            clearInterval(this.#levelTimer);
+        void this.#audioCtx?.close().catch(() => { });
+        try {
+            this.#ws?.close(1000, "leaving");
+        }
+        catch {
+            /* ignore */
+        }
+        this.#ws = null;
+        for (const id of [...this.#remotes.keys()])
+            this.#removeRemote(id);
+        this.media.mic?.stopBroadcasting();
+        this.media.camera?.stopBroadcasting();
+        this.media.screen?.stopBroadcasting();
+        this.media.mic?.disableSource();
+        this.media.camera?.disableSource();
+        this.media.screen?.disableSource();
+        this.#e2ee?.close();
+        if (this.#stateTimer)
+            clearTimeout(this.#stateTimer);
+        for (const sub of Object.values(this.#deviceSubs))
+            sub?.unsubscribe();
+        this.#subs.unsubscribe();
+        void this.#capture?.stop();
+        this.#setConnection("disconnected");
+        this.emit("left", reason);
+        this.removeAllListeners();
+    }
+    // ---------------- startup ----------------
+    /** @internal */
+    async _start() {
+        this.#watchNetwork(true);
+        this.#scheduleTokenWarning(decodeClaims(this.#token).exp);
+        if (this.#e2ee)
+            await this.#e2ee.setKey(this.#opts.e2ee.key, this.#opts.e2ee.keyIndex ?? 0, true);
+        await new Promise((resolve, reject) => {
+            const startTimer = () => setTimeout(() => {
+                reject(new Error("timed out joining room"));
+                this.leave("join-timeout");
+            }, this.#opts.joinTimeoutMs);
+            let timer = startTimer();
+            this.#onWaiting = () => {
+                if (timer)
+                    clearTimeout(timer);
+                timer = null;
+                this.#opts.onWaiting?.();
+                this.emit("waiting");
+            };
+            this.#connect({
+                onWelcome: () => {
+                    if (timer)
+                        clearTimeout(timer);
+                    resolve();
+                },
+                onFatal: (reason) => {
+                    if (timer)
+                        clearTimeout(timer);
+                    reject(new Error(reason));
+                },
+            });
+        });
+        // partytracks fetches ICE servers without custom headers, so we fetch them
+        // ourselves (authenticated) and pass them in. TURN credentials last 24h.
+        const iceServers = this.#opts.iceServers ?? (await this.#fetchIceServers());
+        if (this.#left)
+            return;
+        this.media.partyTracks = new PartyTracks({
+            prefix: `${this.#opts.url}/partytracks`,
+            headers: this.#headers,
+            iceServers,
+        });
+        // Encrypt/decrypt transforms go on each transceiver as partytracks creates it,
+        // before negotiation, so no frame ever leaves unencrypted.
+        const e2ee = this.#e2ee;
+        if (e2ee) {
+            this.#subs.add(this.media.partyTracks.transceiver$.subscribe((t) => {
+                try {
+                    e2ee.attach(t);
+                }
+                catch (err) {
+                    this.emit("error", err instanceof Error ? err : new Error(String(err)));
+                }
+            }));
+        }
+        this.#mediaReady = true;
+        this.#startMedia();
+        // Pull tracks of people who were already publishing when we joined.
+        for (const entry of this.#remotes.values())
+            this.#syncPulls(entry);
+    }
+    async #fetchIceServers() {
+        try {
+            const res = await fetch(`${this.#opts.url}/partytracks/generate-ice-servers`, { headers: this.#headers });
+            if (!res.ok)
+                throw new Error(`HTTP ${res.status}`);
+            const body = (await res.json());
+            if (Array.isArray(body.iceServers) && body.iceServers.length)
+                return body.iceServers;
+            throw new Error("no ICE servers in response");
+        }
+        catch (err) {
+            this.emit("error", new Error(`Could not load ICE servers, using public STUN only (${String(err)})`));
+            return [{ urls: ["stun:stun.cloudflare.com:3478", "stun:stun.cloudflare.com:53"] }];
+        }
+    }
+    #startMedia() {
+        const pt = this.media.partyTracks;
+        this.#subs.add(pt.peerConnectionState$.subscribe((s) => {
+            this.#mediaState = s;
+            if (s === "connected")
+                this.#mediaEverConnected = true;
+            this.#updateConnection();
+            this.emit("media-connection", s);
+            if (s === "disconnected" || s === "failed")
+                this.#setMyQuality("lost");
+        }));
+        this.#subs.add(pt.sessionError$.subscribe((e) => this.emit("error", new Error(e))));
+        this.#subs.add(pt.peerConnection$.subscribe((pc) => (this.#pc = pc)));
+        this.#startStats();
+        this.#speakerTimer = setInterval(() => this.#emitSpeakersIfChanged(), 300);
+        for (const group of ["mic", "camera", "screen"]) {
+            if (this.permissions[group])
+                this.#enableDevice(group);
+        }
+    }
+    /** Create a device and start pushing it. Only for groups we're allowed to publish. */
+    #enableDevice(group) {
+        if (this.#deviceSubs[group] || !this.#mediaReady || this.#left)
+            return;
+        // Voice calls never open the camera (and never ask for permission).
+        if (group === "camera" && this.#opts.mode === "audio")
+            return;
+        const pt = this.media.partyTracks;
+        const simulcast = this.#opts.simulcast ?? true;
+        const subs = new Subscription();
+        this.#deviceSubs[group] = subs;
+        // Publish a track; announce its metadata to the room.
+        const announce = (kind, meta$, active$) => {
+            const source$ = active$
+                ? combineLatest([meta$, active$]).pipe(map(([m, on]) => (on ? m : null)))
+                : meta$;
+            subs.add(source$.subscribe((meta) => {
+                const clean = meta?.trackName && meta.sessionId
+                    ? { location: "remote", trackName: meta.trackName, sessionId: meta.sessionId }
+                    : null;
+                if (clean && kind === "video" && simulcast)
+                    clean.layers = [...this.#cameraLayers];
+                this.#localTracks[kind] = clean;
+                this.#send({ type: "tracks", tracks: { [kind]: clean } });
+            }));
+        };
+        const watch = (on$) => subs.add(on$.subscribe((on) => {
+            this.#broadcasting[group] = on;
+            this.#scheduleState();
+            if (group === "mic")
+                this.#syncCaptions();
+        }));
+        if (group === "screen") {
+            const screen = getScreenshare({ audio: true, video: true });
+            this.media.screen = screen;
+            subs.add(screen.video.error$.subscribe((e) => this.emit("error", e)));
+            subs.add(combineLatest([screen.video.broadcastTrack$, screen.video.isBroadcasting$]).subscribe(([t, on]) => this.#emitLocal("screenVideo", on ? t : null)));
+            announce("screenVideo", pt.push(screen.video.broadcastTrack$), screen.video.isBroadcasting$);
+            announce("screenAudio", pt.push(screen.audio.broadcastTrack$), screen.audio.isBroadcasting$);
+            watch(screen.isBroadcasting$);
+            return;
+        }
+        const label = group === "mic" ? "microphone" : "camera";
+        const d = group === "mic"
+            ? getMic({
+                broadcasting: this.#wanted.microphone,
+                transformations: this.#audioTransform ? [this.#audioTransform] : [],
+            })
+            : getCamera({
+                broadcasting: this.#wanted.camera,
+                transformations: this.#videoTransform ? [this.#videoTransform] : [],
+                ...(simulcast ? { constraints: CAMERA_CONSTRAINTS } : {}),
+            });
+        if (group === "mic")
+            this.media.mic = d;
+        else
+            this.media.camera = d;
+        // A camera/mic can fail to start for a moment (busy, still waking up, OS
+        // permission dialog). partytracks then gives up and turns it off, so retry
+        // a few times before telling the app.
+        //
+        // The retry rebuilds the device from scratch: partytracks' device stream
+        // can stay in a failed state (seen on Windows: the track is stopped ~15s
+        // after starting and the device list never recovers), so restarting the
+        // same device object isn't enough.
+        const attempts = this.#deviceAttempts[group] ?? 0;
+        let healthyTimer = null;
+        subs.add(() => healthyTimer && clearTimeout(healthyTimer));
+        subs.add(d.isBroadcasting$.subscribe((on) => {
+            if (healthyTimer)
+                clearTimeout(healthyTimer);
+            if (on)
+                healthyTimer = setTimeout(() => (this.#deviceAttempts[group] = 0), DEVICE_HEALTHY_MS);
+        }));
+        subs.add(d.error$.subscribe((e) => {
+            if (this.#left || this.#deviceSubs[group] !== subs)
+                return;
+            if (!this.#wanted[label])
+                return;
+            if (attempts < DEVICE_RETRIES) {
+                this.#deviceAttempts[group] = attempts + 1;
+                setTimeout(() => {
+                    if (this.#left || this.#deviceSubs[group] !== subs || !this.#wanted[label])
+                        return;
+                    if (!this.permissions[group])
+                        return;
+                    this.#disableDevice(group);
+                    this.#enableDevice(group);
+                }, DEVICE_RETRY_MS * 2 ** attempts);
+                return;
+            }
+            this.#deviceAttempts[group] = 0;
+            const err = new Error(`Could not start the ${label} (${e.name}${e.message ? ": " + e.message : ""})`);
+            err.name = e.name;
+            this.emit("error", err);
+        }));
+        if (group === "camera")
+            subs.add(d.broadcastTrack$.subscribe((t) => this.#emitLocal("video", t)));
+        if (group === "mic") {
+            announce("audio", pt.push(d.broadcastTrack$, { sendEncodings$: this.#micEncodings$ }));
+            this.#startLevelMeter(d.broadcastTrack$, subs);
+            subs.add(d.broadcastTrack$.subscribe((t) => {
+                this.#micTrack = t;
+                this.#syncCaptions();
+            }));
+            subs.add(() => {
+                this.#micTrack = null;
+                this.#syncCaptions();
+            });
+        }
+        else {
+            // Camera: simulcast layers; the encodings stream also pauses/resumes sending.
+            const s = this.#saver.settings;
+            const on = this.#adaptive.sendVideo && !this.#fallback.active && !s.audioOnly && s.maxSendHeight !== 0;
+            const { encodings, layers } = cameraEncodings(simulcast, s, on);
+            this.#cameraSending = on;
+            this.#cameraLayers = layers;
+            // Without limits, a non-simulcast camera starts with the browser's defaults.
+            const initial = !simulcast && on && encodings.length === 1 && Object.keys(encodings[0]).length === 1 ? [] : encodings;
+            this.#cameraEncodings$ = new BehaviorSubject(initial);
+            announce("video", pt.push(d.broadcastTrack$, { sendEncodings$: this.#cameraEncodings$ }));
+            subs.add(() => (this.#cameraEncodings$ = null));
+        }
+        watch(d.isBroadcasting$);
+    }
+    /** Stop a device we're no longer allowed to publish, and unpublish its tracks. */
+    #disableDevice(group) {
+        const subs = this.#deviceSubs[group];
+        if (!subs)
+            return;
+        delete this.#deviceSubs[group];
+        const d = group === "mic" ? this.media.mic : group === "camera" ? this.media.camera : this.media.screen;
+        d?.stopBroadcasting();
+        subs.unsubscribe(); // closes the pushed tracks
+        d?.disableSource();
+        if (group === "mic")
+            this.media.mic = null;
+        else if (group === "camera")
+            this.media.camera = null;
+        else
+            this.media.screen = null;
+        const cleared = {};
+        for (const kind of GROUP_KINDS[group]) {
+            delete this.#localTracks[kind];
+            cleared[kind] = null;
+        }
+        this.#send({ type: "tracks", tracks: cleared });
+        if (group === "camera")
+            this.#emitLocal("video", null);
+        if (group === "screen")
+            this.#emitLocal("screenVideo", null);
+        this.#broadcasting[group] = false;
+        this.#scheduleState();
+    }
+    /** Mic/camera/screen on/off, sent once things settle (devices flip together). */
+    #scheduleState() {
+        if (this.#stateTimer)
+            clearTimeout(this.#stateTimer);
+        this.#stateTimer = setTimeout(() => {
+            this.#stateTimer = null;
+            if (this.#left)
+                return;
+            const { mic: micOn, camera: cameraOn, screen: screenOn } = this.#broadcasting;
+            const e2ee = this.#e2ee ? true : undefined;
+            this.#localState = { ...this.#localState, micOn, cameraOn, screenOn, custom: this.#customState, ...(e2ee ? { e2ee } : {}) };
+            this.#send({ type: "state", state: { micOn, cameraOn, screenOn, ...(e2ee ? { e2ee } : {}) } });
+            this.emit("local-state", this.localState);
+        }, 50);
+    }
+    #applyRole(next) {
+        if (!next || next === this.role)
+            return;
+        const previous = this.role;
+        this.role = next;
+        this.emit("role", next, previous);
+    }
+    #applyPermissions(next) {
+        const previous = this.permissions;
+        this.permissions = { ...next };
+        if (!this.#mediaReady)
+            return; // _start() enables devices from this.permissions
+        for (const group of ["mic", "camera", "screen"]) {
+            if (next[group] && !this.#deviceSubs[group])
+                this.#enableDevice(group);
+            if (!next[group] && this.#deviceSubs[group])
+                this.#disableDevice(group);
+        }
+        if (JSON.stringify(previous) !== JSON.stringify(next))
+            this.emit("permissions", this.permissions, previous);
+    }
+    // ---------------- adaptive quality ----------------
+    #startStats() {
+        const every = this.#opts.statsIntervalMs ?? 2000;
+        this.#statsTimer = setInterval(() => void this.#sampleStats(), every);
+    }
+    async #sampleStats() {
+        if (this.#left)
+            return;
+        let pc;
+        try {
+            pc = await firstValueFrom(this.media.partyTracks.peerConnection$);
+        }
+        catch {
+            return;
+        }
+        if (pc.connectionState !== "connected")
+            return;
+        const report = await pc.getStats();
+        if (this.#left)
+            return;
+        this.#syncSenders();
+        const bytes = bytesFromStats(report);
+        if (bytes) {
+            this.#usage = nextUsage(this.#usage, bytes, Date.now());
+            this.emit("data-usage", this.dataUsage);
+        }
+        const { sample, cursor } = sampleFromStats(report, this.#statsCursor);
+        const first = this.#statsCursor === null;
+        this.#statsCursor = cursor;
+        if (first)
+            return; // need two readings for a loss rate
+        this.#lastSample = sample;
+        this.#setMyQuality(connectionQualityFromSample(sample));
+        if (this.#opts.adaptive !== false) {
+            const prev = this.#adaptive;
+            this.#adaptive = nextAdaptiveState(prev, sample);
+            if (this.#adaptive.receiveCap !== prev.receiveCap) {
+                for (const entry of this.#remotes.values())
+                    this.#applyQuality(entry);
+            }
+            if (this.#adaptive.sendVideo !== prev.sendVideo)
+                this.#updateCameraEncodings();
+        }
+        if (this.#fallbackOn) {
+            const was = this.#fallback.active;
+            this.#fallback = nextFallbackState(this.#fallback, sample, this.#adaptive, Date.now());
+            if (this.#fallback.active !== was)
+                this.#afterFallbackChange();
+        }
+    }
+    // ---------------- active speaker ----------------
+    /** Measure our own mic level (Web Audio) and share it while speaking. */
+    #startLevelMeter(track$, subs) {
+        if (typeof AudioContext === "undefined")
+            return;
+        if (this.#levelSource) {
+            // Mic re-enabled (permission given back): reuse the meter, follow the new track.
+            subs.add(track$.subscribe((t) => this.#levelSource(t)));
+            return;
+        }
+        const ctx = new AudioContext();
+        this.#audioCtx = ctx;
+        if (ctx.state === "suspended" && typeof document !== "undefined") {
+            // Some browsers only start audio after a user gesture.
+            const resume = () => void ctx.resume().catch(() => { });
+            document.addEventListener("pointerdown", resume, { once: true });
+            document.addEventListener("keydown", resume, { once: true });
+            void ctx.resume().catch(() => { });
+        }
+        const analyser = ctx.createAnalyser();
+        analyser.fftSize = 1024;
+        const buf = new Float32Array(analyser.fftSize);
+        let source = null;
+        this.#levelSource = (t) => {
+            if (ctx.state === "closed")
+                return;
+            source?.disconnect();
+            source = ctx.createMediaStreamSource(new MediaStream([t]));
+            source.connect(analyser);
+        };
+        subs.add(track$.subscribe((t) => this.#levelSource(t)));
+        this.#levelTimer = setInterval(() => {
+            if (this.#left || !this.self)
+                return;
+            analyser.getFloatTimeDomainData(buf);
+            const level = this.#localState.micOn ? rmsLevel(buf) : 0;
+            const now = Date.now();
+            const flipped = this.#vad.update(level, now);
+            if (this.#vad.speaking && (flipped || now - this.#lastLevelSentAt >= SPEAKER.sendEveryMs)) {
+                const shared = Math.max(level, 0.01);
+                this.#send({ type: "speaking", level: shared });
+                this.#lastLevelSentAt = now;
+                this.#speakers.set(this.self.id, shared, now);
+            }
+            else if (flipped && !this.#vad.speaking) {
+                this.#send({ type: "speaking", level: 0 });
+                this.#speakers.set(this.self.id, 0, now);
+            }
+            this.#emitSpeakersIfChanged();
+        }, 100);
+    }
+    #emitSpeakersIfChanged() {
+        const changed = this.#speakers.changed(Date.now());
+        if (!changed)
+            return;
+        this.emit("active-speakers", changed);
+        if (this.#saver.settings.activeSpeakerVideo > 0) {
+            const talking = changed.filter((id) => this.#remotes.has(id));
+            if (talking.length) {
+                this.#recentSpeakers = [...talking, ...this.#recentSpeakers.filter((id) => !talking.includes(id))].slice(0, 16);
+                this.#refreshVideoAllow();
+            }
+        }
+    }
+    #setMyQuality(q) {
+        if (q === this.#myQuality)
+            return;
+        this.#myQuality = q;
+        this.#localState = { ...this.#localState, connectionQuality: q };
+        this.#send({ type: "state", state: { connectionQuality: q } });
+        if (this.self)
+            this.emit("connection-quality", this.self.id, q);
+    }
+    #effectiveQuality(entry) {
+        if (this.#chosenAudioOnly() || this.#fallback.active)
+            return "off";
+        const cap = this.#opts.adaptive === false ? "high" : this.#adaptive.receiveCap;
+        const q = minQuality(minQuality(entry.requested, cap), this.#saver.settings.maxReceiveQuality);
+        if (this.#videoAllow && !this.#videoAllow.has(entry.participant.id))
+            return "off";
+        return q;
+    }
+    #layerFor(entry, q) {
+        return pickLayer(QUALITY_TO_LAYER[q], entry.meta.video.value?.layers);
+    }
+    #applyQuality(entry) {
+        const next = this.#effectiveQuality(entry);
+        const prev = entry.effective;
+        if (next === prev)
+            return;
+        entry.effective = next;
+        if (next !== "off")
+            entry.layer$.next(this.#layerFor(entry, next));
+        this.#syncPulls(entry);
+        if ((prev === "off") !== (next === "off") && entry.meta.video.value) {
+            this.emit("video-paused", entry.participant, next === "off");
+        }
+        this.emit("video-quality", entry.participant, next);
+    }
+    // ---------------- room WebSocket ----------------
+    #connect(hooks) {
+        const wsUrl = this.#opts.url.replace(/^http/, "ws") +
+            `/rooms/${encodeURIComponent(this.roomId)}/ws?token=${encodeURIComponent(this.#token)}`;
+        const ws = new WebSocket(wsUrl);
+        this.#ws = ws;
+        let welcomed = false;
+        ws.onmessage = (ev) => {
+            this.#lastServerMsgAt = Date.now();
+            let msg;
+            try {
+                msg = JSON.parse(String(ev.data));
+            }
+            catch {
+                return;
+            }
+            try {
+                this.#onMessage(ws, msg, hooks, () => (welcomed = true));
+            }
+            catch (err) {
+                // Never let a handler bug silently stall the join.
+                this.emit("error", err instanceof Error ? err : new Error(String(err)));
+            }
+        };
+        ws.onclose = (ev) => this.#handleDrop(ws, ev.code, welcomed, hooks);
+    }
+    /** The room WebSocket closed (or we declared it dead). Decide: give up, or retry. */
+    #handleDrop(ws, code, welcomed, hooks) {
+        if (this.#pingTimer)
+            clearInterval(this.#pingTimer);
+        if (this.#left || ws !== this.#ws)
+            return;
+        this.#ws = null;
+        const fatal = closeReason(code);
+        if (fatal) {
+            hooks?.onFatal(fatal);
+            this.leave(fatal);
+            return;
+        }
+        if (!welcomed && hooks && this.#attempt === 0 && this.#signalLostAt === null) {
+            hooks.onFatal("could not connect to room");
+            this.leave("connect-failed");
+            return;
+        }
+        this.#signalUp = false;
+        this.#signalLostAt ??= Date.now();
+        this.#updateConnection();
+        const timeout = this.#opts.reconnectTimeoutMs ?? 120_000;
+        if (!this.#opts.reconnect || Date.now() - this.#signalLostAt > timeout) {
+            this.leave("connection-lost");
+            return;
+        }
+        this.#scheduleReconnect();
+    }
+    #scheduleReconnect(delay) {
+        if (this.#reconnectTimer)
+            clearTimeout(this.#reconnectTimer);
+        // While the browser says it's offline, wait for the "online" event instead.
+        if (typeof navigator !== "undefined" && navigator.onLine === false && delay === undefined) {
+            this.#reconnectTimer = setTimeout(() => this.#scheduleReconnect(), 5000);
+            return;
+        }
+        const wait = delay ?? Math.min(500 * 2 ** this.#attempt, 8000) * (0.8 + Math.random() * 0.4);
+        this.#attempt++;
+        this.#reconnectTimer = setTimeout(() => {
+            this.#reconnectTimer = null;
+            if (this.#left)
+                return;
+            const timeout = this.#opts.reconnectTimeoutMs ?? 120_000;
+            if (this.#signalLostAt !== null && Date.now() - this.#signalLostAt > timeout) {
+                this.leave("connection-lost");
+                return;
+            }
+            this.#connect();
+        }, wait);
+    }
+    /** Network came back / changed: don't wait for timers, check and reconnect now. */
+    #networkChanged(kind) {
+        if (this.#left)
+            return;
+        if (kind === "offline") {
+            this.#updateConnection(true);
+            return;
+        }
+        if (!this.#signalUp) {
+            this.#attempt = 0;
+            this.#scheduleReconnect(0);
+        }
+        else {
+            // The socket may be silently dead after switching networks: probe it.
+            this.#send({ type: "ping" });
+            this.#lastServerMsgAt = Math.min(this.#lastServerMsgAt, Date.now() - PING_EVERY_MS);
+        }
+        this.#updateConnection();
+    }
+    #watchNetwork(on) {
+        if (typeof window === "undefined")
+            return;
+        const conn = navigator.connection;
+        const fn = on ? "addEventListener" : "removeEventListener";
+        window[fn]("online", this.#onOnline);
+        window[fn]("offline", this.#onOffline);
+        conn?.[fn]("change", this.#onConnChange);
+    }
+    /** Combine room + media state into one ConnectionState. */
+    #updateConnection(offline = false) {
+        if (this.#left)
+            return;
+        const mediaDown = this.#mediaEverConnected && (this.#mediaState === "disconnected" || this.#mediaState === "failed");
+        if (this.#signalUp && !mediaDown && !offline) {
+            this.#setConnection("connected");
+        }
+        else if (this.#signalLostAt !== null || mediaDown || offline) {
+            this.#setConnection("reconnecting");
+        }
+    }
+    #onMessage(ws, msg, hooks, markWelcomed) {
+        if (msg.type === "welcome") {
+            markWelcomed();
+            this.#attempt = 0;
+            this.#signalUp = true;
+            this.#signalLostAt = null;
+            this.self = msg.self;
+            this.#applyRole(msg.self.role);
+            if (msg.self.permissions)
+                this.#applyPermissions(msg.self.permissions);
+            if (msg.room)
+                this.#setRoomState(msg.room);
+            this.#setRecording(msg.recording ?? null);
+            try {
+                this.#reconcile(msg.participants);
+            }
+            catch (err) {
+                this.emit("error", err instanceof Error ? err : new Error(String(err)));
+            }
+            this.#checkHands();
+            // Re-announce our state after a reconnect. State first: it says whether we
+            // encrypt, which rooms that require encryption check before taking tracks.
+            this.#send({ type: "state", state: { ...this.#localState, custom: this.#customState } });
+            if (Object.keys(this.#localTracks).length)
+                this.#send({ type: "tracks", tracks: this.#localTracks });
+            if (this.#captionLanguage)
+                this.#send({ type: "caption-language", language: this.#captionLanguage });
+            this.#updateConnection();
+            if (this.connectionState === "connecting")
+                this.#setConnection("connected");
+            this.#startPing(ws);
+            hooks?.onWelcome();
+            return;
+        }
+        if (msg.type === "bye") {
+            const fatal = closeReason(msg.code) ?? "closed-by-server";
+            this.#ws = null; // ignore the close event that follows
+            try {
+                ws.close();
+            }
+            catch {
+                /* ignore */
+            }
+            hooks?.onFatal(fatal);
+            this.leave(fatal);
+            return;
+        }
+        this.#handle(msg);
+    }
+    /** Keep-alive + dead-socket detection (a socket can stay "open" after a network switch). */
+    #startPing(ws) {
+        if (this.#pingTimer)
+            clearInterval(this.#pingTimer);
+        this.#lastServerMsgAt = Date.now();
+        this.#pingTimer = setInterval(() => {
+            if (ws !== this.#ws)
+                return;
+            if (Date.now() - this.#lastServerMsgAt > PING_EVERY_MS * 2.5) {
+                try {
+                    ws.close();
+                }
+                catch {
+                    /* ignore */
+                }
+                this.#handleDrop(ws, 1006, true);
+                return;
+            }
+            this.#send({ type: "ping" });
+        }, PING_EVERY_MS);
+    }
+    #handle(msg) {
+        switch (msg.type) {
+            case "participant-joined":
+                this.#upsertRemote(msg.participant, true);
+                this.#checkHands();
+                break;
+            case "participant-updated":
+                this.#upsertRemote(msg.participant, false);
+                this.#checkHands();
+                break;
+            case "participant-left":
+                this.#removeRemote(msg.id);
+                this.#checkHands();
+                break;
+            case "chat":
+                this.#addChat(msg.message);
+                break;
+            case "chat-history":
+                for (const m of msg.messages)
+                    this.#addChat(m);
+                break;
+            case "chat-deleted":
+                if (this.chat.some((m) => m.id === msg.id)) {
+                    this.chat = this.chat.filter((m) => m.id !== msg.id);
+                    this.emit("chat-deleted", msg.id);
+                }
+                break;
+            case "waiting":
+                this.#onWaiting?.();
+                break;
+            case "group-changed": {
+                if (this.self)
+                    this.self = { ...this.self, group: msg.group };
+                this.#reconcile(msg.participants);
+                this.#checkHands();
+                this.emit("group-changed", msg.group);
+                break;
+            }
+            case "attendance": {
+                const waiters = this.#attendanceWaiters.splice(0);
+                for (const w of waiters)
+                    w(msg.report);
+                break;
+            }
+            case "waiting-list":
+                this.waiting = msg.waiting;
+                this.emit("waiting-list", msg.waiting);
+                break;
+            case "room-updated":
+                this.#setRoomState(msg.room);
+                break;
+            case "muted": {
+                for (const d of msg.devices) {
+                    if (d === "mic")
+                        this.setMic(false);
+                    else if (d === "camera")
+                        this.setCamera(false);
+                    else if (d === "screen")
+                        this.media.screen?.stopBroadcasting();
+                }
+                this.emit("muted", msg.devices, msg.by ? this.#remotes.get(msg.by)?.participant : undefined);
+                break;
+            }
+            case "self-updated": {
+                this.self = msg.self;
+                this.emit("self", msg.self);
+                this.#checkHands();
+                this.#applyRole(msg.self.role);
+                const prev = this.permissions;
+                this.#applyPermissions(msg.self.permissions);
+                // _start() not done yet: still tell the app.
+                if (!this.#mediaReady && JSON.stringify(prev) !== JSON.stringify(msg.self.permissions)) {
+                    this.emit("permissions", this.permissions, prev);
+                }
+                break;
+            }
+            case "broadcast":
+                this.#onBroadcast(msg.from, msg.data, { topic: msg.topic ?? null, private: msg.private === true });
+                break;
+            case "speaking":
+                this.#speakers.set(msg.from, msg.level, Date.now());
+                this.#emitSpeakersIfChanged();
+                break;
+            case "recording":
+                this.#setRecording(msg.recording);
+                break;
+            case "transcript":
+                this.emit("transcript", msg.segment);
+                break;
+            case "lesson":
+                this.#lessons.set(msg.lesson.lessonId, msg.lesson);
+                this.emit("lesson", msg.lesson);
+                break;
+            case "lesson-ended":
+                if (this.#lessons.delete(msg.lessonId))
+                    this.emit("lesson-ended", msg.lessonId);
+                break;
+            case "lesson-alert":
+                this.emit("lesson-alert", msg.lessonId, msg.alert);
+                break;
+            case "ai-flag":
+                this.emit("ai-flag", msg.agentId, msg.flag);
+                break;
+            case "ai-minutes":
+                this.emit("ai-minutes", msg.agentId, msg.minutes);
+                break;
+            case "reaction":
+                this.emit("reaction", msg.emoji, msg.from === this.self?.id ? null : (this.#remotes.get(msg.from)?.participant ?? null), msg.at);
+                break;
+            case "file-shared":
+                this.#addFile(msg.file);
+                break;
+            case "file-removed":
+                this.#removeFile(msg.id);
+                break;
+            case "poll":
+                this.#polls.set(msg.poll.id, msg.poll);
+                this.emit("poll", msg.poll);
+                break;
+            case "poll-removed":
+                this.#myVotes.delete(msg.id);
+                if (this.#polls.delete(msg.id))
+                    this.emit("poll-removed", msg.id);
+                break;
+            case "poll-voted": {
+                this.#myVotes.set(msg.pollId, msg.choices);
+                const poll = this.#polls.get(msg.pollId);
+                if (poll)
+                    this.emit("poll", poll);
+                break;
+            }
+            case "question":
+                this.#questions.set(msg.question.id, msg.question);
+                this.emit("question", msg.question);
+                break;
+            case "question-removed":
+                this.#myUpvotes.delete(msg.id);
+                if (this.#questions.delete(msg.id))
+                    this.emit("question-removed", msg.id);
+                break;
+            case "question-upvoted": {
+                if (msg.up)
+                    this.#myUpvotes.add(msg.id);
+                else
+                    this.#myUpvotes.delete(msg.id);
+                const q = this.#questions.get(msg.id);
+                if (q)
+                    this.emit("question", q);
+                break;
+            }
+            case "captions-state":
+                this.#captionsState = msg.captions;
+                this.#syncCaptions();
+                this.emit("captions", this.captions);
+                break;
+            case "caption":
+                this.#addCaptionLine(msg.line, msg.translation);
+                break;
+            case "summary":
+                this.#summary = msg.summary;
+                this.emit("summary", msg.summary);
+                break;
+            case "engage-state": {
+                const st = msg.state;
+                if (st.captions) {
+                    this.#captionsState = st.captions;
+                    this.#syncCaptions();
+                    this.emit("captions", this.captions);
+                }
+                for (const l of st.recentCaptions ?? [])
+                    this.#addCaptionLine(l);
+                if (st.summary) {
+                    this.#summary = st.summary;
+                    this.emit("summary", st.summary);
+                }
+                const ids = new Set(st.files.map((f) => f.id));
+                for (const id of [...this.#files.keys()])
+                    if (!ids.has(id))
+                        this.#removeFile(id);
+                for (const f of st.files)
+                    this.#addFile(f);
+                this.#myVotes = new Map(Object.entries(st.myVotes ?? {}));
+                this.#myUpvotes = new Set(st.myUpvotes ?? []);
+                const pollIds = new Set((st.polls ?? []).map((p) => p.id));
+                for (const id of [...this.#polls.keys()])
+                    if (!pollIds.has(id) && this.#polls.delete(id))
+                        this.emit("poll-removed", id);
+                for (const p of st.polls ?? []) {
+                    this.#polls.set(p.id, p);
+                    this.emit("poll", p);
+                }
+                const qIds = new Set((st.questions ?? []).map((q) => q.id));
+                for (const id of [...this.#questions.keys()])
+                    if (!qIds.has(id) && this.#questions.delete(id))
+                        this.emit("question-removed", id);
+                for (const q of st.questions ?? []) {
+                    this.#questions.set(q.id, q);
+                    this.emit("question", q);
+                }
+                break;
+            }
+            case "error":
+                this.emit("error", new Error(msg.message));
+                break;
+            case "pong":
+            case "bye":
+                break;
+        }
+    }
+    #addChat(m) {
+        if (this.chat.some((x) => x.id === m.id))
+            return; // history after a reconnect
+        this.chat.push(m);
+        this.chat.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+        if (this.chat.length > 200)
+            this.chat.splice(0, this.chat.length - 200);
+        this.emit("chat", m);
+    }
+    #handsKey = "";
+    /** Emit `hands` when the queue changed. */
+    #checkHands() {
+        const list = this.raisedHands;
+        const key = list.map((p) => `${p.id}@${p.handRaisedAt}`).join(",");
+        if (key === this.#handsKey)
+            return;
+        this.#handsKey = key;
+        this.emit("hands", list);
+    }
+    #onBroadcast(from, data, info) {
+        const e2ee = this.#e2ee;
+        if (!e2ee) {
+            if (isEncryptedMessage(data))
+                this.emit("encryption-error", "missing-key", "received an encrypted message; dropped");
+            else
+                this.emit("message", data, this.#remotes.get(from)?.participant, info);
+            return;
+        }
+        if (!isEncryptedMessage(data)) {
+            this.emit("encryption-error", "not-encrypted", "received a message that isn't end-to-end encrypted; dropped");
+            return;
+        }
+        e2ee.decryptMessage(data).then((plain) => !this.#left && this.emit("message", plain, this.#remotes.get(from)?.participant, info), (err) => !this.#left && this.emit("encryption-error", err.e2ee ?? "decrypt-failed", err.message));
+    }
+    #setRoomState(state) {
+        const changed = JSON.stringify(state) !== JSON.stringify(this.roomState);
+        const spotChanged = JSON.stringify(state.spotlight ?? []) !== JSON.stringify(this.roomState.spotlight ?? []);
+        this.roomState = { ...state };
+        if (spotChanged)
+            this.#refreshVideoAllow();
+        if (changed)
+            this.emit("room-state", this.roomState);
+    }
+    #setRecording(next) {
+        if (this.recording?.id === next?.id)
+            return;
+        this.recording = next;
+        this.emit("recording", next);
+    }
+    #send(msg) {
+        if (this.#ws?.readyState === WebSocket.OPEN)
+            this.#ws.send(JSON.stringify(msg));
+    }
+    #setConnection(state) {
+        if (this.connectionState === state)
+            return;
+        this.connectionState = state;
+        this.emit("connection", state);
+    }
+    // ---------------- remote participants ----------------
+    #reconcile(list) {
+        const ids = new Set(list.map((p) => p.id));
+        for (const id of [...this.#remotes.keys()])
+            if (!ids.has(id))
+                this.#removeRemote(id);
+        for (const p of list)
+            this.#upsertRemote(p, !this.#remotes.has(p.id));
+    }
+    #upsertRemote(p, isNew) {
+        let entry = this.#remotes.get(p.id);
+        if (!entry) {
+            entry = {
+                participant: p,
+                meta: Object.fromEntries(TRACK_KINDS.map((k) => [k, new BehaviorSubject(null)])),
+                pulls: {},
+                tracks: {},
+                audioEls: {},
+                requested: "high",
+                effective: "high",
+                layer$: new BehaviorSubject("f"),
+                subscribed: {},
+            };
+            this.#remotes.set(p.id, entry);
+            const allowChanged = this.#refreshVideoAllow(false);
+            entry.effective = this.#effectiveQuality(entry);
+            if (allowChanged)
+                this.#applyAllQualities();
+        }
+        const prevAgentState = isNew ? undefined : entry.participant.agent?.state;
+        entry.participant = p;
+        if (isNew)
+            this.emit("participant-joined", p);
+        else
+            this.emit("participant-updated", p);
+        const q = p.state.connectionQuality;
+        if (q && q !== this.#qualities.get(p.id)) {
+            this.#qualities.set(p.id, q);
+            this.emit("connection-quality", p.id, q);
+        }
+        if (p.agent && p.agent.state !== prevAgentState)
+            this.emit("agent-state", p, p.agent.state);
+        for (const kind of TRACK_KINDS)
+            entry.meta[kind].next(p.tracks[kind] ?? null);
+        // Publishers on a data saver announce fewer layers: ask for one they send.
+        if (entry.effective !== "off") {
+            const layer = this.#layerFor(entry, entry.effective);
+            if (layer !== entry.layer$.value)
+                entry.layer$.next(layer);
+        }
+        this.#syncPulls(entry);
+    }
+    #syncPulls(entry) {
+        if (!this.#mediaReady)
+            return;
+        for (const kind of TRACK_KINDS) {
+            let meta = entry.meta[kind].value;
+            if (kind === "video" && entry.effective === "off")
+                meta = null; // audio-only for this participant
+            if (kind === "screenVideo" && this.#fallback.active && !this.#keepScreenInFallback)
+                meta = null;
+            const want = !!meta && this.#wants(entry, kind);
+            if (want && !entry.pulls[kind])
+                this.#pull(entry, kind);
+            if (!want && entry.pulls[kind])
+                this.#stopPull(entry, kind);
+        }
+    }
+    #pull(entry, kind) {
+        const meta$ = entry.meta[kind].pipe(filter((m) => m !== null), distinctUntilChanged((a, b) => a.sessionId === b.sessionId && a.trackName === b.trackName), 
+        // Only what the SFU API understands (our own fields like `layers` stay out).
+        map((m) => ({ location: "remote", trackName: m.trackName, sessionId: m.sessionId })));
+        // Simulcast publishers: ask for the layer we need; changes go to tracks/update.
+        const simulcast = kind === "video" && entry.meta.video.value?.layers?.length ? { preferredRid$: entry.layer$ } : undefined;
+        entry.pulls[kind] = this.media.partyTracks.pull(meta$, simulcast ? { simulcast } : {}).subscribe({
+            next: (track) => {
+                entry.tracks[kind] = track;
+                if (this.#opts.autoPlayAudio && (kind === "audio" || kind === "screenAudio")) {
+                    this.#playAudio(entry, kind, track);
+                }
+                this.emit("track", entry.participant, kind, track);
+            },
+            error: (err) => this.emit("error", err instanceof Error ? err : new Error(String(err))),
+        });
+    }
+    #stopPull(entry, kind) {
+        entry.pulls[kind]?.unsubscribe();
+        delete entry.pulls[kind];
+        delete entry.tracks[kind];
+        const el = entry.audioEls[kind];
+        if (el) {
+            el.srcObject = null;
+            el.remove();
+            delete entry.audioEls[kind];
+        }
+        this.emit("track-removed", entry.participant, kind);
+    }
+    #removeRemote(id) {
+        const entry = this.#remotes.get(id);
+        if (!entry)
+            return;
+        for (const kind of TRACK_KINDS)
+            if (entry.pulls[kind])
+                this.#stopPull(entry, kind);
+        for (const s of Object.values(entry.meta))
+            s.complete();
+        entry.layer$.complete();
+        this.#remotes.delete(id);
+        this.#qualities.delete(id);
+        this.#speakers.remove(id);
+        this.#refreshVideoAllow();
+        this.emit("participant-left", entry.participant);
+    }
+    #playAudio(entry, kind, track) {
+        if (typeof document === "undefined")
+            return;
+        let el = entry.audioEls[kind];
+        if (!el) {
+            el = document.createElement("audio");
+            el.autoplay = true;
+            el.style.display = "none";
+            el.dataset.sfukit = `${entry.participant.id}:${kind}`;
+            document.body.appendChild(el);
+            entry.audioEls[kind] = el;
+            this.#applySink(el);
+        }
+        el.srcObject = new MediaStream([track]);
+        el.play().catch(() => {
+            this.emit("error", new Error("Browser blocked audio autoplay. Call room.resumeAudio() from a click."));
+        });
+    }
+    /** Retry playing remote audio after a user gesture (if autoplay was blocked). */
+    resumeAudio() {
+        for (const r of this.#remotes.values())
+            for (const el of Object.values(r.audioEls))
+                void el?.play().catch(() => { });
+    }
+}
+// ---------------- helpers ----------------
+/** Attach a track to a <video> or <audio> element. */
+export function attachTrack(el, track) {
+    el.srcObject = track ? new MediaStream([track]) : null;
+    if (track && el instanceof HTMLVideoElement) {
+        el.playsInline = true;
+        el.autoplay = true;
+    }
+    if (track)
+        void el.play().catch(() => { });
+}
+/** Read (not verify) the claims in a join token. */
+export function decodeClaims(token) {
+    const part = token.split(".")[1];
+    if (!part)
+        throw new Error("invalid join token");
+    const json = atob(part.replace(/-/g, "+").replace(/_/g, "/").padEnd(Math.ceil(part.length / 4) * 4, "="));
+    const claims = JSON.parse(new TextDecoder().decode(Uint8Array.from(json, (c) => c.charCodeAt(0))));
+    if (!claims.room || !claims.sub)
+        throw new Error("invalid join token");
+    return claims;
+}
+function closeReason(code) {
+    switch (code) {
+        case CloseCodes.Kicked:
+            return "kicked";
+        case CloseCodes.RoomFull:
+            return "room-full";
+        case CloseCodes.Unauthorized:
+            return "unauthorized";
+        case CloseCodes.RoomClosed:
+            return "room-closed";
+        case CloseCodes.RoomLocked:
+            return "room-locked";
+        case CloseCodes.Denied:
+            return "denied";
+        default:
+            return null;
+    }
+}
+//# sourceMappingURL=index.js.map