@ksp-gonogo/kerbcast 1.4.0

package/dist/panZoom.js

@@ -0,0 +1,302 @@
+/**
+ * Headless pan/zoom control state machine extracted from the CameraFeed
+ * component. Manages rate deduplication, analog deadzone, optimistic
+ * accumulators for discrete nudges, debounced FoV slider, and echo-sync
+ * while idle -- all without any DOM or React dependency.
+ *
+ * `KerbcastCameraHandle` satisfies `PanZoomCommandSink` structurally: pass a
+ * camera handle directly as the sink and the controller will drive it.
+ *
+ * ```ts
+ * const cam = client.camera(flightId);
+ * const ctrl = new PanZoomController(cam);
+ *
+ * // Analog stick input
+ * ctrl.setPanRate(stickX, stickY);
+ *
+ * // Discrete nudge buttons
+ * ctrl.nudgePan(1, 0);   // pan right one step
+ * ctrl.nudgeZoom(-1);    // zoom in one step
+ *
+ * // FoV slider
+ * ctrl.setFovSliderDragging(true);
+ * ctrl.fovSliderInput(newFov);
+ * ctrl.setFovSliderDragging(false); // flushes immediately
+ *
+ * // Sync echoed state (call from camera "change" listener)
+ * ctrl.syncFromState({ fov, panYaw, panPitch, fovMin, fovMax,
+ *                      panYawMin, panYawMax, panPitchMin, panPitchMax });
+ *
+ * // Cleanup on unmount
+ * ctrl.stop();
+ * ```
+ */
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function clamp(v, lo, hi) {
+    return Math.max(lo, Math.min(hi, v));
+}
+function applyDeadzone(v, deadzone) {
+    return Math.abs(v) < deadzone ? 0 : v;
+}
+// ---------------------------------------------------------------------------
+// PanZoomController
+// ---------------------------------------------------------------------------
+/**
+ * Headless pan/zoom state machine. Manages rate deduplication, analog
+ * deadzone, optimistic accumulators, FoV slider debounce, and echo-sync
+ * idle rules. Mirrors the behaviour of the CameraFeed component in gonogo
+ * (CameraFeed.tsx lines 323-592) without any React or DOM coupling.
+ */
+export class PanZoomController {
+    constructor(sink, opts = {}) {
+        // Last-sent rates (dedupe against re-sending the same value).
+        this.sentPanRate = { yaw: 0, pitch: 0 };
+        this.sentZoomRate = 0;
+        // Optimistic accumulators for discrete nudges.
+        this.localPan = { yaw: 0, pitch: 0 };
+        this.localFov = 0;
+        // FoV slider state.
+        this._sliderFov = 0;
+        this.sliderDragging = false;
+        this.fovDebounceTimer = null;
+        this.pendingFov = null;
+        // Drag-ball flag (used only for the idle rule; pixel math lives in the UI).
+        this.ballDragging = false;
+        // Last-known bounds for clamping.
+        this.bounds = {
+            fovMin: 0,
+            fovMax: 180,
+            panYawMin: -180,
+            panYawMax: 180,
+            panPitchMin: -90,
+            panPitchMax: 90,
+        };
+        // sliderFov change subscribers.
+        this.sliderFovListeners = new Set();
+        this.sink = sink;
+        this.panNudgeDeg = opts.panNudgeDeg ?? 5;
+        this.fovNudgeDeg = opts.fovNudgeDeg ?? 5;
+        this.fovSliderDebounceMs = opts.fovSliderDebounceMs ?? 120;
+        this.analogDeadzone = opts.analogDeadzone ?? 0.05;
+    }
+    // ---------------------------------------------------------------------------
+    // Public getters
+    // ---------------------------------------------------------------------------
+    /**
+     * Optimistic FoV value tracked by the slider. Follows the pointer while
+     * dragging, then the camera echo when idle. Reactive via
+     * {@link onSliderFov}.
+     */
+    get sliderFov() {
+        return this._sliderFov;
+    }
+    // ---------------------------------------------------------------------------
+    // Echo-sync
+    // ---------------------------------------------------------------------------
+    /**
+     * Sync from the camera's echoed state (call from the camera's `"change"`
+     * event listener). Applies the echoed pan to the pan accumulator only when
+     * the controller is pan-idle (no active pan rate, no active ball drag).
+     * Applies the echoed FoV to the accumulator and slider only when the
+     * controller is zoom-idle (zoom rate 0, slider not dragging, no pending
+     * debounced send). Mirrors CameraFeed.tsx:370-387.
+     */
+    syncFromState(state) {
+        this.bounds = {
+            fovMin: state.fovMin,
+            fovMax: state.fovMax,
+            panYawMin: state.panYawMin,
+            panYawMax: state.panYawMax,
+            panPitchMin: state.panPitchMin,
+            panPitchMax: state.panPitchMax,
+        };
+        const panIdle = !this.ballDragging &&
+            this.sentPanRate.yaw === 0 &&
+            this.sentPanRate.pitch === 0;
+        if (panIdle) {
+            this.localPan = { yaw: state.panYaw, pitch: state.panPitch };
+        }
+        const zoomIdle = this.sentZoomRate === 0 &&
+            !this.sliderDragging &&
+            this.pendingFov === null;
+        if (zoomIdle) {
+            this.localFov = state.fov;
+            this.setSliderFovInternal(state.fov);
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Pan rate
+    // ---------------------------------------------------------------------------
+    /**
+     * Set a persistent normalised pan velocity (-1..1 per axis). Clamps,
+     * applies the analog deadzone, and deduplicates against the last-sent
+     * value before forwarding to the sink. Mirrors sendPanRate.
+     */
+    setPanRate(yaw, pitch) {
+        const y = applyDeadzone(clamp(yaw, -1, 1), this.analogDeadzone);
+        const p = applyDeadzone(clamp(pitch, -1, 1), this.analogDeadzone);
+        if (y === this.sentPanRate.yaw && p === this.sentPanRate.pitch)
+            return;
+        this.sentPanRate = { yaw: y, pitch: p };
+        void this.sink.setPanRate(y, p);
+    }
+    /**
+     * Update one pan axis, preserving the other. Allows two independent inputs
+     * (e.g. a serial stick axis and the ball) to compose rather than clobber
+     * each other. Mirrors setPanAxis.
+     */
+    setPanAxis(axis, value) {
+        const cur = this.sentPanRate;
+        if (axis === "yaw")
+            this.setPanRate(value, cur.pitch);
+        else
+            this.setPanRate(cur.yaw, value);
+    }
+    // ---------------------------------------------------------------------------
+    // Zoom rate
+    // ---------------------------------------------------------------------------
+    /**
+     * Set a persistent normalised zoom velocity (-1..1; +1 = zoom in, FoV
+     * decreasing). Clamps, applies deadzone, deduplicates. Mirrors sendZoomRate.
+     */
+    setZoomRate(rate) {
+        const r = applyDeadzone(clamp(rate, -1, 1), this.analogDeadzone);
+        if (r === this.sentZoomRate)
+            return;
+        this.sentZoomRate = r;
+        void this.sink.setZoomRate(r);
+    }
+    // ---------------------------------------------------------------------------
+    // Discrete nudges
+    // ---------------------------------------------------------------------------
+    /**
+     * Discrete pan step (+1/-1 per axis sign). Moves the pan accumulator by
+     * `panNudgeDeg`, clamped to bounds, then sends an absolute `setPan`.
+     * Mirrors nudgePan.
+     */
+    nudgePan(yawSign, pitchSign) {
+        const b = this.bounds;
+        this.localPan.yaw = clamp(this.localPan.yaw + yawSign * this.panNudgeDeg, b.panYawMin, b.panYawMax);
+        this.localPan.pitch = clamp(this.localPan.pitch + pitchSign * this.panNudgeDeg, b.panPitchMin, b.panPitchMax);
+        void this.sink.setPan(this.localPan.yaw, this.localPan.pitch);
+    }
+    /**
+     * Discrete FoV step. `deltaSign: -1` = zoom in (FoV decreases by
+     * `fovNudgeDeg`), `+1` = zoom out (FoV increases). Clamped to fov bounds.
+     * Mirrors nudgeZoom (which calls onFovChange internally).
+     */
+    nudgeZoom(deltaSign) {
+        const b = this.bounds;
+        const next = clamp(this.localFov + deltaSign * this.fovNudgeDeg, b.fovMin, b.fovMax);
+        this.localFov = next;
+        void this.sink.setFov(next);
+    }
+    // ---------------------------------------------------------------------------
+    // FoV slider
+    // ---------------------------------------------------------------------------
+    /**
+     * Update the optimistic slider value and schedule a debounced `setFov`.
+     * The settled (paused) value is what gets sent; rapid drag input does not
+     * stream a command per pixel. Mirrors scheduleFovSlider.
+     */
+    fovSliderInput(fov) {
+        this.pendingFov = fov;
+        this.setSliderFovInternal(fov);
+        if (this.fovDebounceTimer !== null)
+            clearTimeout(this.fovDebounceTimer);
+        this.fovDebounceTimer = setTimeout(() => {
+            this.fovDebounceTimer = null;
+            this.flushFovSlider();
+        }, this.fovSliderDebounceMs);
+    }
+    /**
+     * Declare slider drag start/end. While dragging, echo-sync does not
+     * override the slider (the user is in control). Setting `false` flushes
+     * any pending debounced FoV immediately. Mirrors the pointer-up
+     * flushFovSlider call.
+     */
+    setFovSliderDragging(dragging) {
+        this.sliderDragging = dragging;
+        if (!dragging)
+            this.flushFovSlider();
+    }
+    /**
+     * Subscribe to slider FoV changes. The callback fires on `fovSliderInput`
+     * and on idle echo-sync (when the camera echo updates the slider). Returns
+     * an unsubscribe function.
+     */
+    onSliderFov(cb) {
+        this.sliderFovListeners.add(cb);
+        return () => {
+            this.sliderFovListeners.delete(cb);
+        };
+    }
+    // ---------------------------------------------------------------------------
+    // Ball drag
+    // ---------------------------------------------------------------------------
+    /**
+     * Declare ball-drag start/end. While dragging, echo-sync does not apply
+     * the echoed pan to the local accumulator (the user is in control).
+     * The pixel-deflection-to-rate conversion happens in the UI layer; the
+     * UI calls `setPanRate` with the normalised result.
+     */
+    setBallDragging(dragging) {
+        this.ballDragging = dragging;
+    }
+    // ---------------------------------------------------------------------------
+    // Lifecycle
+    // ---------------------------------------------------------------------------
+    /**
+     * Send zero pan and zoom rates if (and only if) a non-zero rate is currently
+     * active, and clear drag flags and any pending FoV timer without sending it.
+     * Use on component unmount or camera hide -- mirrors the cleanup effects at
+     * CameraFeed.tsx:477-508.
+     */
+    stop() {
+        if (this.sentPanRate.yaw !== 0 || this.sentPanRate.pitch !== 0) {
+            this.sentPanRate = { yaw: 0, pitch: 0 };
+            void this.sink.setPanRate(0, 0);
+        }
+        if (this.sentZoomRate !== 0) {
+            this.sentZoomRate = 0;
+            void this.sink.setZoomRate(0);
+        }
+        this.ballDragging = false;
+        this.sliderDragging = false;
+        if (this.fovDebounceTimer !== null) {
+            clearTimeout(this.fovDebounceTimer);
+            this.fovDebounceTimer = null;
+        }
+        this.pendingFov = null;
+    }
+    /**
+     * Stop the controller and drop all slider-change subscribers. Call when
+     * the owning component is permanently destroyed.
+     */
+    dispose() {
+        this.stop();
+        this.sliderFovListeners.clear();
+    }
+    // ---------------------------------------------------------------------------
+    // Private helpers
+    // ---------------------------------------------------------------------------
+    flushFovSlider() {
+        if (this.fovDebounceTimer !== null) {
+            clearTimeout(this.fovDebounceTimer);
+            this.fovDebounceTimer = null;
+        }
+        if (this.pendingFov !== null) {
+            const fov = clamp(this.pendingFov, this.bounds.fovMin, this.bounds.fovMax);
+            this.localFov = fov;
+            this.pendingFov = null;
+            void this.sink.setFov(fov);
+        }
+    }
+    setSliderFovInternal(fov) {
+        this._sliderFov = fov;
+        for (const cb of this.sliderFovListeners)
+            cb(fov);
+    }
+}

package/dist/testing/index.d.ts

@@ -0,0 +1,217 @@
+import type { AdaptiveShedPayload, CameraState, ClientMessage, ErrorPayload, SettingsStatePayload } from "../__generated__/types";
+import { CameraLifecycle, Layer, QualityPreset } from "../__generated__/types";
+import type { InboundVideoStats, KerbcastConnectionState, KerbcastTransport } from "../client";
+export interface MockCameraInit {
+    flightId: number;
+    lifecycle?: CameraLifecycle;
+    partName?: string;
+    partTitle?: string;
+    cameraName?: string;
+    vesselName?: string;
+    layers?: Layer[];
+    operatorLayers?: Layer[];
+    renderWidth?: number;
+    renderHeight?: number;
+    operatorWidth?: number;
+    operatorHeight?: number;
+    supportsZoom?: boolean;
+    fov?: number;
+    fovMin?: number;
+    fovMax?: number;
+    supportsPan?: boolean;
+    panYaw?: number;
+    panPitch?: number;
+    panYawMin?: number;
+    panYawMax?: number;
+    panPitchMin?: number;
+    panPitchMax?: number;
+    encoderBitrateBps?: number;
+    targetBitrateBps?: number;
+    degradeLevel?: number;
+    viewerQuality?: QualityPreset;
+    qualityLimitedBy?: string;
+}
+/**
+ * In-process protocol-level fake for the kerbcast sidecar.
+ *
+ * Owns a camera registry and speaks the full kerbcast wire protocol.
+ * Use it in tests to exercise `KerbcastClient` behaviour without a real
+ * sidecar or WebRTC stack.
+ *
+ * ```ts
+ * const sidecar = new MockSidecar();
+ * sidecar.addCamera({ flightId: 42 });
+ *
+ * vi.spyOn(globalThis, "fetch").mockImplementation(() =>
+ *   Promise.resolve(MockSidecar.makeOfferResponse([42]))
+ * );
+ *
+ * const client = new KerbcastClient({ host: "localhost", port: 8088 }, sidecar.createTransport());
+ * await client.connect([42]);
+ * sidecar.open();   // fires hello + camera-snapshot
+ *
+ * expect(client.cameras[0].flightId).toBe(42);
+ * ```
+ */
+export declare class MockSidecar {
+    private readonly _cameras;
+    private readonly _commands;
+    private _throttleMainScreen;
+    private _openHandler;
+    private _clientMsgHandler;
+    private _stateHandler;
+    private _onTrackHandler;
+    private _trackIdx;
+    /** Slot mids available for the dynamic-subscription model. Override with
+     *  {@link withSlots} before connecting if a test needs a specific pool. */
+    private _slotMids;
+    /** mid -> camera currently bound to that slot. */
+    private readonly _slotBindings;
+    /**
+     * Per-flight inbound stats to return from the fake getStats. Set via
+     * {@link setInboundStats}. Keyed by flightId.
+     */
+    private readonly _inboundStats;
+    /**
+     * Tracks delivered by {@link deliverTrack}, keyed by mid/idx string so
+     * getStats can synthesize a trackIdentifier matching what the client saw.
+     */
+    private readonly _deliveredTracks;
+    /** Register a camera that will appear in the `camera-snapshot` sent on `open()`. */
+    addCamera(init: MockCameraInit): void;
+    /**
+     * Returns a `KerbcastTransport` backed by this mock. Pass it as the
+     * second argument to `KerbcastClient`.
+     */
+    createTransport(): KerbcastTransport;
+    /**
+     * Simulate the sidecar completing the WebRTC handshake. Fires the
+     * channel `onOpen` handler (which triggers the client's `hello`), then
+     * responds with `hello` + `camera-snapshot`.
+     */
+    open(): void;
+    /** Drive the underlying peer's connection-state handler. */
+    setConnectionState(state: KerbcastConnectionState): void;
+    /**
+     * Mark a camera as destroyed and push a `camera-state-changed` message
+     * to the client. The camera stays in the internal registry with
+     * `lifecycle: Destroyed`.
+     */
+    destroyCamera(flightId: number): void;
+    /**
+     * Apply a partial update to an existing camera and push a
+     * `camera-state-changed` message to the client.
+     */
+    updateCamera(flightId: number, partial: Partial<CameraState>): void;
+    /**
+     * Replace the entire camera registry and push a fresh `camera-snapshot` to
+     * the client. Models a vessel change / scene switch where the set of
+     * available cameras changes (cameras appear or disappear) — distinct from
+     * {@link destroyCamera}, which keeps the camera present but `Destroyed`.
+     */
+    setCameras(inits: MockCameraInit[]): void;
+    /** Send a `ping` from the sidecar; the client should respond with `pong`. */
+    firePing(): void;
+    /** Push an `adaptive-shed` event to the client. */
+    fireAdaptiveShed(payload: AdaptiveShedPayload): void;
+    /** Push an `error` event to the client (simulates a sidecar error reply). */
+    fireError(payload: ErrorPayload): void;
+    /** Current mock-sidecar throttle state (reflects `set-throttle-main-screen` commands). */
+    get throttleMainScreen(): boolean;
+    /** Push a `settings-state` event to the client (simulates a plugin-status-change broadcast). */
+    fireSettingsState(payload: SettingsStatePayload): void;
+    /** Configure the slot-pool mids before connecting (dynamic mode). */
+    withSlots(mids: string[]): this;
+    /**
+     * Deliver a track onto a slot (by mid), simulating the slot's media
+     * arriving over WebRTC. The client routes it to whichever camera is bound
+     * to that mid. (jsdom can't make real tracks; pass a stub in unit tests or
+     * a `canvas.captureStream()` track in a real-browser harness.)
+     *
+     * The track is remembered so the fake `getStats()` can synthesize a
+     * `trackIdentifier` matching what the client received.
+     */
+    deliverTrack(mid: string, track: MediaStreamTrack): void;
+    /** The slot mid currently carrying `flightId`, or undefined. */
+    slotMidFor(flightId: number): string | undefined;
+    /** Every `ClientMessage` received from the client, in order. */
+    get commands(): ReadonlyArray<ClientMessage>;
+    /**
+     * Find the most recent client command of the given type. Pass `flightId`
+     * to further filter by camera (ignored for message types without a
+     * `content.flightId` field).
+     */
+    lastCommand<T extends ClientMessage["type"]>(type: T, flightId?: number): Extract<ClientMessage, {
+        type: T;
+    }> | undefined;
+    /**
+     * Build a `Response` that looks like the sidecar's `POST /offer` reply.
+     * Pass to `vi.spyOn(globalThis, "fetch").mockImplementation(...)` so the
+     * client's handshake can complete without a real HTTP server.
+     *
+     * ```ts
+     * vi.spyOn(globalThis, "fetch").mockImplementation(() =>
+     *   Promise.resolve(MockSidecar.makeOfferResponse([42]))
+     * );
+     * ```
+     */
+    static makeOfferResponse(cameras: number[]): Response;
+    /**
+     * Signaling-seam analogue of {@link makeOfferResponse}: resolve an offer's
+     * answer without HTTP. Pass as the client's `negotiate` config to exercise
+     * the brokered-signaling path a station uses.
+     */
+    negotiate(offer: {
+        sdp: string;
+        cameras: number[];
+        slots?: number;
+    }): Promise<{
+        sdp: string;
+        cameras: number[];
+    }>;
+    /**
+     * Configure the inbound video stats the fake `getStats()` will return for
+     * a given camera. Call before `client.inboundVideoStats()` in tests.
+     *
+     * The mock synthesizes a minimal `RTCStatsReport`-shaped object: one entry
+     * per flight that has stats set, with `type: "inbound-rtp"`, `kind: "video"`,
+     * and either a `trackIdentifier` matching the track delivered for that camera
+     * (legacy path) or a `mid` matching the slot binding (dynamic path), plus
+     * the stat fields from `partialStats`.
+     *
+     * ```ts
+     * sidecar.setInboundStats(42, { packetsReceived: 1000, framesDecoded: 300 });
+     * const stats = await client.inboundVideoStats();
+     * expect(stats.get(42)?.packetsReceived).toBe(1000);
+     * ```
+     */
+    setInboundStats(flightId: number, partialStats: Partial<InboundVideoStats>): void;
+    /** Build a minimal RTCStatsReport-compatible object for the current state. */
+    private _buildStatsReport;
+    private _sendToClient;
+    private _handleClientMessage;
+}
+/**
+ * Install jsdom shims needed by kerbcast component tests.
+ *
+ * jsdom omits several browser APIs that the SDK and React components call at
+ * construction or mount time. Stubbing here keeps individual tests clean.
+ * Each shim is idempotent so setup files can call `installDomStubs()`
+ * unconditionally.
+ *
+ * Stubs installed:
+ *   ResizeObserver   - jsdom does not implement it; CameraFeed uses it to
+ *                      drive auto render-size updates.
+ *   captureStream    - jsdom's HTMLCanvasElement lacks captureStream; the
+ *                      noise pipeline calls it to get its output MediaStream.
+ *                      Returns a stub MediaStream so callers receive a valid
+ *                      object rather than throwing.
+ *   MediaStream      - jsdom's MediaStream constructor is incomplete; tests
+ *                      need to construct instances for track delivery and
+ *                      stream assertions.
+ *   play             - jsdom prints "Not implemented" for HTMLMediaElement.play;
+ *                      the noise pipeline awaits it on the internal video element.
+ *   matchMedia       - jsdom does not implement window.matchMedia; theme
+ *                      detection reads prefers-color-scheme through it.
+ */
+export declare function installDomStubs(): void;