@ksp-gonogo/kerbcast 1.7.0 → 1.8.0

package/src/testing/index.ts

@@ -1,6 +1,7 @@
 import type { AdaptiveShedPayload, CameraState, ClientMessage, ErrorPayload, ServerMessage, SettingsStatePayload } from "../__generated__/types";
 import { CameraKind, CameraLifecycle, CrewLocation, ErrorSource, Layer, QualityPreset, TrackMode } from "../__generated__/types";
 import type {
+  DiscoveredCamera,
   InboundVideoStats,
   KerbcastConnectionState,
   KerbcastDataChannel,
@@ -46,6 +47,16 @@ 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;
 }
 
 function buildCamera(init: MockCameraInit): CameraState {
@@ -100,6 +111,18 @@ function scaleDim(operatorDim: number, scale: number): number {
   return v < 2 ? 2 : v;
 }
 
+/** 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.
  *
@@ -126,6 +149,17 @@ export class MockSidecar {
   private readonly _cameras = new Map<number, CameraState>();
   private readonly _commands: ClientMessage[] = [];
   private _throttleMainScreen = false;
+  private readonly _forceBumpDelayMs: number;
+  /** Per-flight ceiling (ceiling render size), served by `discoveredCameras()`. */
+  private readonly _maxRenderSizes = new Map<number, { maxWidth: number; maxHeight: number }>();
+  /** Per-flight render size captured just before a force bump, restored on release. */
+  private readonly _preForceSize = new Map<number, { width: number; height: number }>();
+  /** Per-flight pending bump/revert timer, so a rapid force/unforce toggle cancels the stale one. */
+  private readonly _forceTimers = new Map<number, ReturnType<typeof setTimeout>>();
+
+  constructor(opts: MockSidecarOptions = {}) {
+    this._forceBumpDelayMs = opts.forceBumpDelayMs ?? 600;
+  }
 
   private _openHandler: (() => void) | undefined;
   private _clientMsgHandler: ((raw: string) => void) | undefined;
@@ -155,7 +189,47 @@ export class MockSidecar {
 
   /** Register a camera that will appear in the `camera-snapshot` sent on `open()`. */
   addCamera(init: MockCameraInit): void {
-    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(): DiscoveredCamera[] {
+    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,
+      };
+    });
   }
 
   /**
@@ -250,9 +324,17 @@ export class MockSidecar {
    * {@link destroyCamera}, which keeps the camera present but `Destroyed`.
    */
   setCameras(inits: MockCameraInit[]): void {
+    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",
@@ -620,10 +702,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.
+   */
+  private _setForced(flightId: number, force: boolean): void {
+    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. */
+  private _applyRenderSize(flightId: number, width: number | undefined, height: number | undefined): void {
+    const cam = this._cameras.get(flightId);
+    if (!cam || width === undefined || height === undefined) return;
+    const updated: CameraState = {
+      ...cam,
+      renderWidth: width,
+      renderHeight: height,
+      operatorWidth: width,
+      operatorHeight: height,
+    };
+    this._cameras.set(flightId, updated);
+    this._sendToClient({ type: "camera-state-changed", content: { state: updated } });
+  }
 }
 
 /**
@@ -676,6 +818,15 @@ export function installDomStubs(): void {
   // 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 as { MediaRecorder?: unknown }).MediaRecorder === "undefined") {
+    (globalThis as { MediaRecorder?: unknown }).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") {
@@ -704,6 +855,18 @@ class StubMediaStream {
   readonly id: string = Math.random().toString(36).slice(2);
   private readonly _tracks: MediaStreamTrack[] = [];
 
+  /**
+   * 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: MediaStreamTrack[] = []) {
+    this._tracks.push(...tracks);
+  }
+
   getTracks(): MediaStreamTrack[] {
     return [...this._tracks];
   }
@@ -738,3 +901,78 @@ function installStubMediaStream(): void {
   }
   (globalThis as unknown as { MediaStream: unknown }).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 {
+  /** Types isTypeSupported reports available; null = everything. */
+  static supportedTypes: string[] | null = null;
+
+  static isTypeSupported(type: string): boolean {
+    return StubMediaRecorder.supportedTypes === null
+      ? true
+      : StubMediaRecorder.supportedTypes.includes(type);
+  }
+
+  readonly stream: MediaStream;
+  readonly mimeType: string;
+  state: "inactive" | "recording" | "paused" = "inactive";
+
+  private readonly _listeners = new Map<string, Set<(e: { data?: Blob }) => void>>();
+
+  constructor(stream: MediaStream, options?: { mimeType?: string }) {
+    this.stream = stream;
+    this.mimeType = options?.mimeType ?? "";
+  }
+
+  addEventListener(type: string, cb: (e: { data?: Blob }) => void): void {
+    let set = this._listeners.get(type);
+    if (!set) {
+      set = new Set();
+      this._listeners.set(type, set);
+    }
+    set.add(cb);
+  }
+
+  removeEventListener(type: string, cb: (e: { data?: Blob }) => void): void {
+    this._listeners.get(type)?.delete(cb);
+  }
+
+  private _emit(type: string, e: { data?: Blob }): void {
+    this._listeners.get(type)?.forEach((cb) => cb(e));
+  }
+
+  start(_timeslice?: number): void {
+    this.state = "recording";
+  }
+
+  /** Flush a canned data chunk, then fire `stop`, mirroring the real order. */
+  stop(): void {
+    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(): void {
+    if (this.state !== "recording") return;
+    const data = new Blob([new Uint8Array(512)], { type: this.mimeType || "video/webm" });
+    this._emit("dataavailable", { data });
+  }
+}

package/src/testing.test.ts

@@ -1,4 +1,4 @@
-import { beforeEach, describe, expect, it, vi } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { CameraLifecycle, Layer, TrackMode } from "./__generated__/types";
 import { KerbcastClient } from "./index";
 import { MockSidecar } from "./testing/index";
@@ -196,3 +196,149 @@ describe("MockSidecar", () => {
     expect(states).toEqual(["connected", "failed"]);
   });
 });
+
+describe("MockSidecar force-full-resolution", () => {
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("bumps render/operator size to the ceiling after a delay, then reverts on release", async () => {
+    vi.useFakeTimers();
+    const sidecar = new MockSidecar({ forceBumpDelayMs: 100 });
+    sidecar.addCamera({
+      flightId: 42,
+      renderWidth: 640,
+      renderHeight: 360,
+      operatorWidth: 640,
+      operatorHeight: 360,
+      maxWidth: 1920,
+      maxHeight: 1080,
+    });
+
+    const client = new KerbcastClient(
+      { host: "localhost", port: 8088 },
+      sidecar.createTransport(),
+    );
+    await client.connect([42]);
+    sidecar.open();
+
+    await client.camera(42).setForceFullResolution(true);
+    // Not yet bumped: the delay hasn't elapsed.
+    expect(client.camera(42).state?.operatorWidth).toBe(640);
+
+    await vi.advanceTimersByTimeAsync(100);
+    expect(client.camera(42).state).toMatchObject({
+      renderWidth: 1920,
+      renderHeight: 1080,
+      operatorWidth: 1920,
+      operatorHeight: 1080,
+    });
+
+    await client.camera(42).setForceFullResolution(false);
+    expect(client.camera(42).state?.operatorWidth).toBe(1920); // not yet reverted
+
+    await vi.advanceTimersByTimeAsync(100);
+    expect(client.camera(42).state).toMatchObject({
+      renderWidth: 640,
+      renderHeight: 360,
+      operatorWidth: 640,
+      operatorHeight: 360,
+    });
+  });
+
+  it("defaults the ceiling to the camera's initial operator size when maxWidth/maxHeight are omitted", async () => {
+    vi.useFakeTimers();
+    const sidecar = new MockSidecar({ forceBumpDelayMs: 10 });
+    sidecar.addCamera({ flightId: 7, operatorWidth: 1280, operatorHeight: 720 });
+
+    const client = new KerbcastClient(
+      { host: "localhost", port: 8088 },
+      sidecar.createTransport(),
+    );
+    await client.connect([7]);
+    sidecar.open();
+
+    await client.camera(7).setForceFullResolution(true);
+    await vi.advanceTimersByTimeAsync(10);
+
+    expect(client.camera(7).state).toMatchObject({
+      renderWidth: 1280,
+      renderHeight: 720,
+      operatorWidth: 1280,
+      operatorHeight: 720,
+    });
+  });
+
+  it("cancels a pending bump when force is released before the delay elapses", async () => {
+    vi.useFakeTimers();
+    const sidecar = new MockSidecar({ forceBumpDelayMs: 100 });
+    sidecar.addCamera({
+      flightId: 42,
+      operatorWidth: 640,
+      operatorHeight: 360,
+      maxWidth: 1920,
+      maxHeight: 1080,
+    });
+
+    const client = new KerbcastClient(
+      { host: "localhost", port: 8088 },
+      sidecar.createTransport(),
+    );
+    await client.connect([42]);
+    sidecar.open();
+
+    await client.camera(42).setForceFullResolution(true);
+    await vi.advanceTimersByTimeAsync(50);
+    await client.camera(42).setForceFullResolution(false);
+    await vi.advanceTimersByTimeAsync(200);
+
+    // Never bumped, so nothing to revert: still the original size.
+    expect(client.camera(42).state).toMatchObject({
+      operatorWidth: 640,
+      operatorHeight: 360,
+    });
+  });
+});
+
+describe("MockSidecar.discoveredCameras / client.discover()", () => {
+  it("reports maxWidth/maxHeight from each camera's init", () => {
+    const sidecar = new MockSidecar();
+    sidecar.addCamera({
+      flightId: 1,
+      cameraName: "NavCam",
+      operatorWidth: 1280,
+      operatorHeight: 720,
+      maxWidth: 1920,
+      maxHeight: 1080,
+    });
+    sidecar.addCamera({ flightId: 2, operatorWidth: 640, operatorHeight: 360 });
+
+    const discovered = sidecar.discoveredCameras();
+    expect(discovered.find((c) => c.flightId === 1)).toMatchObject({
+      maxWidth: 1920,
+      maxHeight: 1080,
+    });
+    // No explicit ceiling: falls back to the camera's initial operator size.
+    expect(discovered.find((c) => c.flightId === 2)).toMatchObject({
+      maxWidth: 640,
+      maxHeight: 360,
+    });
+  });
+
+  it("populates client.camera(id).maxRenderSize via client.discover()", async () => {
+    const sidecar = new MockSidecar();
+    sidecar.addCamera({ flightId: 42, maxWidth: 1920, maxHeight: 1080 });
+
+    const client = new KerbcastClient(
+      { host: "localhost", port: 8088 },
+      sidecar.createTransport(),
+    );
+
+    vi.spyOn(globalThis, "fetch").mockResolvedValueOnce(
+      new Response(JSON.stringify({ cameras: sidecar.discoveredCameras() }), { status: 200 }),
+    );
+
+    await client.discover();
+    expect(client.camera(42).maxRenderSize).toEqual({ width: 1920, height: 1080 });
+  });
+});