@ksp-gonogo/kerbcast-react 1.10.2 → 1.11.0-rc.4

package/dist/hooks/useDisplayedFrameUt.d.ts

@@ -0,0 +1,11 @@
+import type { DisplayedFrameUt } from "@ksp-gonogo/kerbcast";
+/**
+ * Mission time of the frame `video` is showing for camera `flightId`,
+ * updated on every presented frame (so the calling component re-renders at
+ * the video's frame rate). `source` says whether the UT is the frame's own
+ * capture stamp (`"exact"`) or the capture clock extrapolated
+ * (`"estimated"`). `null` until the first frame with a known UT, and while
+ * either argument is null. For per-frame work without re-rendering, use
+ * `client.watchDisplayedFrames` directly.
+ */
+export declare function useDisplayedFrameUt(flightId: number | null, video: HTMLVideoElement | null): DisplayedFrameUt | null;

package/dist/hooks/useDisplayedFrameUt.js

@@ -0,0 +1,22 @@
+import { useEffect, useState } from "react";
+import { useKerbcastClient } from "../context";
+/**
+ * Mission time of the frame `video` is showing for camera `flightId`,
+ * updated on every presented frame (so the calling component re-renders at
+ * the video's frame rate). `source` says whether the UT is the frame's own
+ * capture stamp (`"exact"`) or the capture clock extrapolated
+ * (`"estimated"`). `null` until the first frame with a known UT, and while
+ * either argument is null. For per-frame work without re-rendering, use
+ * `client.watchDisplayedFrames` directly.
+ */
+export function useDisplayedFrameUt(flightId, video) {
+    const client = useKerbcastClient();
+    const [frame, setFrame] = useState(null);
+    useEffect(() => {
+        setFrame(null);
+        if (flightId === null || !video)
+            return;
+        return client.watchDisplayedFrames(flightId, video, setFrame);
+    }, [client, flightId, video]);
+    return frame;
+}

package/dist/hooks/useReportDisplaySize.d.ts

@@ -1,3 +1,8 @@
+/** Report size for a `width` x `height` box: bucketed width, height at the box's aspect. */
+export declare function displayReportSize(width: number, height: number): {
+    width: number;
+    height: number;
+};
 export interface ReportDisplaySizeOptions {
     /**
      * Report while mounted. Default true. Set false for a fixed-resolution feed

package/dist/hooks/useReportDisplaySize.js

@@ -3,10 +3,12 @@ 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.
+ * resolution until it is resized); later churn is debounced. The width is
+ * ceiled to a BUCKET_PX multiple: that meets-the-minimum-need (never
+ * under-serve) and gives a material-change threshold so a feed re-reports
+ * only when a resize crosses a bucket boundary. The height follows from the
+ * box's own aspect, rounded to even for H.264, so the frame fills the box
+ * instead of letterboxing inside it.
  */
 const DEBOUNCE_MS = 200;
 const BUCKET_PX = 16;
@@ -14,6 +16,14 @@ function bucket(px) {
     const b = Math.ceil(px / BUCKET_PX) * BUCKET_PX;
     return b < BUCKET_PX ? BUCKET_PX : b;
 }
+/** Report size for a `width` x `height` box: bucketed width, height at the box's aspect. */
+export function displayReportSize(width, height) {
+    const w = bucket(width);
+    if (!(width > 0) || !(height > 0))
+        return { width: w, height: bucket(height) };
+    const h = Math.max(2, Math.round((w * height) / width / 2) * 2);
+    return { width: w, height: h };
+}
 /**
  * Self-measure a feed element and drive the client's per-consumer
  * `reportDisplaySize` (via the context display-size registry, which collapses
@@ -48,9 +58,10 @@ export function useReportDisplaySize(flightId, ref, { enabled = true, square = f
         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);
+            const side = bucket(Math.min(width, height));
+            const { width: bw, height: bh } = square
+                ? { width: side, height: side }
+                : displayReportSize(width, height);
             if (bw === lastW && bh === lastH)
                 return;
             lastW = bw;

package/dist/hooks/useTargetBracketsPreference.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Whether target brackets are shown for one command camera, remembered per
+ * camera in this browser. Defaults on. `key` is null for a feed with no
+ * command camera, which reads as on and ignores toggles.
+ */
+export declare function useTargetBracketsPreference(key: string | null): [boolean, () => void];

package/dist/hooks/useTargetBracketsPreference.js

@@ -0,0 +1,39 @@
+import { useCallback, useMemo, useState } from "react";
+const STORAGE_PREFIX = "kerbcast:target-brackets:";
+function readPreference(key) {
+    try {
+        return globalThis.localStorage?.getItem(STORAGE_PREFIX + key) !== "0";
+    }
+    catch {
+        return true;
+    }
+}
+function writePreference(key, on) {
+    try {
+        if (on)
+            globalThis.localStorage?.removeItem(STORAGE_PREFIX + key);
+        else
+            globalThis.localStorage?.setItem(STORAGE_PREFIX + key, "0");
+    }
+    catch {
+        /* Storage blocked or full: the toggle still works for this session. */
+    }
+}
+/**
+ * Whether target brackets are shown for one command camera, remembered per
+ * camera in this browser. Defaults on. `key` is null for a feed with no
+ * command camera, which reads as on and ignores toggles.
+ */
+export function useTargetBracketsPreference(key) {
+    const [overrides, setOverrides] = useState({});
+    const stored = useMemo(() => (key === null ? true : readPreference(key)), [key]);
+    const on = key !== null && key in overrides ? overrides[key] : stored;
+    const toggle = useCallback(() => {
+        if (key === null)
+            return;
+        const next = !on;
+        writePreference(key, next);
+        setOverrides((o) => ({ ...o, [key]: next }));
+    }, [key, on]);
+    return [on, toggle];
+}

package/dist/index.d.ts

@@ -10,6 +10,7 @@ export type { KerbcastProviderProps, KerbcastSubscriptions, KerbcastDisplaySizes
 export { useKerbcastCameras } from "./hooks/useKerbcastCameras";
 export { useKerbcastStream } from "./hooks/useKerbcastStream";
 export { useKerbcastClock } from "./hooks/useKerbcastClock";
+export { useDisplayedFrameUt } from "./hooks/useDisplayedFrameUt";
 export { useKerbcastInFlight } from "./hooks/useKerbcastInFlight";
 export { useReportDisplaySize } from "./hooks/useReportDisplaySize";
 export { useRecordings } from "./hooks/useRecordings";
@@ -22,6 +23,8 @@ export { getCameraLifecycle, isCameraDestroyed } from "./lifecycle";
 export type { CameraLifecycle } from "./lifecycle";
 export { CameraFeed } from "./CameraFeed";
 export type { CameraFeedHandle, CameraFeedProps, CameraStreamHook, FeedAction, } from "./CameraFeed";
+export { bracketGeometry, containedContentRect, COMMAND_BRACKET_COLOURS } from "./CommandBrackets";
+export type { BracketGeometry, BracketPoint, CommandBracketContext, CommandBracketCorner, CommandBracketCornerOverride, CommandBracketCornerOverrides, CommandBracketCornerStyle, CommandBracketOverlay, ContentRect, } from "./CommandBrackets";
 export { FeedActionBar } from "./FeedActionBar";
 export type { FeedActionBarEntry } from "./FeedActionBar";
 export { KerbalFaceFeed } from "./KerbalFaceFeed";

package/dist/index.js

@@ -11,6 +11,7 @@ export { KerbcastProvider, createClientSubscriptions, createClientDisplaySizes,
 export { useKerbcastCameras } from "./hooks/useKerbcastCameras";
 export { useKerbcastStream } from "./hooks/useKerbcastStream";
 export { useKerbcastClock } from "./hooks/useKerbcastClock";
+export { useDisplayedFrameUt } from "./hooks/useDisplayedFrameUt";
 export { useKerbcastInFlight } from "./hooks/useKerbcastInFlight";
 export { useReportDisplaySize } from "./hooks/useReportDisplaySize";
 export { useRecordings } from "./hooks/useRecordings";
@@ -24,6 +25,8 @@ export { buildCameraLabeler } from "./cameraLabels";
 export { getCameraLifecycle, isCameraDestroyed } from "./lifecycle";
 // CameraFeed component
 export { CameraFeed } from "./CameraFeed";
+// Target brackets geometry and the overlay API for drawing on top of them
+export { bracketGeometry, containedContentRect, COMMAND_BRACKET_COLOURS } from "./CommandBrackets";
 // FeedActionBar: the shared action row (tracking, fullscreen, PiP, quality,
 // close, REC) both CameraFeed and KerbalFaceFeed render, with the issue-#6
 // overflow (⋮) engine.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ksp-gonogo/kerbcast-react",
-  "version": "1.10.2",
+  "version": "1.11.0-rc.4",
   "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.10.2"
+    "@ksp-gonogo/kerbcast": "^1.11.0-rc.4"
   },
   "peerDependencies": {
     "react": "^18 || ^19",

package/src/CameraFeed.test.tsx

@@ -22,8 +22,19 @@
  *  - Station (brokered) mode -- gonogo-only KerbcastDataSource.attachBroker.
  */
 
-import { KerbcastClient, QualityPreset, TrackMode } from "@ksp-gonogo/kerbcast";
-import type { CameraLifecycle, ClientMessage } from "@ksp-gonogo/kerbcast";
+import {
+  CameraKind,
+  CommandTargetEligibility,
+  KerbcastClient,
+  QualityPreset,
+  TrackMode,
+} from "@ksp-gonogo/kerbcast";
+import type {
+  CameraLifecycle,
+  ClientMessage,
+  CommandCentreInfo,
+  CommandTrackState,
+} from "@ksp-gonogo/kerbcast";
 import { type MockCameraInit, MockSidecar } from "@ksp-gonogo/kerbcast/testing";
 import {
   act,
@@ -39,6 +50,7 @@ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import {
   CameraFeed,
   type CameraFeedHandle,
+  type CameraFeedProps,
   type CameraStreamHook,
   type FeedAction,
 } from "./CameraFeed";
@@ -225,6 +237,9 @@ function toInit(c: CameraStateLike): MockCameraInit {
     viewerQuality: c.viewerQuality as QualityPreset | undefined,
     qualityLimitedBy: c.qualityLimitedBy as string | undefined,
     trackMode: c.trackMode as TrackMode | undefined,
+    kind: c.kind as CameraKind | undefined,
+    commandCentre: c.commandCentre as CommandCentreInfo | undefined,
+    commandTrack: c.commandTrack as CommandTrackState | undefined,
   };
 }
 
@@ -282,6 +297,9 @@ function renderFeed(
     showStatic?: boolean;
     showStandbyIcon?: boolean;
     showActions?: boolean;
+    enableTargetBrackets?: boolean;
+    targetBracketOverlay?: CameraFeedProps["targetBracketOverlay"];
+    displayUt?: number;
     ref?: React.Ref<CameraFeedHandle>;
   },
 ) {
@@ -2483,3 +2501,274 @@ describe("CameraFeed - recording locks source and close", () => {
     expect(onClose).toHaveBeenCalledTimes(1);
   });
 });
+
+// ---------------------------------------------------------------------------
+// Command camera target brackets
+// ---------------------------------------------------------------------------
+
+describe("CameraFeed - command camera target brackets", () => {
+  const STATION: CommandCentreInfo = {
+    stationId: "ground:KSC",
+    nodeName: "KSC",
+    displayName: "Kerbal Space Center",
+    body: "Kerbin",
+    latitude: -0.1,
+    longitude: -74.6,
+    altitude: 95,
+    subjectPersistentId: 0,
+    trackingLevel: 3,
+    targets: [],
+  };
+
+  function commandTrack(overrides: Partial<CommandTrackState> = {}): CommandTrackState {
+    return {
+      ut: 1000,
+      hasFix: true,
+      rangeM: 11_507_905,
+      occluded: false,
+      occluder: "",
+      sunlit: true,
+      bracketHalfPx: 4,
+      frameHeightPx: 576,
+      framingFits: true,
+      events: [],
+      ...overrides,
+    };
+  }
+
+  function commandCamera(track: CommandTrackState | undefined = commandTrack()) {
+    return makeCamera({
+      flightId: 301,
+      kind: CameraKind.Command,
+      cameraName: "KSC tracking",
+      commandCentre: STATION,
+      commandTrack: track,
+    });
+  }
+
+  beforeEach(() => localStorage.clear());
+
+  it("shows the brackets readout and a pressed toggle on a command feed", async () => {
+    const { client } = await buildConnectedSource([commandCamera()]);
+    renderFeed(client, { flightId: 301 });
+    expect(screen.getByText("IN VIEW · 11,508 km")).toBeTruthy();
+    expect(
+      screen.getByRole("button", { name: "Target brackets" }).getAttribute("aria-pressed"),
+    ).toBe("true");
+  });
+
+  it("offers no toggle on a part feed", async () => {
+    const { client } = await buildConnectedSource();
+    renderFeed(client, { flightId: 42 });
+    expect(screen.queryByRole("button", { name: "Target brackets" })).toBeNull();
+  });
+
+  it("hides the brackets when toggled off and remembers it per camera", async () => {
+    const { client } = await buildConnectedSource([commandCamera()]);
+    const first = renderFeed(client, { flightId: 301 });
+    fireEvent.click(screen.getByRole("button", { name: "Target brackets" }));
+    expect(screen.queryByText("IN VIEW · 11,508 km")).toBeNull();
+    expect(localStorage.getItem("kerbcast:target-brackets:ground:KSC")).toBe("0");
+    first.unmount();
+
+    renderFeed(client, { flightId: 301 });
+    expect(screen.queryByText("IN VIEW · 11,508 km")).toBeNull();
+    expect(
+      screen.getByRole("button", { name: "Target brackets" }).getAttribute("aria-pressed"),
+    ).toBe("false");
+  });
+
+  it("still labels a blanked feed with the brackets toggled off", async () => {
+    localStorage.setItem("kerbcast:target-brackets:ground:KSC", "0");
+    const { client, sidecar } = await buildConnectedSource([commandCamera()]);
+    renderFeed(client, { flightId: 301 });
+    expect(screen.queryByRole("status", { name: "Feed blanked" })).toBeNull();
+    await act(async () => {
+      sidecar.updateCamera(301, { commandTrack: commandTrack({ blank: "Waiting for gonogo" }) });
+    });
+    expect(screen.getByRole("status", { name: "Feed blanked" }).textContent).toBe(
+      "Waiting for gonogo",
+    );
+  });
+
+  it("shows the transition in force at the displayed UT", async () => {
+    const track = commandTrack({
+      authority: { owner: "gonogo" },
+      events: [
+        { ut: 990, occluded: true, occluder: "Mun", sunlit: true },
+        { ut: 999, occluded: false, occluder: "", sunlit: true },
+      ],
+    });
+    const { client } = await buildConnectedSource([commandCamera(track)]);
+    const view = renderFeed(client, { flightId: 301, displayUt: 995 });
+    expect(screen.getByText("OCCLUDED MUN · 11,508 km")).toBeTruthy();
+    view.rerender(
+      <KerbcastProvider client={client}>
+        <CameraFeed flightId={301} displayUt={999.5} />
+      </KerbcastProvider>,
+    );
+    expect(screen.getByText("IN VIEW · 11,508 km")).toBeTruthy();
+  });
+
+  it("passes the target bracket overlay through to the brackets", async () => {
+    const { client } = await buildConnectedSource([commandCamera()]);
+    const seenUts: number[] = [];
+    const { container } = renderFeed(client, {
+      flightId: 301,
+      displayUt: 1060,
+      targetBracketOverlay: {
+        render: (ctx) => {
+          seenUts.push(ctx.displayUt);
+          return <circle data-testid="overlay-mark" cx={ctx.geometry.cx} cy={ctx.geometry.cy} r={2} />;
+        },
+        corners: { bottomRight: { hidden: true } },
+        readout: (text, ctx) => `${text} · T+${ctx.displayUt}`,
+      },
+    });
+    expect(screen.getByTestId("overlay-mark")).toBeTruthy();
+    expect(seenUts).toContain(1060);
+    expect(container.querySelector('path[data-corner="bottomRight"]')).toBeNull();
+    expect(container.querySelector('path[data-corner="topLeft"]')).not.toBeNull();
+    expect(screen.getByText(/ · T\+1060$/)).toBeTruthy();
+  });
+
+  describe("target picker", () => {
+    const TARGETS: CommandCentreInfo = {
+      ...STATION,
+      subjectPersistentId: 11,
+      rangeM: 12_300,
+      trackingLevel: 1,
+      targets: [
+        {
+          persistentId: 11,
+          vesselName: "Kerbal X",
+          vesselType: "Ship",
+          rangeM: 12_300,
+          eligibility: CommandTargetEligibility.Ok,
+          eligibilityText: "Trackable",
+        },
+        {
+          persistentId: 22,
+          vesselName: "Relay 1",
+          vesselType: "Relay",
+          rangeM: 1_500_000,
+          eligibility: CommandTargetEligibility.Ok,
+          eligibilityText: "Trackable",
+        },
+        {
+          persistentId: 33,
+          vesselName: "Ast. HSJ-227",
+          vesselType: "SpaceObject",
+          eligibility: CommandTargetEligibility.LevelTooLow,
+          eligibilityText: "Upgrade the Tracking Station",
+        },
+      ],
+    };
+
+    function targetCamera() {
+      return makeCamera({
+        flightId: 301,
+        kind: CameraKind.Command,
+        cameraName: "KSC tracking",
+        commandCentre: TARGETS,
+        commandTrack: commandTrack(),
+      });
+    }
+
+    it("lists targets, marks the current one and disables ineligible ones", async () => {
+      const { client } = await buildConnectedSource([targetCamera()]);
+      renderFeed(client, { flightId: 301 });
+      const trigger = screen.getByRole("button", { name: "Choose target" });
+      expect(trigger.getAttribute("title")).toBe("Watching Kerbal X");
+      fireEvent.click(trigger);
+      const items = screen.getAllByRole("menuitemradio");
+      expect(items.map((i) => i.textContent)).toEqual([
+        "Kerbal X · 12 km",
+        "Relay 1 · 1,500 km",
+        "Ast. HSJ-227 · Upgrade the Tracking Station",
+      ]);
+      expect(items[0]!.getAttribute("aria-checked")).toBe("true");
+      expect(items[1]!.getAttribute("aria-checked")).toBe("false");
+      expect((items[2] as HTMLButtonElement).disabled).toBe(true);
+      expect(items[2]!.getAttribute("title")).toBe("Upgrade the Tracking Station");
+    });
+
+    it("keeps the quality menu reachable when the row overflows", async () => {
+      const { client } = await buildConnectedSource([targetCamera()]);
+      renderFeed(client, {
+        flightId: 301,
+        enableQualityControl: true,
+        enableFullscreen: true,
+        enablePictureInPicture: true,
+        actions: [
+          { id: "a", label: "Extra A", icon: null, onClick: () => {} },
+          { id: "b", label: "Extra B", icon: null, onClick: () => {} },
+        ],
+      });
+      fireEvent.click(screen.getByRole("button", { name: /quality/i }));
+      expect(screen.getByRole("menu", { name: "Quality" })).toBeTruthy();
+    });
+
+    it("keeps the target menu reachable when the row overflows", async () => {
+      const { client } = await buildConnectedSource([targetCamera()]);
+      renderFeed(client, {
+        flightId: 301,
+        enableFullscreen: true,
+        enablePictureInPicture: true,
+        actions: [
+          { id: "a", label: "Extra A", icon: null, onClick: () => {} },
+          { id: "b", label: "Extra B", icon: null, onClick: () => {} },
+        ],
+      });
+      fireEvent.click(screen.getByRole("button", { name: "Choose target" }));
+      expect(screen.getAllByRole("menuitemradio")).toHaveLength(3);
+    });
+
+    it("sends the choice and follows the published target", async () => {
+      const { client, sidecar } = await buildConnectedSource([targetCamera()]);
+      renderFeed(client, { flightId: 301 });
+      fireEvent.click(screen.getByRole("button", { name: "Choose target" }));
+      await act(async () => {
+        fireEvent.click(screen.getByRole("menuitemradio", { name: /Relay 1/ }));
+      });
+      expect(sidecar.lastCommand("set-command-aim", 301)?.content).toEqual({
+        flightId: 301,
+        aim: { kind: "vessel", persistentId: 22 },
+      });
+      expect(
+        screen.getByRole("button", { name: "Choose target" }).getAttribute("title"),
+      ).toBe("Watching Relay 1");
+    });
+
+    it("is hidden with no targets, with manual controls disabled or under the lock", async () => {
+      const { client } = await buildConnectedSource([targetCamera()]);
+      const view = renderFeed(client, { flightId: 301, disableManualControls: true });
+      expect(screen.queryByRole("button", { name: "Choose target" })).toBeNull();
+      view.unmount();
+
+      const locked = await buildConnectedSource([
+        makeCamera({
+          flightId: 301,
+          kind: CameraKind.Command,
+          cameraName: "KSC tracking",
+          commandCentre: TARGETS,
+          commandTrack: commandTrack({ authority: { owner: "gonogo" } }),
+        }),
+      ]);
+      const lockedView = renderFeed(locked.client, { flightId: 301 });
+      expect(screen.queryByRole("button", { name: "Choose target" })).toBeNull();
+      lockedView.unmount();
+
+      const empty = await buildConnectedSource([commandCamera()]);
+      renderFeed(empty.client, { flightId: 301 });
+      expect(screen.queryByRole("button", { name: "Choose target" })).toBeNull();
+    });
+  });
+
+  it("draws nothing with enableTargetBrackets off", async () => {
+    const { client } = await buildConnectedSource([commandCamera()]);
+    renderFeed(client, { flightId: 301, enableTargetBrackets: false });
+    expect(screen.queryByText("IN VIEW · 11,508 km")).toBeNull();
+    expect(screen.queryByRole("button", { name: "Target brackets" })).toBeNull();
+  });
+});