@ksp-gonogo/kerbcast-react 1.6.3 → 1.8.0

package/src/KerbalFaceFeed.tsx

@@ -0,0 +1,214 @@
+/**
+ * KerbalFaceFeed — the shared single-kerbal-face primitive.
+ *
+ * Renders ONE kerbal's face-camera stream in a fixed SQUARE frame. It is the
+ * reusable building block a crew bar (kerbcast web) or a mission-control
+ * surface (gonogo) composes: identity-keyed by `flightId`, it binds the live
+ * `MediaStream` to a persistent `<video>` and NEVER remounts that element on
+ * re-layout (the "never remount a live feed" rule — the same srcObject-via-ref
+ * technique `CameraFeed` uses).
+ *
+ * Deliberately minimal chrome: just the square live face plus a standby glyph
+ * when there is no live signal. Everything else — name label, IVA/EVA badge,
+ * click behaviour, a "SIGNAL LOST" treatment — is layered OVER it by the
+ * wrapper via `children`, driven by the `onFeedStateChange` signal. A thin
+ * `actions` bar (the shared `FeedAction` shape) is rendered top-right when a
+ * wrapper supplies one, so declarative controls compose the same way they do
+ * on `CameraFeed`.
+ */
+
+import { useEffect, useRef, useState } from "react";
+import styled from "styled-components";
+
+import { CameraStreamHook, FeedAction } from "./CameraFeed";
+import { FeedActionBar, feedActionToEntry } from "./FeedActionBar";
+import { useKerbcastStream } from "./hooks/useKerbcastStream";
+import { useKerbcastCameras } from "./hooks/useKerbcastCameras";
+import { useReportDisplaySize } from "./hooks/useReportDisplaySize";
+import { isCameraDestroyed } from "./lifecycle";
+import { StandbyIcon } from "./StandbyIcon";
+
+/**
+ * Coarse presentation state a wrapper reacts to for its own fallback/badge:
+ * - `live`: a stream is bound and playing.
+ * - `no-signal`: no stream yet (connecting, out of flight, or not visible).
+ * - `destroyed`: the camera's part/kerbal is gone (the wrapper renders SIGNAL
+ *   LOST; the last frame stays on-screen because the `<video>` is not cleared).
+ */
+export type KerbalFeedState = "live" | "no-signal" | "destroyed";
+
+export interface KerbalFaceFeedProps {
+  /** Wire-id (`CameraState.flightId`) of the kerbal face camera to display. */
+  flightId: number;
+  /**
+   * Explicit square side in px, for LAYOUT only. When omitted the feed fills
+   * its parent's width at a 1:1 aspect ratio. This does NOT drive resolution:
+   * the primitive always self-measures its rendered box and reports that to the
+   * sidecar (auto-resolution). Pass it to fix the element's size, not to
+   * request a stream resolution.
+   */
+  size?: number;
+  /**
+   * Report the self-measured display size to the sidecar to drive
+   * auto-resolution. Default true. Set false for a fixed-resolution feed that
+   * should not participate in auto-res. Independent of {@link showActions}
+   * (a resolution concern, not a UI one).
+   */
+  reportSize?: boolean;
+  /**
+   * Consumer action buttons, rendered as a minimal top-right bar (the shared
+   * {@link FeedAction} shape). Omit for no bar — the common case, since a crew
+   * bar usually composes its controls in `children` instead.
+   */
+  actions?: FeedAction[];
+  /**
+   * Render the feed's action UI (the top-right action bar). Default true. Set
+   * false to suppress the bar entirely (e.g. a tiny avatar where hover controls
+   * add nothing). Does not affect display-size reporting.
+   */
+  showActions?: boolean;
+  /**
+   * Overlay content layered OVER the square face: name label, IVA/EVA badge,
+   * click target, a custom destroyed treatment. Absolutely positioned to fill
+   * the frame; the primitive keeps its own chrome out of the way.
+   */
+  children?: React.ReactNode;
+  /**
+   * Fired whenever the derived feed state changes, so the wrapper can swap its
+   * fallback/badge without polling. Fires once on mount with the initial state.
+   */
+  onFeedStateChange?: (state: KerbalFeedState) => void;
+  /**
+   * Draw the built-in standby glyph while not `live`. Default true. Set false
+   * when the wrapper renders its own out-of-signal overlay (so it isn't drawn
+   * twice); the frame then just stays dark / holds the last frame.
+   */
+  showStandby?: boolean;
+  /**
+   * Override how the stream is sourced (delayed playout, alternate transport).
+   * Must be a stable reference passed consistently across renders — it is
+   * called as a hook. Omit to use the built-in {@link useKerbcastStream}.
+   */
+  useStream?: CameraStreamHook;
+}
+
+const Frame = styled.div<{ $size?: number }>`
+  position: relative;
+  ${(p) => (p.$size != null ? `width: ${p.$size}px; height: ${p.$size}px;` : "width: 100%;")}
+  aspect-ratio: 1 / 1;
+  overflow: hidden;
+  background: #000;
+  border-radius: 4px;
+`;
+
+const Face = styled.video`
+  width: 100%;
+  height: 100%;
+  /* Cover the square: the portrait fills the frame, cropping the excess,
+     rather than letterboxing — a face tile reads best edge-to-edge. */
+  object-fit: cover;
+  display: block;
+`;
+
+const StandbyLayer = styled.div`
+  position: absolute;
+  inset: 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  color: rgba(255, 255, 255, 0.35);
+  pointer-events: none;
+`;
+
+const DestroyedScrim = styled.div`
+  position: absolute;
+  inset: 0;
+  background: rgba(0, 0, 0, 0.45);
+  pointer-events: none;
+`;
+
+const OverlayLayer = styled.div`
+  position: absolute;
+  inset: 0;
+`;
+
+/*
+ * The shared FeedActionBar is hover-revealed by default (CameraFeed's larger
+ * frame fades it in on hover/focus). A tiny face tile has no such affordance,
+ * so this override keeps the original always-visible, corner-hugging look;
+ * layout/button styling (flex row, gap, the shared OverlayIconButton) still
+ * comes from FeedActionBar itself.
+ */
+const KerbalActionBarRow = styled(FeedActionBar)`
+  top: 4px;
+  right: 4px;
+  opacity: 1;
+  pointer-events: auto;
+`;
+
+export function KerbalFaceFeed({
+  flightId,
+  size,
+  reportSize = true,
+  actions,
+  showActions = true,
+  children,
+  onFeedStateChange,
+  showStandby = true,
+  useStream,
+}: KerbalFaceFeedProps) {
+  // Match CameraFeed: the built-in hook (which acquires/releases the
+  // subscription slot) runs only when no override is supplied.
+  const resolveStream = useStream ?? useKerbcastStream;
+  const stream = resolveStream(flightId);
+
+  // The camera's lifecycle comes from the registry snapshot; destroyed cameras
+  // linger in the list so the wrapper can show SIGNAL LOST.
+  const cameras = useKerbcastCameras();
+  const destroyed = cameras.some((c) => c.flightId === flightId && isCameraDestroyed(c));
+
+  const state: KerbalFeedState = destroyed
+    ? "destroyed"
+    : stream
+      ? "live"
+      : "no-signal";
+
+  // Self-measure the square frame and report it to the sidecar (auto-res).
+  // Reporting follows the mount lifecycle; the registry collapses multiple
+  // feeds of the same kerbal to one MAX report.
+  const frameRef = useRef<HTMLDivElement>(null);
+  useReportDisplaySize(flightId, frameRef, { square: true, enabled: reportSize });
+
+  // Bind the stream to the persistent <video> without remounting it — the
+  // element stays mounted across every re-layout / prop change, only its
+  // srcObject is (re)assigned. A stall (stream -> null) leaves the last frame.
+  const videoRef = useRef<HTMLVideoElement>(null);
+  useEffect(() => {
+    if (videoRef.current && stream) {
+      videoRef.current.srcObject = stream;
+    }
+  }, [stream]);
+
+  // Notify the wrapper on every state transition (and once on mount).
+  const notify = useRef(onFeedStateChange);
+  notify.current = onFeedStateChange;
+  useEffect(() => {
+    notify.current?.(state);
+  }, [state]);
+
+  return (
+    <Frame ref={frameRef} $size={size} data-testid="kerbal-face-feed" data-feed-state={state}>
+      <Face ref={videoRef} autoPlay playsInline muted controls={false} />
+      {state === "destroyed" && <DestroyedScrim />}
+      {showStandby && state !== "live" && (
+        <StandbyLayer>
+          <StandbyIcon size={Math.round((size ?? 96) * 0.32)} />
+        </StandbyLayer>
+      )}
+      {showActions && actions && actions.length > 0 && (
+        <KerbalActionBarRow entries={actions.map(feedActionToEntry)} />
+      )}
+      {children && <OverlayLayer>{children}</OverlayLayer>}
+    </Frame>
+  );
+}

package/src/RecordingsTray.test.tsx

@@ -0,0 +1,288 @@
+/*
+ * RecordingsTray.
+ *
+ * `useRecordings()` is mocked with a store that mirrors the real hook's shape
+ * (its own per-mount useState, so `discard`/`discardGroup` naturally re-render
+ * the tray exactly like the real hook does) seeded per test via
+ * `fakeStoreSeed` (shared with the mock factory through `vi.hoisted`, the
+ * documented way to reach into a hoisted `vi.mock`). This keeps the tray's
+ * rendering/formatting/object-URL logic under test without a real
+ * MediaRecorder track (jsdom's noise-pipeline stub has none -- see the same
+ * note in CameraFeed.test.tsx).
+ *
+ * jsdom has no working `URL.createObjectURL`/`revokeObjectURL`, so both are
+ * stubbed per test (same pattern as web/src/mock/driver.test.ts).
+ */
+
+import type { GroupedRecordingHandle, RecordingHandle } from "@ksp-gonogo/kerbcast";
+import { cleanup, fireEvent, render, screen } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { ActiveRecordingInfo } from "./hooks/useRecordings";
+import { RecordingsTray } from "./RecordingsTray";
+
+const fakeStoreSeed = vi.hoisted(() => ({
+  recordings: [] as unknown[],
+  groups: [] as unknown[],
+  active: [] as unknown[],
+}));
+
+const storeSpies = vi.hoisted(() => ({
+  discard: vi.fn(),
+  discardGroup: vi.fn(),
+}));
+
+vi.mock("./hooks/useRecordings", async () => {
+  const { useState } = await import("react");
+
+  function useRecordings() {
+    const [state, setState] = useState(() => ({
+      recordings: fakeStoreSeed.recordings,
+      groups: fakeStoreSeed.groups,
+      active: fakeStoreSeed.active,
+    }));
+
+    return {
+      recordings: state.recordings,
+      groups: state.groups,
+      active: state.active,
+      isRecording: () => false,
+      start: vi.fn(),
+      stop: vi.fn(),
+      startGroup: vi.fn(),
+      stopGroup: vi.fn(),
+      discard: (recordingId: string) => {
+        storeSpies.discard(recordingId);
+        setState((s) => ({
+          ...s,
+          recordings: (s.recordings as { recordingId: string }[]).filter(
+            (r) => r.recordingId !== recordingId,
+          ),
+        }));
+      },
+      discardGroup: (groupId: string) => {
+        storeSpies.discardGroup(groupId);
+        setState((s) => ({
+          ...s,
+          groups: (s.groups as { groupId: string }[]).filter((g) => g.groupId !== groupId),
+        }));
+      },
+    };
+  }
+
+  return { useRecordings };
+});
+
+// ---------------------------------------------------------------------------
+// Fixtures
+// ---------------------------------------------------------------------------
+
+function makeRecording(overrides: Partial<RecordingHandle> = {}): RecordingHandle {
+  return {
+    recordingId: "rec-1",
+    flightId: 42,
+    blob: new Blob(["clip"], { type: "video/webm" }),
+    mimeType: "video/webm",
+    utStart: 100,
+    utEnd: 160,
+    utSamples: [],
+    byteSize: 2048,
+    durationMs: 65_000,
+    ...overrides,
+  };
+}
+
+function makeGroup(overrides: Partial<GroupedRecordingHandle> = {}): GroupedRecordingHandle {
+  return {
+    groupId: "grp-1",
+    recordings: [
+      makeRecording({ recordingId: "rec-a" }),
+      makeRecording({ recordingId: "rec-b" }),
+    ],
+    commonUtWindow: [100, 150],
+    ...overrides,
+  };
+}
+
+function activeInfo(overrides: Partial<ActiveRecordingInfo> = {}): ActiveRecordingInfo {
+  return { recordingId: "rec-1", flightId: 42, startedAt: 0, ...overrides };
+}
+
+let urlCounter = 0;
+
+beforeEach(() => {
+  urlCounter = 0;
+  vi.spyOn(URL, "createObjectURL").mockImplementation(() => `blob:mock-${urlCounter++}`);
+  vi.spyOn(URL, "revokeObjectURL").mockImplementation(() => {});
+});
+
+afterEach(() => {
+  cleanup();
+  vi.restoreAllMocks();
+  storeSpies.discard.mockClear();
+  storeSpies.discardGroup.mockClear();
+  fakeStoreSeed.recordings = [];
+  fakeStoreSeed.groups = [];
+  fakeStoreSeed.active = [];
+});
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("RecordingsTray - empty state", () => {
+  it("shows a placeholder when there are no clips", () => {
+    render(<RecordingsTray />);
+    expect(screen.getByText(/no recordings yet/i)).toBeTruthy();
+    expect(screen.queryByText(/unsaved clips/i)).toBeNull();
+  });
+});
+
+describe("RecordingsTray - single clips", () => {
+  it("renders a clip's camera name, UT range, duration, and size", () => {
+    fakeStoreSeed.active = [activeInfo({ recordingId: "rec-1", flightId: 42 })];
+    fakeStoreSeed.recordings = [
+      makeRecording({ recordingId: "rec-1", utStart: 100, utEnd: 160, durationMs: 65_000, byteSize: 2048 }),
+    ];
+
+    render(<RecordingsTray cameraLabel={(flightId) => `Cam ${flightId}`} />);
+
+    expect(screen.getByText("Cam 42")).toBeTruthy();
+    expect(screen.getByText(/T\+100s.*T\+160s/)).toBeTruthy();
+    expect(screen.getByText(/1:05/)).toBeTruthy(); // 65s
+    expect(screen.getByText(/2\.0 KB/)).toBeTruthy();
+    expect(screen.getByText(/unsaved clips/i)).toBeTruthy();
+  });
+
+  it("falls back to 'Camera <flightId>' when no cameraLabel prop is given", () => {
+    fakeStoreSeed.recordings = [makeRecording({ recordingId: "rec-1", flightId: 7 })];
+    render(<RecordingsTray />);
+    expect(screen.getByText("Camera 7")).toBeTruthy();
+  });
+
+  it("labels a finished clip from its own flightId, even when the tray mounts after the recording finished (never in `active`)", () => {
+    fakeStoreSeed.active = []; // the tray mounted after the clip finished
+    fakeStoreSeed.recordings = [makeRecording({ recordingId: "rec-1", flightId: 99 })];
+    render(<RecordingsTray cameraLabel={(flightId) => `Cam ${flightId}`} />);
+    expect(screen.getByText("Cam 99")).toBeTruthy();
+  });
+
+  it("shows 'no UT' when the clip has no UT range", () => {
+    fakeStoreSeed.recordings = [
+      makeRecording({ recordingId: "rec-1", utStart: undefined, utEnd: undefined }),
+    ];
+    render(<RecordingsTray />);
+    expect(screen.getByText(/no ut \(out of flight\)/i)).toBeTruthy();
+  });
+
+  it("download uses an object URL created from the clip's blob", () => {
+    const blob = new Blob(["specific"], { type: "video/webm" });
+    fakeStoreSeed.recordings = [makeRecording({ recordingId: "rec-1", blob })];
+    render(<RecordingsTray />);
+
+    expect(URL.createObjectURL).toHaveBeenCalledWith(blob);
+    const link = screen.getByText("Download").closest("a");
+    expect(link?.getAttribute("href")).toBe("blob:mock-0");
+    expect(link?.hasAttribute("download")).toBe(true);
+  });
+
+  it("mounts a <video> preview sourced from the clip's object URL", () => {
+    fakeStoreSeed.recordings = [makeRecording({ recordingId: "rec-1" })];
+    const { container } = render(<RecordingsTray />);
+    const video = container.querySelector("video");
+    expect(video).toBeTruthy();
+    expect(video?.getAttribute("src")).toBe("blob:mock-0");
+  });
+
+  it("discard calls the store and revokes the clip's object URL", () => {
+    fakeStoreSeed.recordings = [makeRecording({ recordingId: "rec-1" })];
+    render(<RecordingsTray />);
+
+    fireEvent.click(screen.getByText("Discard"));
+
+    expect(storeSpies.discard).toHaveBeenCalledWith("rec-1");
+    expect(URL.revokeObjectURL).toHaveBeenCalledWith("blob:mock-0");
+    expect(screen.queryByText("Discard")).toBeNull();
+  });
+});
+
+describe("RecordingsTray - grouped sets", () => {
+  it("renders a group's clips together with a download-all", () => {
+    fakeStoreSeed.groups = [
+      makeGroup({
+        groupId: "grp-1",
+        recordings: [
+          makeRecording({ recordingId: "rec-a" }),
+          makeRecording({ recordingId: "rec-b" }),
+        ],
+      }),
+    ];
+    render(<RecordingsTray />);
+
+    expect(screen.getByText(/grouped recording/i)).toBeTruthy();
+    expect(screen.getByText(/2 feeds/i)).toBeTruthy();
+    expect(screen.getAllByText("Download")).toHaveLength(2);
+    expect(screen.getByText("Download all")).toBeTruthy();
+  });
+
+  it("download-all clicks one <a> per member", () => {
+    fakeStoreSeed.groups = [
+      makeGroup({
+        groupId: "grp-1",
+        recordings: [
+          makeRecording({ recordingId: "rec-a" }),
+          makeRecording({ recordingId: "rec-b" }),
+        ],
+      }),
+    ];
+    const clickSpy = vi.spyOn(HTMLAnchorElement.prototype, "click").mockImplementation(() => {});
+    render(<RecordingsTray />);
+
+    fireEvent.click(screen.getByText("Download all"));
+
+    expect(clickSpy).toHaveBeenCalledTimes(2);
+  });
+
+  it("labels grouped clips from their own flightId, with no active info needed", () => {
+    fakeStoreSeed.active = [];
+    fakeStoreSeed.groups = [
+      makeGroup({
+        groupId: "grp-1",
+        recordings: [
+          makeRecording({ recordingId: "rec-a", flightId: 10 }),
+          makeRecording({ recordingId: "rec-b", flightId: 11 }),
+        ],
+      }),
+    ];
+    render(<RecordingsTray cameraLabel={(flightId) => `Cam ${flightId}`} />);
+
+    expect(screen.getByText("Cam 10")).toBeTruthy();
+    expect(screen.getByText("Cam 11")).toBeTruthy();
+  });
+
+  it("discard set calls the store's discardGroup, not a per-clip discard", () => {
+    fakeStoreSeed.groups = [makeGroup({ groupId: "grp-1" })];
+    render(<RecordingsTray />);
+
+    fireEvent.click(screen.getByText("Discard set"));
+
+    expect(storeSpies.discardGroup).toHaveBeenCalledWith("grp-1");
+    expect(storeSpies.discard).not.toHaveBeenCalled();
+    expect(screen.queryByText(/grouped recording/i)).toBeNull();
+  });
+});
+
+describe("RecordingsTray - object URL lifecycle", () => {
+  it("revokes every outstanding object URL on unmount", () => {
+    fakeStoreSeed.recordings = [
+      makeRecording({ recordingId: "rec-1" }),
+      makeRecording({ recordingId: "rec-2" }),
+    ];
+    const { unmount } = render(<RecordingsTray />);
+    expect(URL.createObjectURL).toHaveBeenCalledTimes(2);
+
+    unmount();
+
+    expect(URL.revokeObjectURL).toHaveBeenCalledWith("blob:mock-0");
+    expect(URL.revokeObjectURL).toHaveBeenCalledWith("blob:mock-1");
+  });
+});