@ksp-gonogo/kerbcast-react 1.11.1 → 1.12.0-rc.2

package/src/RecordingsTray.tsx

@@ -22,7 +22,11 @@
  * camera registry; omit it for a plain "Camera <flightId>" fallback.
  */
 
-import type { GroupedRecordingHandle, RecordingHandle } from "@ksp-gonogo/kerbcast";
+import type {
+  GroupedRecordingHandle,
+  RecordingEndReason,
+  RecordingHandle,
+} from "@ksp-gonogo/kerbcast";
 import { useCallback, useEffect, useMemo, useReducer, useRef } from "react";
 import styled from "styled-components";
 import { useRecordings } from "./hooks/useRecordings";
@@ -123,6 +127,9 @@ function ClipRow({ rec, label, url, onDiscard }: ClipRowProps) {
         <ClipDetail>
           {formatDuration(rec.durationMs)} &middot; {formatBytes(rec.byteSize)}
         </ClipDetail>
+        {rec.endedBy && recordingEndNote(rec.endedBy) && (
+          <ClipDetail>{recordingEndNote(rec.endedBy)}</ClipDetail>
+        )}
       </ClipMeta>
       <ClipActions>
         {url && (
@@ -243,6 +250,23 @@ function formatUt(ut: number): string {
   return `T+${Math.round(ut)}s`;
 }
 
+/**
+ * A short line saying why a recording stopped on its own, or null for one a
+ * person stopped or that ran its set length.
+ */
+export function recordingEndNote(endedBy: RecordingEndReason): string | null {
+  switch (endedBy) {
+    case "camera-gone":
+      return "Stopped: the camera went away";
+    case "feed-closed":
+      return "Stopped: its feed was closed";
+    case "disconnected":
+      return "Stopped: the connection was lost";
+    default:
+      return null;
+  }
+}
+
 function formatDuration(ms: number): string {
   const totalSeconds = Math.max(0, Math.round(ms / 1000));
   const hours = Math.floor(totalSeconds / 3600);

package/src/hooks/useCommandDisplayUt.test.tsx

@@ -4,12 +4,12 @@
  * which it is, and a host override beats both.
  */
 
-import { KerbcastClient, type CommandTrackEvent } from "@ksp-gonogo/kerbcast";
+import { KerbcastClient, type CommandTrackEvent, type FrameCommandState } 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 { commandShownKey, crossesEvent, useCommandDisplayUt, type CommandDisplayUt } from "./useCommandDisplayUt";
 import { useDisplayedFrameUt } from "./useDisplayedFrameUt";
 
 async function connected() {
@@ -54,10 +54,11 @@ const event = (ut: number): CommandTrackEvent =>
 let last: CommandDisplayUt | null | undefined;
 function CommandProbe(props: {
   override?: number;
+  overrideCommand?: FrameCommandState;
   events?: CommandTrackEvent[];
   video: HTMLVideoElement | null;
 }) {
-  last = useCommandDisplayUt(true, props.override, props.events, 7, props.video);
+  last = useCommandDisplayUt(true, props.override, props.events, 7, props.video, props.overrideCommand);
   return null;
 }
 
@@ -106,6 +107,76 @@ describe("useCommandDisplayUt", () => {
     expect(last?.ut).toBe(999.95);
   });
 
+  it("carries the displayed frame's command state and re-renders when what it shows changes", async () => {
+    const { client, sidecar } = await connected();
+    const { video, present } = fakeVideo();
+    render(
+      <KerbcastProvider client={client}>
+        <CommandProbe video={video} />
+      </KerbcastProvider>,
+    );
+    const command = (rangeM: number, occluded = false) => ({
+      hasFix: true,
+      rangeM,
+      frameHeightPx: 720,
+      framingFits: true,
+      occluded,
+      occluder: occluded ? "Mun" : "",
+      sunlit: true,
+      subjectPersistentId: 42,
+    });
+    sidecar.fireFrameStamp({ flightId: 7, rtpTimestamp: 1, captureUt: 999.8, captureEpoch: 0, command: command(1500) });
+    sidecar.fireFrameStamp({ flightId: 7, rtpTimestamp: 2, captureUt: 999.85, captureEpoch: 0, command: command(1500.4) });
+    sidecar.fireFrameStamp({ flightId: 7, rtpTimestamp: 3, captureUt: 999.9, captureEpoch: 0, command: command(1500.4, true) });
+    present(1);
+    expect(last).toMatchObject({ ut: 999.8, source: "exact", command: { rangeM: 1500 } });
+    /* A range change below what the readout shows keeps the frame shown. */
+    present(2);
+    expect(last?.ut).toBe(999.8);
+    present(3);
+    expect(last).toMatchObject({ ut: 999.9, command: { occluded: true, occluder: "Mun" } });
+  });
+
+  it("keeps the command state of a frame it can only estimate, which lags the picture", async () => {
+    const { client, sidecar } = await connected();
+    const { video, present } = fakeVideo();
+    render(
+      <KerbcastProvider client={client}>
+        <CommandProbe video={video} />
+      </KerbcastProvider>,
+    );
+    const command: FrameCommandState = {
+      hasFix: true, rangeM: 900, frameHeightPx: 720, framingFits: true, occluded: false, occluder: "", sunlit: true, subjectPersistentId: 42,
+    };
+    sidecar.fireFrameStamp({ flightId: 7, rtpTimestamp: 1, captureUt: 999.8, captureEpoch: 0, command });
+    present(1);
+    /* A frame the browser cannot identify falls back to the last exact one: estimated, but its state still applies. */
+    present(55555);
+    expect(last).toMatchObject({ ut: 999.8, source: "estimated", command: { rangeM: 900 } });
+  });
+
+  it("takes a delayed host's own frame state with its override", async () => {
+    const { client } = await connected();
+    const command: FrameCommandState = {
+      hasFix: true, rangeM: 1200, frameHeightPx: 720, framingFits: true, occluded: true, occluder: "Mun", sunlit: true, subjectPersistentId: 42,
+    };
+    render(
+      <KerbcastProvider client={client}>
+        <CommandProbe video={null} override={950} overrideCommand={command} />
+      </KerbcastProvider>,
+    );
+    expect(last).toEqual({ ut: 950, source: "override", command });
+  });
+
+  it("matches the command state's shown key to what a viewer sees", () => {
+    const base = { hasFix: true, frameHeightPx: 720, framingFits: true, occluded: false, occluder: "", sunlit: true, subjectPersistentId: 1 };
+    expect(commandShownKey({ ...base, rangeM: 1500 })).toBe(commandShownKey({ ...base, rangeM: 1501 }));
+    expect(commandShownKey({ ...base, rangeM: 1500 })).not.toBe(commandShownKey({ ...base, rangeM: 1600 }));
+    expect(commandShownKey({ ...base, refusal: "stale" })).not.toBe(commandShownKey(base));
+    expect(commandShownKey({ ...base, waitingForTarget: true })).not.toBe(commandShownKey(base));
+    expect(commandShownKey(undefined)).toBe("");
+  });
+
   it("prefers a host override over the displayed frame", async () => {
     const { client, sidecar } = await connected();
     const { video, present } = fakeVideo();

package/src/hooks/useCommandDisplayUt.ts

@@ -4,6 +4,7 @@ import {
   type DisplayedFrameUt,
   type FrameUtSource,
   type CommandTrackEvent,
+  type FrameCommandState,
 } from "@ksp-gonogo/kerbcast";
 import { useKerbcastClient } from "../context";
 import { nowMs } from "../timing";
@@ -40,6 +41,37 @@ export function crossesEvent(
 export interface CommandDisplayUt {
   ut: number;
   source: FrameUtSource | "override";
+  /** The command state that rode with the displayed frame (1.12 and later), or the host's own with an override. */
+  command?: FrameCommandState;
+}
+
+/**
+ * What of a frame's command state a viewer can see change: the discrete
+ * fields whole, ranges to 3 significant figures, pixel sizes to half a
+ * pixel. Frames that agree on it draw the same, so they skip a re-render.
+ */
+export function commandShownKey(c: FrameCommandState | undefined): string {
+  if (!c) return "";
+  const sig = (v: number | undefined) => (v == null ? "" : Number(v.toPrecision(3)));
+  const half = (v: number | undefined) => (v == null ? "" : Math.round(v * 2));
+  return JSON.stringify([
+    c.hasFix,
+    sig(c.rangeM),
+    half(c.bracketHalfPx),
+    c.frameHeightPx,
+    c.framingFits,
+    half(c.trueOffsetPx),
+    c.occluded,
+    c.occluder,
+    c.sunlit,
+    c.blank ?? null,
+    c.authority?.owner ?? null,
+    c.subjectPersistentId,
+    c.refusal ?? null,
+    c.refusalCode ?? null,
+    c.refusalText ?? null,
+    c.waitingForTarget ?? false,
+  ]);
 }
 
 /**
@@ -50,7 +82,12 @@ export interface CommandDisplayUt {
  * 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.
+ * frame rather than on the next tick. The displayed frame's own command
+ * state comes back as `command`, re-rendering when what it shows changes:
+ * an exact frame's, an estimated one's (which lags the picture, so is never
+ * early; its own UT is used too, so events and lists stay on that frame),
+ * or with an override the host's own `overrideCommand`. `null` when
+ * nothing is known.
  */
 export function useCommandDisplayUt(
   enabled: boolean,
@@ -58,6 +95,7 @@ export function useCommandDisplayUt(
   events?: readonly CommandTrackEvent[],
   flightId?: number | null,
   video?: HTMLVideoElement | null,
+  overrideCommand?: FrameCommandState | null,
 ): CommandDisplayUt | null {
   const client = useKerbcastClient();
   const sample = useRef<{ captureUt: number | null; warpRate: number; at: number }>({
@@ -86,23 +124,27 @@ export function useCommandDisplayUt(
     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. */
+  /* Frames re-render only when they change what is drawn: a switch of
+     source, a step across an event, or a change the command state shows.
+     Ages catch up on the tick. An estimated frame is kept only for the
+     command state it carries. */
   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;
+      frame.current = f.source === "exact" || f.command ? f : null;
       const prev = shown.current;
       if (!frame.current) {
-        if (prev?.source === "exact") tick();
+        if (prev?.source === "exact" || prev?.command) tick();
         return;
       }
       if (
         prev === null ||
-        prev.source !== "exact" ||
-        crossesEvent(eventsRef.current, prev.ut, f.ut)
+        (f.source === "exact" && prev.source !== "exact") ||
+        (f.source !== "exact" && prev.source === "exact") ||
+        crossesEvent(eventsRef.current, prev.ut, f.ut) ||
+        commandShownKey(prev.command) !== commandShownKey(f.command)
       ) {
         tick();
       }
@@ -110,17 +152,21 @@ export function useCommandDisplayUt(
   }, [client, enabled, overriding, flightId, video]);
 
   const { captureUt, warpRate, at } = sample.current;
-  const exact = frame.current;
+  const seen = frame.current;
+  const withCommand = (d: CommandDisplayUt, c: FrameCommandState | null | undefined): CommandDisplayUt =>
+    c ? { ...d, command: c } : d;
   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" };
+    ? withCommand({ ut: override, source: "override" }, overrideCommand)
+    : seen?.source === "exact"
+      ? withCommand({ ut: seen.ut, source: "exact" }, seen.command)
+      : seen
+        ? withCommand({ ut: seen.ut, source: "estimated" }, seen.command)
+        : captureUt === null
+          ? null
+          : { ut: extrapolateCaptureUt(captureUt, warpRate, at, nowMs()), source: "estimated" };
   shown.current = displayUt;
   const untilEdge =
-    enabled && displayUt?.source === "estimated"
+    enabled && displayUt?.source === "estimated" && !seen
       ? msUntilNextEvent(events, displayUt.ut, warpRate)
       : null;
 

package/src/hooks/useKerbcastWaitingForSlot.ts

@@ -0,0 +1,25 @@
+import { useEffect, useState } from "react";
+import { useKerbcastClient } from "../context";
+
+/**
+ * Whether this client wants camera `flightId` but has no video slot to carry
+ * it (see `KerbcastCameraHandle.waitingForSlot`). False for a null id.
+ */
+export function useKerbcastWaitingForSlot(flightId: number | null): boolean {
+  const client = useKerbcastClient();
+  const [waiting, setWaiting] = useState(() =>
+    flightId === null ? false : client.camera(flightId).waitingForSlot,
+  );
+
+  useEffect(() => {
+    if (flightId === null) {
+      setWaiting(false);
+      return;
+    }
+    const cam = client.camera(flightId);
+    setWaiting(cam.waitingForSlot);
+    return cam.on("waiting", setWaiting);
+  }, [client, flightId]);
+
+  return waiting;
+}

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

@@ -31,13 +31,16 @@ function liveStream(): 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() };
+  camera(_flightId: number): {
+    readonly mediaStream: MediaStream | null;
+    on(): () => void;
+  } {
+    return { mediaStream: liveStream(), on: () => () => {} };
   }
   get clock(): { readonly captureUt: number | null } {
     return { captureUt: this.captureUt };
   }
-  on(_event: "settings-change", _handler: (data: unknown) => void): () => void {
+  on(): () => void {
     return () => {};
   }
 }

package/src/hooks/useRecordings.test.tsx

@@ -33,13 +33,16 @@ function liveStream(): 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() };
+  camera(_flightId: number): {
+    readonly mediaStream: MediaStream | null;
+    on(): () => void;
+  } {
+    return { mediaStream: liveStream(), on: () => () => {} };
   }
   get clock(): { readonly captureUt: number | null } {
     return { captureUt: this.captureUt };
   }
-  on(_event: "settings-change", _handler: (data: unknown) => void): () => void {
+  on(): () => void {
     return () => {};
   }
 }

package/src/hooks/useTargetBracketsPreference.ts

@@ -2,9 +2,18 @@ import { useCallback, useMemo, useState } from "react";
 
 const STORAGE_PREFIX = "kerbcast:target-brackets:";
 
-function readPreference(key: string): boolean {
+/* A preference saved under `legacyKey` moves to `key` the first time it is read. */
+function readPreference(key: string, legacyKey: string | null): boolean {
   try {
-    return globalThis.localStorage?.getItem(STORAGE_PREFIX + key) !== "0";
+    const storage = globalThis.localStorage;
+    if (!storage) return true;
+    const value = storage.getItem(STORAGE_PREFIX + key);
+    if (value !== null || legacyKey === null || legacyKey === key) return value !== "0";
+    const legacy = storage.getItem(STORAGE_PREFIX + legacyKey);
+    if (legacy === null) return true;
+    storage.setItem(STORAGE_PREFIX + key, legacy);
+    storage.removeItem(STORAGE_PREFIX + legacyKey);
+    return legacy !== "0";
   } catch {
     return true;
   }
@@ -22,11 +31,12 @@ function writePreference(key: string, on: boolean): void {
 /**
  * Whether target brackets are shown for one command camera, remembered per
  * camera in this browser. Defaults on. `key` is null for a feed with no
- * command camera, which reads as on and ignores toggles.
+ * command camera, which reads as on and ignores toggles. A preference saved
+ * under `legacyKey` (the key an older version used) is moved to `key`.
  */
-export function useTargetBracketsPreference(key: string | null): [boolean, () => void] {
+export function useTargetBracketsPreference(key: string | null, legacyKey: string | null = null): [boolean, () => void] {
   const [overrides, setOverrides] = useState<Record<string, boolean>>({});
-  const stored = useMemo(() => (key === null ? true : readPreference(key)), [key]);
+  const stored = useMemo(() => (key === null ? true : readPreference(key, legacyKey)), [key, legacyKey]);
   const on = key !== null && key in overrides ? overrides[key]! : stored;
   const toggle = useCallback(() => {
     if (key === null) return;

package/src/index.ts

@@ -27,6 +27,7 @@ export { useKerbcastStream } from "./hooks/useKerbcastStream";
 export { useKerbcastClock } from "./hooks/useKerbcastClock";
 export { useDisplayedFrameUt } from "./hooks/useDisplayedFrameUt";
 export { useKerbcastInFlight } from "./hooks/useKerbcastInFlight";
+export { useKerbcastWaitingForSlot } from "./hooks/useKerbcastWaitingForSlot";
 export { useReportDisplaySize } from "./hooks/useReportDisplaySize";
 export { useRecordings } from "./hooks/useRecordings";
 export type { RecordingsStore, ActiveRecordingInfo } from "./hooks/useRecordings";
@@ -68,6 +69,27 @@ export type {
   ContentRect,
 } from "./CommandBrackets";
 
+// Anchored markers: CameraFeed's `anchors` and `anchorOverlay`, and the
+// pieces for drawing a frame's anchors over a video of your own
+export {
+  AnchorMarkers,
+  ANCHOR_MARKER_COLOURS,
+  anchorMarkerGeometry,
+  useDisplayedFrame,
+} from "./AnchorMarkers";
+export type {
+  AnchorContext,
+  AnchorCorner,
+  AnchorCornerOverride,
+  AnchorCornerOverrides,
+  AnchorCornerStyle,
+  AnchorMarkerGeometry,
+  AnchorMarkerShape,
+  AnchorMarkersProps,
+  AnchorOverlay,
+  PlacedAnchor,
+} from "./AnchorMarkers";
+
 // FeedActionBar: the shared action row (tracking, fullscreen, PiP, quality,
 // close, REC) both CameraFeed and KerbalFaceFeed render, with the issue-#6
 // overflow (⋮) engine.
@@ -79,5 +101,5 @@ export { KerbalFaceFeed } from "./KerbalFaceFeed";
 export type { KerbalFaceFeedProps, KerbalFeedState } from "./KerbalFaceFeed";
 
 // RecordingsTray: a presentational drawer over the recordings store
-export { RecordingsTray } from "./RecordingsTray";
+export { RecordingsTray, recordingEndNote } from "./RecordingsTray";
 export type { RecordingsTrayProps } from "./RecordingsTray";

package/src/menuPositioning.ts

@@ -1,6 +1,6 @@
 /**
- * Shared geometry + behaviour for a dropdown portaled to document.body.
- * Used by CameraFeed's camera / quality / tracking menus and by
+ * Shared geometry + behaviour for a portaled dropdown (document.body, or the
+ * fullscreen element while one is fullscreen). 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.
  */
@@ -55,8 +55,19 @@ export function computeMenuPosition(
   return { ...inline, top };
 }
 
+/**
+ * Where a dropdown portals to. Only the fullscreen element and its
+ * descendants render while something is fullscreen, so a menu portaled to
+ * document.body then would open invisibly behind it.
+ */
+export function menuPortalRoot(): Element {
+  const d = document as Document & { webkitFullscreenElement?: Element | null };
+  return d.fullscreenElement ?? d.webkitFullscreenElement ?? document.body;
+}
+
 /*
- * Shared behaviour for a dropdown portaled to document.body: fixed position
+ * Shared behaviour for a dropdown portaled to document.body (or the
+ * fullscreen element, see menuPortalRoot): 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
@@ -92,13 +103,24 @@ export function usePortalMenu({ maxWidth, maxHeight, align }: MenuAnchor) {
 
   useEffect(() => {
     if (!open) return;
+    /* Capture phase and preventDefault so document-level Escape handlers
+       registered earlier (CameraFeed's exit-fullscreen key) see the press
+       as already consumed by the menu. */
     const onKeyDown = (e: KeyboardEvent) => {
       if (e.key === "Escape") {
+        e.preventDefault();
         e.stopPropagation();
         setOpen(false);
         triggerRef.current?.focus();
       }
     };
+    /* The portal root changes with fullscreen and no resize may fire (kiosk,
+       F11), so a menu left open would remount elsewhere with stale
+       coordinates. */
+    const onFullscreenChange = () => {
+      setOpen(false);
+      triggerRef.current?.focus();
+    };
     const onPointerDown = (e: PointerEvent) => {
       if (
         !menuRef.current?.contains(e.target as Node) &&
@@ -107,11 +129,15 @@ export function usePortalMenu({ maxWidth, maxHeight, align }: MenuAnchor) {
         setOpen(false);
       }
     };
-    document.addEventListener("keydown", onKeyDown);
+    document.addEventListener("keydown", onKeyDown, true);
     document.addEventListener("pointerdown", onPointerDown);
+    document.addEventListener("fullscreenchange", onFullscreenChange);
+    document.addEventListener("webkitfullscreenchange", onFullscreenChange);
     return () => {
-      document.removeEventListener("keydown", onKeyDown);
+      document.removeEventListener("keydown", onKeyDown, true);
       document.removeEventListener("pointerdown", onPointerDown);
+      document.removeEventListener("fullscreenchange", onFullscreenChange);
+      document.removeEventListener("webkitfullscreenchange", onFullscreenChange);
     };
   }, [open]);
 

package/src/sharedAnchors.ts

@@ -0,0 +1,67 @@
+import type { Anchor, KerbcastClient } from "@ksp-gonogo/kerbcast";
+
+/**
+ * A client holds one anchor set per camera, so feeds showing the same
+ * camera each claim their anchors here and the camera gets them all: the
+ * first claim of an id wins, and the set stops at the client's cap.
+ */
+const claims = new WeakMap<KerbcastClient, Map<number, Map<symbol, readonly Anchor[]>>>();
+
+/** Add `anchors` to `flightId`'s set until the returned release is called. */
+export function claimAnchors(
+  client: KerbcastClient,
+  flightId: number,
+  anchors: readonly Anchor[],
+): () => void {
+  let byFlight = claims.get(client);
+  if (!byFlight) {
+    byFlight = new Map();
+    claims.set(client, byFlight);
+  }
+  let feeds = byFlight.get(flightId);
+  if (!feeds) {
+    feeds = new Map();
+    byFlight.set(flightId, feeds);
+  }
+  const token = Symbol("anchors");
+  feeds.set(token, anchors);
+  publish(client, flightId, feeds);
+  return () => {
+    if (!feeds.delete(token)) return;
+    if (feeds.size === 0) byFlight.delete(flightId);
+    publish(client, flightId, feeds);
+  };
+}
+
+function publish(client: KerbcastClient, flightId: number, feeds: Map<symbol, readonly Anchor[]>): void {
+  const ids = new Map<string, string>();
+  const merged: Anchor[] = [];
+  let dropped = 0;
+  for (const list of feeds.values()) {
+    for (const a of list) {
+      const seen = ids.get(a.id);
+      if (seen !== undefined) {
+        if (seen !== JSON.stringify(a)) {
+          console.warn(`[kerbcast] two feeds on camera ${flightId} set different anchors with id ${a.id}; the first is kept`);
+        }
+        continue;
+      }
+      if (merged.length >= client.maxAnchorsPerCamera) {
+        dropped++;
+        continue;
+      }
+      ids.set(a.id, JSON.stringify(a));
+      merged.push(a);
+    }
+  }
+  if (dropped > 0) {
+    console.warn(`[kerbcast] ${dropped} anchors over the ${client.maxAnchorsPerCamera} per camera left out`);
+  }
+  if (merged.length === 0) {
+    void client.setAnchors(flightId, null).catch(() => {});
+    return;
+  }
+  client.setAnchors(flightId, merged).catch((err: unknown) => {
+    console.warn("[kerbcast] anchors refused", err);
+  });
+}

package/src/videoBox.ts

@@ -0,0 +1,49 @@
+import { useEffect, useState } from "react";
+
+export interface VideoBox {
+  boxW: number;
+  boxH: number;
+  mediaW: number;
+  mediaH: number;
+}
+
+/** Tracks the rendered box and intrinsic size of a video element. */
+export function useVideoBox(video: HTMLVideoElement | null): VideoBox {
+  const [box, setBox] = useState<VideoBox>({ boxW: 0, boxH: 0, mediaW: 0, mediaH: 0 });
+  useEffect(() => {
+    if (!video) return;
+    const measure = () => {
+      const next = {
+        boxW: video.clientWidth,
+        boxH: video.clientHeight,
+        mediaW: video.videoWidth,
+        mediaH: video.videoHeight,
+      };
+      setBox((prev) =>
+        prev.boxW === next.boxW &&
+        prev.boxH === next.boxH &&
+        prev.mediaW === next.mediaW &&
+        prev.mediaH === next.mediaH
+          ? prev
+          : next,
+      );
+    };
+    measure();
+    const observer = new ResizeObserver(measure);
+    observer.observe(video);
+    video.addEventListener("loadedmetadata", measure);
+    video.addEventListener("resize", measure);
+    return () => {
+      observer.disconnect();
+      video.removeEventListener("loadedmetadata", measure);
+      video.removeEventListener("resize", measure);
+    };
+  }, [video]);
+  return box;
+}
+
+/** The element's CSS `object-fit`, as the two fits a feed uses. */
+export function videoFit(video: HTMLVideoElement | null): "contain" | "cover" {
+  if (!video || typeof getComputedStyle !== "function") return "contain";
+  return getComputedStyle(video).objectFit === "cover" ? "cover" : "contain";
+}