@ksp-gonogo/kerbcast 1.8.1 → 1.9.1-rc.1

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 1.9.1-rc.1 - 2026-08-06
+
+<!-- TODO: fill in. -->
+
+
 ## 1.8.0 - 2026-07-28
 
 Client-side camera recording. The capture itself is pure SDK: the recorder taps

package/dist/__generated__/types.d.ts

@@ -22,6 +22,35 @@ export declare enum CameraKind {
     Part = "part",
     Kerbal = "kerbal"
 }
+/**
+ * How hard a camera is currently being captured. Reported per camera in
+ * `CameraState` so a consumer renders what is actually happening rather than
+ * predicting it from delay arithmetic.
+ *
+ * `Background` and `Off` only occur when background capture is enabled; with it off
+ * (the default) a subscribed camera is `Full` and an unsubscribed one is `Off`,
+ * which is exactly today's behaviour under the new names.
+ */
+export declare enum CaptureState {
+    /** Capturing at the primary rate: an ordinary live feed. */
+    Full = "full",
+    /**
+     * Promoted and on the way to the primary rate, but not there yet — either
+     * awaiting the forced keyframe or still rate-limited by the capture budget.
+     */
+    Ramping = "ramping",
+    /**
+     * Background capture: recent but sparse. A consumer should present this as
+     * a reduced-rate channel, not as a live feed.
+     */
+    Background = "background",
+    /**
+     * Not being captured at all — unsubscribed, or the background layer has
+     * been shed under load. A consumer must NOT keep presenting the last frame
+     * as though it were a live low-rate channel.
+     */
+    Off = "off"
+}
 /**
  * Which source a kerbal camera is currently rendering: a seated IVA
  * portrait, or the kerbal's own view while on EVA. Only meaningful when
@@ -95,6 +124,11 @@ export interface CameraState {
      * Defaults to `Part` so existing payloads are unaffected.
      */
     kind?: CameraKind;
+    /**
+     * How hard this camera is currently being captured. Defaults to `Full` so
+     * existing payloads and plugins predating background capture are unaffected.
+     */
+    captureState?: CaptureState;
     /**
      * The kerbal's real `ProtoCrewMember.persistentID`: the stable key a
      * consumer correlates against. `None` for part cameras. Distinct from
@@ -248,6 +282,18 @@ export interface ReportDisplaySizePayload {
 export interface SceneStateChangedPayload {
     inFlight: boolean;
 }
+/**
+ * Consumer's background-capture request. Global rather than
+ * per-camera: it is a statement about how much background cost this consumer
+ * wants spent, not about one camera. Zero stops asking.
+ */
+export interface SetBackgroundCaptureFpsPayload {
+    /**
+     * Requested rate in fps for cameras this consumer is not displaying.
+     * Clamped to the operator ceiling; 0 means no background capture.
+     */
+    fps: number;
+}
 export interface SetDegradePayload {
     flightId: number;
     /**
@@ -458,6 +504,31 @@ export type ClientMessage =
     type: "set-force-full-resolution";
     content: SetForceFullResolutionPayload;
 }
+/**
+ * Ask for background capture: subscribed cameras that this
+ * consumer is NOT displaying keep capturing at a low rate instead of
+ * stopping, so switching to one promotes an already-flowing stream rather
+ * than cold-starting from black.
+ *
+ * Per-consumer and MAX-aggregated, like `ReportDisplaySize`: it runs
+ * at the highest rate any connected consumer asked for, and relaxes when
+ * they lower it or disconnect. A consumer that never sends this pays
+ * nothing, which is why a stock install needs no configuration to serve
+ * both a plain viewer and a consumer that wants background capture.
+ *
+ * The rate is a REQUEST, not a guarantee. It is clamped to the operator's
+ * `BackgroundCaptureFps` ceiling and is the first thing dropped when the
+ * game approaches its framerate floor — watch `CameraState.capture_state`
+ * for what is actually happening. Send 0 to stop asking.
+ *
+ * Receiving the frames is not the same as keeping them: a consumer that
+ * wants history for a camera it isn't showing has to buffer the background
+ * feed itself.
+ */
+ | {
+    type: "set-background-capture-fps";
+    content: SetBackgroundCaptureFpsPayload;
+}
 /**
  * Set the camera's field-of-view (degrees). Silently ignored for
  * parts whose Hullcam module is the fixed base (`supportsZoom ==

package/dist/__generated__/types.js

@@ -22,6 +22,36 @@ export var CameraKind;
     CameraKind["Part"] = "part";
     CameraKind["Kerbal"] = "kerbal";
 })(CameraKind || (CameraKind = {}));
+/**
+ * How hard a camera is currently being captured. Reported per camera in
+ * `CameraState` so a consumer renders what is actually happening rather than
+ * predicting it from delay arithmetic.
+ *
+ * `Background` and `Off` only occur when background capture is enabled; with it off
+ * (the default) a subscribed camera is `Full` and an unsubscribed one is `Off`,
+ * which is exactly today's behaviour under the new names.
+ */
+export var CaptureState;
+(function (CaptureState) {
+    /** Capturing at the primary rate: an ordinary live feed. */
+    CaptureState["Full"] = "full";
+    /**
+     * Promoted and on the way to the primary rate, but not there yet — either
+     * awaiting the forced keyframe or still rate-limited by the capture budget.
+     */
+    CaptureState["Ramping"] = "ramping";
+    /**
+     * Background capture: recent but sparse. A consumer should present this as
+     * a reduced-rate channel, not as a live feed.
+     */
+    CaptureState["Background"] = "background";
+    /**
+     * Not being captured at all — unsubscribed, or the background layer has
+     * been shed under load. A consumer must NOT keep presenting the last frame
+     * as though it were a live low-rate channel.
+     */
+    CaptureState["Off"] = "off";
+})(CaptureState || (CaptureState = {}));
 /**
  * Which source a kerbal camera is currently rendering: a seated IVA
  * portrait, or the kerbal's own view while on EVA. Only meaningful when

package/dist/client.d.ts

@@ -474,6 +474,31 @@ export declare class KerbcastClient extends TypedEmitter<KerbcastClientEvents> {
      * feed primitives self-measure and call this; consumers do not report by hand.
      */
     reportDisplaySize(flightId: number, width: number, height: number): Promise<void>;
+    /**
+     * Ask for background capture: subscribed cameras this consumer is NOT
+     * displaying keep capturing at a low rate instead of stopping, so switching
+     * to one promotes an already-flowing stream rather than cold-starting from
+     * black.
+     *
+     * Opt-in and per-consumer, aggregated MAX-across-consumers. A consumer that
+     * never calls this pays nothing, which is why the same kerbcast install
+     * serves both a plain viewer and a consumer that wants background capture
+     * with no configuration either side. Pass 0 to stop asking; the request is
+     * dropped automatically on disconnect.
+     *
+     * The rate is a REQUEST, not a guarantee: it is capped by the operator's
+     * `BackgroundCaptureFps` ceiling and is the first thing dropped as the game
+     * approaches its framerate floor. Read `CameraState.captureState` for what is
+     * actually happening rather than assuming this took effect — it reports
+     * `Background` only while the reduced rate is genuinely running, and `Off`
+     * once the layer has been shed.
+     *
+     * Receiving background frames is not the same as keeping them. A consumer
+     * that wants *history* for a camera it isn't showing — to render instantly on
+     * switch under a simulated signal delay, say — has to buffer those feeds
+     * itself; background capture only makes the frames available to buffer.
+     */
+    setBackgroundCaptureFps(fps: 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

package/dist/client.js

@@ -712,6 +712,33 @@ export class KerbcastClient extends TypedEmitter {
     async reportDisplaySize(flightId, width, height) {
         await this._send({ type: "report-display-size", content: { flightId, width, height } });
     }
+    /**
+     * Ask for background capture: subscribed cameras this consumer is NOT
+     * displaying keep capturing at a low rate instead of stopping, so switching
+     * to one promotes an already-flowing stream rather than cold-starting from
+     * black.
+     *
+     * Opt-in and per-consumer, aggregated MAX-across-consumers. A consumer that
+     * never calls this pays nothing, which is why the same kerbcast install
+     * serves both a plain viewer and a consumer that wants background capture
+     * with no configuration either side. Pass 0 to stop asking; the request is
+     * dropped automatically on disconnect.
+     *
+     * The rate is a REQUEST, not a guarantee: it is capped by the operator's
+     * `BackgroundCaptureFps` ceiling and is the first thing dropped as the game
+     * approaches its framerate floor. Read `CameraState.captureState` for what is
+     * actually happening rather than assuming this took effect — it reports
+     * `Background` only while the reduced rate is genuinely running, and `Off`
+     * once the layer has been shed.
+     *
+     * Receiving background frames is not the same as keeping them. A consumer
+     * that wants *history* for a camera it isn't showing — to render instantly on
+     * switch under a simulated signal delay, say — has to buffer those feeds
+     * itself; background capture only makes the frames available to buffer.
+     */
+    async setBackgroundCaptureFps(fps) {
+        await this._send({ type: "set-background-capture-fps", content: { fps } });
+    }
     /**
      * 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

package/dist/panZoom.d.ts

@@ -2,7 +2,7 @@
  * 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.
+ * while idle and settled -- 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.
@@ -74,6 +74,31 @@ export interface PanZoomControllerOptions {
      * Default: 0.05.
      */
     analogDeadzone?: number;
+    /**
+     * How close an echo has to get to an outstanding setpoint (degrees) before
+     * the camera counts as having arrived. Wider than the plugin's own 0.01
+     * degree reporting threshold so a rounding difference does not hold the
+     * setpoint open.
+     * Default: 0.5.
+     */
+    settleEpsilonDeg?: number;
+    /**
+     * How many consecutive *moving* echoes may fail to close on an outstanding
+     * setpoint before the controller gives up and adopts what the camera
+     * reports. Catches something else owning the camera (another operator, or
+     * auto-track) without waiting out the full timeout.
+     * Default: 2.
+     */
+    settleStallEchoes?: number;
+    /**
+     * Hard cap (ms) on how long a setpoint is held against echoes. Backstop for
+     * a camera that parks short of the setpoint and then reports the same
+     * position forever (a bounds mismatch would do it), which no
+     * progress-based rule can detect. Sized for the worst real case: 360
+     * degrees of yaw at 90 deg/s plus the plugin's ~1Hz status write.
+     * Default: 6000.
+     */
+    settleTimeoutMs?: number;
 }
 /**
  * Headless pan/zoom state machine. Manages rate deduplication, analog
@@ -87,10 +112,15 @@ export declare class PanZoomController {
     private readonly fovNudgeDeg;
     private readonly fovSliderDebounceMs;
     private readonly analogDeadzone;
+    private readonly settleEpsilonDeg;
+    private readonly settleStallEchoes;
+    private readonly settleTimeoutMs;
     private sentPanRate;
     private sentZoomRate;
     private localPan;
     private localFov;
+    private panSetpoint;
+    private fovSetpoint;
     private _sliderFov;
     private sliderDragging;
     private fovDebounceTimer;
@@ -112,6 +142,12 @@ export declare class PanZoomController {
      * 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.
+     *
+     * An echo is also held off while an absolute setpoint we sent is still
+     * outstanding: the plugin slews toward a setpoint and reports its position
+     * at ~1Hz, so echoes in that window carry positions the camera has already
+     * left, and adopting one would re-base the next nudge behind where the
+     * camera is going.
      */
     syncFromState(state: {
         fov: number;
@@ -186,5 +222,8 @@ export declare class PanZoomController {
      */
     dispose(): void;
     private flushFovSlider;
+    private panEchoWins;
+    private fovEchoWins;
+    private settled;
     private setSliderFovInternal;
 }

package/dist/panZoom.js

@@ -2,7 +2,7 @@
  * 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.
+ * while idle and settled -- 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.
@@ -40,6 +40,9 @@ function clamp(v, lo, hi) {
 function applyDeadzone(v, deadzone) {
     return Math.abs(v) < deadzone ? 0 : v;
 }
+function newSettling() {
+    return { lastDistance: null, stalls: 0, issuedAt: Date.now() };
+}
 // ---------------------------------------------------------------------------
 // PanZoomController
 // ---------------------------------------------------------------------------
@@ -57,6 +60,14 @@ export class PanZoomController {
         // Optimistic accumulators for discrete nudges.
         this.localPan = { yaw: 0, pitch: 0 };
         this.localFov = 0;
+        /*
+          Outstanding absolute setpoints. Non-null from the moment a setPan / setFov
+          goes out until an echo shows the camera got there (or one of `settled`'s
+          give-up rules fires). While one is outstanding the accumulator holds the
+          setpoint and echoes do not touch it.
+        */
+        this.panSetpoint = null;
+        this.fovSetpoint = null;
         // FoV slider state.
         this._sliderFov = 0;
         this.sliderDragging = false;
@@ -80,6 +91,9 @@ export class PanZoomController {
         this.fovNudgeDeg = opts.fovNudgeDeg ?? 5;
         this.fovSliderDebounceMs = opts.fovSliderDebounceMs ?? 120;
         this.analogDeadzone = opts.analogDeadzone ?? 0.05;
+        this.settleEpsilonDeg = opts.settleEpsilonDeg ?? 0.5;
+        this.settleStallEchoes = opts.settleStallEchoes ?? 2;
+        this.settleTimeoutMs = opts.settleTimeoutMs ?? 6000;
     }
     // ---------------------------------------------------------------------------
     // Public getters
@@ -102,6 +116,12 @@ export class PanZoomController {
      * 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.
+     *
+     * An echo is also held off while an absolute setpoint we sent is still
+     * outstanding: the plugin slews toward a setpoint and reports its position
+     * at ~1Hz, so echoes in that window carry positions the camera has already
+     * left, and adopting one would re-base the next nudge behind where the
+     * camera is going.
      */
     syncFromState(state) {
         this.bounds = {
@@ -115,13 +135,13 @@ export class PanZoomController {
         const panIdle = !this.ballDragging &&
             this.sentPanRate.yaw === 0 &&
             this.sentPanRate.pitch === 0;
-        if (panIdle) {
+        if (panIdle && this.panEchoWins(state.panYaw, state.panPitch)) {
             this.localPan = { yaw: state.panYaw, pitch: state.panPitch };
         }
         const zoomIdle = this.sentZoomRate === 0 &&
             !this.sliderDragging &&
             this.pendingFov === null;
-        if (zoomIdle) {
+        if (zoomIdle && this.fovEchoWins(state.fov)) {
             this.localFov = state.fov;
             this.setSliderFovInternal(state.fov);
         }
@@ -140,6 +160,9 @@ export class PanZoomController {
         if (y === this.sentPanRate.yaw && p === this.sentPanRate.pitch)
             return;
         this.sentPanRate = { yaw: y, pitch: p };
+        // A rate supersedes any absolute we were still waiting on, including the
+        // zero that ends the hold: the camera is wherever the rate left it.
+        this.panSetpoint = null;
         void this.sink.setPanRate(y, p);
     }
     /**
@@ -166,6 +189,7 @@ export class PanZoomController {
         if (r === this.sentZoomRate)
             return;
         this.sentZoomRate = r;
+        this.fovSetpoint = null; // same reasoning as setPanRate
         void this.sink.setZoomRate(r);
     }
     // ---------------------------------------------------------------------------
@@ -180,6 +204,11 @@ export class PanZoomController {
         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);
+        this.panSetpoint = {
+            yaw: this.localPan.yaw,
+            pitch: this.localPan.pitch,
+            ...newSettling(),
+        };
         void this.sink.setPan(this.localPan.yaw, this.localPan.pitch);
     }
     /**
@@ -191,6 +220,7 @@ export class PanZoomController {
         const b = this.bounds;
         const next = clamp(this.localFov + deltaSign * this.fovNudgeDeg, b.fovMin, b.fovMax);
         this.localFov = next;
+        this.fovSetpoint = { fov: next, ...newSettling() };
         void this.sink.setFov(next);
     }
     // ---------------------------------------------------------------------------
@@ -244,6 +274,9 @@ export class PanZoomController {
      */
     setBallDragging(dragging) {
         this.ballDragging = dragging;
+        // Taking the ball abandons any absolute we were waiting on.
+        if (dragging)
+            this.panSetpoint = null;
     }
     // ---------------------------------------------------------------------------
     // Lifecycle
@@ -265,6 +298,9 @@ export class PanZoomController {
         }
         this.ballDragging = false;
         this.sliderDragging = false;
+        // Nothing is being commanded any more, so echoes win again.
+        this.panSetpoint = null;
+        this.fovSetpoint = null;
         if (this.fovDebounceTimer !== null) {
             clearTimeout(this.fovDebounceTimer);
             this.fovDebounceTimer = null;
@@ -291,9 +327,60 @@ export class PanZoomController {
             const fov = clamp(this.pendingFov, this.bounds.fovMin, this.bounds.fovMax);
             this.localFov = fov;
             this.pendingFov = null;
+            this.fovSetpoint = { fov, ...newSettling() };
             void this.sink.setFov(fov);
         }
     }
+    /*
+      Whether an echoed pan should be adopted into the accumulator. True when
+      nothing is outstanding, or when the outstanding setpoint has been settled
+      one way or another (in which case it is cleared and the camera's own
+      reading wins from here).
+    */
+    panEchoWins(yaw, pitch) {
+        const sp = this.panSetpoint;
+        if (sp === null)
+            return true;
+        const distance = Math.max(Math.abs(yaw - sp.yaw), Math.abs(pitch - sp.pitch));
+        if (!this.settled(sp, distance))
+            return false;
+        this.panSetpoint = null;
+        return true;
+    }
+    /* `panEchoWins` for FoV. */
+    fovEchoWins(fov) {
+        const sp = this.fovSetpoint;
+        if (sp === null)
+            return true;
+        if (!this.settled(sp, Math.abs(fov - sp.fov)))
+            return false;
+        this.fovSetpoint = null;
+        return true;
+    }
+    /*
+      Give up on an outstanding setpoint when the camera arrived, when it is
+      moving but no longer closing on it (something else owns the camera: another
+      operator, or auto-track), or when the timeout backstop expires (it parked
+      short and is reporting the same position forever, which no progress-based
+      rule can see). Mutates the settling bookkeeping.
+    */
+    settled(sp, distance) {
+        const eps = this.settleEpsilonDeg;
+        if (distance <= eps)
+            return true;
+        if (Date.now() - sp.issuedAt >= this.settleTimeoutMs)
+            return true;
+        const prev = sp.lastDistance;
+        sp.lastDistance = distance;
+        if (prev === null)
+            return false;
+        const moved = Math.abs(prev - distance) > eps;
+        const closing = distance < prev - eps;
+        if (!moved)
+            return false;
+        sp.stalls = closing ? 0 : sp.stalls + 1;
+        return sp.stalls >= this.settleStallEchoes;
+    }
     setSliderFovInternal(fov) {
         this._sliderFov = fov;
         for (const cb of this.sliderFovListeners)

package/package.json

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

@@ -29,6 +29,36 @@ export enum CameraKind {
 	Kerbal = "kerbal",
 }
 
+/**
+ * How hard a camera is currently being captured. Reported per camera in
+ * `CameraState` so a consumer renders what is actually happening rather than
+ * predicting it from delay arithmetic.
+ * 
+ * `Background` and `Off` only occur when background capture is enabled; with it off
+ * (the default) a subscribed camera is `Full` and an unsubscribed one is `Off`,
+ * which is exactly today's behaviour under the new names.
+ */
+export enum CaptureState {
+	/** Capturing at the primary rate: an ordinary live feed. */
+	Full = "full",
+	/**
+	 * Promoted and on the way to the primary rate, but not there yet — either
+	 * awaiting the forced keyframe or still rate-limited by the capture budget.
+	 */
+	Ramping = "ramping",
+	/**
+	 * Background capture: recent but sparse. A consumer should present this as
+	 * a reduced-rate channel, not as a live feed.
+	 */
+	Background = "background",
+	/**
+	 * Not being captured at all — unsubscribed, or the background layer has
+	 * been shed under load. A consumer must NOT keep presenting the last frame
+	 * as though it were a live low-rate channel.
+	 */
+	Off = "off",
+}
+
 /**
  * Which source a kerbal camera is currently rendering: a seated IVA
  * portrait, or the kerbal's own view while on EVA. Only meaningful when
@@ -106,6 +136,11 @@ export interface CameraState {
 	 * Defaults to `Part` so existing payloads are unaffected.
 	 */
 	kind?: CameraKind;
+	/**
+	 * How hard this camera is currently being captured. Defaults to `Full` so
+	 * existing payloads and plugins predating background capture are unaffected.
+	 */
+	captureState?: CaptureState;
 	/**
 	 * The kerbal's real `ProtoCrewMember.persistentID`: the stable key a
 	 * consumer correlates against. `None` for part cameras. Distinct from
@@ -268,6 +303,19 @@ export interface SceneStateChangedPayload {
 	inFlight: boolean;
 }
 
+/**
+ * Consumer's background-capture request. Global rather than
+ * per-camera: it is a statement about how much background cost this consumer
+ * wants spent, not about one camera. Zero stops asking.
+ */
+export interface SetBackgroundCaptureFpsPayload {
+	/**
+	 * Requested rate in fps for cameras this consumer is not displaying.
+	 * Clamped to the operator ceiling; 0 means no background capture.
+	 */
+	fps: number;
+}
+
 export interface SetDegradePayload {
 	flightId: number;
 	/**
@@ -473,6 +521,28 @@ export type ClientMessage =
 	 * term, never the perf-protection ceiling.
 	 */
 	| { type: "set-force-full-resolution", content: SetForceFullResolutionPayload }
+	/**
+	 * Ask for background capture: subscribed cameras that this
+	 * consumer is NOT displaying keep capturing at a low rate instead of
+	 * stopping, so switching to one promotes an already-flowing stream rather
+	 * than cold-starting from black.
+	 * 
+	 * Per-consumer and MAX-aggregated, like `ReportDisplaySize`: it runs
+	 * at the highest rate any connected consumer asked for, and relaxes when
+	 * they lower it or disconnect. A consumer that never sends this pays
+	 * nothing, which is why a stock install needs no configuration to serve
+	 * both a plain viewer and a consumer that wants background capture.
+	 * 
+	 * The rate is a REQUEST, not a guarantee. It is clamped to the operator's
+	 * `BackgroundCaptureFps` ceiling and is the first thing dropped when the
+	 * game approaches its framerate floor — watch `CameraState.capture_state`
+	 * for what is actually happening. Send 0 to stop asking.
+	 * 
+	 * Receiving the frames is not the same as keeping them: a consumer that
+	 * wants history for a camera it isn't showing has to buffer the background
+	 * feed itself.
+	 */
+	| { type: "set-background-capture-fps", content: SetBackgroundCaptureFpsPayload }
 	/**
 	 * Set the camera's field-of-view (degrees). Silently ignored for
 	 * parts whose Hullcam module is the fixed base (`supportsZoom ==

package/src/client.ts

@@ -1127,6 +1127,34 @@ export class KerbcastClient extends TypedEmitter<KerbcastClientEvents> {
     await this._send({ type: "report-display-size", content: { flightId, width, height } });
   }
 
+  /**
+   * Ask for background capture: subscribed cameras this consumer is NOT
+   * displaying keep capturing at a low rate instead of stopping, so switching
+   * to one promotes an already-flowing stream rather than cold-starting from
+   * black.
+   *
+   * Opt-in and per-consumer, aggregated MAX-across-consumers. A consumer that
+   * never calls this pays nothing, which is why the same kerbcast install
+   * serves both a plain viewer and a consumer that wants background capture
+   * with no configuration either side. Pass 0 to stop asking; the request is
+   * dropped automatically on disconnect.
+   *
+   * The rate is a REQUEST, not a guarantee: it is capped by the operator's
+   * `BackgroundCaptureFps` ceiling and is the first thing dropped as the game
+   * approaches its framerate floor. Read `CameraState.captureState` for what is
+   * actually happening rather than assuming this took effect — it reports
+   * `Background` only while the reduced rate is genuinely running, and `Off`
+   * once the layer has been shed.
+   *
+   * Receiving background frames is not the same as keeping them. A consumer
+   * that wants *history* for a camera it isn't showing — to render instantly on
+   * switch under a simulated signal delay, say — has to buffer those feeds
+   * itself; background capture only makes the frames available to buffer.
+   */
+  async setBackgroundCaptureFps(fps: number): Promise<void> {
+    await this._send({ type: "set-background-capture-fps", content: { fps } });
+  }
+
   /**
    * 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

package/src/panZoom.test.ts

@@ -386,6 +386,217 @@ describe("PanZoomController: nudge after echo-sync", () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// Outstanding setpoints: an echo captured mid-slew must not re-base the
+// accumulator behind where the camera is going. The plugin slews toward an
+// absolute at 90 deg/s and reports position at ~1Hz, so the first echo after
+// a nudge routinely carries the pre-command value.
+// ---------------------------------------------------------------------------
+
+describe("PanZoomController: outstanding setpoint", () => {
+  const WIDE = { ...DEFAULT_BOUNDS, panYawMin: -180, panYawMax: 180 };
+
+  it("ignores an echo carrying the pre-command position", () => {
+    const { sink, setPan } = makeSink();
+    const ctrl = new PanZoomController(sink, { panNudgeDeg: 5 });
+    ctrl.syncFromState({ ...WIDE, panYaw: 0 });
+    ctrl.nudgePan(1, 0);
+    expect(setPan).toHaveBeenLastCalledWith(5, 0);
+
+    // The measured case: an echo lands ~9ms later still reporting the old
+    // position. Adopting it would make the next nudge repeat this one.
+    ctrl.syncFromState({ ...WIDE, panYaw: 0 });
+    ctrl.nudgePan(1, 0);
+    expect(setPan).toHaveBeenLastCalledWith(10, 0);
+  });
+
+  it("releases the setpoint once an echo agrees with it", () => {
+    const { sink, setPan } = makeSink();
+    const ctrl = new PanZoomController(sink, { panNudgeDeg: 5 });
+    ctrl.syncFromState({ ...WIDE, panYaw: 0 });
+    ctrl.nudgePan(1, 0); // setpoint 5
+    ctrl.syncFromState({ ...WIDE, panYaw: 5 }); // arrived -- setpoint released
+    ctrl.syncFromState({ ...WIDE, panYaw: 20 }); // someone else moved it
+    ctrl.nudgePan(1, 0);
+    expect(setPan).toHaveBeenLastCalledWith(25, 0);
+  });
+
+  it("counts an echo within the settle epsilon as arrival", () => {
+    const { sink, setPan } = makeSink();
+    const ctrl = new PanZoomController(sink, {
+      panNudgeDeg: 5,
+      settleEpsilonDeg: 0.5,
+    });
+    ctrl.syncFromState({ ...WIDE, panYaw: 0 });
+    ctrl.nudgePan(1, 0); // setpoint 5
+    ctrl.syncFromState({ ...WIDE, panYaw: 4.7 }); // within 0.5 -- adopted
+    ctrl.nudgePan(1, 0);
+    expect(setPan).toHaveBeenLastCalledWith(9.7, 0);
+  });
+
+  it("holds until BOTH axes arrive", () => {
+    const { sink, setPan } = makeSink();
+    const ctrl = new PanZoomController(sink, { panNudgeDeg: 30 });
+    const bounds = { ...WIDE, panPitchMin: -90, panPitchMax: 90 };
+    ctrl.syncFromState({ ...bounds, panYaw: 0, panPitch: 0 });
+    ctrl.nudgePan(1, 1); // setpoint (30, 30)
+    ctrl.syncFromState({ ...bounds, panYaw: 30, panPitch: 0 }); // pitch mid-slew
+    ctrl.nudgePan(1, 1);
+    expect(setPan).toHaveBeenLastCalledWith(60, 60);
+  });
+
+  it("gives up when the camera moves but stops closing on the setpoint", () => {
+    const { sink, setPan } = makeSink();
+    const ctrl = new PanZoomController(sink, {
+      panNudgeDeg: 30,
+      settleStallEchoes: 2,
+    });
+    ctrl.syncFromState({ ...WIDE, panYaw: 0 });
+    ctrl.nudgePan(1, 0); // setpoint 30
+
+    // Something else owns the camera (another operator, or auto-track): it is
+    // moving, but away from our setpoint.
+    ctrl.syncFromState({ ...WIDE, panYaw: 10 }); // closing, no verdict yet
+    ctrl.syncFromState({ ...WIDE, panYaw: 5 }); // stall 1
+    ctrl.syncFromState({ ...WIDE, panYaw: 0 }); // stall 2 -- adopt reality
+    ctrl.nudgePan(1, 0);
+    expect(setPan).toHaveBeenLastCalledWith(30, 0);
+  });
+
+  it("does not count repeated identical echoes toward the stall", () => {
+    // The sidecar re-broadcasts camera state on unrelated changes (bitrate,
+    // degrade), each carrying the same ~1Hz plugin pan reading. Those are not
+    // evidence that the camera stopped closing.
+    const { sink, setPan } = makeSink();
+    const ctrl = new PanZoomController(sink, {
+      panNudgeDeg: 30,
+      settleStallEchoes: 2,
+    });
+    ctrl.syncFromState({ ...WIDE, panYaw: 0 });
+    ctrl.nudgePan(1, 0); // setpoint 30
+    for (let i = 0; i < 5; i++) ctrl.syncFromState({ ...WIDE, panYaw: 10 });
+    ctrl.nudgePan(1, 0);
+    expect(setPan).toHaveBeenLastCalledWith(60, 0);
+  });
+
+  it("releases the setpoint after the timeout backstop", async () => {
+    vi.useFakeTimers();
+    try {
+      const { sink, setPan } = makeSink();
+      const ctrl = new PanZoomController(sink, {
+        panNudgeDeg: 30,
+        settleTimeoutMs: 6000,
+      });
+      ctrl.syncFromState({ ...WIDE, panYaw: 0 });
+      ctrl.nudgePan(1, 0); // setpoint 30
+
+      // Camera parks short and reports the same position forever, which the
+      // stall rule cannot see. The timeout is the way out.
+      ctrl.syncFromState({ ...WIDE, panYaw: 10 });
+      await vi.advanceTimersByTimeAsync(6000);
+      ctrl.syncFromState({ ...WIDE, panYaw: 10 });
+      ctrl.nudgePan(1, 0);
+      expect(setPan).toHaveBeenLastCalledWith(40, 0);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it("drops the setpoint when a pan rate takes over", () => {
+    const { sink, setPan } = makeSink();
+    const ctrl = new PanZoomController(sink, { panNudgeDeg: 30 });
+    ctrl.syncFromState({ ...WIDE, panYaw: 0 });
+    ctrl.nudgePan(1, 0); // setpoint 30
+    ctrl.setPanRate(0.5, 0);
+    ctrl.setPanRate(0, 0); // hold over; camera is wherever the rate left it
+    ctrl.syncFromState({ ...WIDE, panYaw: 10 });
+    ctrl.nudgePan(1, 0);
+    expect(setPan).toHaveBeenLastCalledWith(40, 0);
+  });
+
+  it("drops the setpoint when the ball is grabbed", () => {
+    const { sink, setPan } = makeSink();
+    const ctrl = new PanZoomController(sink, { panNudgeDeg: 30 });
+    ctrl.syncFromState({ ...WIDE, panYaw: 0 });
+    ctrl.nudgePan(1, 0); // setpoint 30
+    ctrl.setBallDragging(true);
+    ctrl.setBallDragging(false);
+    ctrl.syncFromState({ ...WIDE, panYaw: 10 });
+    ctrl.nudgePan(1, 0);
+    expect(setPan).toHaveBeenLastCalledWith(40, 0);
+  });
+
+  it("drops the setpoint on stop", () => {
+    const { sink, setPan } = makeSink();
+    const ctrl = new PanZoomController(sink, { panNudgeDeg: 30 });
+    ctrl.syncFromState({ ...WIDE, panYaw: 0 });
+    ctrl.nudgePan(1, 0); // setpoint 30
+    ctrl.stop();
+    ctrl.syncFromState({ ...WIDE, panYaw: 10 });
+    ctrl.nudgePan(1, 0);
+    expect(setPan).toHaveBeenLastCalledWith(40, 0);
+  });
+
+  it("keeps applying echoed bounds while a setpoint is outstanding", () => {
+    // Bounds are camera metadata, not a position: holding them back would
+    // clamp later nudges against a stale travel limit.
+    const { sink, setPan } = makeSink();
+    const ctrl = new PanZoomController(sink, { panNudgeDeg: 30 });
+    ctrl.syncFromState({ ...WIDE, panYaw: 0 });
+    ctrl.nudgePan(1, 0); // setpoint 30
+    ctrl.syncFromState({ ...WIDE, panYaw: 0, panYawMax: 45 });
+    ctrl.nudgePan(1, 0);
+    expect(setPan).toHaveBeenLastCalledWith(45, 0);
+  });
+
+  it("does not let an in-transit fov echo drag the slider back", async () => {
+    vi.useFakeTimers();
+    try {
+      const { sink, setFov } = makeSink();
+      const ctrl = new PanZoomController(sink, {
+        fovNudgeDeg: 5,
+        fovSliderDebounceMs: 120,
+      });
+      ctrl.syncFromState({ ...DEFAULT_BOUNDS, fov: 60 });
+      ctrl.fovSliderInput(30);
+      await vi.advanceTimersByTimeAsync(120);
+      expect(setFov).toHaveBeenLastCalledWith(30);
+
+      // Plugin is still slewing 60 -> 30 and reports 60. Adopting it would
+      // visibly snap the slider back and re-base the next zoom nudge.
+      ctrl.syncFromState({ ...DEFAULT_BOUNDS, fov: 60 });
+      expect(ctrl.sliderFov).toBe(30);
+      ctrl.nudgeZoom(-1);
+      expect(setFov).toHaveBeenLastCalledWith(25);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it("releases the fov setpoint once the echo agrees", () => {
+    const { sink, setFov } = makeSink();
+    const ctrl = new PanZoomController(sink, { fovNudgeDeg: 5 });
+    ctrl.syncFromState({ ...DEFAULT_BOUNDS, fov: 60 });
+    ctrl.nudgeZoom(-1); // setpoint 55
+    ctrl.syncFromState({ ...DEFAULT_BOUNDS, fov: 55 }); // arrived
+    ctrl.syncFromState({ ...DEFAULT_BOUNDS, fov: 40 }); // someone else zoomed
+    ctrl.nudgeZoom(-1);
+    expect(setFov).toHaveBeenLastCalledWith(35);
+  });
+
+  it("drops the fov setpoint when a zoom rate takes over", () => {
+    const { sink, setFov } = makeSink();
+    const ctrl = new PanZoomController(sink, { fovNudgeDeg: 5 });
+    ctrl.syncFromState({ ...DEFAULT_BOUNDS, fov: 60 });
+    ctrl.nudgeZoom(-1); // setpoint 55
+    ctrl.setZoomRate(1);
+    ctrl.setZoomRate(0);
+    ctrl.syncFromState({ ...DEFAULT_BOUNDS, fov: 40 });
+    ctrl.nudgeZoom(-1);
+    expect(setFov).toHaveBeenLastCalledWith(35);
+  });
+});
+
 // ---------------------------------------------------------------------------
 // onSliderFov subscription management
 // ---------------------------------------------------------------------------

package/src/panZoom.ts

@@ -2,7 +2,7 @@
  * 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.
+ * while idle and settled -- 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.
@@ -81,6 +81,31 @@ export interface PanZoomControllerOptions {
    * Default: 0.05.
    */
   analogDeadzone?: number;
+  /**
+   * How close an echo has to get to an outstanding setpoint (degrees) before
+   * the camera counts as having arrived. Wider than the plugin's own 0.01
+   * degree reporting threshold so a rounding difference does not hold the
+   * setpoint open.
+   * Default: 0.5.
+   */
+  settleEpsilonDeg?: number;
+  /**
+   * How many consecutive *moving* echoes may fail to close on an outstanding
+   * setpoint before the controller gives up and adopts what the camera
+   * reports. Catches something else owning the camera (another operator, or
+   * auto-track) without waiting out the full timeout.
+   * Default: 2.
+   */
+  settleStallEchoes?: number;
+  /**
+   * Hard cap (ms) on how long a setpoint is held against echoes. Backstop for
+   * a camera that parks short of the setpoint and then reports the same
+   * position forever (a bounds mismatch would do it), which no
+   * progress-based rule can detect. Sized for the worst real case: 360
+   * degrees of yaw at 90 deg/s plus the plugin's ~1Hz status write.
+   * Default: 6000.
+   */
+  settleTimeoutMs?: number;
 }
 
 // ---------------------------------------------------------------------------
@@ -95,6 +120,27 @@ function applyDeadzone(v: number, deadzone: number): number {
   return Math.abs(v) < deadzone ? 0 : v;
 }
 
+/*
+  Bookkeeping for an absolute setpoint the camera has been asked for but has
+  not been observed to reach. The plugin slews toward a setpoint at a fixed
+  rate (90 deg/s of yaw, 60 deg/s of FoV) and reports its position at ~1Hz, so
+  echoes arriving during the slew carry positions the camera has already left.
+  Feeding those to the accumulator would re-base the next nudge on a stale
+  position and lose travel.
+*/
+interface Settling {
+  /* Remaining distance measured at the previous echo; null before the first. */
+  lastDistance: number | null;
+  /* Consecutive moving echoes that failed to close on the setpoint. */
+  stalls: number;
+  /* Wall clock at issue, for the timeout backstop. */
+  issuedAt: number;
+}
+
+function newSettling(): Settling {
+  return { lastDistance: null, stalls: 0, issuedAt: Date.now() };
+}
+
 // ---------------------------------------------------------------------------
 // PanZoomController
 // ---------------------------------------------------------------------------
@@ -111,6 +157,9 @@ export class PanZoomController {
   private readonly fovNudgeDeg: number;
   private readonly fovSliderDebounceMs: number;
   private readonly analogDeadzone: number;
+  private readonly settleEpsilonDeg: number;
+  private readonly settleStallEchoes: number;
+  private readonly settleTimeoutMs: number;
 
   // Last-sent rates (dedupe against re-sending the same value).
   private sentPanRate = { yaw: 0, pitch: 0 };
@@ -120,6 +169,16 @@ export class PanZoomController {
   private localPan = { yaw: 0, pitch: 0 };
   private localFov = 0;
 
+  /*
+    Outstanding absolute setpoints. Non-null from the moment a setPan / setFov
+    goes out until an echo shows the camera got there (or one of `settled`'s
+    give-up rules fires). While one is outstanding the accumulator holds the
+    setpoint and echoes do not touch it.
+  */
+  private panSetpoint: (Settling & { yaw: number; pitch: number }) | null =
+    null;
+  private fovSetpoint: (Settling & { fov: number }) | null = null;
+
   // FoV slider state.
   private _sliderFov = 0;
   private sliderDragging = false;
@@ -148,6 +207,9 @@ export class PanZoomController {
     this.fovNudgeDeg = opts.fovNudgeDeg ?? 5;
     this.fovSliderDebounceMs = opts.fovSliderDebounceMs ?? 120;
     this.analogDeadzone = opts.analogDeadzone ?? 0.05;
+    this.settleEpsilonDeg = opts.settleEpsilonDeg ?? 0.5;
+    this.settleStallEchoes = opts.settleStallEchoes ?? 2;
+    this.settleTimeoutMs = opts.settleTimeoutMs ?? 6000;
   }
 
   // ---------------------------------------------------------------------------
@@ -174,6 +236,12 @@ export class PanZoomController {
    * 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.
+   *
+   * An echo is also held off while an absolute setpoint we sent is still
+   * outstanding: the plugin slews toward a setpoint and reports its position
+   * at ~1Hz, so echoes in that window carry positions the camera has already
+   * left, and adopting one would re-base the next nudge behind where the
+   * camera is going.
    */
   syncFromState(
     state: { fov: number; panYaw: number; panPitch: number } & PanZoomBounds,
@@ -191,7 +259,7 @@ export class PanZoomController {
       !this.ballDragging &&
       this.sentPanRate.yaw === 0 &&
       this.sentPanRate.pitch === 0;
-    if (panIdle) {
+    if (panIdle && this.panEchoWins(state.panYaw, state.panPitch)) {
       this.localPan = { yaw: state.panYaw, pitch: state.panPitch };
     }
 
@@ -199,7 +267,7 @@ export class PanZoomController {
       this.sentZoomRate === 0 &&
       !this.sliderDragging &&
       this.pendingFov === null;
-    if (zoomIdle) {
+    if (zoomIdle && this.fovEchoWins(state.fov)) {
       this.localFov = state.fov;
       this.setSliderFovInternal(state.fov);
     }
@@ -219,6 +287,9 @@ export class PanZoomController {
     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 };
+    // A rate supersedes any absolute we were still waiting on, including the
+    // zero that ends the hold: the camera is wherever the rate left it.
+    this.panSetpoint = null;
     void this.sink.setPanRate(y, p);
   }
 
@@ -245,6 +316,7 @@ export class PanZoomController {
     const r = applyDeadzone(clamp(rate, -1, 1), this.analogDeadzone);
     if (r === this.sentZoomRate) return;
     this.sentZoomRate = r;
+    this.fovSetpoint = null; // same reasoning as setPanRate
     void this.sink.setZoomRate(r);
   }
 
@@ -269,6 +341,11 @@ export class PanZoomController {
       b.panPitchMin,
       b.panPitchMax,
     );
+    this.panSetpoint = {
+      yaw: this.localPan.yaw,
+      pitch: this.localPan.pitch,
+      ...newSettling(),
+    };
     void this.sink.setPan(this.localPan.yaw, this.localPan.pitch);
   }
 
@@ -285,6 +362,7 @@ export class PanZoomController {
       b.fovMax,
     );
     this.localFov = next;
+    this.fovSetpoint = { fov: next, ...newSettling() };
     void this.sink.setFov(next);
   }
 
@@ -342,6 +420,8 @@ export class PanZoomController {
    */
   setBallDragging(dragging: boolean): void {
     this.ballDragging = dragging;
+    // Taking the ball abandons any absolute we were waiting on.
+    if (dragging) this.panSetpoint = null;
   }
 
   // ---------------------------------------------------------------------------
@@ -365,6 +445,9 @@ export class PanZoomController {
     }
     this.ballDragging = false;
     this.sliderDragging = false;
+    // Nothing is being commanded any more, so echoes win again.
+    this.panSetpoint = null;
+    this.fovSetpoint = null;
     if (this.fovDebounceTimer !== null) {
       clearTimeout(this.fovDebounceTimer);
       this.fovDebounceTimer = null;
@@ -394,10 +477,59 @@ export class PanZoomController {
       const fov = clamp(this.pendingFov, this.bounds.fovMin, this.bounds.fovMax);
       this.localFov = fov;
       this.pendingFov = null;
+      this.fovSetpoint = { fov, ...newSettling() };
       void this.sink.setFov(fov);
     }
   }
 
+  /*
+    Whether an echoed pan should be adopted into the accumulator. True when
+    nothing is outstanding, or when the outstanding setpoint has been settled
+    one way or another (in which case it is cleared and the camera's own
+    reading wins from here).
+  */
+  private panEchoWins(yaw: number, pitch: number): boolean {
+    const sp = this.panSetpoint;
+    if (sp === null) return true;
+    const distance = Math.max(
+      Math.abs(yaw - sp.yaw),
+      Math.abs(pitch - sp.pitch),
+    );
+    if (!this.settled(sp, distance)) return false;
+    this.panSetpoint = null;
+    return true;
+  }
+
+  /* `panEchoWins` for FoV. */
+  private fovEchoWins(fov: number): boolean {
+    const sp = this.fovSetpoint;
+    if (sp === null) return true;
+    if (!this.settled(sp, Math.abs(fov - sp.fov))) return false;
+    this.fovSetpoint = null;
+    return true;
+  }
+
+  /*
+    Give up on an outstanding setpoint when the camera arrived, when it is
+    moving but no longer closing on it (something else owns the camera: another
+    operator, or auto-track), or when the timeout backstop expires (it parked
+    short and is reporting the same position forever, which no progress-based
+    rule can see). Mutates the settling bookkeeping.
+  */
+  private settled(sp: Settling, distance: number): boolean {
+    const eps = this.settleEpsilonDeg;
+    if (distance <= eps) return true;
+    if (Date.now() - sp.issuedAt >= this.settleTimeoutMs) return true;
+    const prev = sp.lastDistance;
+    sp.lastDistance = distance;
+    if (prev === null) return false;
+    const moved = Math.abs(prev - distance) > eps;
+    const closing = distance < prev - eps;
+    if (!moved) return false;
+    sp.stalls = closing ? 0 : sp.stalls + 1;
+    return sp.stalls >= this.settleStallEchoes;
+  }
+
   private setSliderFovInternal(fov: number): void {
     this._sliderFov = fov;
     for (const cb of this.sliderFovListeners) cb(fov);