@ksp-gonogo/kerbcast 1.9.0 → 1.9.1

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 1.9.1 - 2026-08-06
+
+<!-- TODO: fill in. -->
+
+
+## 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/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.9.0",
+  "version": "1.9.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/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);