@ksp-gonogo/kerbcast 1.6.2 → 1.7.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 1.7.0 - 2026-07-24
+
+Crew face cameras, auto-resolution, and camera targeting.
+
+### Added
+
+- `KerbcastClient.reportDisplaySize(flightId, width, height)`: report a
+  consumer's own displayed pixel size for a camera. The sidecar aggregates it
+  MAX-across-consumers to drive auto-resolution (distinct from `setRenderSize`,
+  which is the shared operator cap).
+- `KerbcastClient.setTrackTarget(flightId, mode)`: ask a pan+zoom camera to
+  auto-track a moving vessel, or stop.
+- `TrackMode` type (`"none" | "activeVessel" | "target"`).
+- `trackMode?: TrackMode` on `CameraState` (WS push) and `CameraInfo`
+  (`GET /cameras`), server-authoritative so every consumer reflects the same
+  tracking state.
+- `MockSidecar` accepts the new `report-display-size` and `set-track-target`
+  client messages (records them; `report-display-size` is advisory and does not
+  mutate render dims).
+- `MockCameraInit` gains `kind`, `crewLocation`, `kerbalPersistentId`, and
+  `trackMode` for building crew and tracking fixtures.
+
 ## 0.12.0 - 2026-06-07
 
 ### Added

package/README.md

@@ -106,6 +106,22 @@ controls each part actually supports.
   skip, producing the macroblocking and stuttering aesthetic of
   in-game CommNet signal loss. Also a real CPU optimisation when
   every consumer wants degraded video.
+- `kind` (`"part"` | `"kerbal"`) and, for a kerbal face camera,
+  `crewLocation` (`"seat"` | `"eva"`). Distinguish crew face cameras
+  from part cameras.
+- `trackMode` (`"none"` | `"activeVessel"` | `"target"`). Server-authoritative
+  auto-track state on a pan+zoom camera, so every consumer reflects the same
+  tracking state.
+
+## Auto-resolution and targeting
+
+- `client.reportDisplaySize(flightId, width, height)`. Report a consumer's
+  displayed pixel size for a camera; the sidecar takes the MAX across consumers
+  to size the encode (distinct from `setRenderSize`, the shared operator cap).
+  The react feed primitives self-measure and call this for you.
+- `client.setTrackTarget(flightId, mode)`. Ask a pan+zoom camera to auto-track
+  the active vessel or its target (`TrackMode`), or `"none"` to stop. The
+  chosen mode is published back on `CameraState.trackMode`.
 
 ## Pan/zoom input helper
 

package/dist/__generated__/types.d.ts

@@ -14,6 +14,34 @@ export declare enum CameraLifecycle {
     Active = "active",
     Destroyed = "destroyed"
 }
+/**
+ * Distinguishes an existing Hullcam part camera (`Part`) from a
+ * per-kerbal face camera (`Kerbal`).
+ */
+export declare 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 declare 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 declare 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
@@ -62,6 +90,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;
@@ -131,8 +182,8 @@ export interface CameraState {
      */
     targetBitrateBps: number;
     /**
-     * Effective degrade level (max across subscribers' SetDegrade
-     * requests). 0.0 = perfect, 1.0 = max degradation. Applied
+     * Effective degrade level (last-writer-wins across subscribers'
+     * SetDegrade requests). 0.0 = perfect, 1.0 = max degradation. Applied
      * alongside operator render-size + adaptive shed; the encoder
      * multiplies its effective bitrate by `(1 - 0.7 * level)` and
      * skips fan-out for a fraction of frames at high levels.
@@ -175,6 +226,19 @@ export interface HelloPayload {
     sidecarVersion: string;
     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,
@@ -187,10 +251,12 @@ export interface SceneStateChangedPayload {
 export interface SetDegradePayload {
     flightId: number;
     /**
-     * 0.0 = perfect quality, 1.0 = maximum degradation. Caps and
-     * is per-subscriber: the sidecar applies max across active
-     * subscribers so the noisiest consumer's request wins (same
-     * pattern as REMB picking the min bandwidth).
+     * 0.0 = perfect quality, 1.0 = maximum degradation. Clamped.
+     * Last-writer-wins: degrade is a property of the camera's game
+     * state (comms strength), shared by all viewers of the single
+     * encoded stream, so the sidecar stores the latest value rather
+     * than reducing across subscribers. A well-behaved driver
+     * re-asserts every tick.
      */
     level: number;
 }
@@ -246,6 +312,21 @@ 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;
     /**
@@ -322,13 +403,38 @@ export type ClientMessage =
     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;
+}
 /**
  * Set the camera's field-of-view (degrees). Silently ignored for
  * parts whose Hullcam module is the fixed base (`supportsZoom ==
@@ -379,11 +485,12 @@ export type ClientMessage =
 }
 /**
  * Request artificial signal degradation. 0.0 = perfect quality,
- * 1.0 = maximum degradation. Per-subscriber: the sidecar
- * applies max across active subscribers (slowest consumer
- * wins, same pattern as REMB bandwidth). Lets consumers signal
- * to the sidecar "I want to look like the in-game CommNet
- * antenna is struggling"; sidecar takes the opportunity to
+ * 1.0 = maximum degradation. Last-writer-wins: the sidecar stores
+ * the latest value on the camera (degrade is shared across all
+ * viewers of the one encoded stream), so a departed peer can't
+ * pin it. Lets consumers signal to the sidecar "I want to look
+ * like the in-game CommNet antenna is struggling"; sidecar takes
+ * the opportunity to
  * reduce bitrate + skip frames, which both creates the
  * signal-loss aesthetic AND saves encoder CPU.
  */

package/dist/__generated__/types.js

@@ -13,6 +13,37 @@ export var CameraLifecycle;
     CameraLifecycle["Active"] = "active";
     CameraLifecycle["Destroyed"] = "destroyed";
 })(CameraLifecycle || (CameraLifecycle = {}));
+/**
+ * Distinguishes an existing Hullcam part camera (`Part`) from a
+ * per-kerbal face camera (`Kerbal`).
+ */
+export var CameraKind;
+(function (CameraKind) {
+    CameraKind["Part"] = "part";
+    CameraKind["Kerbal"] = "kerbal";
+})(CameraKind || (CameraKind = {}));
+/**
+ * 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 var CrewLocation;
+(function (CrewLocation) {
+    CrewLocation["Seat"] = "seat";
+    CrewLocation["Eva"] = "eva";
+})(CrewLocation || (CrewLocation = {}));
+/**
+ * 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 var TrackMode;
+(function (TrackMode) {
+    TrackMode["None"] = "none";
+    TrackMode["ActiveVessel"] = "activeVessel";
+    TrackMode["Target"] = "target";
+})(TrackMode || (TrackMode = {}));
 /**
  * Layer mask. Mirrors `Kerbcast.CameraLayers` on the plugin side.
  * Receiving clients use this for both the rendered-layer status reports

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import type { AdaptiveShedPayload, CameraState, ClientMessage, ErrorPayload, Layer, QualityPreset, SettingsStatePayload } from "./__generated__/types";
+import type { AdaptiveShedPayload, CameraState, ClientMessage, ErrorPayload, Layer, QualityPreset, SettingsStatePayload, TrackMode } from "./__generated__/types";
 import { CameraLifecycle } from "./__generated__/types";
 /** Controls the digital-static noise overlay baked into `cam.mediaStream`. */
 export interface NoiseConfig {
@@ -409,6 +409,23 @@ export declare class KerbcastClient extends TypedEmitter<KerbcastClientEvents> {
      * goes null once the sidecar confirms with a SlotMap.
      */
     unsubscribe(flightId: number): Promise<void>;
+    /**
+     * Report this consumer's own displayed pixel size for a camera, driving the
+     * sidecar's auto-resolution. Unlike `setRenderSize` (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, so a big
+     * spotlight bumps the stream up while tiny avatars leave it small. The SDK's
+     * feed primitives self-measure and call this; consumers do not report by hand.
+     */
+    reportDisplaySize(flightId: number, width: number, height: number): Promise<void>;
+    /**
+     * Ask a pan+zoom camera to auto-track a moving vessel (or stop). Sends the
+     * intent; the sidecar holds the chosen mode per camera and publishes it in
+     * `CameraState.trackMode`, so the UI must reflect that server-confirmed value
+     * rather than this call (two browsers stay in agreement). While tracking, the
+     * camera also auto-zooms; `TrackMode.None` hands aiming/zoom back.
+     */
+    setTrackTarget(flightId: number, mode: TrackMode): Promise<void>;
     /**
      * Internal — resolves the effective noise enabled state for a camera,
      * merging the per-camera override (if any) with the client-level default.

package/dist/client.js

@@ -4,6 +4,13 @@ import { tryCreateNoisePipeline } from "./noise";
 const SOURCELESS_INTENSITY = 1.0;
 /** Floor applied to the degrade-driven intensity of a live feed. */
 const LIVE_INTENSITY_FLOOR = 0.05;
+/**
+ * While a feed is stalled, how often to re-request a keyframe. A stall is
+ * usually a wedged decoder that only a fresh IDR clears; the first request or
+ * its keyframe can be lost during the same outage, so we keep asking until
+ * frames resume.
+ */
+const STALL_KEYFRAME_RETRY_MS = 2000;
 export class BrowserKerbcastTransport {
     constructor(opts = {}) {
         this.opts = { iceGatheringTimeoutMs: opts.iceGatheringTimeoutMs ?? 2000 };
@@ -159,6 +166,8 @@ class CameraHandle extends TypedEmitter {
         this._sourceless = false;
         /** Stall state mirrored from the pipeline's onStallChange callback. */
         this._stalled = false;
+        /** Interval that re-requests keyframes while stalled; null when not stalled. */
+        this._keyframeRetry = null;
         /** Whether animated static is drawn; survives pipeline rebuilds. */
         this._showStatic = true;
         this.flightId = flightId;
@@ -291,6 +300,26 @@ class CameraHandle extends TypedEmitter {
             return;
         this._stalled = stalled;
         this.emit("stall", stalled);
+        if (stalled) {
+            // A stall usually means the browser decoder is wedged (broken H.264
+            // reference chain after packet loss or heavy degrade), which only a
+            // fresh keyframe clears. Force one now and keep asking while stalled,
+            // rather than waiting on the browser's rate-limited PLI.
+            this._requestKeyframeForRecovery();
+            if (this._keyframeRetry === null) {
+                this._keyframeRetry = setInterval(() => this._requestKeyframeForRecovery(), STALL_KEYFRAME_RETRY_MS);
+            }
+        }
+        else if (this._keyframeRetry !== null) {
+            clearInterval(this._keyframeRetry);
+            this._keyframeRetry = null;
+        }
+    }
+    _requestKeyframeForRecovery() {
+        this.requestKeyframe().catch(() => {
+            // Best effort; a failed send (disconnected) is retried on the next tick,
+            // or cleared when the stall ends.
+        });
     }
     _liveIntensity() {
         return Math.max(LIVE_INTENSITY_FLOOR, this._state?.degradeLevel ?? 0);
@@ -300,6 +329,10 @@ class CameraHandle extends TypedEmitter {
      * the persistent pipeline, stops its rAF loop, and nulls the stream.
      */
     _teardown() {
+        if (this._keyframeRetry !== null) {
+            clearInterval(this._keyframeRetry);
+            this._keyframeRetry = null;
+        }
         this._noisePipeline?.destroy();
         this._noisePipeline = null;
         this._rawStream = null;
@@ -625,6 +658,27 @@ export class KerbcastClient extends TypedEmitter {
     async unsubscribe(flightId) {
         await this._send({ type: "unsubscribe", content: { flightId } });
     }
+    /**
+     * Report this consumer's own displayed pixel size for a camera, driving the
+     * sidecar's auto-resolution. Unlike `setRenderSize` (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, so a big
+     * spotlight bumps the stream up while tiny avatars leave it small. The SDK's
+     * feed primitives self-measure and call this; consumers do not report by hand.
+     */
+    async reportDisplaySize(flightId, width, height) {
+        await this._send({ type: "report-display-size", content: { flightId, width, height } });
+    }
+    /**
+     * Ask a pan+zoom camera to auto-track a moving vessel (or stop). Sends the
+     * intent; the sidecar holds the chosen mode per camera and publishes it in
+     * `CameraState.trackMode`, so the UI must reflect that server-confirmed value
+     * rather than this call (two browsers stay in agreement). While tracking, the
+     * camera also auto-zooms; `TrackMode.None` hands aiming/zoom back.
+     */
+    async setTrackTarget(flightId, mode) {
+        await this._send({ type: "set-track-target", content: { flightId, mode } });
+    }
     /**
      * Internal — resolves the effective noise enabled state for a camera,
      * merging the per-camera override (if any) with the client-level default.

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 { CameraKind, CameraLifecycle, CrewLocation, Layer, QualityPreset, TrackMode } from "../__generated__/types";
 import type { 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,8 @@ export interface MockCameraInit {
     degradeLevel?: number;
     viewerQuality?: QualityPreset;
     qualityLimitedBy?: string;
+    /** Server-authoritative auto-track mode. Defaults to `None` (untracked). */
+    trackMode?: TrackMode;
 }
 /**
  * In-process protocol-level fake for the kerbcast sidecar.
@@ -61,6 +70,7 @@ export declare class MockSidecar {
     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. */
@@ -134,6 +144,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. */

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
@@ -233,6 +237,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 +452,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 +479,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 +507,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":

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ksp-gonogo/kerbcast",
-  "version": "1.6.2",
+  "version": "1.7.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",

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;
@@ -139,8 +193,8 @@ export interface CameraState {
 	 */
 	targetBitrateBps: number;
 	/**
-	 * Effective degrade level (max across subscribers' SetDegrade
-	 * requests). 0.0 = perfect, 1.0 = max degradation. Applied
+	 * Effective degrade level (last-writer-wins across subscribers'
+	 * SetDegrade requests). 0.0 = perfect, 1.0 = max degradation. Applied
 	 * alongside operator render-size + adaptive shed; the encoder
 	 * multiplies its effective bitrate by `(1 - 0.7 * level)` and
 	 * skips fan-out for a fraction of frames at high levels.
@@ -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,
@@ -203,10 +271,12 @@ export interface SceneStateChangedPayload {
 export interface SetDegradePayload {
 	flightId: number;
 	/**
-	 * 0.0 = perfect quality, 1.0 = maximum degradation. Caps and
-	 * is per-subscriber: the sidecar applies max across active
-	 * subscribers so the noisiest consumer's request wins (same
-	 * pattern as REMB picking the min bandwidth).
+	 * 0.0 = perfect quality, 1.0 = maximum degradation. Clamped.
+	 * Last-writer-wins: degrade is a property of the camera's game
+	 * state (comms strength), shared by all viewers of the single
+	 * encoded stream, so the sidecar stores the latest value rather
+	 * than reducing across subscribers. A well-behaved driver
+	 * re-asserts every tick.
 	 */
 	level: number;
 }
@@ -270,6 +340,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;
 	/**
@@ -343,10 +429,29 @@ 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 }
 	/**
 	 * Set the camera's field-of-view (degrees). Silently ignored for
 	 * parts whose Hullcam module is the fixed base (`supportsZoom ==
@@ -385,11 +490,12 @@ export type ClientMessage =
 	| { type: "set-zoom-rate", content: SetZoomRatePayload }
 	/**
 	 * Request artificial signal degradation. 0.0 = perfect quality,
-	 * 1.0 = maximum degradation. Per-subscriber: the sidecar
-	 * applies max across active subscribers (slowest consumer
-	 * wins, same pattern as REMB bandwidth). Lets consumers signal
-	 * to the sidecar "I want to look like the in-game CommNet
-	 * antenna is struggling"; sidecar takes the opportunity to
+	 * 1.0 = maximum degradation. Last-writer-wins: the sidecar stores
+	 * the latest value on the camera (degrade is shared across all
+	 * viewers of the one encoded stream), so a departed peer can't
+	 * pin it. Lets consumers signal to the sidecar "I want to look
+	 * like the in-game CommNet antenna is struggling"; sidecar takes
+	 * the opportunity to
 	 * reduce bitrate + skip frames, which both creates the
 	 * signal-loss aesthetic AND saves encoder CPU.
 	 */

package/src/client.test.ts

@@ -4,6 +4,7 @@ import {
   ErrorSource,
   Layer,
   QualityPreset,
+  TrackMode,
 } from "./__generated__/types";
 import {
   BrowserKerbcastTransport,
@@ -381,6 +382,44 @@ describe("KerbcastClient", () => {
     ]);
   });
 
+  it("reportDisplaySize sends a report-display-size command", 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;
+
+    await client.reportDisplaySize(3, 40, 40);
+
+    expect(captured.dc?.sent).toEqual([
+      JSON.stringify({
+        type: "report-display-size",
+        content: { flightId: 3, width: 40, height: 40 },
+      }),
+    ]);
+  });
+
+  it("setTrackTarget sends a set-track-target command", 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;
+
+    await client.setTrackTarget(5, TrackMode.ActiveVessel);
+
+    expect(captured.dc?.sent).toEqual([
+      JSON.stringify({
+        type: "set-track-target",
+        content: { flightId: 5, mode: TrackMode.ActiveVessel },
+      }),
+    ]);
+  });
+
   it("disconnect tears down peer + emits null MediaStream events", async () => {
     const { transport, captured } = makeFakeTransport();
     const client = new KerbcastClient({ host: "h", port: 1 }, transport);

package/src/client.ts

@@ -7,6 +7,7 @@ import type {
   QualityPreset,
   ServerMessage,
   SettingsStatePayload,
+  TrackMode,
 } from "./__generated__/types";
 import { CameraLifecycle, ErrorSource } from "./__generated__/types";
 import { type NoisePipeline, tryCreateNoisePipeline } from "./noise";
@@ -15,6 +16,13 @@ import { type NoisePipeline, tryCreateNoisePipeline } from "./noise";
 const SOURCELESS_INTENSITY = 1.0;
 /** Floor applied to the degrade-driven intensity of a live feed. */
 const LIVE_INTENSITY_FLOOR = 0.05;
+/**
+ * While a feed is stalled, how often to re-request a keyframe. A stall is
+ * usually a wedged decoder that only a fresh IDR clears; the first request or
+ * its keyframe can be lost during the same outage, so we keep asking until
+ * frames resume.
+ */
+const STALL_KEYFRAME_RETRY_MS = 2000;
 
 /** Controls the digital-static noise overlay baked into `cam.mediaStream`. */
 export interface NoiseConfig {
@@ -473,6 +481,8 @@ class CameraHandle
   private _sourceless = false;
   /** Stall state mirrored from the pipeline's onStallChange callback. */
   private _stalled = false;
+  /** Interval that re-requests keyframes while stalled; null when not stalled. */
+  private _keyframeRetry: ReturnType<typeof setInterval> | null = null;
   /** Whether animated static is drawn; survives pipeline rebuilds. */
   private _showStatic = true;
   private readonly client: KerbcastClient;
@@ -625,6 +635,29 @@ class CameraHandle
     if (this._stalled === stalled) return;
     this._stalled = stalled;
     this.emit("stall", stalled);
+    if (stalled) {
+      // A stall usually means the browser decoder is wedged (broken H.264
+      // reference chain after packet loss or heavy degrade), which only a
+      // fresh keyframe clears. Force one now and keep asking while stalled,
+      // rather than waiting on the browser's rate-limited PLI.
+      this._requestKeyframeForRecovery();
+      if (this._keyframeRetry === null) {
+        this._keyframeRetry = setInterval(
+          () => this._requestKeyframeForRecovery(),
+          STALL_KEYFRAME_RETRY_MS,
+        );
+      }
+    } else if (this._keyframeRetry !== null) {
+      clearInterval(this._keyframeRetry);
+      this._keyframeRetry = null;
+    }
+  }
+
+  private _requestKeyframeForRecovery(): void {
+    this.requestKeyframe().catch(() => {
+      // Best effort; a failed send (disconnected) is retried on the next tick,
+      // or cleared when the stall ends.
+    });
   }
 
   private _liveIntensity(): number {
@@ -636,6 +669,10 @@ class CameraHandle
    * the persistent pipeline, stops its rAF loop, and nulls the stream.
    */
   _teardown(): void {
+    if (this._keyframeRetry !== null) {
+      clearInterval(this._keyframeRetry);
+      this._keyframeRetry = null;
+    }
     this._noisePipeline?.destroy();
     this._noisePipeline = null;
     this._rawStream = null;
@@ -1004,6 +1041,29 @@ export class KerbcastClient extends TypedEmitter<KerbcastClientEvents> {
     await this._send({ type: "unsubscribe", content: { flightId } });
   }
 
+  /**
+   * Report this consumer's own displayed pixel size for a camera, driving the
+   * sidecar's auto-resolution. Unlike `setRenderSize` (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, so a big
+   * spotlight bumps the stream up while tiny avatars leave it small. The SDK's
+   * feed primitives self-measure and call this; consumers do not report by hand.
+   */
+  async reportDisplaySize(flightId: number, width: number, height: number): Promise<void> {
+    await this._send({ type: "report-display-size", content: { flightId, width, height } });
+  }
+
+  /**
+   * Ask a pan+zoom camera to auto-track a moving vessel (or stop). Sends the
+   * intent; the sidecar holds the chosen mode per camera and publishes it in
+   * `CameraState.trackMode`, so the UI must reflect that server-confirmed value
+   * rather than this call (two browsers stay in agreement). While tracking, the
+   * camera also auto-zooms; `TrackMode.None` hands aiming/zoom back.
+   */
+  async setTrackTarget(flightId: number, mode: TrackMode): Promise<void> {
+    await this._send({ type: "set-track-target", content: { flightId, mode } });
+  }
+
   /**
    * Internal — resolves the effective noise enabled state for a camera,
    * merging the per-camera override (if any) with the client-level default.

package/src/testing/index.ts

@@ -1,5 +1,5 @@
 import type { AdaptiveShedPayload, CameraState, ClientMessage, ErrorPayload, ServerMessage, SettingsStatePayload } from "../__generated__/types";
-import { CameraLifecycle, ErrorSource, Layer, QualityPreset } from "../__generated__/types";
+import { CameraKind, CameraLifecycle, CrewLocation, ErrorSource, Layer, QualityPreset, TrackMode } from "../__generated__/types";
 import type {
   InboundVideoStats,
   KerbcastConnectionState,
@@ -11,6 +11,13 @@ import type {
 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;
@@ -37,12 +44,17 @@ export interface MockCameraInit {
   degradeLevel?: number;
   viewerQuality?: QualityPreset;
   qualityLimitedBy?: string;
+  /** Server-authoritative auto-track mode. Defaults to `None` (untracked). */
+  trackMode?: TrackMode;
 }
 
 function buildCamera(init: MockCameraInit): CameraState {
   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}`,
@@ -69,6 +81,7 @@ function buildCamera(init: MockCameraInit): CameraState {
     degradeLevel: init.degradeLevel ?? 0,
     viewerQuality: init.viewerQuality,
     qualityLimitedBy: init.qualityLimitedBy,
+    trackMode: init.trackMode ?? TrackMode.None,
   };
 }
 
@@ -120,6 +133,9 @@ export class MockSidecar {
   private _onTrackHandler:
     | ((track: MediaStreamTrack, idx: number, mid: string) => void)
     | undefined;
+  private _subscribeHandler:
+    | ((flightId: number, mid: string) => void)
+    | undefined;
   private _trackIdx = 0;
   /** Slot mids available for the dynamic-subscription model. Override with
    *  {@link withSlots} before connecting if a test needs a specific pool. */
@@ -295,6 +311,16 @@ export class MockSidecar {
     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: (flightId: number, mid: string) => void): void {
+    this._subscribeHandler = handler;
+  }
+
   /** The slot mid currently carrying `flightId`, or undefined. */
   slotMidFor(flightId: number): string | undefined {
     for (const [mid, fid] of this._slotBindings) {
@@ -520,6 +546,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: CameraState = { ...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));
@@ -534,6 +572,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;
       }
@@ -559,6 +600,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":

package/src/testing.test.ts

@@ -1,5 +1,5 @@
 import { beforeEach, describe, expect, it, vi } from "vitest";
-import { CameraLifecycle, Layer } from "./__generated__/types";
+import { CameraLifecycle, Layer, TrackMode } from "./__generated__/types";
 import { KerbcastClient } from "./index";
 import { MockSidecar } from "./testing/index";
 
@@ -121,6 +121,48 @@ describe("MockSidecar", () => {
     expect(last?.content.fov).toBe(60);
   });
 
+  it("accepts and records report-display-size as an advisory command", async () => {
+    const sidecar = new MockSidecar();
+    sidecar.addCamera({ flightId: 42 });
+
+    const client = new KerbcastClient(
+      { host: "localhost", port: 8088 },
+      sidecar.createTransport(),
+    );
+    await client.connect([42]);
+    sidecar.open();
+
+    // Must not throw on the new message type, and must be retrievable.
+    await client.reportDisplaySize(42, 40, 40);
+
+    const cmd = sidecar.lastCommand("report-display-size", 42);
+    expect(cmd?.content).toEqual({ flightId: 42, width: 40, height: 40 });
+    // Advisory: reporting a display size must NOT be translated into an
+    // operator set-render-size command (that path is the manual cap only).
+    expect(sidecar.commands.some((c) => c.type === "set-render-size")).toBe(false);
+  });
+
+  it("set-track-target updates trackMode and echoes it to the client (server-authoritative)", async () => {
+    const sidecar = new MockSidecar();
+    sidecar.addCamera({ flightId: 7, supportsPan: true, supportsZoom: true });
+
+    const client = new KerbcastClient(
+      { host: "localhost", port: 8088 },
+      sidecar.createTransport(),
+    );
+    await client.connect([7]);
+    sidecar.open();
+
+    await client.setTrackTarget(7, TrackMode.Target);
+    expect(sidecar.lastCommand("set-track-target", 7)?.content.mode).toBe(TrackMode.Target);
+    // The mock echoes camera-state-changed so every client reflects the same
+    // server-held mode (never optimistic-local).
+    expect(client.cameras.find((c) => c.flightId === 7)?.trackMode).toBe(TrackMode.Target);
+
+    await client.setTrackTarget(7, TrackMode.None);
+    expect(client.cameras.find((c) => c.flightId === 7)?.trackMode).toBe(TrackMode.None);
+  });
+
   it("updateCamera pushes state-change to the client", async () => {
     const sidecar = new MockSidecar();
     sidecar.addCamera({ flightId: 42, layers: [Layer.Near] });