@ksp-gonogo/kerbcast 1.6.3 → 1.8.0

package/dist/testing/index.d.ts

@@ -1,9 +1,16 @@
 import type { AdaptiveShedPayload, CameraState, ClientMessage, ErrorPayload, SettingsStatePayload } from "../__generated__/types";
-import { CameraLifecycle, Layer, QualityPreset } from "../__generated__/types";
-import type { InboundVideoStats, KerbcastConnectionState, KerbcastTransport } from "../client";
+import { CameraKind, CameraLifecycle, CrewLocation, Layer, QualityPreset, TrackMode } from "../__generated__/types";
+import type { DiscoveredCamera, InboundVideoStats, KerbcastConnectionState, KerbcastTransport } from "../client";
 export interface MockCameraInit {
     flightId: number;
     lifecycle?: CameraLifecycle;
+    /** Part vs kerbal face camera. Defaults to `part` when omitted, so existing
+     *  part-cam callers are unchanged. */
+    kind?: CameraKind;
+    /** Only meaningful for `kind: Kerbal`: seated IVA portrait vs EVA view. */
+    crewLocation?: CrewLocation;
+    /** Only meaningful for `kind: Kerbal`: informational raw persistentID. */
+    kerbalPersistentId?: number;
     partName?: string;
     partTitle?: string;
     cameraName?: string;
@@ -30,6 +37,29 @@ export interface MockCameraInit {
     degradeLevel?: number;
     viewerQuality?: QualityPreset;
     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.
@@ -57,10 +87,19 @@ 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;
     private _onTrackHandler;
+    private _subscribeHandler;
     private _trackIdx;
     /** Slot mids available for the dynamic-subscription model. Override with
      *  {@link withSlots} before connecting if a test needs a specific pool. */
@@ -79,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`.
@@ -134,6 +181,13 @@ export declare class MockSidecar {
      * `trackIdentifier` matching what the client received.
      */
     deliverTrack(mid: string, track: MediaStreamTrack): void;
+    /**
+     * Register a handler fired each time a `subscribe` binds a camera to a slot,
+     * with `(flightId, mid)`. A browser harness uses it to deliver that camera's
+     * track to the mid it was actually bound to — so tracks follow the real
+     * subscription order, not the registration/array order. Set before connecting.
+     */
+    onSubscribe(handler: (flightId: number, mid: string) => void): void;
     /** The slot mid currently carrying `flightId`, or undefined. */
     slotMidFor(flightId: number): string | undefined;
     /** Every `ClientMessage` received from the client, in order. */
@@ -192,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.
@@ -217,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

@@ -1,8 +1,11 @@
-import { CameraLifecycle, ErrorSource, Layer, QualityPreset } from "../__generated__/types";
+import { CameraKind, CameraLifecycle, ErrorSource, Layer, QualityPreset, TrackMode } from "../__generated__/types";
 function buildCamera(init) {
     return {
         flightId: init.flightId,
         lifecycle: init.lifecycle ?? CameraLifecycle.Active,
+        kind: init.kind ?? CameraKind.Part,
+        crewLocation: init.crewLocation,
+        kerbalPersistentId: init.kerbalPersistentId,
         partName: init.partName ?? `part-${init.flightId}`,
         partTitle: init.partTitle ?? `Part ${init.flightId}`,
         cameraName: init.cameraName ?? `camera-${init.flightId}`,
@@ -29,6 +32,7 @@ function buildCamera(init) {
         degradeLevel: init.degradeLevel ?? 0,
         viewerQuality: init.viewerQuality,
         qualityLimitedBy: init.qualityLimitedBy,
+        trackMode: init.trackMode ?? TrackMode.None,
     };
 }
 /** Fraction of the operator render size each preset targets (mirrors the
@@ -67,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. */
@@ -87,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
@@ -181,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",
@@ -233,6 +292,15 @@ export class MockSidecar {
         this._deliveredTracks.set(mid, track);
         this._onTrackHandler?.(track, this._trackIdx++, mid);
     }
+    /**
+     * Register a handler fired each time a `subscribe` binds a camera to a slot,
+     * with `(flightId, mid)`. A browser harness uses it to deliver that camera's
+     * track to the mid it was actually bound to — so tracks follow the real
+     * subscription order, not the registration/array order. Set before connecting.
+     */
+    onSubscribe(handler) {
+        this._subscribeHandler = handler;
+    }
     /** The slot mid currently carrying `flightId`, or undefined. */
     slotMidFor(flightId) {
         for (const [mid, fid] of this._slotBindings) {
@@ -439,6 +507,18 @@ export class MockSidecar {
                 this._sendToClient({ type: "camera-state-changed", content: { state: updated } });
                 break;
             }
+            case "set-track-target": {
+                // Server-authoritative: hold the chosen mode and broadcast it back as
+                // camera-state-changed, mirroring the sidecar so every browser reflects
+                // the same trackMode (never optimistic-local).
+                const cam = this._cameras.get(msg.content.flightId);
+                if (cam) {
+                    const updated = { ...cam, trackMode: msg.content.mode };
+                    this._cameras.set(msg.content.flightId, updated);
+                    this._sendToClient({ type: "camera-state-changed", content: { state: updated } });
+                }
+                break;
+            }
             case "subscribe": {
                 const flightId = msg.content.flightId;
                 const freeMid = this._slotMids.find((m) => !this._slotBindings.has(m));
@@ -454,6 +534,9 @@ export class MockSidecar {
                         type: "slot-map",
                         content: { mid: freeMid, flightId },
                     });
+                    // Let a harness deliver this camera's track to the slot it was just
+                    // bound to (so tracks follow the actual subscription, not array order).
+                    this._subscribeHandler?.(flightId, freeMid);
                 }
                 break;
             }
@@ -479,6 +562,11 @@ export class MockSidecar {
             // the mock has no frame clock, so it doesn't model their *effect* on
             // panYaw/fov. They're still recorded in `_commands`, so consumer tests
             // can assert the command was sent via `lastCommand("set-pan-rate")`.
+            // Advisory per-consumer display-size input. The real sidecar aggregates
+            // it MAX-across-consumers to drive auto-resolution; the mock has no
+            // aggregator, so it just records the command (via `_commands`) and does
+            // NOT mutate camera render dims (unlike the operator `set-render-size`).
+            case "report-display-size":
             case "set-pan-rate":
             case "set-zoom-rate":
             case "hello":
@@ -494,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.
@@ -544,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") {
@@ -567,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];
@@ -608,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.6.3",
+  "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

@@ -20,6 +20,37 @@ export enum CameraLifecycle {
 	Destroyed = "destroyed",
 }
 
+/**
+ * Distinguishes an existing Hullcam part camera (`Part`) from a
+ * per-kerbal face camera (`Kerbal`).
+ */
+export enum CameraKind {
+	Part = "part",
+	Kerbal = "kerbal",
+}
+
+/**
+ * Which source a kerbal camera is currently rendering: a seated IVA
+ * portrait, or the kerbal's own view while on EVA. Only meaningful when
+ * `CameraState.kind == Kerbal`.
+ */
+export enum CrewLocation {
+	Seat = "seat",
+	Eva = "eva",
+}
+
+/**
+ * Which moving thing a pan+zoom camera should auto-aim at. `None` = tracking
+ * off (manual pan resumes). `ActiveVessel` and `Target` resolve to a world
+ * position from `FlightGlobals` (the active vessel, or its target) with no
+ * orbit math. Only surfaces on cameras with BOTH pan and zoom.
+ */
+export enum TrackMode {
+	None = "none",
+	ActiveVessel = "activeVessel",
+	Target = "target",
+}
+
 /**
  * Layer mask. Mirrors `Kerbcast.CameraLayers` on the plugin side.
  * Receiving clients use this for both the rendered-layer status reports
@@ -70,6 +101,29 @@ export interface CameraState {
 	 * surface a "SIGNAL LOST" overlay and keep the last frame visible.
 	 */
 	lifecycle?: CameraLifecycle;
+	/**
+	 * Whether this is a Hullcam part camera or a per-kerbal face camera.
+	 * Defaults to `Part` so existing payloads are unaffected.
+	 */
+	kind?: CameraKind;
+	/**
+	 * The kerbal's real `ProtoCrewMember.persistentID`: the stable key a
+	 * consumer correlates against. `None` for part cameras. Distinct from
+	 * `flight_id`, which identifies the camera instance, not the kerbal.
+	 */
+	kerbalPersistentId?: number;
+	/**
+	 * Which source a kerbal camera is currently rendering. `None` for
+	 * part cameras.
+	 */
+	crewLocation?: CrewLocation;
+	/**
+	 * Server-authoritative auto-track state for a pan+zoom camera (the
+	 * operator's persistent intent). `None` (the default) = not tracking.
+	 * Every browser reflects this; a browser track overrides a kOS aim on the
+	 * same camera (send `SetTrackTarget` with `none` to hand back to kOS).
+	 */
+	trackMode?: TrackMode;
 	partName: string;
 	partTitle: string;
 	cameraName: string;
@@ -190,6 +244,20 @@ export interface HelloPayload {
 	encoderBackend: string;
 }
 
+/**
+ * A consumer reporting its OWN current display size in px for one camera.
+ * Unlike `SetRenderSizePayload` (an operator command that sets the shared
+ * render size directly, last-writer-wins), this is a per-consumer input the
+ * sidecar aggregates MAX-across-consumers to drive auto-resolution
+ * (meet-the-minimum-need). Shape mirrors `SetRenderSizePayload`; `width` and
+ * `height` are the consumer's display px for this feed.
+ */
+export interface ReportDisplaySizePayload {
+	flightId: number;
+	width: number;
+	height: number;
+}
+
 /**
  * Scene-state change: whether KSP is currently in a flight scene. Sent
  * after `Hello` (priming) and whenever the polled in-flight flag flips,
@@ -213,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;
@@ -272,6 +352,22 @@ export interface SetThrottleMainScreenPayload {
 	enabled: boolean;
 }
 
+/**
+ * Ask a pan+zoom camera to auto-track a moving vessel (or stop). Mirrors
+ * `SetRenderSizePayload` in shape. Server-authoritative: the sidecar holds the
+ * chosen mode per camera and publishes it in `CameraState.track_mode`, so
+ * every browser reflects the same tracking state (never optimistic-local).
+ * 
+ * Precedence note (for operators): a browser track OVERRIDES a kOS aim on the
+ * same camera; set `mode: none` to hand aiming back to kOS. While tracking, the
+ * camera also AUTO-ZOOMS to keep the target framed (distance-driven), owning the
+ * zoom over any manual FoV; `mode: none` restores manual zoom untouched.
+ */
+export interface SetTrackTargetPayload {
+	flightId: number;
+	mode: TrackMode;
+}
+
 export interface SetZoomRatePayload {
 	flightId: number;
 	/**
@@ -345,10 +441,38 @@ export type ClientMessage =
 	 */
 	| { type: "set-layers", content: SetLayersPayload }
 	/**
-	 * Override the operator render size for one camera. Even pixels
-	 * only (H.264 chroma); server caps at the ring's allocated max.
+	 * Cap the auto-resolution for one camera. As of Stage 6 this is a
+	 * CEILING on the demand-driven size (effective = min(auto max-across-
+	 * consumers, this cap)), NOT an authoritative set: it cannot force a
+	 * camera larger than current consumers report, only smaller. Even
+	 * pixels only (H.264 chroma); server caps at the ring's allocated max.
 	 */
 	| { type: "set-render-size", content: SetRenderSizePayload }
+	/**
+	 * Auto-track a moving vessel with a pan+zoom camera (or stop). The sidecar
+	 * holds the chosen `mode` per camera and publishes it in
+	 * `CameraState.track_mode`, so tracking state is server-authoritative and
+	 * consistent across browsers. A browser track OVERRIDES a kOS aim on the
+	 * same camera; send `mode: none` to hand aiming back to kOS.
+	 */
+	| { type: "set-track-target", content: SetTrackTargetPayload }
+	/**
+	 * A consumer reporting its OWN current display size in px; the sidecar
+	 * aggregates MAX-across-consumers to drive auto-resolution
+	 * (meet-the-minimum-need). Distinct from the operator `SetRenderSize`
+	 * command: this is a per-consumer input, not a shared override — a
+	 * 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 ==