@ksp-gonogo/kerbcast-react 1.10.2 → 1.11.0-rc.10

package/src/hooks/useCommandDisplayUt.test.tsx

@@ -0,0 +1,156 @@
+/**
+ * Display UT for command feeds and the displayed-frame UT hook: the presented
+ * frame's own capture stamp wins over the capture clock, every value says
+ * which it is, and a host override beats both.
+ */
+
+import { KerbcastClient, type CommandTrackEvent } from "@ksp-gonogo/kerbcast";
+import { MockSidecar } 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 { crossesEvent, useCommandDisplayUt, type CommandDisplayUt } from "./useCommandDisplayUt";
+import { useDisplayedFrameUt } from "./useDisplayedFrameUt";
+
+async function connected() {
+  const sidecar = new MockSidecar();
+  const client = new KerbcastClient(
+    { host: "h", port: 1, negotiate: (o) => sidecar.negotiate(o) },
+    sidecar.createTransport(),
+  );
+  await act(async () => {
+    await client.connect([], { slots: 4 });
+    sidecar.open();
+    sidecar.setConnectionState("connected");
+  });
+  sidecar.fireSettingsState({ throttleMainScreen: false, captureUt: 1000, timeWarpRate: 1 });
+  return { client, sidecar };
+}
+
+/** A video element whose frames the test presents by hand. */
+function fakeVideo() {
+  let pending: ((now: number, meta: object) => void) | null = null;
+  const video = {
+    requestVideoFrameCallback: (cb: (now: number, meta: object) => void) => {
+      pending = cb;
+      return 1;
+    },
+    cancelVideoFrameCallback: () => {
+      pending = null;
+    },
+  } as unknown as HTMLVideoElement;
+  const present = (rtpTimestamp?: number) =>
+    act(() => {
+      const cb = pending;
+      pending = null;
+      cb?.(0, rtpTimestamp === undefined ? {} : { rtpTimestamp });
+    });
+  return { video, present };
+}
+
+const event = (ut: number): CommandTrackEvent =>
+  ({ ut, occluded: true, sunlit: true, occluder: "", blank: "" }) as CommandTrackEvent;
+
+let last: CommandDisplayUt | null | undefined;
+function CommandProbe(props: {
+  override?: number;
+  events?: CommandTrackEvent[];
+  video: HTMLVideoElement | null;
+}) {
+  last = useCommandDisplayUt(true, props.override, props.events, 7, props.video);
+  return null;
+}
+
+afterEach(() => {
+  cleanup();
+  last = undefined;
+});
+
+describe("useCommandDisplayUt", () => {
+  it("is estimated from the clock until an exactly stamped frame is shown", async () => {
+    const { client, sidecar } = await connected();
+    const { video, present } = fakeVideo();
+    render(
+      <KerbcastProvider client={client}>
+        <CommandProbe video={video} />
+      </KerbcastProvider>,
+    );
+    expect(last?.source).toBe("estimated");
+
+    sidecar.fireFrameStamp({ flightId: 7, rtpTimestamp: 4500, captureUt: 999.8, captureEpoch: 0 });
+    present(4500);
+    expect(last).toEqual({ ut: 999.8, source: "exact" });
+
+    /* An unstamped frame falls back to the clock, and says so. */
+    present(9000);
+    expect(last?.source).toBe("estimated");
+  });
+
+  it("re-renders when an exact frame steps across an event", async () => {
+    const { client, sidecar } = await connected();
+    const { video, present } = fakeVideo();
+    render(
+      <KerbcastProvider client={client}>
+        <CommandProbe video={video} events={[event(999.9)]} />
+      </KerbcastProvider>,
+    );
+    sidecar.fireFrameStamp({ flightId: 7, rtpTimestamp: 1, captureUt: 999.8, captureEpoch: 0 });
+    sidecar.fireFrameStamp({ flightId: 7, rtpTimestamp: 2, captureUt: 999.85, captureEpoch: 0 });
+    sidecar.fireFrameStamp({ flightId: 7, rtpTimestamp: 3, captureUt: 999.95, captureEpoch: 0 });
+    present(1);
+    expect(last?.ut).toBe(999.8);
+    /* Same side of the event: no re-render needed, the value shown holds. */
+    present(2);
+    expect(last?.ut).toBe(999.8);
+    present(3);
+    expect(last?.ut).toBe(999.95);
+  });
+
+  it("prefers a host override over the displayed frame", async () => {
+    const { client, sidecar } = await connected();
+    const { video, present } = fakeVideo();
+    render(
+      <KerbcastProvider client={client}>
+        <CommandProbe video={video} override={990} />
+      </KerbcastProvider>,
+    );
+    sidecar.fireFrameStamp({ flightId: 7, rtpTimestamp: 1, captureUt: 999.8, captureEpoch: 0 });
+    present(1);
+    expect(last).toEqual({ ut: 990, source: "override" });
+  });
+});
+
+describe("crossesEvent", () => {
+  it("counts an event the display moves onto or past, in either direction", () => {
+    const events = [event(10)];
+    expect(crossesEvent(events, 9, 10)).toBe(true);
+    expect(crossesEvent(events, 11, 9)).toBe(true);
+    expect(crossesEvent(events, 10, 11)).toBe(false);
+    expect(crossesEvent(undefined, 0, 100)).toBe(false);
+  });
+});
+
+describe("useDisplayedFrameUt", () => {
+  let frame: ReturnType<typeof useDisplayedFrameUt> | undefined;
+  function FrameProbe({ video }: { video: HTMLVideoElement }) {
+    frame = useDisplayedFrameUt(7, video);
+    return null;
+  }
+
+  it("reports every presented frame with its source", async () => {
+    const { client, sidecar } = await connected();
+    const { video, present } = fakeVideo();
+    render(
+      <KerbcastProvider client={client}>
+        <FrameProbe video={video} />
+      </KerbcastProvider>,
+    );
+    expect(frame).toBeNull();
+    sidecar.fireFrameStamp({ flightId: 7, rtpTimestamp: 77, captureUt: 999.5, captureEpoch: 4 });
+    present(77);
+    expect(frame).toMatchObject({ ut: 999.5, epoch: 4, source: "exact", rtpTimestamp: 77 });
+    /* Unstamped: bounded by the last exactly identified frame. */
+    present(78);
+    expect(frame).toMatchObject({ ut: 999.5, source: "estimated", rtpTimestamp: 77 });
+  });
+});

package/src/hooks/useCommandDisplayUt.ts

@@ -0,0 +1,135 @@
+import { useEffect, useReducer, useRef } from "react";
+import {
+  extrapolateCaptureUt,
+  type DisplayedFrameUt,
+  type FrameUtSource,
+  type CommandTrackEvent,
+} from "@ksp-gonogo/kerbcast";
+import { useKerbcastClient } from "../context";
+import { nowMs } from "../timing";
+
+export { MAX_UT_EXTRAPOLATION_MS, extrapolateCaptureUt } from "@ksp-gonogo/kerbcast";
+
+const TICK_MS = 500;
+
+/** Real milliseconds until the first event after `displayUt`, or `null` when none is ahead. */
+export function msUntilNextEvent(
+  events: readonly CommandTrackEvent[] | undefined,
+  displayUt: number,
+  warpRate: number,
+): number | null {
+  if (!events?.length || !(warpRate > 0)) return null;
+  let next = Infinity;
+  for (const e of events) if (e.ut > displayUt && e.ut < next) next = e.ut;
+  return next === Infinity ? null : ((next - displayUt) / warpRate) * 1000;
+}
+
+/** Whether an event's UT lies in `(from, to]`, i.e. moving the display from `from` to `to` changes the state in force. */
+export function crossesEvent(
+  events: readonly CommandTrackEvent[] | undefined,
+  from: number,
+  to: number,
+): boolean {
+  if (!events?.length) return false;
+  const lo = Math.min(from, to);
+  const hi = Math.max(from, to);
+  return events.some((e) => e.ut > lo && e.ut <= hi);
+}
+
+/** The UT a command feed is showing and where it came from; `"override"` is a host's own value. */
+export interface CommandDisplayUt {
+  ut: number;
+  source: FrameUtSource | "override";
+}
+
+/**
+ * The UT a command feed is showing. An explicit `override` (a host with its
+ * own delayed playout) wins. Otherwise, given the feed's `flightId` and the
+ * `video` element showing it, the presented frame's own capture stamp is
+ * used (`source: "exact"`); without one, the client's capture clock is
+ * interpolated to now (`"estimated"`). Re-evaluated twice a second while
+ * `enabled` so readout ages keep counting, and again the moment the
+ * displayed UT reaches the next of `events`, so a state change lands on its
+ * frame rather than on the next tick. `null` when nothing is known.
+ */
+export function useCommandDisplayUt(
+  enabled: boolean,
+  override?: number,
+  events?: readonly CommandTrackEvent[],
+  flightId?: number | null,
+  video?: HTMLVideoElement | null,
+): CommandDisplayUt | null {
+  const client = useKerbcastClient();
+  const sample = useRef<{ captureUt: number | null; warpRate: number; at: number }>({
+    captureUt: client.clock.captureUt,
+    warpRate: client.clock.warpRate,
+    at: nowMs(),
+  });
+  const frame = useRef<DisplayedFrameUt | null>(null);
+  const shown = useRef<CommandDisplayUt | null>(null);
+  const eventsRef = useRef(events);
+  eventsRef.current = events;
+  const [, tick] = useReducer((c: number) => c + 1, 0);
+
+  useEffect(() => {
+    const take = () => {
+      const { captureUt, warpRate } = client.clock;
+      sample.current = { captureUt, warpRate, at: nowMs() };
+    };
+    take();
+    return client.on("settings-change", take);
+  }, [client]);
+
+  useEffect(() => {
+    if (!enabled) return;
+    const interval = setInterval(tick, TICK_MS);
+    return () => clearInterval(interval);
+  }, [enabled]);
+
+  /* Exact frames re-render only when they change what is drawn: a switch of
+     source, or a step across an event. Ages catch up on the tick. */
+  const overriding = override !== undefined;
+  useEffect(() => {
+    frame.current = null;
+    if (!enabled || overriding || flightId == null || !video) return;
+    return client.watchDisplayedFrames(flightId, video, (f) => {
+      frame.current = f.source === "exact" ? f : null;
+      const prev = shown.current;
+      if (!frame.current) {
+        if (prev?.source === "exact") tick();
+        return;
+      }
+      if (
+        prev === null ||
+        prev.source !== "exact" ||
+        crossesEvent(eventsRef.current, prev.ut, f.ut)
+      ) {
+        tick();
+      }
+    });
+  }, [client, enabled, overriding, flightId, video]);
+
+  const { captureUt, warpRate, at } = sample.current;
+  const exact = frame.current;
+  const displayUt: CommandDisplayUt | null = overriding
+    ? { ut: override, source: "override" }
+    : exact
+      ? { ut: exact.ut, source: "exact" }
+      : captureUt === null
+        ? null
+        : { ut: extrapolateCaptureUt(captureUt, warpRate, at, nowMs()), source: "estimated" };
+  shown.current = displayUt;
+  const untilEdge =
+    enabled && displayUt?.source === "estimated"
+      ? msUntilNextEvent(events, displayUt.ut, warpRate)
+      : null;
+
+  /* Edges further out than a tick are caught by a later render's timer. */
+  useEffect(() => {
+    if (untilEdge === null || untilEdge > TICK_MS) return;
+    const timer = setTimeout(tick, Math.max(0, untilEdge) + 1);
+    return () => clearTimeout(timer);
+  });
+
+  return displayUt;
+}

package/src/hooks/useDisplayedFrameUt.ts

@@ -0,0 +1,26 @@
+import { useEffect, useState } from "react";
+import type { DisplayedFrameUt } from "@ksp-gonogo/kerbcast";
+import { useKerbcastClient } from "../context";
+
+/**
+ * Mission time of the frame `video` is showing for camera `flightId`,
+ * updated on every presented frame (so the calling component re-renders at
+ * the video's frame rate). `source` says whether the UT is the frame's own
+ * capture stamp (`"exact"`) or the capture clock extrapolated
+ * (`"estimated"`). `null` until the first frame with a known UT, and while
+ * either argument is null. For per-frame work without re-rendering, use
+ * `client.watchDisplayedFrames` directly.
+ */
+export function useDisplayedFrameUt(
+  flightId: number | null,
+  video: HTMLVideoElement | null,
+): DisplayedFrameUt | null {
+  const client = useKerbcastClient();
+  const [frame, setFrame] = useState<DisplayedFrameUt | null>(null);
+  useEffect(() => {
+    setFrame(null);
+    if (flightId === null || !video) return;
+    return client.watchDisplayedFrames(flightId, video, setFrame);
+  }, [client, flightId, video]);
+  return frame;
+}

package/src/hooks/useReportDisplaySize.loop.test.tsx

@@ -0,0 +1,290 @@
+/**
+ * The render-size request must never feed the stream back into itself. A host
+ * that sizes the measured box from the stream (a frame at the video's aspect,
+ * a `<video>` at its own size) closes a loop: stream -> box -> request ->
+ * stream. These tests run that loop against a stand-in sidecar that delivers
+ * a stream of whatever size it is asked for (or smaller, or late) and assert
+ * the request settles instead of spiralling.
+ *
+ * Layout is faked: a ResizeObserver stub reports the px size in the measured
+ * element's inline style (or the tile's when it has none), once per change,
+ * on each animation frame the test steps through.
+ */
+
+import type { KerbcastClient } from "@ksp-gonogo/kerbcast";
+import { act, cleanup, render } from "@testing-library/react";
+import { useEffect, useRef, useState } from "react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { KerbcastProvider, type KerbcastDisplaySizes } from "../context";
+import { useReportDisplaySize, type Size } from "./useReportDisplaySize";
+
+const FRAME_MS = 16;
+const fakeClient = { on: () => () => {} } as unknown as KerbcastClient;
+
+let tile: Size = { width: 170, height: 400 };
+/* Re-renders the host after the tile changes, as a real layout change would. */
+let relayout = () => {};
+
+function resizeTile(size: Size) {
+  tile = size;
+  act(() => relayout());
+}
+
+interface Watched {
+  el: Element;
+  cb: ResizeObserverCallback;
+  last: string | null;
+}
+let watched: Watched[] = [];
+
+function boxOf(el: Element): Size {
+  const style = (el as HTMLElement).style;
+  if (style?.width.endsWith("px") && style.height.endsWith("px")) {
+    return { width: Number.parseFloat(style.width), height: Number.parseFloat(style.height) };
+  }
+  return tile;
+}
+
+function layout() {
+  for (const w of watched) {
+    const box = boxOf(w.el);
+    const key = `${box.width}x${box.height}`;
+    if (key === w.last) continue;
+    w.last = key;
+    w.cb(
+      [{ target: w.el, contentRect: box as DOMRectReadOnly } as ResizeObserverEntry],
+      {} as ResizeObserver,
+    );
+  }
+}
+
+/** Step `ms` of time a frame at a time, laying out after each. */
+function run(ms: number) {
+  for (let t = 0; t < ms; t += FRAME_MS) {
+    act(() => {
+      vi.advanceTimersByTime(FRAME_MS);
+    });
+    act(() => layout());
+  }
+}
+
+const FIRST_RENDER: Size = { width: 1280, height: 720 };
+
+type Mode = "fit" | "intrinsic" | "late-intrinsic" | "tile";
+
+/**
+ * The stand-in sidecar: after `latencyMs` the stream becomes `deliver(request)`,
+ * seen both as the video's own size and as the camera's render size.
+ */
+interface Sidecar {
+  reports: Size[];
+  deliver: (req: Size) => Size;
+  latencyMs: number;
+  streamBecomes: (size: Size) => void;
+}
+
+function makeSidecar(): Sidecar {
+  return {
+    reports: [],
+    deliver: (req) => req,
+    latencyMs: 300,
+    streamBecomes: () => {},
+  };
+}
+
+function registry(sidecar: Sidecar): KerbcastDisplaySizes {
+  return {
+    report: (_flightId, _id, width, height) => {
+      sidecar.reports.push({ width, height });
+      setTimeout(() => sidecar.streamBecomes(sidecar.deliver({ width, height })), sidecar.latencyMs);
+    },
+    clear: () => {},
+  };
+}
+
+/**
+ * A host whose measured box comes from the stream in one of a few natural
+ * ways, or ("tile") from layout alone.
+ */
+function Host({ mode, sidecar }: { mode: Mode; sidecar: Sidecar }) {
+  const frameRef = useRef<HTMLDivElement>(null);
+  const videoRef = useRef<HTMLVideoElement>(null);
+  const [render, setRender] = useState<Size>(FIRST_RENDER);
+  const [shown, setShown] = useState<Size | null>(null);
+  const [, bump] = useState(0);
+  relayout = () => bump((n) => n + 1);
+
+  sidecar.streamBecomes = (size) => {
+    const v = videoRef.current;
+    if (!v) return;
+    act(() => {
+      Object.defineProperty(v, "videoWidth", { value: size.width, configurable: true });
+      Object.defineProperty(v, "videoHeight", { value: size.height, configurable: true });
+      setRender(size);
+      v.dispatchEvent(new Event("resize"));
+    });
+  };
+
+  useEffect(() => {
+    const v = videoRef.current;
+    if (!v) return;
+    const onResize = () => {
+      bump((n) => n + 1);
+      const size = { width: v.videoWidth, height: v.videoHeight };
+      setTimeout(() => setShown(size), 1500);
+    };
+    v.addEventListener("resize", onResize);
+    return () => v.removeEventListener("resize", onResize);
+  }, []);
+
+  useReportDisplaySize(7, frameRef, { videoRef, streamSize: render });
+
+  const v = videoRef.current;
+  const stream = v && v.videoWidth > 0 ? { width: v.videoWidth, height: v.videoHeight } : render;
+  let style: React.CSSProperties | undefined;
+  if (mode === "fit") {
+    const aspect = stream.width / stream.height;
+    const w = Math.min(tile.width, tile.height * aspect);
+    style = { width: `${Math.floor(w)}px`, height: `${Math.floor(w / aspect)}px` };
+  } else if (mode === "intrinsic") {
+    style = { width: `${stream.width}px`, height: `${stream.height}px` };
+  } else if (mode === "late-intrinsic") {
+    const s = shown ?? FIRST_RENDER;
+    style = { width: `${s.width}px`, height: `${s.height}px` };
+  }
+  return (
+    <div ref={frameRef} style={style}>
+      <video ref={videoRef} />
+    </div>
+  );
+}
+
+function mount(mode: Mode, sidecar = makeSidecar()) {
+  render(
+    <KerbcastProvider client={fakeClient} displaySizes={registry(sidecar)}>
+      <Host mode={mode} sidecar={sidecar} />
+    </KerbcastProvider>,
+  );
+  run(FRAME_MS * 2);
+  return sidecar;
+}
+
+beforeEach(() => {
+  vi.useFakeTimers();
+  tile = { width: 170, height: 400 };
+  watched = [];
+  globalThis.ResizeObserver = class {
+    private readonly cb: ResizeObserverCallback;
+    constructor(cb: ResizeObserverCallback) {
+      this.cb = cb;
+    }
+    observe(el: Element) {
+      watched.push({ el, cb: this.cb, last: null });
+    }
+    unobserve() {}
+    disconnect() {
+      watched = watched.filter((w) => w.cb !== this.cb);
+    }
+  } as unknown as typeof ResizeObserver;
+});
+
+afterEach(() => {
+  cleanup();
+  vi.useRealTimers();
+});
+
+describe("useReportDisplaySize: a box sized from the stream", () => {
+  it("asks once for a tile sized by layout, at 16:9 whatever the tile's shape", () => {
+    const sidecar = mount("tile");
+    run(5000);
+    expect(sidecar.reports).toEqual([{ width: 176, height: 100 }]);
+  });
+
+  it("settles after the first request when the frame keeps the stream's aspect", () => {
+    const sidecar = mount("fit");
+    run(10_000);
+    expect(sidecar.reports).toEqual([{ width: 176, height: 100 }]);
+  });
+
+  it("does not ratchet down when a video at its own size arrives smaller than asked", () => {
+    const sidecar = makeSidecar();
+    sidecar.deliver = (req) => ({ width: req.width / 2, height: req.height / 2 });
+    mount("intrinsic", sidecar);
+    run(20_000);
+    expect(sidecar.reports).toEqual([{ width: 1280, height: 720 }]);
+  });
+
+  it("sends nothing when the stream changes size or shape on its own", () => {
+    const sidecar = mount("fit");
+    const before = sidecar.reports.length;
+    for (const size of [
+      { width: 96, height: 54 },
+      { width: 1920, height: 1080 },
+      { width: 160, height: 120 },
+      { width: 176, height: 400 },
+    ]) {
+      sidecar.streamBecomes(size);
+      run(3000);
+    }
+    expect(sidecar.reports.length - before).toBe(0);
+  });
+
+  it("sends nothing while the stream flips between two sizes", () => {
+    const sidecar = mount("fit");
+    const before = sidecar.reports.length;
+    for (let i = 0; i < 6; i++) {
+      sidecar.streamBecomes(i % 2 ? { width: 176, height: 128 } : { width: 176, height: 96 });
+      run(300);
+    }
+    run(5000);
+    expect(sidecar.reports.length - before).toBe(0);
+  });
+
+  it("lets at most one more request through when the box follows too late to be recognised", () => {
+    const sidecar = makeSidecar();
+    sidecar.deliver = (req) => ({ width: (req.width * 3) / 4, height: (req.height * 3) / 4 });
+    mount("late-intrinsic", sidecar);
+    run(30_000);
+    expect(sidecar.reports.length).toBeLessThanOrEqual(2);
+    for (const r of sidecar.reports) {
+      expect(r.width).toBeGreaterThanOrEqual(960);
+      expect(r.height).toBeGreaterThanOrEqual(540);
+    }
+    const settled = sidecar.reports.length;
+    run(30_000);
+    expect(sidecar.reports.length).toBe(settled);
+  });
+});
+
+describe("useReportDisplaySize: a genuine layout change", () => {
+  it("sends exactly one request, sized from the tile, for a resize dragged across several sizes", () => {
+    const sidecar = mount("tile");
+    const before = sidecar.reports.length;
+    for (const width of [240, 280, 320]) {
+      resizeTile({ width, height: 400 });
+      act(() => layout());
+    }
+    run(1000);
+    expect(sidecar.reports.slice(before)).toEqual([{ width: 320, height: 180 }]);
+  });
+
+  it("still reports once a stream-sized frame has settled", () => {
+    const sidecar = mount("fit");
+    run(10_000);
+    const before = sidecar.reports.length;
+    resizeTile({ width: 320, height: 400 });
+    run(1000);
+    expect(sidecar.reports.slice(before)).toEqual([{ width: 320, height: 180 }]);
+  });
+
+  it("still reports a resize right after a stream change that the stream can not explain", () => {
+    const sidecar = mount("fit");
+    run(10_000);
+    const before = sidecar.reports.length;
+    sidecar.streamBecomes({ width: 160, height: 90 });
+    resizeTile({ width: 640, height: 400 });
+    run(1000);
+    expect(sidecar.reports.slice(before)).toEqual([{ width: 640, height: 360 }]);
+  });
+});

package/src/hooks/useReportDisplaySize.test.tsx

@@ -11,7 +11,7 @@ import { useRef } from "react";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
 import { KerbcastProvider, type KerbcastDisplaySizes } from "../context";
-import { useReportDisplaySize } from "./useReportDisplaySize";
+import { displayReportSize, useReportDisplaySize } from "./useReportDisplaySize";
 
 // A controllable ResizeObserver: captures the callback so a test can fire a
 // resize with a chosen contentRect.
@@ -89,9 +89,18 @@ describe("useReportDisplaySize", () => {
         <Harness flightId={7} />
       </KerbcastProvider>,
     );
-    // 40x30 -> ceil to a 16-multiple = 48x32, reported without advancing timers.
+    // 40x30 -> width ceiled to a 16-multiple (48), height at 16:9 rounded to even (28), reported without advancing timers.
     fireResize(40, 30);
-    expect(reports).toEqual([{ flightId: 7, id: expect.any(String), w: 48, h: 32 }]);
+    expect(reports).toEqual([{ flightId: 7, id: expect.any(String), w: 48, h: 28 }]);
+  });
+
+  it("asks for the 16:9 picture that fits the box, never the box's shape", () => {
+    expect(displayReportSize(1024, 576)).toEqual({ width: 1024, height: 576 });
+    expect(displayReportSize(441, 246)).toEqual({ width: 448, height: 252 });
+    // A narrow, tall tile is limited by its width.
+    expect(displayReportSize(170, 400)).toEqual({ width: 176, height: 100 });
+    // A wide, short one by its height: the letterboxed picture is ~356x200.
+    expect(displayReportSize(800, 200)).toEqual({ width: 368, height: 208 });
   });
 
   it("reports a square (min edge) when square is set", () => {
@@ -113,12 +122,12 @@ describe("useReportDisplaySize", () => {
         <Harness flightId={7} />
       </KerbcastProvider>,
     );
-    fireResize(48, 48); // prompt first -> 48x48
+    fireResize(48, 48); // prompt first -> 48x28
     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 });
+    // 200 -> 208 wide at 16:9; the debounced resize now lands.
+    expect(reports.at(-1)).toMatchObject({ w: 208, h: 118 });
   });
 
   it("does not re-report a sub-bucket change", () => {
@@ -128,8 +137,8 @@ describe("useReportDisplaySize", () => {
         <Harness flightId={7} />
       </KerbcastProvider>,
     );
-    fireResize(40, 40); // -> 48x48
-    fireResize(44, 44); // still ceils to 48x48 -> no new report
+    fireResize(40, 40); // -> 48x28
+    fireResize(44, 44); // still ceils to 48x28 -> no new report
     act(() => vi.advanceTimersByTime(200));
     expect(reports).toHaveLength(1);
   });
@@ -181,6 +190,6 @@ describe("useReportDisplaySize", () => {
     expect(resizeCallback).toBeUndefined();
     rerender(view(true));
     fireResize(40, 30);
-    expect(reports).toEqual([{ flightId: 7, id: expect.any(String), w: 48, h: 32 }]);
+    expect(reports).toEqual([{ flightId: 7, id: expect.any(String), w: 48, h: 28 }]);
   });
 });