@ksp-gonogo/kerbcast 1.7.0 → 1.8.0

package/dist/recording.js

@@ -0,0 +1,898 @@
+/*
+ * Client-side camera recording.
+ *
+ * Records an already-received WebRTC camera track with the browser's
+ * MediaRecorder, annotating the clip with the mission-time (UT) clock so a
+ * consumer can align frames to telemetry. Pure client-side: no sidecar,
+ * plugin, protocol, or network involvement. The sidecar never learns a
+ * recording happened.
+ *
+ * The value-add over a bare MediaRecorder is the UT track: `utStart` /
+ * `utEnd` bracket the clip, and `utSamples` is a ~1Hz series of
+ * (recording-time, UT) points sampled from the client's capture clock, so a
+ * consumer can interpolate any frame's UT near-frame-tight. Out of flight the
+ * clock is unknown, so samples fall back to wall-clock timing (`ut` absent)
+ * and upgrade automatically once UT appears.
+ */
+/**
+ * Bound on the single-recording arm-and-wait: how long
+ * {@link RecordingController.startRecording} waits for a forced feed to
+ * reach full resolution before starting the recorder anyway. Never hangs a
+ * start indefinitely (feed out of flight, wedged, or the sidecar/plugin
+ * round trip taking longer than expected).
+ */
+export const ARM_TIMEOUT_MS = 3000;
+/** Default {@link StopGroupedRecordingOptions.coverageTimeoutMs}. */
+export const DEFAULT_COVERAGE_TIMEOUT_MS = 10000;
+/** Preference order for mime negotiation, after any caller-supplied choice. */
+const MIME_CANDIDATES = [
+    "video/mp4;codecs=avc1",
+    "video/webm;codecs=vp9",
+    "video/webm",
+];
+/**
+ * Pick a MediaRecorder mime type. Tries `preferred` first (when given), then
+ * the standard preference order, using `MediaRecorder.isTypeSupported`. Falls
+ * back to `video/webm` when nothing reports support (or the API is absent).
+ */
+export function negotiateMimeType(preferred) {
+    const ctor = globalThis.MediaRecorder;
+    const candidates = preferred ? [preferred, ...MIME_CANDIDATES] : MIME_CANDIDATES;
+    if (ctor && typeof ctor.isTypeSupported === "function") {
+        for (const candidate of candidates) {
+            if (ctor.isTypeSupported(candidate))
+                return candidate;
+        }
+    }
+    return "video/webm";
+}
+/** Monotonic clock for recording-time. Falls back to Date.now under jsdom. */
+function now() {
+    return typeof performance !== "undefined" && typeof performance.now === "function"
+        ? performance.now()
+        : Date.now();
+}
+/**
+ * Intersection of the feeds' UT ranges: [max(utStart), min(utEnd)]. Returns
+ * undefined if any clip lacks a full range or the spans don't overlap.
+ */
+export function commonUtWindow(recordings) {
+    if (recordings.length === 0)
+        return undefined;
+    let lo = -Infinity;
+    let hi = Infinity;
+    for (const rec of recordings) {
+        if (rec.utStart == null || rec.utEnd == null)
+            return undefined;
+        lo = Math.max(lo, rec.utStart);
+        hi = Math.min(hi, rec.utEnd);
+    }
+    return lo <= hi ? [lo, hi] : undefined;
+}
+/**
+ * Recording-time (ms since clip start) for a mission UT, linearly interpolated
+ * off a clip's `utSamples`. UT is linear in recording time at constant
+ * time-warp (the launch/landing/docking moments a group captures), so this maps
+ * the common UT window onto each clip's own timeline for a keyframe trim.
+ * Clamps to the sampled span; returns null when the clip has no UT samples.
+ */
+export function utToRecordingTimeMs(samples, ut) {
+    const pts = samples.filter((s) => s.ut != null);
+    if (pts.length === 0)
+        return null;
+    if (ut <= pts[0].ut)
+        return pts[0].t;
+    for (let i = 0; i < pts.length - 1; i++) {
+        const a = pts[i];
+        const b = pts[i + 1];
+        if (ut >= a.ut && ut <= b.ut) {
+            if (b.ut === a.ut)
+                return a.t;
+            const frac = (ut - a.ut) / (b.ut - a.ut);
+            return a.t + frac * (b.t - a.t);
+        }
+    }
+    return pts[pts.length - 1].t;
+}
+/**
+ * Builds a {@link GroupTrimmer} from an already-resolved Mediabunny module
+ * namespace: keyframe-boundary remux via its Conversion API, no re-encode.
+ */
+function mediabunnyTrimmer(mb) {
+    return {
+        async trim(blob, mimeType, startMs, endMs) {
+            const input = new mb.Input({
+                source: new mb.BlobSource(blob),
+                formats: mb.ALL_FORMATS,
+            });
+            const target = new mb.BufferTarget();
+            const output = new mb.Output({ format: new mb.Mp4OutputFormat(), target });
+            const conversion = await mb.Conversion.init({
+                input,
+                output,
+                trim: { start: startMs / 1000, end: endMs / 1000 },
+            });
+            await conversion.execute();
+            if (!target.buffer)
+                throw new Error("mediabunny produced no output buffer");
+            return new Blob([target.buffer], { type: mimeType });
+        },
+    };
+}
+/**
+ * Builds a {@link TrimmerLoader} around a caller-supplied module import.
+ * `loadMediabunnyTrimmer` (the default, below) resolves the bare
+ * `import("mediabunny")` specifier for bundler consumers (e.g. gonogo). A
+ * consumer that can't rely on that resolution -- the sidecar's embedded web
+ * page, which serves its own copy of the package locally for an offline/LAN
+ * install with no CDN -- supplies a different `importModule` (e.g. a dynamic
+ * import of a served URL) and passes the result as
+ * {@link RecordingControllerOptions.loadTrimmer}. Resolves null on any
+ * failure, so a group degrades to metadata-only rather than failing.
+ */
+export function createMediabunnyTrimmerLoader(importModule) {
+    return async () => {
+        try {
+            return mediabunnyTrimmer((await importModule()));
+        }
+        catch {
+            return null;
+        }
+    };
+}
+/**
+ * Default trimmer: dynamically imports Mediabunny by its package name and
+ * remuxes with its Conversion API. Loaded on group-start so it's ready by
+ * stop.
+ */
+const loadMediabunnyTrimmer = createMediabunnyTrimmerLoader(() => import("mediabunny"));
+let idCounter = 0;
+function mintId(prefix) {
+    idCounter += 1;
+    return `${prefix}_${Date.now().toString(36)}_${idCounter.toString(36)}`;
+}
+/**
+ * Owns every in-flight and finished recording for one client. Reached via
+ * `client.recording`. All state is in-memory: a page reload discards it.
+ *
+ * Observable: {@link subscribe} + {@link getSnapshot} let every call site
+ * (a tile's own REC control, a RecordingsTray mounted elsewhere) read the same
+ * state, so a clip started or finished through one is visible to all the
+ * others -- no per-instance state to fall out of sync.
+ */
+export class RecordingController {
+    constructor(client, options) {
+        this.active = new Map();
+        this.finished = new Map();
+        /** flightId -> recordingId, so a second start on a busy feed is rejected. */
+        this.byFlight = new Map();
+        this.groups = new Map();
+        this.finishedGroups = new Map();
+        /** Per-group trimmer load kicked off at group-start, awaited at stop. */
+        this.groupTrimmers = new Map();
+        /** recordingIds in a grouped set, so they stay out of the standalone `recordings` list. */
+        this.groupMemberIds = new Set();
+        /** recordingId -> groupId, so discarding one member can pull it out of its group's array. */
+        this.memberOfGroup = new Map();
+        /**
+         * Per-feed force ref-count. The sidecar OR-aggregates force across
+         * viewers already; this is the local mirror so two overlapping
+         * recordings of the same feed (in this one controller) release force
+         * only when the last of them stops.
+         */
+        this.forceCounts = new Map();
+        /**
+         * Per-feed force-true send status: "pending" while a send is in flight,
+         * "sent" once it has actually succeeded. Absent means neither: either
+         * never attempted, or a prior attempt failed. Distinct from
+         * {@link forceCounts} so a failed send never masquerades as a completed
+         * one; see {@link acquireForce}.
+         */
+        this.forceSendState = new Map();
+        this.listeners = new Set();
+        this.snapshot = { recordings: [], groups: [], active: [] };
+        /** While true, {@link rebuild} is a no-op; used to batch startGroupedRecording's
+         *  per-member starts into a single notification once the group is fully set up. */
+        this.suppressRebuild = false;
+        /** Subscribe to snapshot changes. Returns an unsubscribe function. */
+        this.subscribe = (fn) => {
+            this.listeners.add(fn);
+            return () => {
+                this.listeners.delete(fn);
+            };
+        };
+        /** The current snapshot; the same object reference until the next mutation. */
+        this.getSnapshot = () => this.snapshot;
+        this.client = client;
+        this.loadTrimmer = options?.loadTrimmer ?? loadMediabunnyTrimmer;
+    }
+    /**
+     * Recompute the snapshot from current state and notify subscribers. Called
+     * at the end of every state-mutating operation, including the async settle
+     * points (recorder stop, grouped stop) where the data actually changes.
+     */
+    rebuild() {
+        if (this.suppressRebuild)
+            return;
+        const recordings = [...this.finished.values()].filter((r) => !this.groupMemberIds.has(r.recordingId));
+        const groups = [...this.finishedGroups.values()];
+        const active = [...this.active.values()].map((rec) => {
+            let groupId;
+            for (const [gid, ids] of this.groups) {
+                if (ids.includes(rec.recordingId)) {
+                    groupId = gid;
+                    break;
+                }
+            }
+            return {
+                recordingId: rec.recordingId,
+                flightId: rec.flightId,
+                startedAt: rec.startedAt,
+                groupId,
+                arming: rec.arming ?? false,
+            };
+        });
+        this.snapshot = { recordings, groups, active };
+        for (const l of this.listeners)
+            l();
+    }
+    /**
+     * Acquire the local force ref-count for a feed; sends
+     * `setForceFullResolution(true)` unless one is already in flight or has
+     * already succeeded for this feed (tracked in {@link forceSendState}, not
+     * just the ref-count reaching 1). The sidecar OR-aggregates force across
+     * viewers already; this ref-count is the belt-and-braces local mirror for
+     * two overlapping recordings of the same feed in this one controller.
+     *
+     * A send failure clears `forceSendState` instead of leaving it "sent", so
+     * it never masquerades as done: a later acquire (e.g. a second overlapping
+     * recording's 1->2 transition) sees the feed as not-yet-forced and retries
+     * the send, rather than silently leaving the feed un-forced forever.
+     */
+    acquireForce(flightId) {
+        const count = (this.forceCounts.get(flightId) ?? 0) + 1;
+        this.forceCounts.set(flightId, count);
+        if (this.forceSendState.has(flightId))
+            return;
+        this.forceSendState.set(flightId, "pending");
+        void this.client
+            .camera(flightId)
+            .setForceFullResolution(true)
+            .then(() => {
+            this.forceSendState.set(flightId, "sent");
+        })
+            .catch((err) => {
+            this.forceSendState.delete(flightId);
+            console.error(`kerbcast: setForceFullResolution(true) failed for feed ${flightId}; will retry on next acquire`, err);
+        });
+    }
+    /**
+     * Release one holder of a feed's force ref-count; sends
+     * `setForceFullResolution(false)` once the count reaches zero. Never goes
+     * below zero (a stray extra release is a no-op, not an underflow). Clears
+     * `forceSendState` too, so a later, unrelated recording of this feed
+     * starts its own send from a clean slate.
+     */
+    releaseForce(flightId) {
+        const count = (this.forceCounts.get(flightId) ?? 0) - 1;
+        if (count <= 0) {
+            this.forceCounts.delete(flightId);
+            this.forceSendState.delete(flightId);
+            void this.client
+                .camera(flightId)
+                .setForceFullResolution(false)
+                .catch(() => { });
+        }
+        else {
+            this.forceCounts.set(flightId, count);
+        }
+    }
+    /**
+     * Whether `state` shows a feed actually rendering at its full target size,
+     * as opposed to merely having caught up to whatever small size it already
+     * had. Two ways to know the target:
+     *
+     * - `target` known (from `maxRenderSize`): ready once the operator size
+     *   has reached it and the rendered size has caught up to the operator
+     *   size. Resolves promptly even when the feed was already at its ceiling
+     *   before the force was sent (nothing ever "increases").
+     * - `target` unknown: falls back to requiring the operator size to have
+     *   increased past `baseline` (the first REAL state observed at or after
+     *   watch-start; see {@link watchResolutionReady}) and the rendered size
+     *   to have caught up. `baseline` is `null` until that first real state
+     *   arrives, and a `null` baseline is never ready: a placeholder `{0,0}`
+     *   would let any positive operator size look like an increase, so no
+     *   verdict is possible until a genuine baseline exists. This is a
+     *   strictly weaker guarantee than the known-target path: a feed already
+     *   at its true ceiling when forced will not be recognised as ready until
+     *   something else changes its operator size, or the wait simply times
+     *   out, but it still refuses to treat the pre-force snapshot itself as
+     *   ready.
+     *
+     * Either way, a state whose rendered size has not yet caught up to its own
+     * operator size (adaptive shed still catching up) is never ready.
+     */
+    isAtFullResolution(state, target, baseline) {
+        if (!state)
+            return false;
+        if (state.renderWidth !== state.operatorWidth || state.renderHeight !== state.operatorHeight) {
+            return false;
+        }
+        if (target) {
+            return state.operatorWidth >= target.width && state.operatorHeight >= target.height;
+        }
+        if (!baseline)
+            return false;
+        return state.operatorWidth > baseline.width && state.operatorHeight > baseline.height;
+    }
+    /**
+     * Seeds a fallback baseline from an observed state, or returns `null` if
+     * the state isn't a REAL observation (operator size still zero, i.e. no
+     * dimensions have ever been reported for this feed). A `null` result
+     * means the caller must keep waiting for a state worth basing readiness
+     * on, rather than latching onto a `{0,0}` placeholder.
+     */
+    seedResolutionBaseline(state) {
+        if (!state)
+            return null;
+        if (state.operatorWidth <= 0 && state.operatorHeight <= 0)
+            return null;
+        return { width: state.operatorWidth, height: state.operatorHeight };
+    }
+    /**
+     * Waits for a forced feed to actually render at full resolution.
+     * `timeoutMs` omitted means no bound: the wait only ends when the feed
+     * becomes ready or the caller cancels it (the grouped path, bounded by the
+     * recording's own lifetime instead; see {@link startRecording}).
+     * Resolves `true` once ready, `false` on timeout. Returns a `cancel` next
+     * to the promise so a caller can abandon the wait (stop/discard) without
+     * leaking the underlying "change" subscription or timer; cancelling never
+     * settles the promise.
+     */
+    watchResolutionReady(flightId, timeoutMs) {
+        const cam = this.client.camera(flightId);
+        const target = cam.maxRenderSize;
+        /* Known-ceiling path never consults baseline; unknown-ceiling path
+           starts with no baseline until a real state seeds one, so a null
+           cam.state at watch-start (e.g. no discover() yet, since state and
+           the track are independent transports with no ordering guarantee)
+           can never masquerade as a {0,0} baseline. */
+        let baseline = target ? null : this.seedResolutionBaseline(cam.state);
+        let settled = false;
+        let unsubscribe = () => { };
+        let timer;
+        const ready = new Promise((resolve) => {
+            const finish = (reached) => {
+                if (settled)
+                    return;
+                settled = true;
+                if (timer != null)
+                    clearTimeout(timer);
+                unsubscribe();
+                resolve(reached);
+            };
+            if (this.isAtFullResolution(cam.state, target, baseline)) {
+                finish(true);
+                return;
+            }
+            unsubscribe = cam.on("change", (state) => {
+                if (!target && !baseline) {
+                    /* This is the first real state we've ever seen: it becomes the
+                       baseline, but a state can't ready itself against its own
+                       just-established baseline, so wait for the NEXT state. */
+                    baseline = this.seedResolutionBaseline(state);
+                    return;
+                }
+                if (this.isAtFullResolution(state, target, baseline))
+                    finish(true);
+            });
+            if (timeoutMs != null) {
+                timer = setTimeout(() => finish(false), timeoutMs);
+            }
+        });
+        return {
+            ready,
+            cancel: () => {
+                if (settled)
+                    return;
+                settled = true;
+                if (timer != null)
+                    clearTimeout(timer);
+                unsubscribe();
+            },
+        };
+    }
+    /**
+     * Start recording a feed's live track. Returns a client-minted recordingId
+     * synchronously. Throws if the feed has no live track or is already
+     * recording.
+     *
+     * `inGroup` is internal (set by {@link startGroupedRecording}) and governs
+     * how `opts.forceFullResolution` behaves: a single recording (`inGroup`
+     * false) arms and waits, bounded by {@link ARM_TIMEOUT_MS}, for the feed to
+     * reach full resolution before the recorder actually starts, so the clip
+     * opens on full-res frames. A grouped member starts immediately and
+     * instead records the moment it reaches full resolution
+     * (`resolutionReadyAt`/`resolutionReadyUt`) so {@link stopGroupedRecording}
+     * can fold it into the common trim window.
+     */
+    startRecording(flightId, opts, inGroup = false) {
+        if (this.byFlight.has(flightId)) {
+            throw new Error(`camera ${flightId} is already recording`);
+        }
+        const stream = this.client.camera(flightId).mediaStream;
+        if (!stream || stream.getVideoTracks().length === 0) {
+            throw new Error(`camera ${flightId} has no live track to record`);
+        }
+        const mimeType = negotiateMimeType(opts?.mimeType);
+        const ctor = globalThis.MediaRecorder;
+        if (!ctor)
+            throw new Error("MediaRecorder is not available in this environment");
+        const recorder = new ctor(stream, { mimeType });
+        const recordingId = mintId("rec");
+        const startedAt = now();
+        const utStart = this.client.clock.captureUt ?? undefined;
+        const rec = {
+            recordingId,
+            flightId,
+            mimeType,
+            recorder,
+            chunks: [],
+            startedAt,
+            utStart,
+            utSamples: [{ t: 0, ut: utStart }],
+            latestUt: utStart,
+            unsubscribeClock: () => { },
+        };
+        recorder.addEventListener("dataavailable", (e) => {
+            if (e.data && e.data.size > 0)
+                rec.chunks.push(e.data);
+        });
+        /* Sample the capture clock on each ~1Hz settings-change push. Duplicates
+           (a paused sim) are kept so `t` still advances; ut upgrades from absent
+           to present automatically once out-of-flight becomes in-flight. */
+        rec.unsubscribeClock = this.client.on("settings-change", () => {
+            const ut = this.client.clock.captureUt ?? undefined;
+            rec.utSamples.push({ t: now() - rec.startedAt, ut });
+            if (ut != null)
+                rec.latestUt = ut;
+        });
+        this.active.set(recordingId, rec);
+        this.byFlight.set(flightId, recordingId);
+        const forceRequested = opts?.forceFullResolution === true;
+        if (forceRequested) {
+            rec.forced = true;
+            this.acquireForce(flightId);
+        }
+        if (opts?.maxDurationMs != null) {
+            rec.maxDurationTimer = setTimeout(() => {
+                void this.stopRecording(recordingId).catch(() => { });
+            }, opts.maxDurationMs);
+        }
+        if (forceRequested && !inGroup) {
+            /* Single path: arm-and-wait. Show "arming" immediately; the recorder
+               itself doesn't start until the feed reaches full resolution (or the
+               bounded wait gives up), so the clip never opens on low-res frames. */
+            rec.arming = true;
+            const watch = this.watchResolutionReady(flightId, ARM_TIMEOUT_MS);
+            rec.cancelResolutionWatch = watch.cancel;
+            void watch.ready.then(() => {
+                rec.cancelResolutionWatch = undefined;
+                /* Discarded while arming: the recorder was never started and this
+                   id is gone from `active`, so there is nothing left to do. */
+                if (!this.active.has(recordingId))
+                    return;
+                rec.arming = false;
+                /* The real recording starts now: reset the clock base so the
+                   elapsed timer and utSamples track begin at actual record start,
+                   not at arm time. */
+                rec.startedAt = now();
+                rec.utStart = this.client.clock.captureUt ?? undefined;
+                rec.utSamples = [{ t: 0, ut: rec.utStart }];
+                rec.latestUt = rec.utStart;
+                rec.recorder.start();
+                this.rebuild();
+            });
+        }
+        else {
+            recorder.start();
+            if (forceRequested) {
+                /* Grouped path: record immediately. Watch for the moment this feed
+                   actually reaches full resolution so stopGroupedRecording can fold
+                   it into the common trim window and cut the low-res lead-in. No
+                   bound here: the wait is naturally bounded by the recording's own
+                   lifetime (cancelled on stop/discard); a feed that never reaches
+                   full resolution simply keeps its lead-in untrimmed. */
+                const watch = this.watchResolutionReady(flightId);
+                rec.cancelResolutionWatch = watch.cancel;
+                void watch.ready.then((reached) => {
+                    rec.cancelResolutionWatch = undefined;
+                    if (!reached)
+                        return;
+                    if (!this.active.has(recordingId))
+                        return;
+                    if (rec.resolutionReadyAt == null) {
+                        rec.resolutionReadyAt = now() - rec.startedAt;
+                        rec.resolutionReadyUt = this.client.clock.captureUt ?? undefined;
+                    }
+                });
+            }
+        }
+        this.rebuild();
+        return recordingId;
+    }
+    /**
+     * Stop a recording and resolve its finished handle. Idempotent per id: a
+     * second call (or a race with maxDurationMs auto-stop) returns the same
+     * pending/settled result.
+     */
+    stopRecording(recordingId) {
+        const rec = this.active.get(recordingId);
+        if (!rec) {
+            const done = this.finished.get(recordingId);
+            if (done)
+                return Promise.resolve(done);
+            return Promise.reject(new Error(`no recording ${recordingId}`));
+        }
+        if (rec.stopPromise)
+            return rec.stopPromise;
+        if (rec.maxDurationTimer)
+            clearTimeout(rec.maxDurationTimer);
+        rec.unsubscribeClock();
+        rec.cancelResolutionWatch?.();
+        rec.cancelResolutionWatch = undefined;
+        if (rec.arming) {
+            /* Stopped (e.g. a short maxDurationMs firing) before the arm-wait
+               ever let the recorder start: there is nothing to flush from
+               MediaRecorder, and calling stop() on a never-started recorder would
+               never fire its "stop" event (hanging this promise forever). Settle
+               immediately with an empty clip instead. Force is still released
+               unconditionally. */
+            if (rec.forced)
+                this.releaseForce(rec.flightId);
+            const utEnd = this.client.clock.captureUt ?? undefined;
+            const handle = {
+                recordingId,
+                flightId: rec.flightId,
+                blob: new Blob([], { type: rec.mimeType }),
+                mimeType: rec.mimeType,
+                utStart: rec.utStart,
+                utEnd,
+                utSamples: [...rec.utSamples, { t: now() - rec.startedAt, ut: utEnd }],
+                byteSize: 0,
+                durationMs: now() - rec.startedAt,
+            };
+            rec.stopPromise = Promise.resolve(handle);
+            this.finished.set(recordingId, handle);
+            this.active.delete(recordingId);
+            this.byFlight.delete(rec.flightId);
+            this.rebuild();
+            return rec.stopPromise;
+        }
+        const utEnd = this.client.clock.captureUt ?? undefined;
+        rec.utSamples.push({ t: now() - rec.startedAt, ut: utEnd });
+        rec.stopPromise = new Promise((resolve) => {
+            const onStop = () => {
+                rec.recorder.removeEventListener("stop", onStop);
+                const blob = new Blob(rec.chunks, { type: rec.mimeType });
+                const handle = {
+                    recordingId,
+                    flightId: rec.flightId,
+                    blob,
+                    mimeType: rec.mimeType,
+                    utStart: rec.utStart,
+                    utEnd,
+                    utSamples: rec.utSamples,
+                    byteSize: blob.size,
+                    durationMs: now() - rec.startedAt,
+                };
+                /* Unconditional: a discarded-while-settling recording still held the
+                   force ref-count and must release it, even though it won't be
+                   resurrected into `finished` below. */
+                if (rec.forced)
+                    this.releaseForce(rec.flightId);
+                /* Discarded while this stop was settling: don't resurrect it into
+                   `finished`, standalone or grouped. Still resolve so a caller
+                   awaiting this same promise doesn't hang. */
+                if (!rec.discarded) {
+                    this.finished.set(recordingId, handle);
+                    this.active.delete(recordingId);
+                    this.byFlight.delete(rec.flightId);
+                    this.rebuild();
+                }
+                resolve(handle);
+            };
+            rec.recorder.addEventListener("stop", onStop);
+            rec.recorder.stop();
+        });
+        return rec.stopPromise;
+    }
+    /** Return a finished recording's handle, or undefined if unknown/still active. */
+    fetchRecording(recordingId) {
+        return this.finished.get(recordingId);
+    }
+    /** Whether a feed currently has a recording in progress. */
+    isRecording(flightId) {
+        return this.byFlight.has(flightId);
+    }
+    /**
+     * Drop a recording. If still active, tears it down without producing a
+     * handle; if finished, frees the stored handle/blob reference. If the id
+     * is a member of a still-active group, pulls it out of that group's member
+     * set too, so a later `stopGroupedRecording` only waits on (and stops) the
+     * ids that remain -- discarding one member no longer corrupts the group.
+     */
+    discardRecording(recordingId) {
+        const rec = this.active.get(recordingId);
+        let changed = false;
+        if (rec) {
+            if (rec.stopPromise) {
+                /* stopRecording already called: the recorder is "inactive" but its
+                   "stop" event hasn't fired. Flag it so that pending onStop bails
+                   instead of resurrecting a "discarded" recording once it settles.
+                   That same onStop releases the force ref-count unconditionally, so
+                   it must not be released again here. */
+                rec.discarded = true;
+            }
+            else {
+                if (rec.maxDurationTimer)
+                    clearTimeout(rec.maxDurationTimer);
+                rec.unsubscribeClock();
+                rec.cancelResolutionWatch?.();
+                rec.cancelResolutionWatch = undefined;
+                try {
+                    if (rec.recorder.state !== "inactive")
+                        rec.recorder.stop();
+                }
+                catch {
+                    /* a recorder already torn down by the browser is fine to ignore */
+                }
+                /* No pending stopRecording to release it later (this is the only
+                   teardown path this recording will see): release the force
+                   ref-count now, unconditionally. Covers a discard mid-arm too --
+                   the recorder above was never started (still "inactive"), so this
+                   is the only place its force gets released. */
+                if (rec.forced)
+                    this.releaseForce(rec.flightId);
+            }
+            this.active.delete(recordingId);
+            this.byFlight.delete(rec.flightId);
+            changed = true;
+        }
+        if (this.finished.delete(recordingId))
+            changed = true;
+        const groupId = this.memberOfGroup.get(recordingId);
+        if (groupId != null) {
+            this.memberOfGroup.delete(recordingId);
+            this.groupMemberIds.delete(recordingId);
+            const ids = this.groups.get(groupId);
+            if (ids) {
+                const idx = ids.indexOf(recordingId);
+                if (idx !== -1) {
+                    ids.splice(idx, 1);
+                    changed = true;
+                }
+            }
+        }
+        if (changed)
+            this.rebuild();
+    }
+    // -------------------------------------------------------------------------
+    // Grouped recording
+    // -------------------------------------------------------------------------
+    /**
+     * Start recording several feeds as one synchronised moment. All recorders
+     * open in a single tick to minimise skew. Returns the groupId plus the real
+     * per-feed recordingIds (so a caller can cancel one member individually via
+     * `stopRecording`/`discardRecording`, the same ids that end up on each
+     * clip's `RecordingHandle`). If any feed can't start (no track / already
+     * recording), the ones already started are discarded and the error
+     * rethrows.
+     */
+    startGroupedRecording(flightIds, opts) {
+        const started = [];
+        /* Suppress the per-member rebuild() each startRecording call would fire:
+           without this, a synchronous subscriber could observe a member as
+           active with groupId undefined (this.groups doesn't have the entry yet).
+           One rebuild happens below, once the group is fully set up. */
+        this.suppressRebuild = true;
+        try {
+            try {
+                for (const flightId of flightIds) {
+                    started.push(this.startRecording(flightId, opts, /* inGroup */ true));
+                }
+            }
+            catch (err) {
+                for (const id of started)
+                    this.discardRecording(id);
+                throw err;
+            }
+            const groupId = mintId("grp");
+            this.groups.set(groupId, started);
+            for (const id of started) {
+                this.groupMemberIds.add(id);
+                this.memberOfGroup.set(id, groupId);
+            }
+            /* Grouped output is physically trimmed to the common window by default, so
+               load the trim package now (never fail start over a loader error) so it is
+               ready by stop. A single recording never reaches here, so it stays
+               dependency-free. Accepted tradeoff: this eagerly imports Mediabunny even
+               when every feed ends up negotiating webm (no mp4 clip to trim). */
+            this.groupTrimmers.set(groupId, (async () => {
+                try {
+                    return await this.loadTrimmer();
+                }
+                catch {
+                    return null;
+                }
+            })());
+            return { groupId, recordingIds: [...started] };
+        }
+        finally {
+            this.suppressRebuild = false;
+            this.rebuild();
+        }
+    }
+    /**
+     * Stop a grouped recording. With `targetUt`, holds until every feed's latest
+     * UT sample has passed it (coverage guarantee) before stopping any feed;
+     * without it, stops all now. Resolves the grouped handle with the intersected
+     * `commonUtWindow`. See {@link StopGroupedRecordingOptions.targetUt} for the
+     * coverage caveat around a member's own `maxDurationMs`.
+     */
+    async stopGroupedRecording(groupId, opts) {
+        const done = this.finishedGroups.get(groupId);
+        if (done)
+            return done;
+        const ids = this.groups.get(groupId);
+        if (!ids)
+            throw new Error(`no grouped recording ${groupId}`);
+        if (opts?.targetUt != null) {
+            await this.awaitCoverage(ids, opts.targetUt, opts.coverageTimeoutMs ?? DEFAULT_COVERAGE_TIMEOUT_MS);
+        }
+        /* Capture each forced member's resolution-ready UT before stopRecording
+           tears down its ActiveRecording bookkeeping below. */
+        const resolutionReadyUts = [];
+        for (const id of ids) {
+            const ut = this.active.get(id)?.resolutionReadyUt;
+            if (ut != null)
+                resolutionReadyUts.push(ut);
+        }
+        const recordings = await Promise.all(ids.map((id) => this.stopRecording(id)));
+        const window = commonUtWindow(recordings);
+        /* Fold the low-res lead-in cut into the same common-window trim: extend
+           the window's start to the latest point any forced member actually
+           reached full resolution, so every clip stays cut to one shared window
+           (UT-synced) rather than each clip getting its own start. A member that
+           never reached full resolution before stop simply doesn't contribute
+           (its own lead-in stays untrimmed, per the documented edge case). This
+           only widens the physical trim cut: `commonUtWindow` on the returned
+           handle keeps reporting the clips' own raw UT intersection, unchanged,
+           since that's metadata about what the clips cover independent of
+           whether (or how) they got physically cut. */
+        let trimWindow = window;
+        if (trimWindow && resolutionReadyUts.length > 0) {
+            const windowStart = Math.max(trimWindow[0], ...resolutionReadyUts);
+            trimWindow = [windowStart, trimWindow[1]];
+        }
+        /* Physically remux-trim each clip to the common window so the grouped
+           output is pre-aligned by default. The UT metadata (utSamples +
+           commonUtWindow) still rides along so a consumer can align the trimmed
+           clips to telemetry. Trimming never fails the recording: any clip that
+           can't be cut cleanly degrades to metadata-only. */
+        let finalRecordings = recordings;
+        if (trimWindow) {
+            const trimmer = await (this.groupTrimmers.get(groupId) ?? Promise.resolve(null));
+            if (trimmer) {
+                finalRecordings = await Promise.all(recordings.map((rec) => this.maybeTrim(rec, trimWindow, trimmer)));
+            }
+        }
+        const handle = {
+            groupId,
+            recordings: finalRecordings,
+            commonUtWindow: window,
+        };
+        this.groups.delete(groupId);
+        this.groupTrimmers.delete(groupId);
+        this.finishedGroups.set(groupId, handle);
+        this.rebuild();
+        return handle;
+    }
+    /**
+     * Remux-trim one clip to the common UT window, or return it untouched
+     * (metadata-only) when it can't be cut cleanly: a non-mp4 container, an
+     * unmappable window, or a trimmer error. The stored per-clip handle is
+     * replaced with the trimmed one so fetch/discard stay consistent.
+     */
+    async maybeTrim(rec, window, trimmer) {
+        /* MediaRecorder webm output isn't remuxed to mp4 here; degrade to
+           metadata-only for those clips (mp4 is the default container). */
+        if (!/mp4/i.test(rec.mimeType))
+            return rec;
+        const startMs = utToRecordingTimeMs(rec.utSamples, window[0]);
+        const endMs = utToRecordingTimeMs(rec.utSamples, window[1]);
+        if (startMs == null || endMs == null || endMs <= startMs)
+            return rec;
+        try {
+            const blob = await trimmer.trim(rec.blob, rec.mimeType, startMs, endMs);
+            const trimmed = {
+                ...rec,
+                blob,
+                byteSize: blob.size,
+                durationMs: endMs - startMs,
+            };
+            this.finished.set(rec.recordingId, trimmed);
+            return trimmed;
+        }
+        catch {
+            return rec;
+        }
+    }
+    /** Return a finished grouped recording, or undefined if unknown/still active. */
+    fetchGroupedRecording(groupId) {
+        return this.finishedGroups.get(groupId);
+    }
+    /** Drop a grouped recording and each of its clips. */
+    discardGroupedRecording(groupId) {
+        /* Accepted gap: racing this against an in-flight stopGroupedRecording(groupId)
+           is untested and unlikely misuse (a caller wouldn't normally discard and
+           stop the same group at once). */
+        let changed = false;
+        const active = this.groups.get(groupId);
+        if (active) {
+            /* discardRecording now splices ids out of this very array as it goes
+               (fix for cancelling one grouped member); iterate a copy so removals
+               mid-loop can't skip an id. */
+            for (const id of [...active])
+                this.discardRecording(id);
+            this.groups.delete(groupId);
+            this.groupTrimmers.delete(groupId);
+            changed = true;
+        }
+        const finished = this.finishedGroups.get(groupId);
+        if (finished) {
+            for (const rec of finished.recordings)
+                this.discardRecording(rec.recordingId);
+            this.finishedGroups.delete(groupId);
+            changed = true;
+        }
+        if (changed)
+            this.rebuild();
+    }
+    /**
+     * Resolve once every listed recording's latest UT sample has reached
+     * `targetUt`. UT arrives on the shared ~1Hz clock feed, so this polls the
+     * settings-change stream rather than a wall-clock timer. Bounded by
+     * `timeoutMs`: if coverage never arrives (feed out of flight, sim frozen,
+     * warp reversed), gives up and resolves anyway so the group finalizes with
+     * whatever UT each feed has captured, rather than hanging forever. Always
+     * releases the settings-change subscription, on either exit path.
+     */
+    awaitCoverage(recordingIds, targetUt, timeoutMs) {
+        const covered = () => recordingIds.every((id) => {
+            const rec = this.active.get(id);
+            /* A recording already stopped counts as covered (nothing to wait on). */
+            if (!rec)
+                return true;
+            return rec.latestUt != null && rec.latestUt >= targetUt;
+        });
+        if (covered())
+            return Promise.resolve();
+        return new Promise((resolve) => {
+            let settled = false;
+            const finish = () => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                unsubscribe();
+                resolve();
+            };
+            const unsubscribe = this.client.on("settings-change", () => {
+                if (covered())
+                    finish();
+            });
+            const timer = setTimeout(finish, timeoutMs);
+        });
+    }
+}