@ksp-gonogo/kerbcast-react 1.4.0

package/dist/cameraLabels.d.ts

@@ -0,0 +1,14 @@
+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 declare function buildCameraLabeler<T extends LabelableCamera>(cameras: readonly T[]): (camera: T) => string;

package/dist/cameraLabels.js

@@ -0,0 +1,59 @@
+/*
+ * 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.
+ */
+/**
+ * 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(cameras) {
+    const counts = new Map();
+    for (const c of cameras) {
+        counts.set(c.cameraName, (counts.get(c.cameraName) ?? 0) + 1);
+    }
+    const baseLabel = (camera) => (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();
+    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();
+    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) => {
+        const label = baseLabel(camera);
+        const ordinal = ordinals.get(camera.flightId);
+        return ordinal === undefined ? label : `${label} #${ordinal}`;
+    };
+}

package/dist/context.d.ts

@@ -0,0 +1,34 @@
+import type { KerbcastClient } from "@ksp-gonogo/kerbcast";
+import { type ReactNode } from "react";
+/**
+ * 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 declare function createClientSubscriptions(client: KerbcastClient): KerbcastSubscriptions;
+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 declare function KerbcastProvider({ client, subscriptions: subscriptionsProp, children, }: KerbcastProviderProps): React.JSX.Element;
+/**
+ * Return the `KerbcastClient` from the nearest `KerbcastProvider`.
+ * Throws if called outside a provider.
+ */
+export declare function useKerbcastClient(): KerbcastClient;
+/**
+ * Return the `KerbcastSubscriptions` from the nearest `KerbcastProvider`.
+ * Throws if called outside a provider.
+ */
+export declare function useKerbcastSubscriptions(): KerbcastSubscriptions;

package/dist/context.js

@@ -0,0 +1,70 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext, useMemo, useRef, } from "react";
+/** Build the default refcounted subscriptions implementation for a client. */
+export function createClientSubscriptions(client) {
+    const refcounts = new Map();
+    return {
+        acquire(flightId) {
+            const count = (refcounts.get(flightId) ?? 0) + 1;
+            refcounts.set(flightId, count);
+            if (count === 1) {
+                client.subscribe(flightId).catch(() => { });
+            }
+        },
+        release(flightId) {
+            const count = (refcounts.get(flightId) ?? 1) - 1;
+            if (count <= 0) {
+                refcounts.delete(flightId);
+                client.unsubscribe(flightId).catch(() => { });
+            }
+            else {
+                refcounts.set(flightId, count);
+            }
+        },
+    };
+}
+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, }) {
+    // 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);
+    }
+    const value = useMemo(() => ({
+        client,
+        subscriptions: subscriptionsProp ?? defaultSubsRef.current,
+    }), 
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [client, subscriptionsProp]);
+    return (_jsx(KerbcastContext.Provider, { value: value, children: children }));
+}
+// ---------------------------------------------------------------------------
+// Hooks
+// ---------------------------------------------------------------------------
+/**
+ * Return the `KerbcastClient` from the nearest `KerbcastProvider`.
+ * Throws if called outside a provider.
+ */
+export function useKerbcastClient() {
+    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() {
+    const ctx = useContext(KerbcastContext);
+    if (!ctx) {
+        throw new Error("useKerbcastSubscriptions must be used inside a KerbcastProvider");
+    }
+    return ctx.subscriptions;
+}

package/dist/hooks/useKerbcamCameras.d.ts

@@ -0,0 +1,8 @@
+import type { CameraState } from "@jonpepler/kerbcam";
+/**
+ * Live snapshot of the kerbcam camera registry. Returns the empty list
+ * before the data channel handshake completes (and after a disconnect).
+ * Subscribes via the underlying `KerbcamClient`'s `cameras-change` event for
+ * one synchronous push per server-side snapshot or state-changed message.
+ */
+export declare function useKerbcamCameras(): CameraState[];

package/dist/hooks/useKerbcamCameras.js

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

package/dist/hooks/useKerbcamStream.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Live `MediaStream` for one kerbcam 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 `KerbcamSubscriptions`. Releases the slot when the component
+ * unmounts or the `flightId` changes.
+ */
+export declare function useKerbcamStream(flightId: number | null): MediaStream | null;

package/dist/hooks/useKerbcamStream.js

@@ -0,0 +1,35 @@
+import { useEffect, useState } from "react";
+import { useKerbcamClient, useKerbcamSubscriptions } from "../context";
+/**
+ * Live `MediaStream` for one kerbcam 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 `KerbcamSubscriptions`. Releases the slot when the component
+ * unmounts or the `flightId` changes.
+ */
+export function useKerbcamStream(flightId) {
+    const client = useKerbcamClient();
+    const subscriptions = useKerbcamSubscriptions();
+    const [stream, setStream] = useState(() => {
+        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/dist/hooks/useKerbcastCameras.d.ts

@@ -0,0 +1,8 @@
+import type { CameraState } from "@ksp-gonogo/kerbcast";
+/**
+ * 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 declare function useKerbcastCameras(): CameraState[];

package/dist/hooks/useKerbcastCameras.js

@@ -0,0 +1,19 @@
+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() {
+    const client = useKerbcastClient();
+    const [cameras, setCameras] = useState(() => [
+        ...client.cameras,
+    ]);
+    useEffect(() => {
+        setCameras([...client.cameras]);
+        return client.on("cameras-change", (next) => setCameras([...next]));
+    }, [client]);
+    return cameras;
+}

package/dist/hooks/useKerbcastClock.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 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 declare function useKerbcastClock(): {
+    captureUt: number | null;
+    epoch: number;
+    warpRate: number;
+};

package/dist/hooks/useKerbcastClock.js

@@ -0,0 +1,26 @@
+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() {
+    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/dist/hooks/useKerbcastStream.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 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 declare function useKerbcastStream(flightId: number | null): MediaStream | null;

package/dist/hooks/useKerbcastStream.js

@@ -0,0 +1,35 @@
+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) {
+    const client = useKerbcastClient();
+    const subscriptions = useKerbcastSubscriptions();
+    const [stream, setStream] = useState(() => {
+        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/dist/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @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.
+ */
+export { KerbcastProvider, createClientSubscriptions, useKerbcastClient, useKerbcastSubscriptions, } from "./context";
+export type { KerbcastProviderProps, KerbcastSubscriptions } from "./context";
+export { useKerbcastCameras } from "./hooks/useKerbcastCameras";
+export { useKerbcastStream } from "./hooks/useKerbcastStream";
+export { useKerbcastClock } from "./hooks/useKerbcastClock";
+export { buildCameraLabeler } from "./cameraLabels";
+export type { LabelableCamera } from "./cameraLabels";
+export { getCameraLifecycle, isCameraDestroyed } from "./lifecycle";
+export type { CameraLifecycle } from "./lifecycle";
+export { CameraFeed } from "./CameraFeed";
+export type { CameraFeedHandle, CameraFeedProps, CameraStreamHook, FeedAction, } from "./CameraFeed";

package/dist/index.js

@@ -0,0 +1,19 @@
+/**
+ * @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";
+// Hooks
+export { useKerbcastCameras } from "./hooks/useKerbcastCameras";
+export { useKerbcastStream } from "./hooks/useKerbcastStream";
+export { useKerbcastClock } from "./hooks/useKerbcastClock";
+// Camera label utilities
+export { buildCameraLabeler } from "./cameraLabels";
+// Lifecycle utilities
+export { getCameraLifecycle, isCameraDestroyed } from "./lifecycle";
+// CameraFeed component
+export { CameraFeed } from "./CameraFeed";

package/dist/lifecycle.d.ts

@@ -0,0 +1,5 @@
+import type { CameraState } from "@ksp-gonogo/kerbcast";
+import { CameraLifecycle } from "@ksp-gonogo/kerbcast";
+export type { CameraLifecycle };
+export declare function getCameraLifecycle(cam: CameraState): CameraLifecycle;
+export declare function isCameraDestroyed(cam: CameraState): boolean;

package/dist/lifecycle.js

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

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@ksp-gonogo/kerbcast-react",
+  "version": "1.4.0",
+  "description": "React components and hooks for kerbcast camera feeds.",
+  "license": "CC-BY-NC-SA-4.0",
+  "author": "Jon Pepler",
+  "homepage": "https://github.com/ksp-gonogo/kerbcast#readme",
+  "bugs": {
+    "url": "https://github.com/ksp-gonogo/kerbcast/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ksp-gonogo/kerbcast.git",
+    "directory": "client-sdk/react"
+  },
+  "keywords": [
+    "kerbcast",
+    "ksp",
+    "kerbal-space-program",
+    "webrtc",
+    "react",
+    "camera"
+  ],
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist/",
+    "src/",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@ksp-gonogo/kerbcast": "^1.4.0"
+  },
+  "peerDependencies": {
+    "react": "^18 || ^19",
+    "react-dom": "^18 || ^19",
+    "styled-components": "^6"
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.3.2",
+    "@testing-library/user-event": "^14.0.0",
+    "@types/react": "^18.3.28",
+    "@types/react-dom": "^18.3.0",
+    "@vitest/coverage-v8": "^4.1.4",
+    "jsdom": "^29.0.2",
+    "react": "^18.0.0",
+    "react-dom": "^18.0.0",
+    "styled-components": "^6.0.0",
+    "typescript": "^5.4.0",
+    "vitest": "^4.1.4"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}