@ksp-gonogo/kerbcast-react 1.6.2 → 1.7.0

package/dist/context.d.ts

@@ -11,17 +11,38 @@ export interface KerbcastSubscriptions {
 }
 /** Build the default refcounted subscriptions implementation for a client. */
 export declare function createClientSubscriptions(client: KerbcastClient): KerbcastSubscriptions;
+/**
+ * Collects each mounted feed's self-measured display size and drives the
+ * client's per-consumer `reportDisplaySize`. Multiple feeds can show the SAME
+ * camera at once (e.g. a tiny avatar and a spotlight of the same kerbal); the
+ * sidecar keys the auto-resolution max per CONSUMER, so those would clobber
+ * each other last-writer-wins. This collapses them at the client edge: it
+ * keeps the MAX display size across every mounted reporter for a flightId and
+ * sends one report per max-change. Co-located with the subscription refcount
+ * (same per-flightId lifetime) so one object owns everything this client is
+ * doing with camera N.
+ */
+export interface KerbcastDisplaySizes {
+    /** Register/update a reporter's measured size for a camera. */
+    report(flightId: number, instanceId: string, width: number, height: number): void;
+    /** Deregister a reporter (on unmount / flightId change). */
+    clear(flightId: number, instanceId: string): void;
+}
+/** Build the default per-flightId MAX display-size registry for a client. */
+export declare function createClientDisplaySizes(client: KerbcastClient): KerbcastDisplaySizes;
 export interface KerbcastProviderProps {
     client: KerbcastClient;
     /** Override the subscription manager. Defaults to a refcounted per-client impl. */
     subscriptions?: KerbcastSubscriptions;
+    /** Override the display-size registry. Defaults to a per-flightId MAX impl. */
+    displaySizes?: KerbcastDisplaySizes;
     children: ReactNode;
 }
 /**
  * Provide a `KerbcastClient` (and optional subscriptions override) to the
  * component subtree. Hooks and `CameraFeed` read both from this context.
  */
-export declare function KerbcastProvider({ client, subscriptions: subscriptionsProp, children, }: KerbcastProviderProps): React.JSX.Element;
+export declare function KerbcastProvider({ client, subscriptions: subscriptionsProp, displaySizes: displaySizesProp, children, }: KerbcastProviderProps): React.JSX.Element;
 /**
  * Return the `KerbcastClient` from the nearest `KerbcastProvider`.
  * Throws if called outside a provider.
@@ -32,3 +53,8 @@ export declare function useKerbcastClient(): KerbcastClient;
  * Throws if called outside a provider.
  */
 export declare function useKerbcastSubscriptions(): KerbcastSubscriptions;
+/**
+ * Return the `KerbcastDisplaySizes` registry from the nearest
+ * `KerbcastProvider`. Throws if called outside a provider.
+ */
+export declare function useKerbcastDisplaySizes(): KerbcastDisplaySizes;

package/dist/context.js

@@ -23,24 +23,79 @@ export function createClientSubscriptions(client) {
         },
     };
 }
+/** Build the default per-flightId MAX display-size registry for a client. */
+export function createClientDisplaySizes(client) {
+    // flightId -> (instanceId -> measured size)
+    const perCamera = new Map();
+    // Last size reported to the sidecar per flightId, so we send only on change.
+    const lastSent = new Map();
+    function recompute(flightId) {
+        const instances = perCamera.get(flightId);
+        if (!instances || instances.size === 0) {
+            // No reporters left. Drop bookkeeping and send nothing: the subscription
+            // release (unsubscribe -> sidecar remove_track -> forget_display_size)
+            // clears the sidecar side. Sending a spurious size here would fight it.
+            perCamera.delete(flightId);
+            lastSent.delete(flightId);
+            return;
+        }
+        let maxW = 0;
+        let maxH = 0;
+        for (const { w, h } of instances.values()) {
+            if (w > maxW)
+                maxW = w;
+            if (h > maxH)
+                maxH = h;
+        }
+        const prev = lastSent.get(flightId);
+        if (prev && prev.w === maxW && prev.h === maxH)
+            return;
+        lastSent.set(flightId, { w: maxW, h: maxH });
+        client.reportDisplaySize(flightId, maxW, maxH).catch(() => { });
+    }
+    return {
+        report(flightId, instanceId, width, height) {
+            let instances = perCamera.get(flightId);
+            if (!instances) {
+                instances = new Map();
+                perCamera.set(flightId, instances);
+            }
+            instances.set(instanceId, { w: width, h: height });
+            recompute(flightId);
+        },
+        clear(flightId, instanceId) {
+            const instances = perCamera.get(flightId);
+            if (!instances)
+                return;
+            instances.delete(instanceId);
+            recompute(flightId);
+        },
+    };
+}
 const KerbcastContext = createContext(null);
 /**
  * Provide a `KerbcastClient` (and optional subscriptions override) to the
  * component subtree. Hooks and `CameraFeed` read both from this context.
  */
-export function KerbcastProvider({ client, subscriptions: subscriptionsProp, children, }) {
+export function KerbcastProvider({ client, subscriptions: subscriptionsProp, displaySizes: displaySizesProp, children, }) {
     // Create default subscriptions once per client. A ref so the object is
     // stable across renders even if the parent re-renders.
     const defaultSubsRef = useRef(null);
     if (defaultSubsRef.current === null) {
         defaultSubsRef.current = createClientSubscriptions(client);
     }
+    // Same for the display-size registry: one per client, stable across renders.
+    const defaultSizesRef = useRef(null);
+    if (defaultSizesRef.current === null) {
+        defaultSizesRef.current = createClientDisplaySizes(client);
+    }
     const value = useMemo(() => ({
         client,
         subscriptions: subscriptionsProp ?? defaultSubsRef.current,
+        displaySizes: displaySizesProp ?? defaultSizesRef.current,
     }), 
     // eslint-disable-next-line react-hooks/exhaustive-deps
-    [client, subscriptionsProp]);
+    [client, subscriptionsProp, displaySizesProp]);
     return (_jsx(KerbcastContext.Provider, { value: value, children: children }));
 }
 // ---------------------------------------------------------------------------
@@ -68,3 +123,14 @@ export function useKerbcastSubscriptions() {
     }
     return ctx.subscriptions;
 }
+/**
+ * Return the `KerbcastDisplaySizes` registry from the nearest
+ * `KerbcastProvider`. Throws if called outside a provider.
+ */
+export function useKerbcastDisplaySizes() {
+    const ctx = useContext(KerbcastContext);
+    if (!ctx) {
+        throw new Error("useKerbcastDisplaySizes must be used inside a KerbcastProvider");
+    }
+    return ctx.displaySizes;
+}

package/dist/hooks/useReportDisplaySize.d.ts

@@ -0,0 +1,23 @@
+export interface ReportDisplaySizeOptions {
+    /**
+     * Report while mounted. Default true. Set false for a fixed-resolution feed
+     * that should not drive auto-resolution. This is a RESOLUTION concern only,
+     * independent of whether the feed shows its action UI.
+     */
+    enabled?: boolean;
+    /**
+     * Report a square (side x side, the min edge) rather than the raw w x h.
+     * Face cams are square; part cams are not.
+     */
+    square?: boolean;
+}
+/**
+ * Self-measure a feed element and drive the client's per-consumer
+ * `reportDisplaySize` (via the context display-size registry, which collapses
+ * multiple feeds of the same camera to one MAX report). Attach `ref` to the
+ * element whose rendered pixel box is the display size. Reporting follows the
+ * mount lifecycle: on unmount / `flightId` change / `enabled` flip it
+ * deregisters, and the sidecar's clear-on-departure (unsubscribe) does the
+ * server-side clear.
+ */
+export declare function useReportDisplaySize(flightId: number | null, ref: React.RefObject<Element | null>, { enabled, square }?: ReportDisplaySizeOptions): void;

package/dist/hooks/useReportDisplaySize.js

@@ -0,0 +1,71 @@
+import { useEffect, useId } from "react";
+import { useKerbcastDisplaySizes } from "../context";
+/*
+ * Debounce + bucket for self-measured display-size reporting. The first
+ * measurement after mount reports promptly (so a feed never sits at a stale
+ * resolution until it is resized); later churn is debounced. Sizes are ceiled
+ * to a BUCKET_PX multiple: that meets-the-minimum-need (never under-serve),
+ * yields an even value (H.264-friendly), and gives a material-change threshold
+ * so a feed re-reports only when a resize crosses a bucket boundary.
+ */
+const DEBOUNCE_MS = 200;
+const BUCKET_PX = 16;
+function bucket(px) {
+    const b = Math.ceil(px / BUCKET_PX) * BUCKET_PX;
+    return b < BUCKET_PX ? BUCKET_PX : b;
+}
+/**
+ * Self-measure a feed element and drive the client's per-consumer
+ * `reportDisplaySize` (via the context display-size registry, which collapses
+ * multiple feeds of the same camera to one MAX report). Attach `ref` to the
+ * element whose rendered pixel box is the display size. Reporting follows the
+ * mount lifecycle: on unmount / `flightId` change / `enabled` flip it
+ * deregisters, and the sidecar's clear-on-departure (unsubscribe) does the
+ * server-side clear.
+ */
+export function useReportDisplaySize(flightId, ref, { enabled = true, square = false } = {}) {
+    const displaySizes = useKerbcastDisplaySizes();
+    const instanceId = useId();
+    useEffect(() => {
+        if (flightId === null || !enabled)
+            return;
+        const el = ref.current;
+        if (!el)
+            return;
+        let timer = null;
+        let lastW = -1;
+        let lastH = -1;
+        let firstReported = false;
+        const report = (width, height) => {
+            const side = square ? Math.min(width, height) : 0;
+            const bw = bucket(square ? side : width);
+            const bh = bucket(square ? side : height);
+            if (bw === lastW && bh === lastH)
+                return;
+            lastW = bw;
+            lastH = bh;
+            displaySizes.report(flightId, instanceId, bw, bh);
+        };
+        const observer = new ResizeObserver((entries) => {
+            const entry = entries[0];
+            if (!entry)
+                return;
+            const { width, height } = entry.contentRect;
+            if (!firstReported) {
+                firstReported = true;
+                report(width, height);
+                return;
+            }
+            if (timer !== null)
+                clearTimeout(timer);
+            timer = setTimeout(() => report(width, height), DEBOUNCE_MS);
+        });
+        observer.observe(el);
+        return () => {
+            observer.disconnect();
+            if (timer !== null)
+                clearTimeout(timer);
+            displaySizes.clear(flightId, instanceId);
+        };
+    }, [displaySizes, flightId, ref, enabled, square, instanceId]);
+}

package/dist/index.d.ts

@@ -5,12 +5,13 @@
  * is a peer to @ksp-gonogo/kerbcast (the core SDK) and requires React 18+
  * and styled-components 6+ as peer dependencies.
  */
-export { KerbcastProvider, createClientSubscriptions, useKerbcastClient, useKerbcastSubscriptions, } from "./context";
-export type { KerbcastProviderProps, KerbcastSubscriptions } from "./context";
+export { KerbcastProvider, createClientSubscriptions, createClientDisplaySizes, useKerbcastClient, useKerbcastSubscriptions, useKerbcastDisplaySizes, } from "./context";
+export type { KerbcastProviderProps, KerbcastSubscriptions, KerbcastDisplaySizes, } from "./context";
 export { useKerbcastCameras } from "./hooks/useKerbcastCameras";
 export { useKerbcastStream } from "./hooks/useKerbcastStream";
 export { useKerbcastClock } from "./hooks/useKerbcastClock";
 export { useKerbcastInFlight } from "./hooks/useKerbcastInFlight";
+export { useReportDisplaySize } from "./hooks/useReportDisplaySize";
 export { StandbyIcon } from "./StandbyIcon";
 export { buildCameraLabeler } from "./cameraLabels";
 export type { LabelableCamera } from "./cameraLabels";
@@ -18,3 +19,5 @@ export { getCameraLifecycle, isCameraDestroyed } from "./lifecycle";
 export type { CameraLifecycle } from "./lifecycle";
 export { CameraFeed } from "./CameraFeed";
 export type { CameraFeedHandle, CameraFeedProps, CameraStreamHook, FeedAction, } from "./CameraFeed";
+export { KerbalFaceFeed } from "./KerbalFaceFeed";
+export type { KerbalFaceFeedProps, KerbalFeedState } from "./KerbalFaceFeed";

package/dist/index.js

@@ -6,12 +6,13 @@
  * and styled-components 6+ as peer dependencies.
  */
 // Context and provider
-export { KerbcastProvider, createClientSubscriptions, useKerbcastClient, useKerbcastSubscriptions, } from "./context";
+export { KerbcastProvider, createClientSubscriptions, createClientDisplaySizes, useKerbcastClient, useKerbcastSubscriptions, useKerbcastDisplaySizes, } from "./context";
 // Hooks
 export { useKerbcastCameras } from "./hooks/useKerbcastCameras";
 export { useKerbcastStream } from "./hooks/useKerbcastStream";
 export { useKerbcastClock } from "./hooks/useKerbcastClock";
 export { useKerbcastInFlight } from "./hooks/useKerbcastInFlight";
+export { useReportDisplaySize } from "./hooks/useReportDisplaySize";
 // Shared standby glyph (used by CameraFeed + downstream dashboards)
 export { StandbyIcon } from "./StandbyIcon";
 // Camera label utilities
@@ -20,3 +21,5 @@ export { buildCameraLabeler } from "./cameraLabels";
 export { getCameraLifecycle, isCameraDestroyed } from "./lifecycle";
 // CameraFeed component
 export { CameraFeed } from "./CameraFeed";
+// KerbalFaceFeed — shared single-kerbal-face primitive
+export { KerbalFaceFeed } from "./KerbalFaceFeed";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ksp-gonogo/kerbcast-react",
-  "version": "1.6.2",
+  "version": "1.7.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.6.2"
+    "@ksp-gonogo/kerbcast": "^1.7.0"
   },
   "peerDependencies": {
     "react": "^18 || ^19",

package/src/CameraFeed.test.tsx

@@ -22,7 +22,7 @@
  *  - Station (brokered) mode -- gonogo-only KerbcastDataSource.attachBroker.
  */
 
-import { KerbcastClient, QualityPreset } from "@ksp-gonogo/kerbcast";
+import { KerbcastClient, QualityPreset, TrackMode } from "@ksp-gonogo/kerbcast";
 import type { CameraLifecycle, ClientMessage } from "@ksp-gonogo/kerbcast";
 import { type MockCameraInit, MockSidecar } from "@ksp-gonogo/kerbcast/testing";
 import {
@@ -108,6 +108,7 @@ function toInit(c: CameraStateLike): MockCameraInit {
     degradeLevel: c.degradeLevel as number | undefined,
     viewerQuality: c.viewerQuality as QualityPreset | undefined,
     qualityLimitedBy: c.qualityLimitedBy as string | undefined,
+    trackMode: c.trackMode as TrackMode | undefined,
   };
 }
 
@@ -154,8 +155,10 @@ function renderFeed(
     showDebugInfo?: boolean;
     renderSize?: "auto" | "none";
     enableQualityControl?: boolean;
+    enableTracking?: boolean;
     showStatic?: boolean;
     showStandbyIcon?: boolean;
+    showActions?: boolean;
     ref?: React.Ref<CameraFeedHandle>;
   },
 ) {
@@ -1351,28 +1354,61 @@ describe("CameraFeed - ResizeObserver render-size feedback", () => {
     resizeCallback = undefined;
   });
 
-  it("render-size observer fires set-render-size command", async () => {
+  it("reports the measured display size (report-display-size, real w x h)", async () => {
     const { client, sidecar } = await buildConnectedSource();
 
     renderFeed(client, { flightId: 42 });
 
+    // First measurement reports promptly (no debounce wait).
     await act(async () => {
       resizeCallback?.(
-        [{ contentRect: { width: 400, height: 400 } }] as ResizeObserverEntry[],
+        [{ contentRect: { width: 400, height: 224 } }] as ResizeObserverEntry[],
         {} as ResizeObserver,
       );
     });
 
-    await act(async () => {
-      vi.advanceTimersByTime(501);
-    });
+    const msg = sidecar.lastCommand("report-display-size");
+    expect(msg).toBeTruthy();
+    // Measured w x h (no synthetic 16:9 crop), bucketed to a 16-multiple:
+    // 400 -> 400, 224 -> 224.
+    expect(msg?.content.width).toBe(400);
+    expect(msg?.content.height).toBe(224);
+    // Measurement no longer drives the operator set-render-size (that path is
+    // the manual quality cap only).
+    expect(sidecar.commands.some((c) => c.type === "set-render-size")).toBe(false);
+  });
+
+  it("does not report when renderSize is none", async () => {
+    const { client, sidecar } = await buildConnectedSource();
 
-    const renderSizeMsg = sidecar.lastCommand("set-render-size");
-    expect(renderSizeMsg).toBeTruthy();
-    // Width as-is (already even); height derived 16:9 then rounded to even px:
-    // 400 * 9/16 = 225 -> 226.
-    expect(renderSizeMsg?.content.width).toBe(400);
-    expect(renderSizeMsg?.content.height).toBe(226);
+    renderFeed(client, { flightId: 42, renderSize: "none" });
+
+    // The observer is never armed when reporting is disabled.
+    expect(resizeCallback).toBeUndefined();
+    expect(sidecar.commands.some((c) => c.type === "report-display-size")).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// showActions
+// ---------------------------------------------------------------------------
+
+describe("CameraFeed - showActions", () => {
+  it("renders the action bar by default", async () => {
+    const { client } = await buildConnectedSource();
+    const { queryByLabelText } = renderFeed(client, { flightId: 42 });
+    // The camera step buttons live in the action bar.
+    expect(queryByLabelText("Next camera")).toBeTruthy();
+  });
+
+  it("hides the action bar when showActions is false", async () => {
+    const { client } = await buildConnectedSource();
+    const { queryByLabelText } = renderFeed(client, {
+      flightId: 42,
+      showActions: false,
+    });
+    expect(queryByLabelText("Next camera")).toBeNull();
+    expect(queryByLabelText("Previous camera")).toBeNull();
   });
 });
 
@@ -1682,3 +1718,131 @@ describe("CameraFeed - client prop override", () => {
     });
   });
 });
+
+// ---------------------------------------------------------------------------
+// Tracking (crosshair) — auto-track a moving vessel, server-authoritative
+// ---------------------------------------------------------------------------
+
+describe("CameraFeed - tracking (crosshair)", () => {
+  function panZoomCam(overrides: Record<string, unknown> = {}) {
+    return makeCamera({
+      flightId: 42,
+      cameraName: "Launchpad Cam",
+      supportsPan: true,
+      supportsZoom: true,
+      panPitchMin: -90,
+      panPitchMax: 90,
+      ...overrides,
+    });
+  }
+
+  it("shows the crosshair on a pan+zoom camera when enableTracking", async () => {
+    const { client } = await buildConnectedSource([panZoomCam()]);
+    const { queryByLabelText } = renderFeed(client, {
+      flightId: 42,
+      enableTracking: true,
+    });
+    expect(queryByLabelText("Auto-track")).toBeTruthy();
+  });
+
+  it("hides the crosshair without enableTracking", async () => {
+    const { client } = await buildConnectedSource([panZoomCam()]);
+    const { queryByLabelText } = renderFeed(client, { flightId: 42 });
+    expect(queryByLabelText("Auto-track")).toBeNull();
+  });
+
+  it("hides the crosshair when the camera lacks pan or zoom", async () => {
+    const { client } = await buildConnectedSource([
+      makeCamera({ flightId: 42, supportsPan: true, supportsZoom: false }),
+    ]);
+    const { queryByLabelText } = renderFeed(client, {
+      flightId: 42,
+      enableTracking: true,
+    });
+    expect(queryByLabelText("Auto-track")).toBeNull();
+  });
+
+  it("clicking a mode sends set-track-target with that mode", async () => {
+    const { client, sidecar } = await buildConnectedSource([panZoomCam()]);
+    const { getByLabelText } = renderFeed(client, {
+      flightId: 42,
+      enableTracking: true,
+    });
+    fireEvent.click(getByLabelText("Auto-track"));
+    fireEvent.click(
+      await screen.findByRole("menuitemradio", { name: "Track active vessel" }),
+    );
+    expect(sidecar.lastCommand("set-track-target", 42)?.content.mode).toBe(
+      TrackMode.ActiveVessel,
+    );
+  });
+
+  it("highlight reflects the SERVER trackMode, never the click (not optimistic)", async () => {
+    const { client, sidecar } = await buildConnectedSource([panZoomCam()]);
+    // Suppress the echo so a click alone cannot flip the highlight; only a
+    // real server state change may.
+    const spy = vi.spyOn(client, "setTrackTarget").mockResolvedValue();
+    const { getByLabelText } = renderFeed(client, {
+      flightId: 42,
+      enableTracking: true,
+    });
+    expect(getByLabelText("Auto-track").getAttribute("aria-pressed")).toBe("false");
+
+    fireEvent.click(getByLabelText("Auto-track"));
+    fireEvent.click(
+      await screen.findByRole("menuitemradio", { name: "Track target" }),
+    );
+    expect(spy).toHaveBeenCalledWith(42, TrackMode.Target);
+    // No echo yet -> highlight must stay off.
+    expect(getByLabelText("Auto-track").getAttribute("aria-pressed")).toBe("false");
+
+    // Server confirms -> highlight turns on.
+    await act(async () => {
+      sidecar.updateCamera(42, { trackMode: TrackMode.Target });
+    });
+    expect(getByLabelText("Auto-track").getAttribute("aria-pressed")).toBe("true");
+  });
+
+  it("clicking the active mode deselects to none", async () => {
+    const { client, sidecar } = await buildConnectedSource([
+      panZoomCam({ trackMode: TrackMode.ActiveVessel }),
+    ]);
+    const { getByLabelText } = renderFeed(client, {
+      flightId: 42,
+      enableTracking: true,
+    });
+    fireEvent.click(getByLabelText("Auto-track"));
+    fireEvent.click(
+      await screen.findByRole("menuitemradio", { name: "Track active vessel" }),
+    );
+    expect(sidecar.lastCommand("set-track-target", 42)?.content.mode).toBe(
+      TrackMode.None,
+    );
+  });
+
+  it("disables the manual pan + zoom controls while tracking", async () => {
+    const { client } = await buildConnectedSource([
+      panZoomCam({ trackMode: TrackMode.Target }),
+    ]);
+    const { getByLabelText } = renderFeed(client, {
+      flightId: 42,
+      enableTracking: true,
+    });
+    expect((getByLabelText("Zoom in") as HTMLButtonElement).disabled).toBe(true);
+    expect((getByLabelText("Zoom out") as HTMLButtonElement).disabled).toBe(true);
+    expect((getByLabelText("Pan left") as HTMLButtonElement).disabled).toBe(true);
+    expect((getByLabelText("Pan right") as HTMLButtonElement).disabled).toBe(true);
+  });
+
+  it("keeps manual pan + zoom enabled when not tracking", async () => {
+    const { client } = await buildConnectedSource([
+      panZoomCam({ trackMode: TrackMode.None }),
+    ]);
+    const { getByLabelText } = renderFeed(client, {
+      flightId: 42,
+      enableTracking: true,
+    });
+    expect((getByLabelText("Zoom in") as HTMLButtonElement).disabled).toBe(false);
+    expect((getByLabelText("Pan left") as HTMLButtonElement).disabled).toBe(false);
+  });
+});