@ksp-gonogo/kerbcast-react 1.6.2 → 1.7.0

package/src/KerbalFaceFeed.tsx

@@ -0,0 +1,236 @@
+/**
+ * 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 { FeedAction, CameraStreamHook } from "./CameraFeed";
+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;
+`;
+
+const ActionBar = styled.div`
+  position: absolute;
+  top: 4px;
+  right: 4px;
+  display: flex;
+  gap: 4px;
+  z-index: 2;
+`;
+
+const ActionButton = styled.button<{ $active?: boolean }>`
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 22px;
+  height: 22px;
+  padding: 0;
+  border: none;
+  border-radius: 3px;
+  cursor: pointer;
+  color: #fff;
+  background: ${(p) => (p.$active ? "rgba(255,255,255,0.28)" : "rgba(0,0,0,0.45)")};
+`;
+
+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 && (
+        <ActionBar>
+          {actions.map((a) => (
+            <ActionButton
+              key={a.id}
+              type="button"
+              aria-label={a.label}
+              title={a.label}
+              aria-pressed={a.active}
+              $active={a.active}
+              onClick={a.onClick}
+            >
+              {a.icon}
+            </ActionButton>
+          ))}
+        </ActionBar>
+      )}
+      {children && <OverlayLayer>{children}</OverlayLayer>}
+    </Frame>
+  );
+}

package/src/context.test.tsx

@@ -0,0 +1,94 @@
+import { describe, expect, it, vi } from "vitest";
+import type { KerbcastClient } from "@ksp-gonogo/kerbcast";
+import { createClientDisplaySizes } from "./context";
+
+/**
+ * A client stub that only records reportDisplaySize calls. The registry is the
+ * per-consumer MAX collapse across every mounted reporter for one flightId, so
+ * a spotlight and a tiny avatar of the same camera resolve to one report = max,
+ * and a departing big reporter relaxes the stream back down (the v1.6.3
+ * "don't pin large" discipline at the client edge).
+ */
+function fakeClient() {
+  const reports: Array<{ flightId: number; width: number; height: number }> = [];
+  const client = {
+    reportDisplaySize: vi.fn(async (flightId: number, width: number, height: number) => {
+      reports.push({ flightId, width, height });
+    }),
+  } as unknown as KerbcastClient;
+  return { client, reports };
+}
+
+describe("createClientDisplaySizes", () => {
+  it("reports the measured size for a single reporter", () => {
+    const { client, reports } = fakeClient();
+    const reg = createClientDisplaySizes(client);
+    reg.report(1, "a", 40, 40);
+    expect(reports).toEqual([{ flightId: 1, width: 40, height: 40 }]);
+  });
+
+  it("collapses two reporters of one camera to a single MAX report", () => {
+    const { client, reports } = fakeClient();
+    const reg = createClientDisplaySizes(client);
+    reg.report(1, "small", 40, 40);
+    reg.report(1, "big", 512, 512);
+    // 40 first, then bumped to the max 512 when the big one mounts.
+    expect(reports).toEqual([
+      { flightId: 1, width: 40, height: 40 },
+      { flightId: 1, width: 512, height: 512 },
+    ]);
+  });
+
+  it("maxes width and height independently across reporters", () => {
+    const { client, reports } = fakeClient();
+    const reg = createClientDisplaySizes(client);
+    reg.report(1, "a", 640, 360);
+    reg.report(1, "b", 320, 400);
+    expect(reports.at(-1)).toEqual({ flightId: 1, width: 640, height: 400 });
+  });
+
+  it("does not re-report when the max is unchanged", () => {
+    const { client, reports } = fakeClient();
+    const reg = createClientDisplaySizes(client);
+    reg.report(1, "big", 512, 512);
+    reg.report(1, "small", 40, 40); // below current max -> no new report
+    reg.report(1, "small", 44, 44); // still below -> no new report
+    expect(reports).toEqual([{ flightId: 1, width: 512, height: 512 }]);
+  });
+
+  it("relaxes to the next-largest reporter when the big one departs", () => {
+    const { client, reports } = fakeClient();
+    const reg = createClientDisplaySizes(client);
+    reg.report(1, "small", 40, 40);
+    reg.report(1, "big", 512, 512);
+    reg.clear(1, "big");
+    expect(reports.at(-1)).toEqual({ flightId: 1, width: 40, height: 40 });
+  });
+
+  it("sends nothing more once the last reporter departs (backend forget clears it)", () => {
+    const { client, reports } = fakeClient();
+    const reg = createClientDisplaySizes(client);
+    reg.report(1, "a", 40, 40);
+    const countBefore = reports.length;
+    reg.clear(1, "a");
+    expect(reports.length).toBe(countBefore); // no extra report on empty
+  });
+
+  it("keeps separate maxes per flightId", () => {
+    const { client, reports } = fakeClient();
+    const reg = createClientDisplaySizes(client);
+    reg.report(1, "a", 40, 40);
+    reg.report(2, "b", 512, 512);
+    expect(reports).toEqual([
+      { flightId: 1, width: 40, height: 40 },
+      { flightId: 2, width: 512, height: 512 },
+    ]);
+  });
+
+  it("clearing an unknown reporter is a no-op", () => {
+    const { client, reports } = fakeClient();
+    const reg = createClientDisplaySizes(client);
+    reg.clear(99, "ghost");
+    expect(reports).toEqual([]);
+  });
+});

package/src/context.tsx

@@ -46,6 +46,78 @@ export function createClientSubscriptions(
   };
 }
 
+// ---------------------------------------------------------------------------
+// Display-size reporting seam
+// ---------------------------------------------------------------------------
+
+/**
+ * Collects each mounted feed's self-measured display size and drives the
+ * client's per-consumer `reportDisplaySize`. Multiple feeds can show the SAME
+ * camera at once (e.g. a tiny avatar and a spotlight of the same kerbal); the
+ * sidecar keys the auto-resolution max per CONSUMER, so those would clobber
+ * each other last-writer-wins. This collapses them at the client edge: it
+ * keeps the MAX display size across every mounted reporter for a flightId and
+ * sends one report per max-change. Co-located with the subscription refcount
+ * (same per-flightId lifetime) so one object owns everything this client is
+ * doing with camera N.
+ */
+export interface KerbcastDisplaySizes {
+  /** Register/update a reporter's measured size for a camera. */
+  report(flightId: number, instanceId: string, width: number, height: number): void;
+  /** Deregister a reporter (on unmount / flightId change). */
+  clear(flightId: number, instanceId: string): void;
+}
+
+/** Build the default per-flightId MAX display-size registry for a client. */
+export function createClientDisplaySizes(
+  client: KerbcastClient,
+): KerbcastDisplaySizes {
+  // flightId -> (instanceId -> measured size)
+  const perCamera = new Map<number, Map<string, { w: number; h: number }>>();
+  // Last size reported to the sidecar per flightId, so we send only on change.
+  const lastSent = new Map<number, { w: number; h: number }>();
+
+  function recompute(flightId: number): void {
+    const instances = perCamera.get(flightId);
+    if (!instances || instances.size === 0) {
+      // No reporters left. Drop bookkeeping and send nothing: the subscription
+      // release (unsubscribe -> sidecar remove_track -> forget_display_size)
+      // clears the sidecar side. Sending a spurious size here would fight it.
+      perCamera.delete(flightId);
+      lastSent.delete(flightId);
+      return;
+    }
+    let maxW = 0;
+    let maxH = 0;
+    for (const { w, h } of instances.values()) {
+      if (w > maxW) maxW = w;
+      if (h > maxH) maxH = h;
+    }
+    const prev = lastSent.get(flightId);
+    if (prev && prev.w === maxW && prev.h === maxH) return;
+    lastSent.set(flightId, { w: maxW, h: maxH });
+    client.reportDisplaySize(flightId, maxW, maxH).catch(() => {});
+  }
+
+  return {
+    report(flightId: number, instanceId: string, width: number, height: number): void {
+      let instances = perCamera.get(flightId);
+      if (!instances) {
+        instances = new Map();
+        perCamera.set(flightId, instances);
+      }
+      instances.set(instanceId, { w: width, h: height });
+      recompute(flightId);
+    },
+    clear(flightId: number, instanceId: string): void {
+      const instances = perCamera.get(flightId);
+      if (!instances) return;
+      instances.delete(instanceId);
+      recompute(flightId);
+    },
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Context shape
 // ---------------------------------------------------------------------------
@@ -53,6 +125,7 @@ export function createClientSubscriptions(
 interface KerbcastContextValue {
   client: KerbcastClient;
   subscriptions: KerbcastSubscriptions;
+  displaySizes: KerbcastDisplaySizes;
 }
 
 const KerbcastContext = createContext<KerbcastContextValue | null>(null);
@@ -65,6 +138,8 @@ export interface KerbcastProviderProps {
   client: KerbcastClient;
   /** Override the subscription manager. Defaults to a refcounted per-client impl. */
   subscriptions?: KerbcastSubscriptions;
+  /** Override the display-size registry. Defaults to a per-flightId MAX impl. */
+  displaySizes?: KerbcastDisplaySizes;
   children: ReactNode;
 }
 
@@ -75,6 +150,7 @@ export interface KerbcastProviderProps {
 export function KerbcastProvider({
   client,
   subscriptions: subscriptionsProp,
+  displaySizes: displaySizesProp,
   children,
 }: KerbcastProviderProps): React.JSX.Element {
   // Create default subscriptions once per client. A ref so the object is
@@ -84,13 +160,20 @@ export function KerbcastProvider({
     defaultSubsRef.current = createClientSubscriptions(client);
   }
 
+  // Same for the display-size registry: one per client, stable across renders.
+  const defaultSizesRef = useRef<KerbcastDisplaySizes | null>(null);
+  if (defaultSizesRef.current === null) {
+    defaultSizesRef.current = createClientDisplaySizes(client);
+  }
+
   const value = useMemo(
     () => ({
       client,
       subscriptions: subscriptionsProp ?? defaultSubsRef.current!,
+      displaySizes: displaySizesProp ?? defaultSizesRef.current!,
     }),
     // eslint-disable-next-line react-hooks/exhaustive-deps
-    [client, subscriptionsProp],
+    [client, subscriptionsProp, displaySizesProp],
   );
 
   return (
@@ -127,3 +210,17 @@ export function useKerbcastSubscriptions(): KerbcastSubscriptions {
   }
   return ctx.subscriptions;
 }
+
+/**
+ * Return the `KerbcastDisplaySizes` registry from the nearest
+ * `KerbcastProvider`. Throws if called outside a provider.
+ */
+export function useKerbcastDisplaySizes(): KerbcastDisplaySizes {
+  const ctx = useContext(KerbcastContext);
+  if (!ctx) {
+    throw new Error(
+      "useKerbcastDisplaySizes must be used inside a KerbcastProvider",
+    );
+  }
+  return ctx.displaySizes;
+}

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([]);
+  });
+});