@ksp-gonogo/kerbcast-react 1.7.0 → 1.8.0

package/src/hooks/useRecordings.test.tsx

@@ -0,0 +1,217 @@
+/*
+ * useRecordings store.
+ *
+ * Renders the hook through a real KerbcastProvider, backed by a fake client
+ * whose `recording` is a real RecordingController over a fake clock/camera
+ * surface (the SDK's own controller path is unit-tested in the typescript
+ * package). Asserts the store reflects start -> stop into `recordings` /
+ * `groups` / `active`, keeps grouped members out of the singles list, and
+ * clears on discard.
+ */
+
+import type { KerbcastClient } from "@ksp-gonogo/kerbcast";
+import {
+  RecordingController,
+  type RecordingClient,
+} from "@ksp-gonogo/kerbcast";
+import { installDomStubs, StubMediaRecorder } 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 { useRecordings, type RecordingsStore } from "./useRecordings";
+
+installDomStubs();
+
+function liveStream(): MediaStream {
+  const track = { kind: "video" } as MediaStreamTrack;
+  return {
+    getVideoTracks: () => [track],
+    getTracks: () => [track],
+  } as unknown as MediaStream;
+}
+
+/** Fake RecordingClient with a settable clock; enough for the controller. */
+class FakeRecordingClient implements RecordingClient {
+  captureUt: number | null = 100;
+  camera(_flightId: number): { readonly mediaStream: MediaStream | null } {
+    return { mediaStream: liveStream() };
+  }
+  get clock(): { readonly captureUt: number | null } {
+    return { captureUt: this.captureUt };
+  }
+  on(_event: "settings-change", _handler: (data: unknown) => void): () => void {
+    return () => {};
+  }
+}
+
+/** A KerbcastClient stand-in exposing only what the hook reads: `.recording`.
+ *  The trimmer loader is stubbed to null so grouped stops stay hermetic (the
+ *  physical-trim path itself is covered in the typescript package). */
+function fakeClient(): KerbcastClient {
+  const controller = new RecordingController(new FakeRecordingClient(), {
+    loadTrimmer: () => Promise.resolve(null),
+  });
+  return { recording: controller } as unknown as KerbcastClient;
+}
+
+let store: RecordingsStore | undefined;
+function Probe(): null {
+  store = useRecordings();
+  return null;
+}
+
+function mount(client: KerbcastClient): void {
+  render(
+    <KerbcastProvider client={client}>
+      <Probe />
+    </KerbcastProvider>,
+  );
+}
+
+afterEach(() => {
+  cleanup();
+  store = undefined;
+  StubMediaRecorder.supportedTypes = null;
+});
+
+describe("useRecordings", () => {
+  it("starts empty", () => {
+    mount(fakeClient());
+    expect(store?.recordings).toEqual([]);
+    expect(store?.groups).toEqual([]);
+    expect(store?.active).toEqual([]);
+  });
+
+  it("tracks an active recording, then lands the clip in recordings on stop", async () => {
+    mount(fakeClient());
+
+    let id = "";
+    act(() => {
+      id = store!.start(42);
+    });
+    expect(store?.active).toHaveLength(1);
+    expect(store?.active[0]).toMatchObject({ flightId: 42, recordingId: id });
+
+    await act(async () => {
+      await store!.stop(id);
+    });
+    expect(store?.active).toHaveLength(0);
+    expect(store?.recordings).toHaveLength(1);
+    expect(store?.recordings[0].recordingId).toBe(id);
+    expect(store?.recordings[0].flightId).toBe(42);
+  });
+
+  it("keeps grouped clips out of the singles list and in groups", async () => {
+    mount(fakeClient());
+
+    let groupId = "";
+    act(() => {
+      groupId = store!.startGroup([1, 2]);
+    });
+    expect(store?.active).toHaveLength(2);
+    expect(store?.active.every((a) => a.groupId === groupId)).toBe(true);
+
+    await act(async () => {
+      await store!.stopGroup(groupId);
+    });
+    expect(store?.active).toHaveLength(0);
+    expect(store?.recordings).toHaveLength(0);
+    expect(store?.groups).toHaveLength(1);
+    expect(store?.groups[0].recordings).toHaveLength(2);
+  });
+
+  it("gives each active group member the real controller-minted recordingId, not a fabricated one", () => {
+    const client = fakeClient();
+    mount(client);
+
+    let groupId = "";
+    act(() => {
+      groupId = store!.startGroup([1, 2]);
+    });
+
+    for (const member of store!.active) {
+      expect(member.groupId).toBe(groupId);
+      /* Not the old `${groupId}:${flightId}` fabrication. */
+      expect(member.recordingId).not.toBe(`${groupId}:${member.flightId}`);
+      /* A real id the controller actually tracks. */
+      expect(client.recording.fetchRecording(member.recordingId)).toBeUndefined();
+      expect(client.recording.isRecording(member.flightId)).toBe(true);
+    }
+  });
+
+  it("cancels a single active group member without disturbing the rest of the group", async () => {
+    const client = fakeClient();
+    mount(client);
+
+    let groupId = "";
+    act(() => {
+      groupId = store!.startGroup([1, 2]);
+    });
+    const [first, second] = store!.active;
+
+    await act(async () => {
+      await store!.stop(first.recordingId);
+    });
+
+    /* The cancelled member's feed actually unlocks. */
+    expect(client.recording.isRecording(first.flightId)).toBe(false);
+    /* The other member is untouched: still active, still recording. */
+    expect(client.recording.isRecording(second.flightId)).toBe(true);
+    expect(store?.active).toHaveLength(1);
+    expect(store?.active[0].recordingId).toBe(second.recordingId);
+  });
+
+  it("discards a single active group member without disturbing the rest of the group", () => {
+    const client = fakeClient();
+    mount(client);
+
+    let groupId = "";
+    act(() => {
+      groupId = store!.startGroup([1, 2]);
+    });
+    const [first, second] = store!.active;
+
+    act(() => {
+      store!.discard(first.recordingId);
+    });
+
+    expect(client.recording.isRecording(first.flightId)).toBe(false);
+    expect(client.recording.isRecording(second.flightId)).toBe(true);
+    expect(store?.active).toHaveLength(1);
+    expect(store?.active[0].recordingId).toBe(second.recordingId);
+  });
+
+  it("discards a finished single clip", async () => {
+    mount(fakeClient());
+    let id = "";
+    act(() => {
+      id = store!.start(7);
+    });
+    await act(async () => {
+      await store!.stop(id);
+    });
+    expect(store?.recordings).toHaveLength(1);
+
+    act(() => {
+      store!.discard(id);
+    });
+    expect(store?.recordings).toHaveLength(0);
+  });
+
+  it("discards a finished grouped set", async () => {
+    mount(fakeClient());
+    let groupId = "";
+    act(() => {
+      groupId = store!.startGroup([1, 2]);
+    });
+    await act(async () => {
+      await store!.stopGroup(groupId);
+    });
+    expect(store?.groups).toHaveLength(1);
+
+    act(() => {
+      store!.discardGroup(groupId);
+    });
+    expect(store?.groups).toHaveLength(0);
+  });
+});

package/src/hooks/useRecordings.ts

@@ -0,0 +1,110 @@
+import { useCallback, useSyncExternalStore } from "react";
+import type {
+  ActiveRecordingInfo,
+  GroupedRecordingHandle,
+  RecordingHandle,
+  StartRecordingOptions,
+  StopGroupedRecordingOptions,
+} from "@ksp-gonogo/kerbcast";
+import { useKerbcastClient } from "../context";
+
+/* Re-exported for compatibility: consumers importing ActiveRecordingInfo from
+   this module keep working now that the SDK owns the definition. */
+export type { ActiveRecordingInfo };
+
+/**
+ * Reactive recordings store over the SDK's `client.recording` controller.
+ *
+ * Holds the in-session, in-memory clips: standalone singles in `recordings`,
+ * synchronised sets in `groups`, and the still-running ones in `active`. This
+ * is the headless data layer the recordings tray + REC controls sit on; it
+ * owns no chrome. All state is in-memory, so a page reload discards it (the UI
+ * guards navigation while unsaved clips exist).
+ */
+export interface RecordingsStore {
+  /** Finished standalone (non-grouped) clips, newest last. */
+  recordings: RecordingHandle[];
+  /** Finished grouped sets, newest last. */
+  groups: GroupedRecordingHandle[];
+  /** Recordings currently in progress (single + grouped members). */
+  active: ActiveRecordingInfo[];
+  /** Whether a feed currently has a recording in progress. */
+  isRecording(flightId: number): boolean;
+
+  start(flightId: number, opts?: StartRecordingOptions): string;
+  stop(recordingId: string): Promise<RecordingHandle>;
+  startGroup(flightIds: number[], opts?: StartRecordingOptions): string;
+  stopGroup(
+    groupId: string,
+    opts?: StopGroupedRecordingOptions,
+  ): Promise<GroupedRecordingHandle>;
+  discard(recordingId: string): void;
+  discardGroup(groupId: string): void;
+}
+
+/**
+ * Subscribe a component to the recording store for the context client. The
+ * controller itself is the single source of truth for every call site;
+ * `useSyncExternalStore` re-renders this component whenever the controller's
+ * snapshot changes, no matter which call site (or which component) drove the
+ * change.
+ */
+export function useRecordings(): RecordingsStore {
+  const client = useKerbcastClient();
+  const controller = client.recording;
+
+  const snapshot = useSyncExternalStore(controller.subscribe, controller.getSnapshot);
+
+  const start = useCallback(
+    (flightId: number, opts?: StartRecordingOptions): string =>
+      controller.startRecording(flightId, opts),
+    [controller],
+  );
+
+  const stop = useCallback(
+    (recordingId: string): Promise<RecordingHandle> => controller.stopRecording(recordingId),
+    [controller],
+  );
+
+  const startGroup = useCallback(
+    (flightIds: number[], opts?: StartRecordingOptions): string =>
+      controller.startGroupedRecording(flightIds, opts).groupId,
+    [controller],
+  );
+
+  const stopGroup = useCallback(
+    (
+      groupId: string,
+      opts?: StopGroupedRecordingOptions,
+    ): Promise<GroupedRecordingHandle> => controller.stopGroupedRecording(groupId, opts),
+    [controller],
+  );
+
+  const discard = useCallback(
+    (recordingId: string): void => controller.discardRecording(recordingId),
+    [controller],
+  );
+
+  const discardGroup = useCallback(
+    (groupId: string): void => controller.discardGroupedRecording(groupId),
+    [controller],
+  );
+
+  const isRecording = useCallback(
+    (flightId: number): boolean => controller.isRecording(flightId),
+    [controller],
+  );
+
+  return {
+    recordings: snapshot.recordings,
+    groups: snapshot.groups,
+    active: snapshot.active,
+    isRecording,
+    start,
+    stop,
+    startGroup,
+    stopGroup,
+    discard,
+    discardGroup,
+  };
+}

package/src/index.ts

@@ -27,6 +27,11 @@ export { useKerbcastStream } from "./hooks/useKerbcastStream";
 export { useKerbcastClock } from "./hooks/useKerbcastClock";
 export { useKerbcastInFlight } from "./hooks/useKerbcastInFlight";
 export { useReportDisplaySize } from "./hooks/useReportDisplaySize";
+export { useRecordings } from "./hooks/useRecordings";
+export type { RecordingsStore, ActiveRecordingInfo } from "./hooks/useRecordings";
+
+// Shared elapsed-timer helpers (REC badges, RecGroupBar's toolbar)
+export { nowMs, formatElapsed } from "./timing";
 
 // Shared standby glyph (used by CameraFeed + downstream dashboards)
 export { StandbyIcon } from "./StandbyIcon";
@@ -48,6 +53,16 @@ export type {
   FeedAction,
 } from "./CameraFeed";
 
+// FeedActionBar: the shared action row (tracking, fullscreen, PiP, quality,
+// close, REC) both CameraFeed and KerbalFaceFeed render, with the issue-#6
+// overflow (⋮) engine.
+export { FeedActionBar } from "./FeedActionBar";
+export type { FeedActionBarEntry } from "./FeedActionBar";
+
 // KerbalFaceFeed — shared single-kerbal-face primitive
 export { KerbalFaceFeed } from "./KerbalFaceFeed";
 export type { KerbalFaceFeedProps, KerbalFeedState } from "./KerbalFaceFeed";
+
+// RecordingsTray: a presentational drawer over the recordings store
+export { RecordingsTray } from "./RecordingsTray";
+export type { RecordingsTrayProps } from "./RecordingsTray";

package/src/menuPositioning.ts

@@ -0,0 +1,126 @@
+/**
+ * Shared geometry + behaviour for a dropdown portaled to document.body.
+ * Used by CameraFeed's camera / quality / tracking menus and by
+ * FeedActionBar's overflow menu, so the anchoring, dismissal, and Escape
+ * handling live in exactly one place.
+ */
+
+import { useCallback, useEffect, useRef, useState } from "react";
+
+const MENU_GAP = 4; // trigger-to-menu spacing
+const MENU_EDGE = 8; // minimum inset from the viewport edge
+
+/*
+ * Geometry of a portaled dropdown: the CSS size caps of the menu (the
+ * helper clamps as if the menu fills them) and which edge of the trigger
+ * the menu hangs from: "start" lines the menu's left edge up with the
+ * trigger's, "end" lines the right edges up.
+ */
+export interface MenuAnchor {
+  maxWidth: number;
+  maxHeight: number;
+  align: "start" | "end";
+}
+
+/*
+ * Fixed-position style for a portaled menu, anchored to its trigger button.
+ * Opens downward by default; flips above the trigger when there is not
+ * enough room below but there is above, otherwise clamps to the viewport.
+ */
+export function computeMenuPosition(
+  trigger: HTMLElement,
+  anchor: MenuAnchor,
+): React.CSSProperties {
+  const rect = trigger.getBoundingClientRect();
+  const vw = window.innerWidth;
+  const vh = window.innerHeight;
+  const width = Math.min(anchor.maxWidth, vw - 2 * MENU_EDGE);
+  /* Inline offset from the aligned viewport edge, clamped so a full-width
+     menu still fits inside the opposite edge. */
+  const inset = Math.max(MENU_EDGE, vw - width - MENU_EDGE);
+  const inline: React.CSSProperties =
+    anchor.align === "start"
+      ? { left: Math.min(Math.max(rect.left, MENU_EDGE), inset) }
+      : { right: Math.min(Math.max(vw - rect.right, MENU_EDGE), inset) };
+  const menuH = Math.min(0.4 * vh, anchor.maxHeight);
+  const fitsBelow = rect.bottom + MENU_GAP + menuH <= vh - MENU_EDGE;
+  const fitsAbove = rect.top - MENU_GAP - menuH >= MENU_EDGE;
+  if (!fitsBelow && fitsAbove) {
+    return { ...inline, bottom: vh - rect.top + MENU_GAP };
+  }
+  const top = Math.min(
+    rect.bottom + MENU_GAP,
+    Math.max(MENU_EDGE, vh - MENU_EDGE - menuH),
+  );
+  return { ...inline, top };
+}
+
+/*
+ * Shared behaviour for a dropdown portaled to document.body: fixed position
+ * computed from the trigger's rect (so tile overflow cannot clip it),
+ * re-anchored on window resize/scroll while open, Escape to close with focus
+ * returned to the trigger, and portal-aware outside-pointer-down dismissal
+ * (menuRef points at the portaled menu, so clicks inside it stay "inside").
+ * One menu at a time falls out of the dismissal: opening another menu's
+ * trigger is an outside press for this one.
+ */
+export function usePortalMenu({ maxWidth, maxHeight, align }: MenuAnchor) {
+  const [open, setOpen] = useState(false);
+  const [position, setPosition] = useState<React.CSSProperties | null>(null);
+  const menuRef = useRef<HTMLDivElement>(null);
+  const triggerRef = useRef<HTMLButtonElement>(null);
+
+  useEffect(() => {
+    if (!open) {
+      setPosition(null);
+      return;
+    }
+    const update = () => {
+      const trigger = triggerRef.current;
+      if (trigger) {
+        setPosition(computeMenuPosition(trigger, { maxWidth, maxHeight, align }));
+      }
+    };
+    update();
+    window.addEventListener("resize", update);
+    window.addEventListener("scroll", update, true);
+    return () => {
+      window.removeEventListener("resize", update);
+      window.removeEventListener("scroll", update, true);
+    };
+  }, [open, maxWidth, maxHeight, align]);
+
+  useEffect(() => {
+    if (!open) return;
+    const onKeyDown = (e: KeyboardEvent) => {
+      if (e.key === "Escape") {
+        e.stopPropagation();
+        setOpen(false);
+        triggerRef.current?.focus();
+      }
+    };
+    const onPointerDown = (e: PointerEvent) => {
+      if (
+        !menuRef.current?.contains(e.target as Node) &&
+        !triggerRef.current?.contains(e.target as Node)
+      ) {
+        setOpen(false);
+      }
+    };
+    document.addEventListener("keydown", onKeyDown);
+    document.addEventListener("pointerdown", onPointerDown);
+    return () => {
+      document.removeEventListener("keydown", onKeyDown);
+      document.removeEventListener("pointerdown", onPointerDown);
+    };
+  }, [open]);
+
+  const toggle = useCallback(() => setOpen((v) => !v), []);
+  /** Close after an item pick, returning focus to the trigger. */
+  const close = useCallback(() => {
+    setOpen(false);
+    triggerRef.current?.focus();
+  }, []);
+
+  return { open, toggle, close, position, menuRef, triggerRef };
+}

package/src/timing.test.ts

@@ -0,0 +1,34 @@
+/*
+ * Shared elapsed-timer helpers, extracted out of CameraFeed.tsx and
+ * RecGroupBar.tsx (formerly duplicated verbatim between the two).
+ */
+
+import { describe, expect, it } from "vitest";
+import { formatElapsed, nowMs } from "./timing";
+
+describe("formatElapsed", () => {
+  it("formats sub-minute durations as 0:ss", () => {
+    expect(formatElapsed(3_000)).toBe("0:03");
+  });
+
+  it("formats minutes and seconds, zero-padding seconds", () => {
+    expect(formatElapsed(65_000)).toBe("1:05");
+  });
+
+  it("floors partial seconds", () => {
+    expect(formatElapsed(1_999)).toBe("0:01");
+  });
+
+  it("clamps negative durations to 0:00", () => {
+    expect(formatElapsed(-500)).toBe("0:00");
+  });
+});
+
+describe("nowMs", () => {
+  it("returns a monotonically increasing, non-negative number", () => {
+    const a = nowMs();
+    const b = nowMs();
+    expect(a).toBeGreaterThanOrEqual(0);
+    expect(b).toBeGreaterThanOrEqual(a);
+  });
+});

package/src/timing.ts

@@ -0,0 +1,21 @@
+/*
+ * Shared elapsed-timer helpers for REC-style live-duration displays: the
+ * per-feed REC badge (CameraFeed) and the REC+ grouped-recording toolbar
+ * (a host's own RecGroupBar). Framework-free so both places read the same
+ * clock and format the same way instead of drifting apart.
+ */
+
+/** Monotonic clock for elapsed-timer math. Falls back to Date.now under jsdom. */
+export function nowMs(): number {
+  return typeof performance !== "undefined" && typeof performance.now === "function"
+    ? performance.now()
+    : Date.now();
+}
+
+/** Formats a millisecond duration as m:ss (e.g. "REC 1:05", "Recording 3 feeds - 0:42"). */
+export function formatElapsed(ms: number): string {
+  const totalSeconds = Math.max(0, Math.floor(ms / 1000));
+  const minutes = Math.floor(totalSeconds / 60);
+  const seconds = totalSeconds % 60;
+  return `${minutes}:${seconds.toString().padStart(2, "0")}`;
+}