@ksp-gonogo/kerbcast 1.7.0 → 1.8.0

package/dist/testing/index.d.ts

@@ -1,6 +1,6 @@
 import type { AdaptiveShedPayload, CameraState, ClientMessage, ErrorPayload, SettingsStatePayload } from "../__generated__/types";
 import { CameraKind, CameraLifecycle, CrewLocation, Layer, QualityPreset, TrackMode } from "../__generated__/types";
-import type { InboundVideoStats, KerbcastConnectionState, KerbcastTransport } from "../client";
+import type { DiscoveredCamera, InboundVideoStats, KerbcastConnectionState, KerbcastTransport } from "../client";
 export interface MockCameraInit {
     flightId: number;
     lifecycle?: CameraLifecycle;
@@ -39,6 +39,27 @@ export interface MockCameraInit {
     qualityLimitedBy?: string;
     /** Server-authoritative auto-track mode. Defaults to `None` (untracked). */
     trackMode?: TrackMode;
+    /**
+     * Physical/ceiling render size, served by the mock's `/cameras` discovery
+     * intercept (`DiscoveredCamera.maxWidth`/`maxHeight`). Defaults to
+     * `operatorWidth`/`operatorHeight` (i.e. already at ceiling) so a camera
+     * that never sets these behaves as it always has. Give a camera a ceiling
+     * above its initial `operatorWidth`/`operatorHeight` to demonstrate a
+     * visible bump when `set-force-full-resolution` lands.
+     */
+    maxWidth?: number;
+    maxHeight?: number;
+}
+/** Options for {@link MockSidecar}'s constructor. */
+export interface MockSidecarOptions {
+    /**
+     * Delay (ms) before a forced camera's simulated resolution bump lands,
+     * once `set-force-full-resolution` (`force: true`) is received, and
+     * before the render size reverts on `force: false`. Long enough that a
+     * screenshot can catch the resulting "ARMING" state; short enough that
+     * automated tests/waits don't feel slow. Defaults to 600ms.
+     */
+    forceBumpDelayMs?: number;
 }
 /**
  * In-process protocol-level fake for the kerbcast sidecar.
@@ -66,6 +87,14 @@ export declare class MockSidecar {
     private readonly _cameras;
     private readonly _commands;
     private _throttleMainScreen;
+    private readonly _forceBumpDelayMs;
+    /** Per-flight ceiling (ceiling render size), served by `discoveredCameras()`. */
+    private readonly _maxRenderSizes;
+    /** Per-flight render size captured just before a force bump, restored on release. */
+    private readonly _preForceSize;
+    /** Per-flight pending bump/revert timer, so a rapid force/unforce toggle cancels the stale one. */
+    private readonly _forceTimers;
+    constructor(opts?: MockSidecarOptions);
     private _openHandler;
     private _clientMsgHandler;
     private _stateHandler;
@@ -89,6 +118,14 @@ export declare class MockSidecar {
     private readonly _deliveredTracks;
     /** Register a camera that will appear in the `camera-snapshot` sent on `open()`. */
     addCamera(init: MockCameraInit): void;
+    /**
+     * The `DiscoveredCamera[]` the mock's `GET /cameras` intercept serves,
+     * mirroring the real sidecar's discovery endpoint. `maxWidth`/`maxHeight`
+     * come from each camera's `maxWidth`/`maxHeight` init (or its initial
+     * `operatorWidth`/`operatorHeight` when omitted). Used by
+     * `client.discover()` to populate `KerbcastCameraHandle.maxRenderSize`.
+     */
+    discoveredCameras(): DiscoveredCamera[];
     /**
      * Returns a `KerbcastTransport` backed by this mock. Pass it as the
      * second argument to `KerbcastClient`.
@@ -209,6 +246,18 @@ export declare class MockSidecar {
     private _buildStatsReport;
     private _sendToClient;
     private _handleClientMessage;
+    /**
+     * Simulate the sidecar's `effective_render_size` force branch: after
+     * {@link _forceBumpDelayMs}, bump the camera's render/operator size to its
+     * ceiling (`force: true`) or restore whatever it was before the force
+     * (`force: false`), pushing a `camera-state-changed` either way. The delay
+     * models the real round trip (control-file write, plugin capture pickup,
+     * WebRTC renegotiation) and gives a UI something to show an "ARMING" state
+     * for. A rapid re-toggle cancels the previous pending bump/revert.
+     */
+    private _setForced;
+    /** Push a render/operator size onto a camera (both fields alike, i.e. no adaptive shed in effect) and broadcast it. */
+    private _applyRenderSize;
 }
 /**
  * Install jsdom shims needed by kerbcast component tests.
@@ -234,3 +283,41 @@ export declare class MockSidecar {
  *                      detection reads prefers-color-scheme through it.
  */
 export declare function installDomStubs(): void;
+/**
+ * Minimal MediaRecorder stand-in for jsdom, installed by {@link installDomStubs}.
+ *
+ * jsdom implements no MediaRecorder, so the recording controller can't run
+ * headlessly without this. On `stop()` it synchronously flushes one canned
+ * Blob (a fixed byte pattern tagged with the negotiated mimeType) then fires
+ * `stop`, closing the start -> stop -> Blob path the controller drives.
+ *
+ * `isTypeSupported` is controllable so tests exercise mime negotiation:
+ *   - `supportedTypes = null` (default): support everything, so negotiation
+ *     picks the mp4 preference.
+ *   - `supportedTypes = ["video/webm"]`: force the webm fallback.
+ * Reset `supportedTypes` back to null between tests that change it.
+ */
+export declare class StubMediaRecorder {
+    /** Types isTypeSupported reports available; null = everything. */
+    static supportedTypes: string[] | null;
+    static isTypeSupported(type: string): boolean;
+    readonly stream: MediaStream;
+    readonly mimeType: string;
+    state: "inactive" | "recording" | "paused";
+    private readonly _listeners;
+    constructor(stream: MediaStream, options?: {
+        mimeType?: string;
+    });
+    addEventListener(type: string, cb: (e: {
+        data?: Blob;
+    }) => void): void;
+    removeEventListener(type: string, cb: (e: {
+        data?: Blob;
+    }) => void): void;
+    private _emit;
+    start(_timeslice?: number): void;
+    /** Flush a canned data chunk, then fire `stop`, mirroring the real order. */
+    stop(): void;
+    /** Emit a partial data chunk without stopping (matches the real API). */
+    requestData(): void;
+}

package/dist/testing/index.js

@@ -71,10 +71,16 @@ function scaleDim(operatorDim, scale) {
  * ```
  */
 export class MockSidecar {
-    constructor() {
+    constructor(opts = {}) {
         this._cameras = new Map();
         this._commands = [];
         this._throttleMainScreen = false;
+        /** Per-flight ceiling (ceiling render size), served by `discoveredCameras()`. */
+        this._maxRenderSizes = new Map();
+        /** Per-flight render size captured just before a force bump, restored on release. */
+        this._preForceSize = new Map();
+        /** Per-flight pending bump/revert timer, so a rapid force/unforce toggle cancels the stale one. */
+        this._forceTimers = new Map();
         this._trackIdx = 0;
         /** Slot mids available for the dynamic-subscription model. Override with
          *  {@link withSlots} before connecting if a test needs a specific pool. */
@@ -91,10 +97,50 @@ export class MockSidecar {
          * getStats can synthesize a trackIdentifier matching what the client saw.
          */
         this._deliveredTracks = new Map();
+        this._forceBumpDelayMs = opts.forceBumpDelayMs ?? 600;
     }
     /** Register a camera that will appear in the `camera-snapshot` sent on `open()`. */
     addCamera(init) {
-        this._cameras.set(init.flightId, buildCamera(init));
+        const cam = buildCamera(init);
+        this._cameras.set(init.flightId, cam);
+        this._maxRenderSizes.set(init.flightId, {
+            maxWidth: init.maxWidth ?? cam.operatorWidth,
+            maxHeight: init.maxHeight ?? cam.operatorHeight,
+        });
+    }
+    /**
+     * The `DiscoveredCamera[]` the mock's `GET /cameras` intercept serves,
+     * mirroring the real sidecar's discovery endpoint. `maxWidth`/`maxHeight`
+     * come from each camera's `maxWidth`/`maxHeight` init (or its initial
+     * `operatorWidth`/`operatorHeight` when omitted). Used by
+     * `client.discover()` to populate `KerbcastCameraHandle.maxRenderSize`.
+     */
+    discoveredCameras() {
+        return Array.from(this._cameras.values()).map((cam) => {
+            const max = this._maxRenderSizes.get(cam.flightId);
+            return {
+                flightId: cam.flightId,
+                lifecycle: cam.lifecycle,
+                partName: cam.partName,
+                partTitle: cam.partTitle,
+                cameraName: cam.cameraName,
+                vesselName: cam.vesselName,
+                maxWidth: max?.maxWidth ?? cam.operatorWidth,
+                maxHeight: max?.maxHeight ?? cam.operatorHeight,
+                supportsZoom: cam.supportsZoom,
+                fov: cam.fov,
+                fovMin: cam.fovMin,
+                fovMax: cam.fovMax,
+                supportsPan: cam.supportsPan,
+                panYawMin: cam.panYawMin,
+                panYawMax: cam.panYawMax,
+                panPitchMin: cam.panPitchMin,
+                panPitchMax: cam.panPitchMax,
+                encoderBitrateBps: cam.encoderBitrateBps,
+                targetBitrateBps: cam.targetBitrateBps,
+                degradeLevel: cam.degradeLevel,
+            };
+        });
     }
     /**
      * Returns a `KerbcastTransport` backed by this mock. Pass it as the
@@ -185,9 +231,18 @@ export class MockSidecar {
      * {@link destroyCamera}, which keeps the camera present but `Destroyed`.
      */
     setCameras(inits) {
+        for (const timer of this._forceTimers.values())
+            clearTimeout(timer);
+        this._forceTimers.clear();
+        this._preForceSize.clear();
         this._cameras.clear();
+        this._maxRenderSizes.clear();
         for (const init of inits) {
             this._cameras.set(init.flightId, buildCamera(init));
+            this._maxRenderSizes.set(init.flightId, {
+                maxWidth: init.maxWidth ?? init.operatorWidth ?? 1280,
+                maxHeight: init.maxHeight ?? init.operatorHeight ?? 720,
+            });
         }
         this._sendToClient({
             type: "camera-snapshot",
@@ -527,10 +582,70 @@ export class MockSidecar {
                 });
                 break;
             }
+            case "set-force-full-resolution": {
+                this._setForced(msg.content.flightId, msg.content.force);
+                break;
+            }
             case "disconnect":
                 break;
         }
     }
+    /**
+     * Simulate the sidecar's `effective_render_size` force branch: after
+     * {@link _forceBumpDelayMs}, bump the camera's render/operator size to its
+     * ceiling (`force: true`) or restore whatever it was before the force
+     * (`force: false`), pushing a `camera-state-changed` either way. The delay
+     * models the real round trip (control-file write, plugin capture pickup,
+     * WebRTC renegotiation) and gives a UI something to show an "ARMING" state
+     * for. A rapid re-toggle cancels the previous pending bump/revert.
+     */
+    _setForced(flightId, force) {
+        const pending = this._forceTimers.get(flightId);
+        if (pending !== undefined) {
+            clearTimeout(pending);
+            this._forceTimers.delete(flightId);
+        }
+        const cam = this._cameras.get(flightId);
+        if (!cam)
+            return;
+        if (force) {
+            if (!this._preForceSize.has(flightId)) {
+                this._preForceSize.set(flightId, { width: cam.operatorWidth, height: cam.operatorHeight });
+            }
+            const max = this._maxRenderSizes.get(flightId);
+            const timer = setTimeout(() => {
+                this._forceTimers.delete(flightId);
+                this._applyRenderSize(flightId, max?.maxWidth, max?.maxHeight);
+            }, this._forceBumpDelayMs);
+            this._forceTimers.set(flightId, timer);
+        }
+        else {
+            const prior = this._preForceSize.get(flightId);
+            this._preForceSize.delete(flightId);
+            if (!prior)
+                return;
+            const timer = setTimeout(() => {
+                this._forceTimers.delete(flightId);
+                this._applyRenderSize(flightId, prior.width, prior.height);
+            }, this._forceBumpDelayMs);
+            this._forceTimers.set(flightId, timer);
+        }
+    }
+    /** Push a render/operator size onto a camera (both fields alike, i.e. no adaptive shed in effect) and broadcast it. */
+    _applyRenderSize(flightId, width, height) {
+        const cam = this._cameras.get(flightId);
+        if (!cam || width === undefined || height === undefined)
+            return;
+        const updated = {
+            ...cam,
+            renderWidth: width,
+            renderHeight: height,
+            operatorWidth: width,
+            operatorHeight: height,
+        };
+        this._cameras.set(flightId, updated);
+        this._sendToClient({ type: "camera-state-changed", content: { state: updated } });
+    }
 }
 /**
  * Install jsdom shims needed by kerbcast component tests.
@@ -577,6 +692,14 @@ export function installDomStubs() {
     // with tracks. Provide a stub that satisfies the basic interface used by
     // tests (getTracks, addTrack, id).
     installStubMediaStream();
+    // MediaRecorder: jsdom ships none, so the recording controller can't be
+    // exercised headlessly without it. The stub emits one canned Blob on stop,
+    // closing the start -> stop -> Blob path. Its isTypeSupported is controllable
+    // (StubMediaRecorder.supportedTypes) so tests can drive mime negotiation and
+    // its fallback.
+    if (typeof globalThis.MediaRecorder === "undefined") {
+        globalThis.MediaRecorder = StubMediaRecorder;
+    }
     // play: jsdom's HTMLMediaElement.play is not implemented and prints a warning.
     // The noise pipeline awaits video.play() on its internal video element.
     if (typeof HTMLMediaElement !== "undefined") {
@@ -600,9 +723,18 @@ export function installDomStubs() {
 }
 /** Minimal MediaStream stand-in for jsdom environments. */
 class StubMediaStream {
-    constructor() {
+    /**
+     * Mirrors the real `MediaStream(tracks?)` constructor: the real SDK builds
+     * its per-camera stream as `new MediaStream([track])` on track arrival, so
+     * without this the tracks array is silently dropped and the stream always
+     * reports zero video tracks: the client and anything downstream (e.g. a
+     * real `RecordingController.startRecording`, which requires at least one
+     * live video track) would never see the delivered track.
+     */
+    constructor(tracks = []) {
         this.id = Math.random().toString(36).slice(2);
         this._tracks = [];
+        this._tracks.push(...tracks);
     }
     getTracks() {
         return [...this._tracks];
@@ -641,3 +773,68 @@ function installStubMediaStream() {
     }
     globalThis.MediaStream = StubMediaStream;
 }
+/**
+ * Minimal MediaRecorder stand-in for jsdom, installed by {@link installDomStubs}.
+ *
+ * jsdom implements no MediaRecorder, so the recording controller can't run
+ * headlessly without this. On `stop()` it synchronously flushes one canned
+ * Blob (a fixed byte pattern tagged with the negotiated mimeType) then fires
+ * `stop`, closing the start -> stop -> Blob path the controller drives.
+ *
+ * `isTypeSupported` is controllable so tests exercise mime negotiation:
+ *   - `supportedTypes = null` (default): support everything, so negotiation
+ *     picks the mp4 preference.
+ *   - `supportedTypes = ["video/webm"]`: force the webm fallback.
+ * Reset `supportedTypes` back to null between tests that change it.
+ */
+export class StubMediaRecorder {
+    static isTypeSupported(type) {
+        return StubMediaRecorder.supportedTypes === null
+            ? true
+            : StubMediaRecorder.supportedTypes.includes(type);
+    }
+    constructor(stream, options) {
+        this.state = "inactive";
+        this._listeners = new Map();
+        this.stream = stream;
+        this.mimeType = options?.mimeType ?? "";
+    }
+    addEventListener(type, cb) {
+        let set = this._listeners.get(type);
+        if (!set) {
+            set = new Set();
+            this._listeners.set(type, set);
+        }
+        set.add(cb);
+    }
+    removeEventListener(type, cb) {
+        this._listeners.get(type)?.delete(cb);
+    }
+    _emit(type, e) {
+        this._listeners.get(type)?.forEach((cb) => cb(e));
+    }
+    start(_timeslice) {
+        this.state = "recording";
+    }
+    /** Flush a canned data chunk, then fire `stop`, mirroring the real order. */
+    stop() {
+        if (this.state === "inactive")
+            return;
+        this.state = "inactive";
+        const bytes = new Uint8Array(2048);
+        for (let i = 0; i < bytes.length; i++)
+            bytes[i] = i & 0xff;
+        const data = new Blob([bytes], { type: this.mimeType || "video/webm" });
+        this._emit("dataavailable", { data });
+        this._emit("stop", {});
+    }
+    /** Emit a partial data chunk without stopping (matches the real API). */
+    requestData() {
+        if (this.state !== "recording")
+            return;
+        const data = new Blob([new Uint8Array(512)], { type: this.mimeType || "video/webm" });
+        this._emit("dataavailable", { data });
+    }
+}
+/** Types isTypeSupported reports available; null = everything. */
+StubMediaRecorder.supportedTypes = null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ksp-gonogo/kerbcast",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "description": "TypeScript client for the kerbcast KSP camera-streaming sidecar. KerbcastClient wraps the WebRTC peer + control channel; wire-format types are typeshare-generated from the sidecar's Rust protocol module.",
   "license": "MIT",
   "author": "Jon Pepler",
@@ -54,5 +54,8 @@
     "jsdom": "^29.0.2",
     "typescript": "^5.4.0",
     "vitest": "^4.1.4"
+  },
+  "dependencies": {
+    "mediabunny": "^1.51.0"
   }
 }

package/src/__generated__/types.ts

@@ -281,6 +281,18 @@ export interface SetDegradePayload {
 	level: number;
 }
 
+/**
+ * Forces a camera to render at the operator ceiling regardless of
+ * display-size demand. Per-viewer, OR-aggregated by the sidecar: a feed
+ * stays forced while any connected viewer forces it, and releases when
+ * the last one clears it (or disconnects). Still yields to the adaptive
+ * framerate shed; overrides only the demand term.
+ */
+export interface SetForceFullResolutionPayload {
+	flightId: number;
+	force: boolean;
+}
+
 export interface SetFovPayload {
 	flightId: number;
 	fov: number;
@@ -452,6 +464,15 @@ export type ClientMessage =
 	 * departing consumer's size is cleared so the max relaxes.
 	 */
 	| { type: "report-display-size", content: ReportDisplaySizePayload }
+	/**
+	 * Force a camera to render at the operator ceiling regardless of
+	 * display-size demand. Per-viewer, OR-aggregated by the sidecar: a
+	 * feed stays forced while any connected viewer forces it, and
+	 * releases when the last one clears it (or disconnects). Still
+	 * yields to the adaptive framerate shed; overrides only the demand
+	 * term, never the perf-protection ceiling.
+	 */
+	| { type: "set-force-full-resolution", content: SetForceFullResolutionPayload }
 	/**
 	 * Set the camera's field-of-view (degrees). Silently ignored for
 	 * parts whose Hullcam module is the fixed base (`supportsZoom ==

package/src/client.test.ts

@@ -382,6 +382,30 @@ describe("KerbcastClient", () => {
     ]);
   });
 
+  it("set-force-full-resolution routes onto the control channel via the handle", async () => {
+    const { transport, captured } = makeFakeTransport();
+    const client = new KerbcastClient({ host: "h", port: 1 }, transport);
+    vi.spyOn(globalThis, "fetch").mockResolvedValue(fakeAnswer());
+
+    await client.connect();
+    captured.dc?._open();
+    captured.dc!.sent.length = 0; // drop the hello
+
+    await client.camera(42).setForceFullResolution(true);
+    await client.camera(42).setForceFullResolution(false);
+
+    expect(captured.dc?.sent).toEqual([
+      JSON.stringify({
+        type: "set-force-full-resolution",
+        content: { flightId: 42, force: true },
+      }),
+      JSON.stringify({
+        type: "set-force-full-resolution",
+        content: { flightId: 42, force: false },
+      }),
+    ]);
+  });
+
   it("reportDisplaySize sends a report-display-size command", async () => {
     const { transport, captured } = makeFakeTransport();
     const client = new KerbcastClient({ host: "h", port: 1 }, transport);

package/src/client.ts

@@ -11,6 +11,7 @@ import type {
 } from "./__generated__/types";
 import { CameraLifecycle, ErrorSource } from "./__generated__/types";
 import { type NoisePipeline, tryCreateNoisePipeline } from "./noise";
+import { RecordingController, type RecordingControllerOptions } from "./recording";
 
 /** Intensity the static runs at when a camera has no live source (signal lost). */
 const SOURCELESS_INTENSITY = 1.0;
@@ -47,6 +48,16 @@ export interface KerbcastCameraHandle {
   readonly stalled: boolean;
   /** Current {@link setShowStatic} setting. */
   readonly showStatic: boolean;
+  /**
+   * The feed's physical/ceiling maximum render size (`DiscoveredCamera.maxWidth`
+   * / `maxHeight`), or `null` until known. Populated from a prior
+   * `client.discover()` call (there is no live-pushed field for it), so a
+   * consumer that never calls `discover()` sees `null` here indefinitely.
+   * Used by `RecordingController` to recognise a force-full-resolution feed
+   * that has actually reached its ceiling, as opposed to one merely
+   * unchanged since before the force was sent.
+   */
+  readonly maxRenderSize: { width: number; height: number } | null;
 
   setLayers(layers: Layer[]): Promise<void>;
   setRenderSize(width: number, height: number): Promise<void>;
@@ -78,6 +89,15 @@ export interface KerbcastCameraHandle {
    * machinery keeps overriding it downward while throttled.
    */
   setQuality(preset: QualityPreset | null): Promise<void>;
+  /**
+   * Force this feed to render at the operator's configured maximum
+   * regardless of display size, until released by calling this with
+   * `false`. Per-viewer, OR-aggregated server-side across viewers: a feed
+   * stays forced while any viewer forces it, and releases when the last one
+   * clears it (or disconnects). Still yields to the adaptive framerate
+   * shed; it only overrides the display-size demand term.
+   */
+  setForceFullResolution(force: boolean): Promise<void>;
   requestKeyframe(): Promise<void>;
 
   /**
@@ -150,6 +170,15 @@ export interface KerbcastClientConfig {
     cameras: number[];
     slots?: number;
   }) => Promise<{ sdp: string; cameras: number[] }>;
+  /**
+   * Options for the lazily-built {@link RecordingController} (`client.recording`).
+   * The load-bearing use is `loadTrimmer`: a consumer that can't rely on the
+   * default bare `import("mediabunny")` resolving (the sidecar's embedded web
+   * page serves its own copy of the package locally, offline/LAN, no CDN)
+   * supplies its own loader here. Bundler consumers (e.g. gonogo) can omit
+   * this and get the default.
+   */
+  recording?: RecordingControllerOptions;
 }
 
 /** WebRTC connection state surface. */
@@ -509,6 +538,10 @@ class CameraHandle
     return this._showStatic;
   }
 
+  get maxRenderSize(): { width: number; height: number } | null {
+    return this.client._maxRenderSize(this.flightId);
+  }
+
   configure(options: { noise?: Partial<NoiseConfig> }): void {
     this._noiseOverride = options.noise ?? null;
     // Re-evaluate with the new noise setting: rebuild from whatever source
@@ -739,6 +772,13 @@ class CameraHandle
     });
   }
 
+  async setForceFullResolution(force: boolean): Promise<void> {
+    await this.client._send({
+      type: "set-force-full-resolution",
+      content: { flightId: this.flightId, force },
+    });
+  }
+
   async requestKeyframe(): Promise<void> {
     await this.client._send({
       type: "request-keyframe",
@@ -816,6 +856,15 @@ export class KerbcastClient extends TypedEmitter<KerbcastClientEvents> {
   private _warpRate = 1;
   /** Whether KSP is in a flight scene. `undefined` until the first signal. */
   private _inFlight: boolean | undefined = undefined;
+  /** Client-side recording controller, lazily built on first `recording` access. */
+  private _recording: RecordingController | null = null;
+  /**
+   * Physical/ceiling max render size per camera, cached from the last
+   * `discover()` call. Empty until `discover()` has been called at least
+   * once; a camera absent from the last discovery response is simply
+   * missing here (its handle's `maxRenderSize` reads `null`).
+   */
+  private readonly maxRenderSizeByFlight = new Map<number, { width: number; height: number }>();
 
   constructor(cfg: KerbcastClientConfig, transport?: KerbcastTransport) {
     super();
@@ -868,6 +917,17 @@ export class KerbcastClient extends TypedEmitter<KerbcastClientEvents> {
     };
   }
 
+  /**
+   * Client-side recording controller. Records a camera's already-received
+   * track with the browser's `MediaRecorder`, annotated with the mission-time
+   * (UT) clock; purely local, no sidecar involvement. Lazily created on first
+   * access and stable thereafter. See {@link RecordingController}.
+   */
+  get recording(): RecordingController {
+    if (!this._recording) this._recording = new RecordingController(this, this.cfg.recording);
+    return this._recording;
+  }
+
   /**
    * Whether KSP is currently in a flight scene, from the sidecar's
    * `scene-state-changed`. `undefined` until the first signal (so a
@@ -899,9 +959,23 @@ export class KerbcastClient extends TypedEmitter<KerbcastClientEvents> {
     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()) as { cameras: DiscoveredCamera[] };
+    for (const cam of body.cameras) {
+      this.maxRenderSizeByFlight.set(cam.flightId, {
+        width: cam.maxWidth,
+        height: cam.maxHeight,
+      });
+    }
     return body.cameras;
   }
 
+  /**
+   * Internal: backs {@link KerbcastCameraHandle.maxRenderSize}. `null` when
+   * `discover()` has never been called or never reported this camera.
+   */
+  _maxRenderSize(flightId: number): { width: number; height: number } | null {
+    return this.maxRenderSizeByFlight.get(flightId) ?? null;
+  }
+
   /**
    * Open the WebRTC peer and subscribe to cameras. Idempotent: calling
    * `connect` while already connected disconnects first.

package/src/index.ts

@@ -27,3 +27,25 @@ export {
   type PanZoomBounds,
   type PanZoomControllerOptions,
 } from "./panZoom";
+
+export {
+  RecordingController,
+  createMediabunnyTrimmerLoader,
+  negotiateMimeType,
+  commonUtWindow,
+  utToRecordingTimeMs,
+  DEFAULT_COVERAGE_TIMEOUT_MS,
+  ARM_TIMEOUT_MS,
+  type ActiveRecordingInfo,
+  type RecordingClient,
+  type RecordingControllerOptions,
+  type RecordingHandle,
+  type RecordingsSnapshot,
+  type GroupedRecordingHandle,
+  type GroupedRecordingStart,
+  type GroupTrimmer,
+  type TrimmerLoader,
+  type UtSample,
+  type StartRecordingOptions,
+  type StopGroupedRecordingOptions,
+} from "./recording";