@ksp-gonogo/kerbcast-react 1.11.0 → 1.12.0-rc.1

package/dist/index.d.ts

@@ -12,6 +12,7 @@ export { useKerbcastStream } from "./hooks/useKerbcastStream";
 export { useKerbcastClock } from "./hooks/useKerbcastClock";
 export { useDisplayedFrameUt } from "./hooks/useDisplayedFrameUt";
 export { useKerbcastInFlight } from "./hooks/useKerbcastInFlight";
+export { useKerbcastWaitingForSlot } from "./hooks/useKerbcastWaitingForSlot";
 export { useReportDisplaySize } from "./hooks/useReportDisplaySize";
 export { useRecordings } from "./hooks/useRecordings";
 export type { RecordingsStore, ActiveRecordingInfo } from "./hooks/useRecordings";
@@ -25,9 +26,11 @@ 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 { AnchorMarkers, ANCHOR_MARKER_COLOURS, anchorMarkerGeometry, useDisplayedFrame, } from "./AnchorMarkers";
+export type { AnchorContext, AnchorCorner, AnchorCornerOverride, AnchorCornerOverrides, AnchorCornerStyle, AnchorMarkerGeometry, AnchorMarkerShape, AnchorMarkersProps, AnchorOverlay, PlacedAnchor, } from "./AnchorMarkers";
 export { FeedActionBar } from "./FeedActionBar";
 export type { FeedActionBarEntry } from "./FeedActionBar";
 export { KerbalFaceFeed } from "./KerbalFaceFeed";
 export type { KerbalFaceFeedProps, KerbalFeedState } from "./KerbalFaceFeed";
-export { RecordingsTray } from "./RecordingsTray";
+export { RecordingsTray, recordingEndNote } from "./RecordingsTray";
 export type { RecordingsTrayProps } from "./RecordingsTray";

package/dist/index.js

@@ -13,6 +13,7 @@ export { useKerbcastStream } from "./hooks/useKerbcastStream";
 export { useKerbcastClock } from "./hooks/useKerbcastClock";
 export { useDisplayedFrameUt } from "./hooks/useDisplayedFrameUt";
 export { useKerbcastInFlight } from "./hooks/useKerbcastInFlight";
+export { useKerbcastWaitingForSlot } from "./hooks/useKerbcastWaitingForSlot";
 export { useReportDisplaySize } from "./hooks/useReportDisplaySize";
 export { useRecordings } from "./hooks/useRecordings";
 // Shared elapsed-timer helpers (REC badges, RecGroupBar's toolbar)
@@ -27,6 +28,9 @@ export { getCameraLifecycle, isCameraDestroyed } from "./lifecycle";
 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";
+// Anchored markers: CameraFeed's `anchors` and `anchorOverlay`, and the
+// pieces for drawing a frame's anchors over a video of your own
+export { AnchorMarkers, ANCHOR_MARKER_COLOURS, anchorMarkerGeometry, useDisplayedFrame, } from "./AnchorMarkers";
 // FeedActionBar: the shared action row (tracking, fullscreen, PiP, quality,
 // close, REC) both CameraFeed and KerbalFaceFeed render, with the issue-#6
 // overflow (⋮) engine.
@@ -34,4 +38,4 @@ export { FeedActionBar } from "./FeedActionBar";
 // KerbalFaceFeed — shared single-kerbal-face primitive
 export { KerbalFaceFeed } from "./KerbalFaceFeed";
 // RecordingsTray: a presentational drawer over the recordings store
-export { RecordingsTray } from "./RecordingsTray";
+export { RecordingsTray, recordingEndNote } from "./RecordingsTray";

package/dist/sharedAnchors.d.ts

@@ -0,0 +1,3 @@
+import type { Anchor, KerbcastClient } from "@ksp-gonogo/kerbcast";
+/** Add `anchors` to `flightId`'s set until the returned release is called. */
+export declare function claimAnchors(client: KerbcastClient, flightId: number, anchors: readonly Anchor[]): () => void;

package/dist/sharedAnchors.js

@@ -0,0 +1,61 @@
+/**
+ * A client holds one anchor set per camera, so feeds showing the same
+ * camera each claim their anchors here and the camera gets them all: the
+ * first claim of an id wins, and the set stops at the client's cap.
+ */
+const claims = new WeakMap();
+/** Add `anchors` to `flightId`'s set until the returned release is called. */
+export function claimAnchors(client, flightId, anchors) {
+    let byFlight = claims.get(client);
+    if (!byFlight) {
+        byFlight = new Map();
+        claims.set(client, byFlight);
+    }
+    let feeds = byFlight.get(flightId);
+    if (!feeds) {
+        feeds = new Map();
+        byFlight.set(flightId, feeds);
+    }
+    const token = Symbol("anchors");
+    feeds.set(token, anchors);
+    publish(client, flightId, feeds);
+    return () => {
+        if (!feeds.delete(token))
+            return;
+        if (feeds.size === 0)
+            byFlight.delete(flightId);
+        publish(client, flightId, feeds);
+    };
+}
+function publish(client, flightId, feeds) {
+    const ids = new Map();
+    const merged = [];
+    let dropped = 0;
+    for (const list of feeds.values()) {
+        for (const a of list) {
+            const seen = ids.get(a.id);
+            if (seen !== undefined) {
+                if (seen !== JSON.stringify(a)) {
+                    console.warn(`[kerbcast] two feeds on camera ${flightId} set different anchors with id ${a.id}; the first is kept`);
+                }
+                continue;
+            }
+            if (merged.length >= client.maxAnchorsPerCamera) {
+                dropped++;
+                continue;
+            }
+            ids.set(a.id, JSON.stringify(a));
+            merged.push(a);
+        }
+    }
+    if (dropped > 0) {
+        console.warn(`[kerbcast] ${dropped} anchors over the ${client.maxAnchorsPerCamera} per camera left out`);
+    }
+    if (merged.length === 0) {
+        void client.setAnchors(flightId, null).catch(() => { });
+        return;
+    }
+    client.setAnchors(flightId, merged).catch((err) => {
+        console.warn("[kerbcast] anchors refused", err);
+    });
+}

package/dist/videoBox.d.ts

@@ -0,0 +1,10 @@
+export interface VideoBox {
+    boxW: number;
+    boxH: number;
+    mediaW: number;
+    mediaH: number;
+}
+/** Tracks the rendered box and intrinsic size of a video element. */
+export declare function useVideoBox(video: HTMLVideoElement | null): VideoBox;
+/** The element's CSS `object-fit`, as the two fits a feed uses. */
+export declare function videoFit(video: HTMLVideoElement | null): "contain" | "cover";

package/dist/videoBox.js

@@ -0,0 +1,40 @@
+import { useEffect, useState } from "react";
+/** Tracks the rendered box and intrinsic size of a video element. */
+export function useVideoBox(video) {
+    const [box, setBox] = useState({ boxW: 0, boxH: 0, mediaW: 0, mediaH: 0 });
+    useEffect(() => {
+        if (!video)
+            return;
+        const measure = () => {
+            const next = {
+                boxW: video.clientWidth,
+                boxH: video.clientHeight,
+                mediaW: video.videoWidth,
+                mediaH: video.videoHeight,
+            };
+            setBox((prev) => prev.boxW === next.boxW &&
+                prev.boxH === next.boxH &&
+                prev.mediaW === next.mediaW &&
+                prev.mediaH === next.mediaH
+                ? prev
+                : next);
+        };
+        measure();
+        const observer = new ResizeObserver(measure);
+        observer.observe(video);
+        video.addEventListener("loadedmetadata", measure);
+        video.addEventListener("resize", measure);
+        return () => {
+            observer.disconnect();
+            video.removeEventListener("loadedmetadata", measure);
+            video.removeEventListener("resize", measure);
+        };
+    }, [video]);
+    return box;
+}
+/** The element's CSS `object-fit`, as the two fits a feed uses. */
+export function videoFit(video) {
+    if (!video || typeof getComputedStyle !== "function")
+        return "contain";
+    return getComputedStyle(video).objectFit === "cover" ? "cover" : "contain";
+}

package/package.json

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

package/src/AnchorMarkers.test.tsx

@@ -0,0 +1,173 @@
+import type { DisplayedFrameUt, FrameAnchor } from "@ksp-gonogo/kerbcast";
+import { cleanup, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it } from "vitest";
+import {
+  ANCHOR_MARKER_COLOURS,
+  AnchorMarkers,
+  anchorMarkerGeometry,
+  type AnchorContext,
+  type AnchorOverlay,
+} from "./AnchorMarkers";
+
+afterEach(cleanup);
+
+function sizedVideo(boxW: number, boxH: number, fit?: "cover"): HTMLVideoElement {
+  const v = document.createElement("video");
+  Object.defineProperty(v, "clientWidth", { value: boxW });
+  Object.defineProperty(v, "clientHeight", { value: boxH });
+  Object.defineProperty(v, "videoWidth", { value: 1280 });
+  Object.defineProperty(v, "videoHeight", { value: 720 });
+  if (fit) v.style.objectFit = fit;
+  return v;
+}
+
+function anchor(overrides: Partial<FrameAnchor> = {}): FrameAnchor {
+  return {
+    id: "port",
+    x: 640,
+    y: 360,
+    inFrame: true,
+    behind: false,
+    distanceM: 30,
+    apparentRadiusPx: 40,
+    angleOffAxis: 0.5,
+    ...overrides,
+  };
+}
+
+function frame(anchors: FrameAnchor[]): DisplayedFrameUt {
+  return {
+    ut: 5000,
+    epoch: 1,
+    source: "exact",
+    flightId: 7,
+    rtpTimestamp: 90_000,
+    presentedAt: 0,
+    anchors,
+    fov: 30,
+    frameWidth: 1280,
+    frameHeight: 720,
+  };
+}
+
+function draw(anchors: FrameAnchor[], overlay?: AnchorOverlay, video = sizedVideo(640, 360)) {
+  return render(<AnchorMarkers frame={frame(anchors)} video={video} overlay={overlay} />);
+}
+
+const marks = (c: HTMLElement) => [...c.querySelectorAll("path[data-corner]")] as SVGPathElement[];
+
+describe("anchorMarkerGeometry", () => {
+  it("sizes from the apparent radius on the displayed frame, never below the minimum", () => {
+    const content = { x: 0, y: 0, width: 640, height: 360, scale: 0.5 };
+    expect(anchorMarkerGeometry({ x: 1, y: 2 }, 40, 720, content)).toMatchObject({ cx: 1, cy: 2, half: 20 });
+    expect(anchorMarkerGeometry({ x: 0, y: 0 }, 2, 720, content).half).toBe(14);
+  });
+});
+
+describe("AnchorMarkers", () => {
+  it("draws four solid corner marks around this client's anchor", () => {
+    const { container } = draw([anchor()]);
+    const paths = marks(container);
+    expect(paths.map((p) => p.getAttribute("data-corner"))).toEqual(["top", "right", "bottom", "left"]);
+    expect(paths.every((p) => p.getAttribute("data-shape") === "corners")).toBe(true);
+    expect(paths.every((p) => p.getAttribute("stroke-dasharray") === null)).toBe(true);
+    expect(paths[0].style.stroke).toBe(ANCHOR_MARKER_COLOURS.clear);
+    /* Centre (320, 180) on a half-size display, half 20: the top-left corner starts at (300, 160). */
+    expect(paths[0].getAttribute("d")).toContain("L300 160");
+  });
+
+  it("dashes an occluded anchor in the occluded colour", () => {
+    const { container } = draw([anchor({ occluded: true })]);
+    expect(marks(container).every((p) => p.getAttribute("stroke-dasharray") === "3 2")).toBe(true);
+    expect(marks(container)[0].style.stroke).toBe(ANCHOR_MARKER_COLOURS.occluded);
+  });
+
+  it("draws a direction reticle: triangles coloured per side by the consumer", () => {
+    const seen: AnchorContext[] = [];
+    const { container } = draw([anchor({ forward: [0, 0.1, -1], up: [0, 1, 0] })], {
+      shape: "triangles",
+      corners: (a, ctx) => {
+        seen.push(ctx);
+        const tilted = (a.forward?.[1] ?? 0) > 0.05;
+        return { top: { colour: tilted ? "red" : "lime" }, bottom: { colour: tilted ? "red" : "lime" } };
+      },
+    });
+    const paths = marks(container);
+    expect(paths.every((p) => p.getAttribute("data-shape") === "triangles")).toBe(true);
+    expect(paths[0].style.stroke).toBe("red");
+    expect(paths[0].style.fill).toBe("red");
+    expect(paths[1].style.stroke).toBe(ANCHOR_MARKER_COLOURS.clear);
+    expect(seen[0].geometry.cx).toBe(320);
+    expect(seen[0].displayUt).toBe(5000);
+    expect(seen[0].frame.fov).toBe(30);
+  });
+
+  it("hides a mark and switches the shape of one", () => {
+    const { container } = draw([anchor()], {
+      corners: { right: { hidden: true }, left: { shape: "triangles" } },
+    });
+    const paths = marks(container);
+    expect(paths.map((p) => p.getAttribute("data-corner"))).toEqual(["top", "bottom", "left"]);
+    expect(paths[2].getAttribute("data-shape")).toBe("triangles");
+  });
+
+  it("runs render for an anchor out of frame but leaves its marks out", () => {
+    const { container } = draw([anchor({ inFrame: false, behind: true, x: -500 })], {
+      render: (a, ctx) => <circle data-testid="edge" cx={Math.max(0, ctx.geometry.cx)} r={2} data-id={a.id} />,
+    });
+    expect(marks(container)).toHaveLength(0);
+    expect(screen.getByTestId("edge").getAttribute("data-id")).toBe("port");
+  });
+
+  it("draws only this client's anchors unless an owner is listed", () => {
+    const game = anchor({ id: "reticle", owner: "mission-control" });
+    const subject = anchor({ id: "subject", owner: "kerbcast" });
+    const mine = draw([anchor(), game, subject]);
+    expect(mine.container.querySelectorAll("g[data-anchor]")).toHaveLength(1);
+    cleanup();
+    const withGame = draw([anchor(), game, subject], { owners: ["mission-control"] });
+    const ids = [...withGame.container.querySelectorAll("g[data-anchor]")].map((g) => g.getAttribute("data-anchor"));
+    expect(ids).toEqual(["port", "reticle"]);
+  });
+
+  it("leaves Kerbcast's aim anchor out unless asked for", () => {
+    const subject = anchor({ id: "subject", owner: "kerbcast" });
+    const aim = anchor({ id: "aim", owner: "kerbcast" });
+    const plain = draw([subject, aim], { owners: ["kerbcast"] });
+    const ids = (c: HTMLElement) => [...c.querySelectorAll("g[data-anchor]")].map((g) => g.getAttribute("data-anchor"));
+    expect(ids(plain.container)).toEqual(["subject"]);
+    cleanup();
+    const asked = draw([subject, aim], { owners: ["kerbcast"], showAim: true });
+    expect(ids(asked.container)).toEqual(["subject", "aim"]);
+  });
+
+  it("puts the consumer's readout under the marker", () => {
+    draw([anchor()], { readout: (a) => `${a.distanceM} m` });
+    const el = screen.getByText("30 m");
+    expect(el.style.top).toBe(`${180 + 20 + 11}px`);
+  });
+
+  it("maps positions under object-fit cover", () => {
+    /* 1280x720 cropped into 400x400: scale 400/720, 311 px cut off each side. */
+    const { container } = draw([anchor({ x: 0, y: 360, apparentRadiusPx: 0 })], {}, sizedVideo(400, 400, "cover"));
+    const top = marks(container)[0].getAttribute("d")!;
+    const cx = -(1280 * (400 / 720) - 400) / 2;
+    expect(top.startsWith(`M${cx - 14} `)).toBe(true);
+  });
+
+  it("draws no marker for an observed anchor out of view, which carries no position", () => {
+    const hidden: FrameAnchor = { id: "port", observed: true, inFrame: true, occluded: true };
+    let rendered = 0;
+    const { container } = draw([hidden, anchor({ id: "seen", observed: true, occluded: false })], {
+      render: () => (rendered++, null),
+    });
+    const ids = [...container.querySelectorAll("g[data-anchor]")].map((g) => g.getAttribute("data-anchor"));
+    expect(ids).toEqual(["seen"]);
+    expect(rendered).toBe(1);
+  });
+
+  it("draws nothing for a frame without anchors", () => {
+    const { container } = render(<AnchorMarkers frame={null} video={sizedVideo(640, 360)} />);
+    expect(container.innerHTML).toBe("");
+  });
+});