@ksp-gonogo/kerbcast-react 1.4.0

package/src/cameraLabels.test.ts

@@ -0,0 +1,82 @@
+import { describe, expect, it } from "vitest";
+import { buildCameraLabeler } from "./cameraLabels";
+import type { LabelableCamera } from "./cameraLabels";
+
+function cam(
+  flightId: number,
+  cameraName: string,
+  partTitle?: string | null,
+): LabelableCamera {
+  return { flightId, cameraName, partTitle };
+}
+
+describe("buildCameraLabeler", () => {
+  it("leaves non-colliding names unchanged", () => {
+    const cameras = [cam(1, "NavCam", "NavCam"), cam(2, "Tail Cam", "Some Part")];
+    const label = buildCameraLabeler(cameras);
+    expect(label(cameras[0]!)).toBe("NavCam");
+    expect(label(cameras[1]!)).toBe("Tail Cam");
+  });
+
+  it("disambiguates colliding names by part title when titles differ", () => {
+    const cameras = [
+      cam(1, "NavCam", "NavCam"),
+      cam(2, "NavCam", "Clamp-O-Tron Docking Port Jr."),
+    ];
+    const label = buildCameraLabeler(cameras);
+    expect(label(cameras[0]!)).toBe("NavCam");
+    expect(label(cameras[1]!)).toBe("NavCam - Clamp-O-Tron Docking Port Jr.");
+  });
+
+  it("numbers identical cameras that the part title cannot tell apart", () => {
+    const cameras = [
+      cam(10, "KazzelBlad - BoosterCam", "KazzelBlad - BoosterCam"),
+      cam(20, "KazzelBlad - BoosterCam", "KazzelBlad - BoosterCam"),
+      cam(30, "KazzelBlad - BoosterCam", "KazzelBlad - BoosterCam"),
+    ];
+    const label = buildCameraLabeler(cameras);
+    expect(label(cameras[0]!)).toBe("KazzelBlad - BoosterCam #1");
+    expect(label(cameras[1]!)).toBe("KazzelBlad - BoosterCam #2");
+    expect(label(cameras[2]!)).toBe("KazzelBlad - BoosterCam #3");
+  });
+
+  it("numbers by flightId order, not list order", () => {
+    const cameras = [
+      cam(30, "BoosterCam", "BoosterCam"),
+      cam(10, "BoosterCam", "BoosterCam"),
+      cam(20, "BoosterCam", "BoosterCam"),
+    ];
+    const label = buildCameraLabeler(cameras);
+    expect(label(cameras[0]!)).toBe("BoosterCam #3");
+    expect(label(cameras[1]!)).toBe("BoosterCam #1");
+    expect(label(cameras[2]!)).toBe("BoosterCam #2");
+  });
+
+  it("keeps numbers stable when unrelated cameras join the list", () => {
+    const a = cam(10, "BoosterCam", "BoosterCam");
+    const b = cam(20, "BoosterCam", "BoosterCam");
+    const before = buildCameraLabeler([a, b]);
+    const after = buildCameraLabeler([a, b, cam(5, "NavCam", "NavCam")]);
+    expect(after(a)).toBe(before(a));
+    expect(after(b)).toBe(before(b));
+  });
+
+  it("numbers cameras whose part titles collide too, after title disambiguation", () => {
+    const cameras = [
+      cam(1, "NavCam", "NavCam"),
+      cam(2, "NavCam", "Clamp-O-Tron"),
+      cam(3, "NavCam", "Clamp-O-Tron"),
+    ];
+    const label = buildCameraLabeler(cameras);
+    expect(label(cameras[0]!)).toBe("NavCam");
+    expect(label(cameras[1]!)).toBe("NavCam - Clamp-O-Tron #1");
+    expect(label(cameras[2]!)).toBe("NavCam - Clamp-O-Tron #2");
+  });
+
+  it("falls back to numbering when colliding cameras have no part title", () => {
+    const cameras = [cam(1, "Camera", null), cam(2, "Camera", undefined)];
+    const label = buildCameraLabeler(cameras);
+    expect(label(cameras[0]!)).toBe("Camera #1");
+    expect(label(cameras[1]!)).toBe("Camera #2");
+  });
+});

package/src/cameraLabels.ts

@@ -0,0 +1,68 @@
+/*
+ * Camera display labels, shared by every widget that lets the operator pick a
+ * camera.
+ *
+ * Hullcam names cameras non-uniquely: its DockingPortCameraPatch labels EVERY
+ * docking-port camera "NavCam", colliding with the dedicated NavCam part, so a
+ * raw `cameraName` list shows two indistinguishable "NavCam" rows and the
+ * docking-port feed looks missing. When a name is shared by more than one
+ * camera in the list, we append the part title (e.g. "NavCam - Clamp-O-Tron
+ * Docking Port Jr.") to tell them apart; non-colliding cameras are unchanged.
+ *
+ * Identical parts defeat that too (nine BoosterCams share both name and part
+ * title), so labels that still collide get a "#N" suffix, numbered in
+ * ascending flightId order. flightId is stable per part, so the numbers do
+ * not shuffle between sessions or when unrelated cameras come and go.
+ */
+
+export interface LabelableCamera {
+  flightId: number;
+  cameraName: string;
+  partTitle?: string | null;
+}
+
+/**
+ * Build a labeller closed over the current camera list. The returned function
+ * maps a camera to its display name, disambiguating only the cameras whose
+ * `cameraName` collides with another in the same list.
+ *
+ * The label does NOT include the vessel name. Call sites append that (and any
+ * " - signal lost" suffix) themselves.
+ */
+export function buildCameraLabeler<T extends LabelableCamera>(
+  cameras: readonly T[],
+): (camera: T) => string {
+  const counts = new Map<string, number>();
+  for (const c of cameras) {
+    counts.set(c.cameraName, (counts.get(c.cameraName) ?? 0) + 1);
+  }
+  const baseLabel = (camera: T): string =>
+    (counts.get(camera.cameraName) ?? 0) > 1 &&
+    camera.partTitle &&
+    camera.partTitle !== camera.cameraName
+      ? `${camera.cameraName} - ${camera.partTitle}`
+      : camera.cameraName;
+
+  /* Number the cameras whose base label still collides: per colliding label,
+     sort by flightId and hand out #1..#N. */
+  const byLabel = new Map<string, T[]>();
+  for (const c of cameras) {
+    const label = baseLabel(c);
+    const group = byLabel.get(label);
+    if (group) group.push(c);
+    else byLabel.set(label, [c]);
+  }
+  const ordinals = new Map<number, number>();
+  for (const group of byLabel.values()) {
+    if (group.length < 2) continue;
+    [...group]
+      .sort((a, b) => a.flightId - b.flightId)
+      .forEach((c, i) => ordinals.set(c.flightId, i + 1));
+  }
+
+  return (camera: T): string => {
+    const label = baseLabel(camera);
+    const ordinal = ordinals.get(camera.flightId);
+    return ordinal === undefined ? label : `${label} #${ordinal}`;
+  };
+}

package/src/context.tsx

@@ -0,0 +1,129 @@
+import type { KerbcastClient } from "@ksp-gonogo/kerbcast";
+import {
+  createContext,
+  useContext,
+  useMemo,
+  useRef,
+  type ReactNode,
+} from "react";
+
+// ---------------------------------------------------------------------------
+// Subscriptions seam
+// ---------------------------------------------------------------------------
+
+/**
+ * Lifecycle controller for per-camera slot subscriptions. The default
+ * implementation refcounts so multiple widgets sharing the same flightId
+ * share one slot.
+ */
+export interface KerbcastSubscriptions {
+  acquire(flightId: number): void;
+  release(flightId: number): void;
+}
+
+/** Build the default refcounted subscriptions implementation for a client. */
+export function createClientSubscriptions(
+  client: KerbcastClient,
+): KerbcastSubscriptions {
+  const refcounts = new Map<number, number>();
+  return {
+    acquire(flightId: number): void {
+      const count = (refcounts.get(flightId) ?? 0) + 1;
+      refcounts.set(flightId, count);
+      if (count === 1) {
+        client.subscribe(flightId).catch(() => {});
+      }
+    },
+    release(flightId: number): void {
+      const count = (refcounts.get(flightId) ?? 1) - 1;
+      if (count <= 0) {
+        refcounts.delete(flightId);
+        client.unsubscribe(flightId).catch(() => {});
+      } else {
+        refcounts.set(flightId, count);
+      }
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Context shape
+// ---------------------------------------------------------------------------
+
+interface KerbcastContextValue {
+  client: KerbcastClient;
+  subscriptions: KerbcastSubscriptions;
+}
+
+const KerbcastContext = createContext<KerbcastContextValue | null>(null);
+
+// ---------------------------------------------------------------------------
+// Provider
+// ---------------------------------------------------------------------------
+
+export interface KerbcastProviderProps {
+  client: KerbcastClient;
+  /** Override the subscription manager. Defaults to a refcounted per-client impl. */
+  subscriptions?: KerbcastSubscriptions;
+  children: ReactNode;
+}
+
+/**
+ * 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,
+}: KerbcastProviderProps): React.JSX.Element {
+  // Create default subscriptions once per client. A ref so the object is
+  // stable across renders even if the parent re-renders.
+  const defaultSubsRef = useRef<KerbcastSubscriptions | null>(null);
+  if (defaultSubsRef.current === null) {
+    defaultSubsRef.current = createClientSubscriptions(client);
+  }
+
+  const value = useMemo(
+    () => ({
+      client,
+      subscriptions: subscriptionsProp ?? defaultSubsRef.current!,
+    }),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [client, subscriptionsProp],
+  );
+
+  return (
+    <KerbcastContext.Provider value={value}>{children}</KerbcastContext.Provider>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Hooks
+// ---------------------------------------------------------------------------
+
+/**
+ * Return the `KerbcastClient` from the nearest `KerbcastProvider`.
+ * Throws if called outside a provider.
+ */
+export function useKerbcastClient(): KerbcastClient {
+  const ctx = useContext(KerbcastContext);
+  if (!ctx) {
+    throw new Error("useKerbcastClient must be used inside a KerbcastProvider");
+  }
+  return ctx.client;
+}
+
+/**
+ * Return the `KerbcastSubscriptions` from the nearest `KerbcastProvider`.
+ * Throws if called outside a provider.
+ */
+export function useKerbcastSubscriptions(): KerbcastSubscriptions {
+  const ctx = useContext(KerbcastContext);
+  if (!ctx) {
+    throw new Error(
+      "useKerbcastSubscriptions must be used inside a KerbcastProvider",
+    );
+  }
+  return ctx.subscriptions;
+}

package/src/hooks/useKerbcastCameras.ts

@@ -0,0 +1,24 @@
+import type { CameraState } from "@ksp-gonogo/kerbcast";
+import { useEffect, useState } from "react";
+import { useKerbcastClient } from "../context";
+
+/**
+ * Live snapshot of the kerbcast camera registry. Returns the empty list
+ * before the data channel handshake completes (and after a disconnect).
+ * Subscribes via the underlying `KerbcastClient`'s `cameras-change` event for
+ * one synchronous push per server-side snapshot or state-changed message.
+ */
+export function useKerbcastCameras(): CameraState[] {
+  const client = useKerbcastClient();
+
+  const [cameras, setCameras] = useState<CameraState[]>(() => [
+    ...client.cameras,
+  ]);
+
+  useEffect(() => {
+    setCameras([...client.cameras]);
+    return client.on("cameras-change", (next) => setCameras([...next]));
+  }, [client]);
+
+  return cameras;
+}

package/src/hooks/useKerbcastClock.test.tsx

@@ -0,0 +1,73 @@
+/**
+ * useKerbcastClock capture-clock subscription.
+ *
+ * Renders a probe through the real hook + real KerbcastClient with only the
+ * WebRTC transport faked by the SDK's MockSidecar. Asserts the hook seeds from
+ * the client and re-renders on each `settings-state` push.
+ */
+
+import { KerbcastClient } from "@ksp-gonogo/kerbcast";
+import { MockSidecar } from "@ksp-gonogo/kerbcast/testing";
+import { act, cleanup, render } from "@testing-library/react";
+import { afterEach, describe, expect, it } from "vitest";
+import { KerbcastProvider } from "../context";
+import { useKerbcastClock } from "./useKerbcastClock";
+
+let lastClock: ReturnType<typeof useKerbcastClock> | undefined;
+
+function ClockProbe(): null {
+  lastClock = useKerbcastClock();
+  return null;
+}
+
+async function connected(): Promise<{
+  client: KerbcastClient;
+  sidecar: MockSidecar;
+}> {
+  const sidecar = new MockSidecar();
+  const client = new KerbcastClient(
+    { host: "h", port: 1, negotiate: (o) => sidecar.negotiate(o) },
+    sidecar.createTransport(),
+  );
+  await act(async () => {
+    await client.connect([], { slots: 4 });
+    sidecar.open();
+    sidecar.setConnectionState("connected");
+  });
+  return { client, sidecar };
+}
+
+afterEach(() => {
+  cleanup();
+  lastClock = undefined;
+});
+
+describe("useKerbcastClock", () => {
+  it("starts with no clock and updates on a settings-state push", async () => {
+    const { client, sidecar } = await connected();
+
+    render(
+      <KerbcastProvider client={client}>
+        <ClockProbe />
+      </KerbcastProvider>,
+    );
+
+    /* Open sent a bare settings-state (no capture fields) => no clock. */
+    expect(lastClock).toEqual({ captureUt: null, epoch: 0, warpRate: 1 });
+
+    act(() => {
+      sidecar.fireSettingsState({
+        throttleMainScreen: false,
+        captureUt: 500.25,
+        captureEpoch: 2,
+        timeWarpRate: 10,
+      });
+    });
+
+    expect(lastClock).toEqual({ captureUt: 500.25, epoch: 2, warpRate: 10 });
+
+    await act(async () => {
+      await client.disconnect();
+    });
+  });
+});

package/src/hooks/useKerbcastClock.ts

@@ -0,0 +1,33 @@
+import { useEffect, useState } from "react";
+import { useKerbcastClient } from "../context";
+
+/**
+ * Mission-time capture clock, from the sidecar's ~1Hz `settings-state`.
+ *
+ * - `captureUt`: KSP universal time (seconds) the current video was captured
+ *   at, or `null` when no clock is known (old plugin/sidecar, or before the
+ *   first push). A consumer treats `null` as "no clock" and keeps a live
+ *   passthrough.
+ * - `epoch`: bumps on a UT discontinuity (revert / quickload / scene reload);
+ *   only the change is meaningful, so a consumer flushes and resyncs on it.
+ * - `warpRate`: current time-warp multiplier, for interpolating `captureUt`
+ *   between samples; defaults to 1.
+ *
+ * This is a single global sim clock, not a per-camera value, so it takes no
+ * `flightId`.
+ */
+export function useKerbcastClock(): {
+  captureUt: number | null;
+  epoch: number;
+  warpRate: number;
+} {
+  const client = useKerbcastClient();
+  const [clock, setClock] = useState(() => client.clock);
+
+  useEffect(() => {
+    setClock(client.clock);
+    return client.on("settings-change", () => setClock(client.clock));
+  }, [client]);
+
+  return clock;
+}

package/src/hooks/useKerbcastStream.test.tsx

@@ -0,0 +1,119 @@
+/**
+ * useKerbcastStream slot-subscription lifecycle.
+ *
+ * Renders a probe component through the real hook + real KerbcastClient,
+ * with only the WebRTC transport faked by the SDK's canonical MockSidecar.
+ * Asserts the hook drives the dynamic-mode subscription: a slot binds while a
+ * camera is on screen, switches when the selected flightId changes, and frees
+ * on unmount.
+ */
+
+import { KerbcastClient } from "@ksp-gonogo/kerbcast";
+import { MockSidecar } from "@ksp-gonogo/kerbcast/testing";
+import { act, cleanup, render } from "@testing-library/react";
+import { afterEach, describe, expect, it } from "vitest";
+import { KerbcastProvider } from "../context";
+import { useKerbcastStream } from "./useKerbcastStream";
+
+function StreamProbe({ flightId }: { flightId: number | null }): null {
+  useKerbcastStream(flightId);
+  return null;
+}
+
+function Wrapper({
+  client,
+  flightId,
+}: {
+  client: KerbcastClient;
+  flightId: number | null;
+}): React.JSX.Element {
+  return (
+    <KerbcastProvider client={client}>
+      <StreamProbe flightId={flightId} />
+    </KerbcastProvider>
+  );
+}
+
+async function connectedSource(
+  flightIds: number[] = [42, 43],
+): Promise<{ client: KerbcastClient; sidecar: MockSidecar }> {
+  const sidecar = new MockSidecar();
+  for (const flightId of flightIds) {
+    sidecar.addCamera({ flightId });
+  }
+  const client = new KerbcastClient(
+    { host: "h", port: 1, negotiate: (o) => sidecar.negotiate(o) },
+    sidecar.createTransport(),
+  );
+  await act(async () => {
+    await client.connect([], { slots: 4 });
+    sidecar.open();
+    sidecar.setConnectionState("connected");
+  });
+  return { client, sidecar };
+}
+
+afterEach(() => {
+  cleanup();
+});
+
+describe("useKerbcastStream - slot subscription lifecycle", () => {
+  it("subscribes the camera on mount and releases it on unmount", async () => {
+    const { client, sidecar } = await connectedSource();
+
+    const { unmount } = render(<Wrapper client={client} flightId={42} />);
+
+    expect(sidecar.lastCommand("subscribe", 42)).toBeTruthy();
+    expect(sidecar.slotMidFor(42)).toBeDefined();
+
+    act(() => {
+      unmount();
+    });
+
+    // Disconnect after unmount so stream-null emission hits no mounted widget.
+    await act(async () => {
+      await client.disconnect();
+    });
+
+    expect(sidecar.lastCommand("unsubscribe", 42)).toBeTruthy();
+    expect(sidecar.slotMidFor(42)).toBeUndefined();
+  });
+
+  it("switches slots when the selected flightId changes", async () => {
+    const { client, sidecar } = await connectedSource();
+
+    const { rerender, unmount } = render(
+      <Wrapper client={client} flightId={42} />,
+    );
+    expect(sidecar.slotMidFor(42)).toBeDefined();
+
+    act(() => {
+      rerender(<Wrapper client={client} flightId={43} />);
+    });
+
+    expect(sidecar.slotMidFor(42)).toBeUndefined();
+    expect(sidecar.slotMidFor(43)).toBeDefined();
+
+    act(() => {
+      unmount();
+    });
+    await act(async () => {
+      await client.disconnect();
+    });
+  });
+
+  it("does not subscribe when no camera is selected", async () => {
+    const { client, sidecar } = await connectedSource();
+
+    const { unmount } = render(<Wrapper client={client} flightId={null} />);
+
+    expect(sidecar.commands.some((c) => c.type === "subscribe")).toBe(false);
+
+    act(() => {
+      unmount();
+    });
+    await act(async () => {
+      await client.disconnect();
+    });
+  });
+});

package/src/hooks/useKerbcastStream.ts

@@ -0,0 +1,38 @@
+import { useEffect, useState } from "react";
+import { useKerbcastClient, useKerbcastSubscriptions } from "../context";
+
+/**
+ * Live `MediaStream` for one kerbcast camera. Returns `null` while the WebRTC
+ * track hasn't arrived yet (during connection setup, or after a disconnect).
+ * Components bind the stream to a `<video>`'s `srcObject` directly.
+ *
+ * While mounted with a non-null `flightId`, acquires a subscription slot via
+ * the context `KerbcastSubscriptions`. Releases the slot when the component
+ * unmounts or the `flightId` changes.
+ */
+export function useKerbcastStream(flightId: number | null): MediaStream | null {
+  const client = useKerbcastClient();
+  const subscriptions = useKerbcastSubscriptions();
+
+  const [stream, setStream] = useState<MediaStream | null>(() => {
+    if (flightId === null) return null;
+    return client.camera(flightId).mediaStream;
+  });
+
+  useEffect(() => {
+    if (flightId === null) {
+      setStream(null);
+      return;
+    }
+    const cam = client.camera(flightId);
+    setStream(cam.mediaStream);
+    const off = cam.on("stream", setStream);
+    subscriptions.acquire(flightId);
+    return () => {
+      off();
+      subscriptions.release(flightId);
+    };
+  }, [client, subscriptions, flightId]);
+
+  return stream;
+}

package/src/index.test.ts

@@ -0,0 +1,10 @@
+import { describe, it, expect } from "vitest";
+
+// Smoke test: the package module resolves and its shape is what consumers
+// expect. Real component tests land with the CameraFeed extraction.
+describe("@ksp-gonogo/kerbcast-react", () => {
+  it("module resolves", async () => {
+    const mod = await import("./index");
+    expect(mod).toBeDefined();
+  });
+});

package/src/index.ts

@@ -0,0 +1,38 @@
+/**
+ * @ksp-gonogo/kerbcast-react
+ *
+ * React components and hooks for kerbcast camera feeds. This package
+ * is a peer to @ksp-gonogo/kerbcast (the core SDK) and requires React 18+
+ * and styled-components 6+ as peer dependencies.
+ */
+
+// Context and provider
+export {
+  KerbcastProvider,
+  createClientSubscriptions,
+  useKerbcastClient,
+  useKerbcastSubscriptions,
+} from "./context";
+export type { KerbcastProviderProps, KerbcastSubscriptions } from "./context";
+
+// Hooks
+export { useKerbcastCameras } from "./hooks/useKerbcastCameras";
+export { useKerbcastStream } from "./hooks/useKerbcastStream";
+export { useKerbcastClock } from "./hooks/useKerbcastClock";
+
+// Camera label utilities
+export { buildCameraLabeler } from "./cameraLabels";
+export type { LabelableCamera } from "./cameraLabels";
+
+// Lifecycle utilities
+export { getCameraLifecycle, isCameraDestroyed } from "./lifecycle";
+export type { CameraLifecycle } from "./lifecycle";
+
+// CameraFeed component
+export { CameraFeed } from "./CameraFeed";
+export type {
+  CameraFeedHandle,
+  CameraFeedProps,
+  CameraStreamHook,
+  FeedAction,
+} from "./CameraFeed";

package/src/lifecycle.ts

@@ -0,0 +1,14 @@
+import type { CameraState } from "@ksp-gonogo/kerbcast";
+import { CameraLifecycle } from "@ksp-gonogo/kerbcast";
+
+export type { CameraLifecycle };
+
+export function getCameraLifecycle(cam: CameraState): CameraLifecycle {
+  return cam.lifecycle === CameraLifecycle.Destroyed
+    ? CameraLifecycle.Destroyed
+    : CameraLifecycle.Active;
+}
+
+export function isCameraDestroyed(cam: CameraState): boolean {
+  return getCameraLifecycle(cam) === CameraLifecycle.Destroyed;
+}

package/src/test/setup.ts

@@ -0,0 +1,3 @@
+import { installDomStubs } from "@ksp-gonogo/kerbcast/testing";
+
+installDomStubs();