@ksp-gonogo/kerbcast-react 1.6.3 → 1.8.0

package/src/hooks/useRecordings.sharedState.test.tsx

@@ -0,0 +1,117 @@
+/*
+ * Regression test for the shared-state bug: two independent useRecordings()
+ * call sites over the same client must see the same controller state. Before
+ * the observable-store fix, each call site held its own useState mirror, so
+ * a clip started/stopped through one component's hook was invisible to
+ * another -- the exact scenario where a tile's own REC button starts a clip
+ * a RecordingsTray elsewhere can never reach (data loss).
+ *
+ * Must fail on the old per-instance-useState hook and pass once
+ * useRecordings consumes RecordingController via useSyncExternalStore.
+ */
+
+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 () => {};
+  }
+}
+
+function fakeClient(): KerbcastClient {
+  const controller = new RecordingController(new FakeRecordingClient(), {
+    loadTrimmer: () => Promise.resolve(null),
+  });
+  return { recording: controller } as unknown as KerbcastClient;
+}
+
+let storeA: RecordingsStore | undefined;
+let storeB: RecordingsStore | undefined;
+
+/* Two components mounted side by side, each calling useRecordings() on its
+   own, standing in for a CameraFeed's own REC control and a separately
+   mounted RecordingsTray. */
+function ProbeA(): null {
+  storeA = useRecordings();
+  return null;
+}
+function ProbeB(): null {
+  storeB = useRecordings();
+  return null;
+}
+
+function mount(client: KerbcastClient): void {
+  render(
+    <KerbcastProvider client={client}>
+      <ProbeA />
+      <ProbeB />
+    </KerbcastProvider>,
+  );
+}
+
+afterEach(() => {
+  cleanup();
+  storeA = undefined;
+  storeB = undefined;
+  StubMediaRecorder.supportedTypes = null;
+});
+
+describe("useRecordings shared store", () => {
+  it("makes an in-progress recording started via one call site visible to another", () => {
+    mount(fakeClient());
+
+    let id = "";
+    act(() => {
+      id = storeA!.start(42);
+    });
+
+    expect(storeB?.active).toHaveLength(1);
+    expect(storeB?.active[0]).toMatchObject({ flightId: 42, recordingId: id });
+  });
+
+  it("makes a clip finished via one call site's stop visible in another's recordings", async () => {
+    mount(fakeClient());
+
+    let id = "";
+    act(() => {
+      id = storeA!.start(42);
+    });
+
+    await act(async () => {
+      await storeA!.stop(id);
+    });
+
+    expect(storeA?.active).toHaveLength(0);
+    expect(storeA?.recordings).toHaveLength(1);
+
+    /* storeB never called start/stop itself: without the fix, this clip is
+       unreachable through it, which is exactly the data-loss bug. */
+    expect(storeB?.active).toHaveLength(0);
+    expect(storeB?.recordings).toHaveLength(1);
+    expect(storeB?.recordings[0].recordingId).toBe(id);
+  });
+});

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/hooks/useReportDisplaySize.test.tsx

@@ -0,0 +1,166 @@
+/**
+ * Tests for useReportDisplaySize: the self-measure -> report path. Drives a
+ * controllable ResizeObserver and a recording displaySizes registry override
+ * so the debounce / bucket / prompt-first / square-vs-wh / clear-on-unmount
+ * behaviour is asserted directly, without a real layout engine.
+ */
+
+import type { KerbcastClient } from "@ksp-gonogo/kerbcast";
+import { act, cleanup, render } from "@testing-library/react";
+import { useRef } from "react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { KerbcastProvider, type KerbcastDisplaySizes } from "../context";
+import { useReportDisplaySize } from "./useReportDisplaySize";
+
+// A controllable ResizeObserver: captures the callback so a test can fire a
+// resize with a chosen contentRect.
+let resizeCallback:
+  | ((entries: ResizeObserverEntry[], observer: ResizeObserver) => void)
+  | undefined;
+const originalResizeObserver = globalThis.ResizeObserver;
+
+// A recording registry override, injected via the provider.
+function recordingRegistry() {
+  const reports: Array<{ flightId: number; id: string; w: number; h: number }> = [];
+  const clears: Array<{ flightId: number; id: string }> = [];
+  const displaySizes: KerbcastDisplaySizes = {
+    report: (flightId, id, w, h) => reports.push({ flightId, id, w, h }),
+    clear: (flightId, id) => clears.push({ flightId, id }),
+  };
+  return { displaySizes, reports, clears };
+}
+
+const fakeClient = {} as unknown as KerbcastClient;
+
+function fireResize(width: number, height: number) {
+  act(() => {
+    resizeCallback?.(
+      [{ contentRect: { width, height } }] as ResizeObserverEntry[],
+      {} as ResizeObserver,
+    );
+  });
+}
+
+function Harness({
+  flightId,
+  square,
+  enabled,
+}: {
+  flightId: number | null;
+  square?: boolean;
+  enabled?: boolean;
+}) {
+  const ref = useRef<HTMLDivElement>(null);
+  useReportDisplaySize(flightId, ref, { square, enabled });
+  return <div ref={ref} data-testid="feed" />;
+}
+
+beforeEach(() => {
+  vi.useFakeTimers();
+  globalThis.ResizeObserver = class {
+    constructor(cb: (entries: ResizeObserverEntry[], observer: ResizeObserver) => void) {
+      resizeCallback = cb;
+    }
+    observe() {}
+    unobserve() {}
+    disconnect() {}
+  } as unknown as typeof ResizeObserver;
+});
+
+afterEach(() => {
+  cleanup();
+  globalThis.ResizeObserver = originalResizeObserver;
+  resizeCallback = undefined;
+  vi.useRealTimers();
+});
+
+describe("useReportDisplaySize", () => {
+  it("reports the first measurement promptly (no debounce wait)", () => {
+    const { displaySizes, reports } = recordingRegistry();
+    render(
+      <KerbcastProvider client={fakeClient} displaySizes={displaySizes}>
+        <Harness flightId={7} />
+      </KerbcastProvider>,
+    );
+    // 40x30 -> ceil to a 16-multiple = 48x32, reported without advancing timers.
+    fireResize(40, 30);
+    expect(reports).toEqual([{ flightId: 7, id: expect.any(String), w: 48, h: 32 }]);
+  });
+
+  it("reports a square (min edge) when square is set", () => {
+    const { displaySizes, reports } = recordingRegistry();
+    render(
+      <KerbcastProvider client={fakeClient} displaySizes={displaySizes}>
+        <Harness flightId={7} square />
+      </KerbcastProvider>,
+    );
+    // min(50,40)=40 -> 48x48 square.
+    fireResize(50, 40);
+    expect(reports.at(-1)).toMatchObject({ w: 48, h: 48 });
+  });
+
+  it("debounces churn after the first report", () => {
+    const { displaySizes, reports } = recordingRegistry();
+    render(
+      <KerbcastProvider client={fakeClient} displaySizes={displaySizes}>
+        <Harness flightId={7} />
+      </KerbcastProvider>,
+    );
+    fireResize(48, 48); // prompt first -> 48x48
+    fireResize(200, 200); // debounced, not yet applied
+    expect(reports).toHaveLength(1);
+    act(() => vi.advanceTimersByTime(200));
+    // 200 -> 208; the debounced resize now lands.
+    expect(reports.at(-1)).toMatchObject({ w: 208, h: 208 });
+  });
+
+  it("does not re-report a sub-bucket change", () => {
+    const { displaySizes, reports } = recordingRegistry();
+    render(
+      <KerbcastProvider client={fakeClient} displaySizes={displaySizes}>
+        <Harness flightId={7} />
+      </KerbcastProvider>,
+    );
+    fireResize(40, 40); // -> 48x48
+    fireResize(44, 44); // still ceils to 48x48 -> no new report
+    act(() => vi.advanceTimersByTime(200));
+    expect(reports).toHaveLength(1);
+  });
+
+  it("clears its registration on unmount", () => {
+    const { displaySizes, reports, clears } = recordingRegistry();
+    const { unmount } = render(
+      <KerbcastProvider client={fakeClient} displaySizes={displaySizes}>
+        <Harness flightId={7} />
+      </KerbcastProvider>,
+    );
+    fireResize(40, 40);
+    const id = reports[0].id;
+    act(() => unmount());
+    expect(clears).toEqual([{ flightId: 7, id }]);
+  });
+
+  it("does not observe or report when disabled", () => {
+    const { displaySizes, reports } = recordingRegistry();
+    render(
+      <KerbcastProvider client={fakeClient} displaySizes={displaySizes}>
+        <Harness flightId={7} enabled={false} />
+      </KerbcastProvider>,
+    );
+    // The observer is never constructed when disabled, so no callback is armed.
+    expect(resizeCallback).toBeUndefined();
+    expect(reports).toEqual([]);
+  });
+
+  it("does nothing for a null flightId", () => {
+    const { displaySizes, reports } = recordingRegistry();
+    render(
+      <KerbcastProvider client={fakeClient} displaySizes={displaySizes}>
+        <Harness flightId={null} />
+      </KerbcastProvider>,
+    );
+    expect(resizeCallback).toBeUndefined();
+    expect(reports).toEqual([]);
+  });
+});

package/src/hooks/useReportDisplaySize.ts

@@ -0,0 +1,91 @@
+import { useEffect, useId } from "react";
+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.
+ */
+const DEBOUNCE_MS = 200;
+const BUCKET_PX = 16;
+
+function bucket(px: number): number {
+  const b = Math.ceil(px / BUCKET_PX) * BUCKET_PX;
+  return b < BUCKET_PX ? BUCKET_PX : b;
+}
+
+export interface ReportDisplaySizeOptions {
+  /**
+   * Report while mounted. Default true. Set false for a fixed-resolution feed
+   * that should not drive auto-resolution. This is a RESOLUTION concern only,
+   * independent of whether the feed shows its action UI.
+   */
+  enabled?: boolean;
+  /**
+   * Report a square (side x side, the min edge) rather than the raw w x h.
+   * Face cams are square; part cams are not.
+   */
+  square?: boolean;
+}
+
+/**
+ * Self-measure a feed element and drive the client's per-consumer
+ * `reportDisplaySize` (via the context display-size registry, which collapses
+ * multiple feeds of the same camera to one MAX report). Attach `ref` to the
+ * element whose rendered pixel box is the display size. Reporting follows the
+ * mount lifecycle: on unmount / `flightId` change / `enabled` flip it
+ * deregisters, and the sidecar's clear-on-departure (unsubscribe) does the
+ * server-side clear.
+ */
+export function useReportDisplaySize(
+  flightId: number | null,
+  ref: React.RefObject<Element | null>,
+  { enabled = true, square = false }: ReportDisplaySizeOptions = {},
+): void {
+  const displaySizes = useKerbcastDisplaySizes();
+  const instanceId = useId();
+
+  useEffect(() => {
+    if (flightId === null || !enabled) return;
+    const el = ref.current;
+    if (!el) return;
+
+    let timer: ReturnType<typeof setTimeout> | null = null;
+    let lastW = -1;
+    let lastH = -1;
+    let firstReported = false;
+
+    const report = (width: number, height: number) => {
+      const side = square ? Math.min(width, height) : 0;
+      const bw = bucket(square ? side : width);
+      const bh = bucket(square ? side : height);
+      if (bw === lastW && bh === lastH) return;
+      lastW = bw;
+      lastH = bh;
+      displaySizes.report(flightId, instanceId, bw, bh);
+    };
+
+    const observer = new ResizeObserver((entries) => {
+      const entry = entries[0];
+      if (!entry) return;
+      const { width, height } = entry.contentRect;
+      if (!firstReported) {
+        firstReported = true;
+        report(width, height);
+        return;
+      }
+      if (timer !== null) clearTimeout(timer);
+      timer = setTimeout(() => report(width, height), DEBOUNCE_MS);
+    });
+    observer.observe(el);
+
+    return () => {
+      observer.disconnect();
+      if (timer !== null) clearTimeout(timer);
+      displaySizes.clear(flightId, instanceId);
+    };
+  }, [displaySizes, flightId, ref, enabled, square, instanceId]);
+}