@ksp-gonogo/kerbcast 1.4.0

package/dist/client.js

@@ -0,0 +1,821 @@
+import { CameraLifecycle, ErrorSource } from "./__generated__/types";
+import { tryCreateNoisePipeline } from "./noise";
+/** Intensity the static runs at when a camera has no live source (signal lost). */
+const SOURCELESS_INTENSITY = 1.0;
+/** Floor applied to the degrade-driven intensity of a live feed. */
+const LIVE_INTENSITY_FLOOR = 0.05;
+export class BrowserKerbcastTransport {
+    constructor(opts = {}) {
+        this.opts = { iceGatheringTimeoutMs: opts.iceGatheringTimeoutMs ?? 2000 };
+    }
+    createPeer(iceServers) {
+        const pc = new RTCPeerConnection({ iceServers });
+        const { iceGatheringTimeoutMs } = this.opts;
+        let trackIdx = 0;
+        let onTrack = null;
+        let onStateChange = null;
+        pc.ontrack = (ev) => {
+            // ev.transceiver.mid is the stable m-line id the sidecar keys its
+            // SlotMap on; it's set by the time ontrack fires (post-answer).
+            onTrack?.(ev.track, trackIdx++, ev.transceiver.mid ?? "");
+        };
+        pc.onconnectionstatechange = () => {
+            onStateChange?.(mapPeerState(pc.connectionState));
+        };
+        return {
+            addRecvOnlyTransceiver: () => {
+                pc.addTransceiver("video", { direction: "recvonly" });
+            },
+            createDataChannel: (label) => wrapBrowserDataChannel(pc.createDataChannel(label)),
+            onTrack: (h) => {
+                onTrack = h;
+            },
+            onStateChange: (h) => {
+                onStateChange = h;
+            },
+            createOffer: async () => {
+                const offer = await pc.createOffer();
+                return offer.sdp ?? "";
+            },
+            setLocalDescription: async (sdp) => {
+                await pc.setLocalDescription({ type: "offer", sdp });
+            },
+            setRemoteAnswer: async (sdp) => {
+                await pc.setRemoteDescription({ type: "answer", sdp });
+            },
+            waitForIceComplete: () => new Promise((resolve) => {
+                if (pc.iceGatheringState === "complete") {
+                    resolve();
+                    return;
+                }
+                let timer = null;
+                const cleanup = () => {
+                    pc.removeEventListener("icegatheringstatechange", check);
+                    if (timer !== null) {
+                        clearTimeout(timer);
+                        timer = null;
+                    }
+                };
+                const check = () => {
+                    if (pc.iceGatheringState === "complete") {
+                        cleanup();
+                        resolve();
+                    }
+                };
+                timer = setTimeout(() => {
+                    timer = null;
+                    cleanup();
+                    resolve();
+                }, iceGatheringTimeoutMs);
+                pc.addEventListener("icegatheringstatechange", check);
+            }),
+            localSdp: () => pc.localDescription?.sdp ?? "",
+            getStats: () => pc.getStats(null),
+            close: () => {
+                pc.close();
+            },
+        };
+    }
+}
+function wrapBrowserDataChannel(dc) {
+    let onOpen = null;
+    let onMessage = null;
+    let onClose = null;
+    dc.onopen = () => onOpen?.();
+    dc.onclose = () => onClose?.();
+    dc.onmessage = (ev) => {
+        if (typeof ev.data === "string")
+            onMessage?.(ev.data);
+    };
+    return {
+        send: (s) => {
+            dc.send(s);
+        },
+        onOpen: (h) => {
+            onOpen = h;
+        },
+        onMessage: (h) => {
+            onMessage = h;
+        },
+        onClose: (h) => {
+            onClose = h;
+        },
+    };
+}
+function mapPeerState(state) {
+    switch (state) {
+        case "new":
+        case "connecting":
+            return "connecting";
+        case "connected":
+            return "connected";
+        case "failed":
+            return "failed";
+        case "disconnected":
+        case "closed":
+            return "disconnected";
+    }
+}
+// No bound on E so consumers can use `interface` declarations
+// (interfaces don't carry an implicit string index signature, so
+// `extends Record<string, unknown>` would reject them).
+class TypedEmitter {
+    constructor() {
+        this.listeners = new Map();
+    }
+    on(event, handler) {
+        let set = this.listeners.get(event);
+        if (!set) {
+            set = new Set();
+            this.listeners.set(event, set);
+        }
+        set.add(handler);
+        return () => {
+            set?.delete(handler);
+        };
+    }
+    emit(event, data) {
+        const set = this.listeners.get(event);
+        set?.forEach((h) => h(data));
+    }
+}
+// ---------------------------------------------------------------------------
+// Camera handle implementation
+// ---------------------------------------------------------------------------
+class CameraHandle extends TypedEmitter {
+    constructor(flightId, client) {
+        super();
+        this._state = null;
+        this._mediaStream = null;
+        this._rawStream = null;
+        this._noisePipeline = null;
+        this._noiseOverride = null;
+        /**
+         * True while the handle has no live source but is still showing static
+         * (signal-loss / camera-switch gap). Distinct from a true teardown, where
+         * the pipeline is destroyed and `_mediaStream` goes null. While sourceless,
+         * intensity is pinned at full and degrade updates must not lower it.
+         */
+        this._sourceless = false;
+        /** Stall state mirrored from the pipeline's onStallChange callback. */
+        this._stalled = false;
+        /** Whether animated static is drawn; survives pipeline rebuilds. */
+        this._showStatic = true;
+        this.flightId = flightId;
+        this.client = client;
+    }
+    get state() {
+        return this._state;
+    }
+    get mediaStream() {
+        return this._mediaStream;
+    }
+    get stalled() {
+        return this._stalled;
+    }
+    get showStatic() {
+        return this._showStatic;
+    }
+    configure(options) {
+        this._noiseOverride = options.noise ?? null;
+        // Re-evaluate with the new noise setting: rebuild from whatever source
+        // state we're currently in (live, sourceless, or torn down).
+        this._applySource(this._rawStream);
+    }
+    setShowStatic(enabled) {
+        this._showStatic = enabled;
+        this._noisePipeline?.setShowStatic(enabled);
+    }
+    /**
+     * Internal — called by the client when CameraState pushes arrive. Returns
+     * `true` when this update resurrected the camera (Destroyed -> Active), so
+     * the client can re-source the handle from its retained track.
+     */
+    _setState(state) {
+        const prevDestroyed = this._state?.lifecycle === CameraLifecycle.Destroyed;
+        this._state = state;
+        this.emit("change", state);
+        // A destroyed camera stops forwarding frames but its track never ends, so
+        // nothing else drives the handle into the sourceless state — do it here.
+        if (state.lifecycle === CameraLifecycle.Destroyed) {
+            if (!this._sourceless || !prevDestroyed)
+                this._applySource(null);
+            return false;
+        }
+        // Live feed: degrade drives intensity. Don't touch a sourceless pipeline,
+        // which is pinned at full static.
+        if (!this._sourceless) {
+            this._noisePipeline?.setIntensity(this._liveIntensity());
+        }
+        // Resurrection: KSP reused this part.flightID after a revert, so the
+        // sidecar tombstoned then re-attached the SAME camera and rebound the SAME
+        // track with no new slot-map. The handle went sourceless on destroy and
+        // only re-sources on a slot-map, so signal the client to re-source it from
+        // the track it still holds.
+        return prevDestroyed;
+    }
+    /**
+     * Internal — called by the client when a track arrives or drops.
+     * A null stream does NOT tear down: if a pipeline can run, the handle keeps
+     * emitting live full-intensity static (signal-loss / camera-switch gap).
+     * Use {@link _teardown} for genuine teardown (disconnect / peer failure).
+     */
+    _setMediaStream(stream) {
+        this._applySource(stream);
+    }
+    /**
+     * Drive the persistent pipeline to a given source (or sourceless static when
+     * `raw` is null). Creates the pipeline lazily on first need and reuses it
+     * thereafter so the output stream stays stable across source swaps.
+     */
+    _applySource(raw) {
+        this._rawStream = raw;
+        this._sourceless = raw === null;
+        const noiseEnabled = this.client._resolveNoise(this._noiseOverride);
+        if (noiseEnabled) {
+            // Reuse an existing pipeline; otherwise try to create one.
+            if (!this._noisePipeline) {
+                const initial = raw ? this._liveIntensity() : SOURCELESS_INTENSITY;
+                this._noisePipeline = tryCreateNoisePipeline(raw, initial, {
+                    showStatic: this._showStatic,
+                    onStallChange: (stalled) => this._setStalled(stalled),
+                });
+            }
+            else {
+                this._noisePipeline.setSource(raw);
+            }
+            const pipeline = this._noisePipeline;
+            if (pipeline) {
+                pipeline.setIntensity(raw ? this._liveIntensity() : SOURCELESS_INTENSITY);
+                this._setOutput(pipeline.processedStream);
+                return;
+            }
+        }
+        else if (this._noisePipeline) {
+            // Noise just got disabled — drop the pipeline and fall through to raw.
+            this._noisePipeline.destroy();
+            this._noisePipeline = null;
+            this._setStalled(false);
+        }
+        // Noise disabled, or captureStream unavailable (no pipeline creatable):
+        // expose the raw stream directly, or null when there's no source.
+        this._setOutput(raw);
+    }
+    _setOutput(stream) {
+        this._mediaStream = stream;
+        this.emit("stream", stream);
+    }
+    _setStalled(stalled) {
+        if (this._stalled === stalled)
+            return;
+        this._stalled = stalled;
+        this.emit("stall", stalled);
+    }
+    _liveIntensity() {
+        return Math.max(LIVE_INTENSITY_FLOOR, this._state?.degradeLevel ?? 0);
+    }
+    /**
+     * Internal — genuine teardown (client disconnect / peer failure). Destroys
+     * the persistent pipeline, stops its rAF loop, and nulls the stream.
+     */
+    _teardown() {
+        this._noisePipeline?.destroy();
+        this._noisePipeline = null;
+        this._rawStream = null;
+        this._sourceless = false;
+        this._setStalled(false);
+        this._setOutput(null);
+    }
+    async setLayers(layers) {
+        await this.client._send({
+            type: "set-layers",
+            content: { flightId: this.flightId, layers },
+        });
+    }
+    async setRenderSize(width, height) {
+        await this.client._send({
+            type: "set-render-size",
+            content: { flightId: this.flightId, width, height },
+        });
+    }
+    async setFov(fov) {
+        await this.client._send({
+            type: "set-fov",
+            content: { flightId: this.flightId, fov },
+        });
+    }
+    async setPan(yaw, pitch) {
+        await this.client._send({
+            type: "set-pan",
+            content: { flightId: this.flightId, yaw, pitch },
+        });
+    }
+    async setPanRate(yawRate, pitchRate) {
+        await this.client._send({
+            type: "set-pan-rate",
+            content: { flightId: this.flightId, yawRate, pitchRate },
+        });
+    }
+    async setZoomRate(rate) {
+        await this.client._send({
+            type: "set-zoom-rate",
+            content: { flightId: this.flightId, rate },
+        });
+    }
+    async setDegrade(level) {
+        await this.client._send({
+            type: "set-degrade",
+            content: { flightId: this.flightId, level },
+        });
+    }
+    async setQuality(preset) {
+        await this.client._send({
+            type: "set-quality",
+            // null (auto) deserializes to None on the sidecar; the generated
+            // payload type marks the field optional, so widen for the wire.
+            content: { flightId: this.flightId, preset: preset ?? undefined },
+        });
+    }
+    async requestKeyframe() {
+        await this.client._send({
+            type: "request-keyframe",
+            content: { flightId: this.flightId },
+        });
+    }
+}
+// ---------------------------------------------------------------------------
+// KerbcastClient
+// ---------------------------------------------------------------------------
+/**
+ * High-level kerbcast sidecar client. Owns the WebRTC peer + the
+ * `kerbcast-control` data channel + the per-camera registry + the
+ * `MediaStream`s for each subscribed camera.
+ *
+ * Usage:
+ *
+ * ```ts
+ * const client = new KerbcastClient({ host: "192.168.1.74", port: 8088 });
+ * await client.connect();
+ *
+ * const cam = client.camera(2592004302);
+ * await cam.setFov(35);
+ * videoEl.srcObject = cam.mediaStream;
+ *
+ * cam.on("change", (state) => { ... });
+ * client.on("adaptive-shed", (event) => { ... });
+ * ```
+ *
+ * Disconnect with {@link disconnect}. The handles returned by
+ * `camera()` remain valid across reconnects; their `mediaStream`
+ * goes null on disconnect and is replaced when the next connect's
+ * tracks arrive.
+ */
+export class KerbcastClient extends TypedEmitter {
+    constructor(cfg, transport) {
+        super();
+        this.peer = null;
+        this.control = null;
+        this._state = "disconnected";
+        this._cameras = [];
+        this.handles = new Map();
+        this.requestedOrder = [];
+        /** Set when `connect` is given an explicit slot pool. Switches track
+         *  routing from legacy index order to mid-keyed dynamic slots. */
+        this.dynamicMode = false;
+        /** Dynamic mode: transceiver mid -> the live track on that slot. */
+        this.trackByMid = new Map();
+        /** Dynamic mode: transceiver mid -> the camera bound to that slot
+         *  (populated by SlotMap -- initial bindings announced on Hello). */
+        this.flightByMid = new Map();
+        /**
+         * Legacy mode: raw incoming track id -> flightId. Populated in handleTrack
+         * so inboundVideoStats() can match inbound-rtp report entries by
+         * trackIdentifier. Cleared on disconnect. Not used in dynamic mode (which
+         * matches by mid instead).
+         */
+        this.flightByTrackId = new Map();
+        /** Sidecar version reported on `Hello`; null before handshake. */
+        this._sidecarVersion = null;
+        this._encoderBackend = null;
+        /** Last-received throttle state from `settings-state`. False until the first push. */
+        this._throttleMainScreen = false;
+        /**
+         * Mission-time capture clock from `settings-state`. `_captureUt` is null
+         * until the first clock arrives (and against an old sidecar that never
+         * sends one), so consumers treat it as "no clock". `_captureEpoch` bumps
+         * on discontinuities (revert / quickload / scene reload); only the change
+         * is meaningful. `_warpRate` defaults to 1 when the field is absent.
+         */
+        this._captureUt = null;
+        this._captureEpoch = 0;
+        this._warpRate = 1;
+        this.cfg = cfg;
+        this.transport =
+            transport ??
+                new BrowserKerbcastTransport({
+                    iceGatheringTimeoutMs: cfg.iceGatheringTimeoutMs,
+                });
+    }
+    get state() {
+        return this._state;
+    }
+    get cameras() {
+        return this._cameras;
+    }
+    get sidecarVersion() {
+        return this._sidecarVersion;
+    }
+    get encoderBackend() {
+        return this._encoderBackend;
+    }
+    /**
+     * Current effective state of the "Throttle KSP main render" setting.
+     * Reflects what the plugin has applied (from `settings-state` messages),
+     * not just what was last requested. False until the first push arrives.
+     */
+    get throttleMainScreen() {
+        return this._throttleMainScreen;
+    }
+    /**
+     * Mission-time capture clock, from the sidecar's ~1Hz `settings-state`.
+     * `captureUt` is the KSP universal time (seconds) the current video was
+     * captured at, or null when no clock is known (old plugin/sidecar, or
+     * before the first push). `epoch` bumps on a UT discontinuity so a
+     * consumer can flush and resync. `warpRate` lets a consumer interpolate
+     * `captureUt` between samples; defaults to 1.
+     */
+    get clock() {
+        return {
+            captureUt: this._captureUt,
+            epoch: this._captureEpoch,
+            warpRate: this._warpRate,
+        };
+    }
+    /**
+     * Send a `set-throttle-main-screen` command to the sidecar, which writes
+     * `global.control.json` for the plugin to apply. The plugin persists the
+     * change in the per-save difficulty parameter. The resulting
+     * `settings-state` broadcast reflects the applied value.
+     */
+    async setThrottleMainScreen(enabled) {
+        await this._send({
+            type: "set-throttle-main-screen",
+            content: { enabled },
+        });
+    }
+    /**
+     * Pre-handshake camera discovery via the sidecar's HTTP `/cameras`
+     * endpoint. Useful when the consumer wants to pick which cameras
+     * to subscribe to before opening a peer connection.
+     */
+    async discover() {
+        const res = await fetch(`http://${this.cfg.host}:${this.cfg.port}/cameras`);
+        if (!res.ok)
+            throw new Error(`/cameras returned ${res.status}`);
+        const body = (await res.json());
+        return body.cameras;
+    }
+    /**
+     * Open the WebRTC peer and subscribe to cameras. Idempotent: calling
+     * `connect` while already connected disconnects first.
+     *
+     * Two modes:
+     * - **Legacy** (no `opts.slots`): one transceiver per requested camera;
+     *   an empty array subscribes to every currently-known camera. Tracks
+     *   route by m-line index. Unchanged behaviour.
+     * - **Dynamic** (`opts.slots` set): negotiates a pool of `opts.slots`
+     *   recv-only video slots. `requestedCameras` are the *initial*
+     *   subscription bound to the first slots; spare slots are filled at
+     *   runtime via {@link subscribe}. Tracks route by transceiver mid
+     *   (the sidecar announces bindings via SlotMap), so switching a slot's
+     *   camera needs no renegotiation.
+     */
+    async connect(requestedCameras = [], opts = {}) {
+        this.disconnect();
+        this.setState("connecting");
+        this.requestedOrder = [...requestedCameras];
+        this.dynamicMode = opts.slots !== undefined;
+        this.trackByMid.clear();
+        this.flightByMid.clear();
+        this.flightByTrackId.clear();
+        const peer = this.transport.createPeer(this.cfg.iceServers ?? [{ urls: "stun:stun.l.google.com:19302" }]);
+        this.peer = peer;
+        // Slot-pool size = the recv-only transceivers we offer. Dynamic mode
+        // uses the explicit pool size (spares subscribable at runtime); legacy
+        // uses one per requested camera (>=1).
+        const slotCount = this.dynamicMode
+            ? Math.max(opts.slots ?? 0, 1)
+            : Math.max(this.requestedOrder.length, 1);
+        for (let i = 0; i < slotCount; i++) {
+            peer.addRecvOnlyTransceiver();
+        }
+        peer.onTrack((track, idx, mid) => this.handleTrack(track, idx, mid));
+        peer.onStateChange((s) => {
+            this.setState(s);
+            if (s === "disconnected" || s === "failed") {
+                this.tearDownStreams();
+            }
+        });
+        this.control = peer.createDataChannel("kerbcast-control");
+        this.control.onOpen(() => {
+            void this._send({ type: "hello" });
+        });
+        this.control.onMessage((raw) => {
+            this.handleServerMessage(raw);
+        });
+        this.control.onClose(() => {
+            // Channel closure usually follows peer disconnect; the peer
+            // state-change handler covers the tear-down. Nothing to do here.
+        });
+        await peer.createOffer().then((sdp) => peer.setLocalDescription(sdp));
+        await peer.waitForIceComplete();
+        const body = {
+            sdp: peer.localSdp(),
+            cameras: this.requestedOrder,
+        };
+        if (this.dynamicMode)
+            body.slots = slotCount;
+        let answer;
+        try {
+            answer = await (this.cfg.negotiate
+                ? this.cfg.negotiate(body)
+                : this.httpNegotiate(body));
+        }
+        catch (err) {
+            this.setState("failed");
+            throw err;
+        }
+        await peer.setRemoteAnswer(answer.sdp);
+        // Legacy mode routes by index → requestedOrder, so realign to what the
+        // sidecar actually wired. Dynamic mode routes by mid via SlotMap (initial
+        // bindings arrive on Hello), so the answer's camera list isn't used.
+        if (!this.dynamicMode) {
+            this.requestedOrder = answer.cameras;
+        }
+    }
+    /** Default signaling: POST the offer to the sidecar's HTTP `/offer`. */
+    async httpNegotiate(offer) {
+        const res = await fetch(`http://${this.cfg.host}:${this.cfg.port}/offer`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(offer),
+        });
+        if (!res.ok)
+            throw new Error(`POST /offer returned ${res.status}`);
+        return (await res.json());
+    }
+    disconnect() {
+        this.peer?.close();
+        this.peer = null;
+        this.control = null;
+        this.tearDownStreams();
+        this.setState("disconnected");
+    }
+    /**
+     * Stable per-flight-id handle. Creates a new handle on first call
+     * for a given ID; returns the same handle on subsequent calls.
+     */
+    camera(flightId) {
+        return this.getOrCreateHandle(flightId);
+    }
+    /**
+     * Dynamic mode only: bind a camera to a free slot on the already-connected
+     * peer. The camera's stream appears on its handle once the sidecar answers
+     * with a SlotMap; the sidecar emits an `error` event if no slot is free. No
+     * renegotiation.
+     */
+    async subscribe(flightId) {
+        await this._send({ type: "subscribe", content: { flightId } });
+    }
+    /**
+     * Dynamic mode only: release a camera's slot. Its handle's `mediaStream`
+     * goes null once the sidecar confirms with a SlotMap.
+     */
+    async unsubscribe(flightId) {
+        await this._send({ type: "unsubscribe", content: { flightId } });
+    }
+    /**
+     * Internal — resolves the effective noise enabled state for a camera,
+     * merging the per-camera override (if any) with the client-level default.
+     */
+    _resolveNoise(override) {
+        if (override?.enabled !== undefined)
+            return override.enabled;
+        return this.cfg.noise?.enabled !== false; // default: enabled
+    }
+    /**
+     * Internal — sends a typed `ClientMessage` over the control
+     * channel. Drops silently if the channel hasn't opened yet (and
+     * logs to console). Public on the camera handle, but consumers
+     * shouldn't need to call this directly.
+     */
+    async _send(msg) {
+        if (!this.control) {
+            throw new Error("[kerbcast] control channel not open");
+        }
+        this.control.send(JSON.stringify(msg));
+    }
+    // -- private --
+    getOrCreateHandle(flightId) {
+        let handle = this.handles.get(flightId);
+        if (!handle) {
+            handle = new CameraHandle(flightId, this);
+            this.handles.set(flightId, handle);
+        }
+        return handle;
+    }
+    handleTrack(track, idx, mid) {
+        if (this.dynamicMode) {
+            // Store the slot's track keyed by mid; bind it to a camera if (or once)
+            // a SlotMap names this mid. Track and SlotMap can arrive in either
+            // order — whichever lands second triggers the binding.
+            this.trackByMid.set(mid, track);
+            const flightId = this.flightByMid.get(mid);
+            if (flightId !== undefined) {
+                this.getOrCreateHandle(flightId)._setMediaStream(new MediaStream([track]));
+            }
+            return;
+        }
+        // Legacy: m-line index maps to the requested camera list.
+        const flightId = this.requestedOrder[idx];
+        if (flightId === undefined)
+            return;
+        // Record the raw track id so inboundVideoStats() can match it against
+        // the report's trackIdentifier field.
+        if (track.id)
+            this.flightByTrackId.set(track.id, flightId);
+        this.getOrCreateHandle(flightId)._setMediaStream(new MediaStream([track]));
+    }
+    handleServerMessage(raw) {
+        let msg;
+        try {
+            msg = JSON.parse(raw);
+        }
+        catch (err) {
+            this.emit("error", {
+                message: err instanceof Error ? err.message : String(err),
+                source: ErrorSource.Client,
+            });
+            return;
+        }
+        switch (msg.type) {
+            case "hello":
+                this._sidecarVersion = msg.content.sidecarVersion;
+                this._encoderBackend = msg.content.encoderBackend;
+                break;
+            case "camera-snapshot":
+                this._cameras = msg.content.cameras;
+                for (const cam of this._cameras) {
+                    if (this.getOrCreateHandle(cam.flightId)._setState(cam)) {
+                        this._resourceHandle(cam.flightId);
+                    }
+                }
+                this.emit("cameras-change", this._cameras);
+                break;
+            case "camera-state-changed": {
+                const next = this._cameras.filter((c) => c.flightId !== msg.content.state.flightId);
+                next.push(msg.content.state);
+                next.sort((a, b) => a.flightId - b.flightId);
+                this._cameras = next;
+                if (this.getOrCreateHandle(msg.content.state.flightId)._setState(msg.content.state)) {
+                    this._resourceHandle(msg.content.state.flightId);
+                }
+                this.emit("cameras-change", this._cameras);
+                break;
+            }
+            case "slot-map": {
+                const { mid, flightId } = msg.content;
+                const prev = this.flightByMid.get(mid);
+                if (flightId == null) {
+                    // Slot freed — the camera that held it loses its stream.
+                    if (prev !== undefined) {
+                        this.getOrCreateHandle(prev)._setMediaStream(null);
+                    }
+                    this.flightByMid.delete(mid);
+                }
+                else {
+                    // A switch (a different camera held this slot) clears the old one.
+                    if (prev !== undefined && prev !== flightId) {
+                        this.getOrCreateHandle(prev)._setMediaStream(null);
+                    }
+                    this.flightByMid.set(mid, flightId);
+                    const track = this.trackByMid.get(mid);
+                    if (track) {
+                        this.getOrCreateHandle(flightId)._setMediaStream(new MediaStream([track]));
+                    }
+                    else {
+                        // Bound to a slot but the track hasn't arrived yet (the
+                        // camera-switch gap). Drive the incoming handle sourceless so it
+                        // shows static rather than going blank until the track lands.
+                        this.getOrCreateHandle(flightId)._setMediaStream(null);
+                    }
+                }
+                break;
+            }
+            case "adaptive-shed":
+                this.emit("adaptive-shed", msg.content);
+                break;
+            case "error":
+                this.emit("error", msg.content);
+                break;
+            case "ping":
+                /*
+                 * A ping can race a closing channel (disconnect mid-flight); a
+                 * pong that can't be delivered is moot, not an error.
+                 */
+                void this._send({ type: "pong" }).catch(() => { });
+                this.emit("ping", undefined);
+                break;
+            case "settings-state":
+                this._throttleMainScreen = msg.content.throttleMainScreen;
+                /*
+                 * Capture clock: null captureUt means "no clock" (absent field).
+                 * Epoch is retained across pushes that omit it (only a present
+                 * value updates it); warpRate falls back to 1 when absent.
+                 */
+                this._captureUt = msg.content.captureUt ?? null;
+                if (msg.content.captureEpoch != null) {
+                    this._captureEpoch = msg.content.captureEpoch;
+                }
+                this._warpRate = msg.content.timeWarpRate ?? 1;
+                this.emit("settings-change", msg.content);
+                break;
+        }
+    }
+    /**
+     * Re-source a resurrected camera's handle from the track the client still
+     * holds for its slot. Called when {@link KerbcastCameraHandle._setState}
+     * reports a Destroyed -> Active transition: the sidecar rebinds the same
+     * track without a new slot-map, so nothing else drives the handle back out
+     * of the sourceless (static) state it entered on destroy.
+     */
+    _resourceHandle(flightId) {
+        for (const [mid, boundFlightId] of this.flightByMid) {
+            if (boundFlightId !== flightId)
+                continue;
+            const track = this.trackByMid.get(mid);
+            if (track) {
+                this.getOrCreateHandle(flightId)._setMediaStream(new MediaStream([track]));
+            }
+            return;
+        }
+    }
+    setState(state) {
+        if (this._state === state)
+            return;
+        this._state = state;
+        this.emit("state-change", state);
+    }
+    /**
+     * Inbound RTP video statistics keyed by flight ID. Returns an empty map
+     * when not connected or when the transport does not implement `getStats`.
+     *
+     * Iterates the stats report and matches `inbound-rtp` + `kind === "video"`
+     * entries to cameras. Legacy mode matches by `trackIdentifier`; dynamic
+     * mode falls back to the `mid` field when `trackIdentifier` is absent
+     * (modern browsers include it; some implementations omit it).
+     */
+    async inboundVideoStats() {
+        const result = new Map();
+        if (!this.peer?.getStats)
+            return result;
+        let report;
+        try {
+            report = await this.peer.getStats();
+        }
+        catch {
+            return result;
+        }
+        report.forEach((raw) => {
+            if (raw.type !== "inbound-rtp" || raw.kind !== "video")
+                return;
+            const entry = raw;
+            // Resolve the flightId: trackIdentifier wins (legacy path populated it),
+            // mid fallback covers dynamic mode and browsers that omit trackIdentifier.
+            let flightId;
+            if (entry.trackIdentifier) {
+                flightId = this.flightByTrackId.get(entry.trackIdentifier);
+            }
+            if (flightId === undefined && entry.mid) {
+                flightId = this.flightByMid.get(entry.mid);
+            }
+            if (flightId === undefined)
+                return;
+            result.set(flightId, {
+                packetsReceived: entry.packetsReceived ?? 0,
+                bytesReceived: entry.bytesReceived ?? 0,
+                framesReceived: entry.framesReceived,
+                framesDecoded: entry.framesDecoded,
+                jitter: entry.jitter,
+                framesPerSecond: entry.framesPerSecond,
+            });
+        });
+        return result;
+    }
+    tearDownStreams() {
+        this.flightByTrackId.clear();
+        for (const handle of this.handles.values()) {
+            handle._teardown();
+        }
+    }
+}