@ksp-gonogo/kerbcast-react 1.8.0 → 1.9.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Changelog
 
-## Unreleased (next minor)
+## 1.8.0 - 2026-07-28
 
 ### Added
 

package/dist/CameraFeed.d.ts

@@ -116,6 +116,25 @@ export interface CameraFeedProps {
      * the gimbal + FoV). Default false.
      */
     enableTracking?: boolean;
+    /**
+     * Stand down the built-in MANUAL camera controls: the pan ball and the
+     * zoom/FoV controls disappear, their in-flight rates are zeroed, and the
+     * imperative handle's pan/zoom methods become no-ops (so a physical
+     * controller wired to the handle can't reach the camera either).
+     *
+     * "Manual" in the sense this file already uses it - a human directly driving
+     * the gimbal and optics - and named for that intent rather than for today's
+     * specific surfaces, so anything added later that hand-flies the camera
+     * stands down under this flag too. Auto-track is NOT manual and stays live:
+     * the aim loop runs game-side, so it keeps working when a host takes the
+     * hand-flown path away. Feed affordances are untouched as well - action bar,
+     * recording, fullscreen, PiP, quality.
+     *
+     * For a host that owns manual control itself, e.g. a signal-delay setpoint
+     * surface where live pan/zoom would be steering at where the craft is now
+     * while watching where it was a light-time ago. Default false.
+     */
+    disableManualControls?: boolean;
     /**
      * Show a built-in REC control in the action bar: a STATEFUL toggle (never
      * overflow-eligible, per the #6 spec) that starts/stops a client-side

package/dist/CameraFeed.js

@@ -59,7 +59,7 @@ function exitFullscreen() {
 // ---------------------------------------------------------------------------
 // Inner component (reads from context)
 // ---------------------------------------------------------------------------
-const CameraFeedInner = forwardRef(function CameraFeedInner({ flightId: requestedFlightId, onSelectCamera, cameraFilter, onDisplayedCameraChange, showDebugInfo = false, showStatic, inFlight: inFlightProp, showStandbyIcon = true, renderSize = "auto", emptyMessage = "No camera feeds - start a vessel with Hullcam parts installed", enableFullscreen = false, enablePictureInPicture = false, enableQualityControl = false, enableTracking = false, enableRecording = false, recordFullResolution = false, actions, trailingActions, showActions = true, useStream, }, ref) {
+const CameraFeedInner = forwardRef(function CameraFeedInner({ flightId: requestedFlightId, onSelectCamera, cameraFilter, onDisplayedCameraChange, showDebugInfo = false, showStatic, inFlight: inFlightProp, showStandbyIcon = true, renderSize = "auto", emptyMessage = "No camera feeds - start a vessel with Hullcam parts installed", enableFullscreen = false, enablePictureInPicture = false, enableQualityControl = false, enableTracking = false, disableManualControls = false, enableRecording = false, recordFullResolution = false, actions, trailingActions, showActions = true, useStream, }, ref) {
     const client = useKerbcastClient();
     // Always called (rules of hooks); `enableRecording` only gates whether the
     // REC entry/badge render, not whether the store is subscribed.
@@ -232,8 +232,11 @@ const CameraFeedInner = forwardRef(function CameraFeedInner({ flightId: requeste
         }
     }, []);
     const isDestroyed = camera ? isCameraDestroyed(camera) : false;
-    const showPan = camera?.supportsPan && !isDestroyed;
-    const showZoom = camera?.supportsZoom && !isDestroyed;
+    /* Gating here rather than at the render sites covers the whole manual
+       path at once: the controls unmount, the effects below zero any in-flight
+       rate, and the imperative handle's pan/zoom methods no-op. */
+    const showPan = camera?.supportsPan && !isDestroyed && !disableManualControls;
+    const showZoom = camera?.supportsZoom && !isDestroyed && !disableManualControls;
     // Auto-track state is server-authoritative: driven purely by the published
     // trackMode (absent -> none), never local click. While tracking, the aim
     // loop owns the gimbal + FoV, so the manual pan/zoom controls are disabled

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ksp-gonogo/kerbcast-react",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "description": "React components and hooks for kerbcast camera feeds.",
   "license": "MIT",
   "author": "Jon Pepler",
@@ -45,7 +45,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@ksp-gonogo/kerbcast": "^1.8.0"
+    "@ksp-gonogo/kerbcast": "^1.9.0"
   },
   "peerDependencies": {
     "react": "^18 || ^19",

package/src/CameraFeed.test.tsx

@@ -272,6 +272,7 @@ function renderFeed(
     renderSize?: "auto" | "none";
     enableQualityControl?: boolean;
     enableTracking?: boolean;
+    disableManualControls?: boolean;
     enableRecording?: boolean;
     recordFullResolution?: boolean;
     enableFullscreen?: boolean;
@@ -2014,6 +2015,97 @@ describe("CameraFeed - tracking (crosshair)", () => {
     expect((getByLabelText("Zoom in") as HTMLButtonElement).disabled).toBe(false);
     expect((getByLabelText("Pan left") as HTMLButtonElement).disabled).toBe(false);
   });
+
+  // -------------------------------------------------------------------------
+  // disableManualControls: a host taking over the hand-flown path
+  // -------------------------------------------------------------------------
+
+  it("shows the manual pan + zoom controls by default", async () => {
+    const { client } = await buildConnectedSource([panZoomCam()]);
+    const { queryByLabelText } = renderFeed(client, { flightId: 42 });
+    expect(queryByLabelText("Zoom in")).not.toBeNull();
+    expect(queryByLabelText("Pan camera")).not.toBeNull();
+  });
+
+  it("removes the manual pan + zoom controls when disableManualControls", async () => {
+    const { client } = await buildConnectedSource([panZoomCam()]);
+    const { queryByLabelText } = renderFeed(client, {
+      flightId: 42,
+      disableManualControls: true,
+    });
+    // Gone, not merely disabled: a host owning control shouldn't have to
+    // occlude ours.
+    expect(queryByLabelText("Zoom in")).toBeNull();
+    expect(queryByLabelText("Zoom out")).toBeNull();
+    expect(queryByLabelText("Pan camera")).toBeNull();
+    expect(queryByLabelText("Pan left")).toBeNull();
+  });
+
+  it("keeps auto-track live when disableManualControls: the aim loop is not manual", async () => {
+    const { client } = await buildConnectedSource([panZoomCam()]);
+    const { queryByLabelText } = renderFeed(client, {
+      flightId: 42,
+      enableTracking: true,
+      disableManualControls: true,
+    });
+    expect(queryByLabelText(/track/i)).not.toBeNull();
+  });
+
+  const panRates = (sidecar: MockSidecar) =>
+    sidecar.commands.filter((c) => c.type === "set-pan-rate");
+
+  it("no-ops the imperative pan/zoom handle when disableManualControls", async () => {
+    // Covers the serial-controller path: a host that hides the on-screen
+    // controls must not be reachable through the handle either.
+    const { client, sidecar } = await buildConnectedSource([panZoomCam()]);
+
+    const handleRef = createRef<CameraFeedHandle>();
+    renderFeed(client, {
+      flightId: 42,
+      disableManualControls: true,
+      ref: handleRef,
+    });
+
+    await act(async () => {
+      handleRef.current?.setPanAxis("yaw", 1);
+      handleRef.current?.nudgePan(1, 0);
+      handleRef.current?.setZoomRate(1);
+      handleRef.current?.nudgeZoom(1);
+    });
+
+    expect(panRates(sidecar)).toHaveLength(0);
+  });
+
+  it("zeroes an in-flight pan rate when disableManualControls flips on", async () => {
+    const { client, sidecar } = await buildConnectedSource([panZoomCam()]);
+
+    const handleRef = createRef<CameraFeedHandle>();
+    const { rerender } = render(
+      <KerbcastProvider client={client}>
+        <CameraFeed ref={handleRef} flightId={42} />
+      </KerbcastProvider>,
+    );
+
+    await act(async () => {
+      handleRef.current?.setPanAxis("yaw", 1);
+    });
+    expect(panRates(sidecar).length).toBeGreaterThan(0);
+
+    // Handing control over mid-pan must not leave the gimbal running.
+    await act(async () => {
+      rerender(
+        <KerbcastProvider client={client}>
+          <CameraFeed ref={handleRef} flightId={42} disableManualControls />
+        </KerbcastProvider>,
+      );
+    });
+
+    expect(sidecar.lastCommand("set-pan-rate")?.content).toMatchObject({
+      flightId: 42,
+      yawRate: 0,
+      pitchRate: 0,
+    });
+  });
 });
 
 // ---------------------------------------------------------------------------

package/src/CameraFeed.tsx

@@ -220,6 +220,25 @@ export interface CameraFeedProps {
    * the gimbal + FoV). Default false.
    */
   enableTracking?: boolean;
+  /**
+   * Stand down the built-in MANUAL camera controls: the pan ball and the
+   * zoom/FoV controls disappear, their in-flight rates are zeroed, and the
+   * imperative handle's pan/zoom methods become no-ops (so a physical
+   * controller wired to the handle can't reach the camera either).
+   *
+   * "Manual" in the sense this file already uses it - a human directly driving
+   * the gimbal and optics - and named for that intent rather than for today's
+   * specific surfaces, so anything added later that hand-flies the camera
+   * stands down under this flag too. Auto-track is NOT manual and stays live:
+   * the aim loop runs game-side, so it keeps working when a host takes the
+   * hand-flown path away. Feed affordances are untouched as well - action bar,
+   * recording, fullscreen, PiP, quality.
+   *
+   * For a host that owns manual control itself, e.g. a signal-delay setpoint
+   * surface where live pan/zoom would be steering at where the craft is now
+   * while watching where it was a light-time ago. Default false.
+   */
+  disableManualControls?: boolean;
   /**
    * Show a built-in REC control in the action bar: a STATEFUL toggle (never
    * overflow-eligible, per the #6 spec) that starts/stops a client-side
@@ -302,6 +321,7 @@ const CameraFeedInner = forwardRef<CameraFeedHandle, CameraFeedProps>(
       enablePictureInPicture = false,
       enableQualityControl = false,
       enableTracking = false,
+      disableManualControls = false,
       enableRecording = false,
       recordFullResolution = false,
       actions,
@@ -496,8 +516,12 @@ const CameraFeedInner = forwardRef<CameraFeedHandle, CameraFeedProps>(
     }, []);
 
     const isDestroyed = camera ? isCameraDestroyed(camera) : false;
-    const showPan = camera?.supportsPan && !isDestroyed;
-    const showZoom = camera?.supportsZoom && !isDestroyed;
+    /* Gating here rather than at the render sites covers the whole manual
+       path at once: the controls unmount, the effects below zero any in-flight
+       rate, and the imperative handle's pan/zoom methods no-op. */
+    const showPan = camera?.supportsPan && !isDestroyed && !disableManualControls;
+    const showZoom =
+      camera?.supportsZoom && !isDestroyed && !disableManualControls;
 
     // Auto-track state is server-authoritative: driven purely by the published
     // trackMode (absent -> none), never local click. While tracking, the aim