@ksp-gonogo/kerbcast-react 1.11.0 → 1.12.0-rc.1

package/src/CommandBrackets.tsx

@@ -1,10 +1,19 @@
 import {
+  COMMAND_AIM_ANCHOR_ID,
+  COMMAND_SUBJECT_ANCHOR_ID,
+  KERBCAST_ANCHOR_OWNER,
+  anchorPoint,
   commandReadout,
+  findAnchor,
+  frameToScreen,
   type EffectiveCommandTrack,
+  type FrameAnchor,
   type FrameUtSource,
 } from "@ksp-gonogo/kerbcast";
-import { useEffect, useState, type ReactNode } from "react";
+import { type ReactNode } from "react";
 import styled from "styled-components";
+import { useDisplayedFrame } from "./AnchorMarkers";
+import { useVideoBox } from "./videoBox";
 
 const BRACKET_STROKE_PX = 2;
 const BRACKET_MIN_HALF_PX = 14;
@@ -51,7 +60,10 @@ export interface BracketPoint {
 
 /** The bracket box, in the pixel space of the bracket SVG (the video element's box). */
 export interface BracketGeometry {
-  /** Box centre, which is the aim point. */
+  /**
+   * Box centre: where the subject is in the displayed frame, or the frame
+   * centre (the aim point) while that is not known.
+   */
   cx: number;
   cy: number;
   /** Half the box side in display px. */
@@ -65,20 +77,22 @@ export interface BracketGeometry {
 }
 
 /**
- * The bracket box centred on the displayed frame. `bracketHalfPx` is in
- * capture px of a `frameHeightPx`-tall frame, so it scales by the displayed
- * height; a missing half-size draws the minimum box.
+ * The bracket box, centred on the displayed frame or on `centre` (in the
+ * same pixel space as `rect`). `bracketHalfPx` is in capture px of a
+ * `frameHeightPx`-tall frame, so it scales by the displayed height; a
+ * missing half-size draws the minimum box.
  */
 export function bracketGeometry(
   rect: ContentRect,
   bracketHalfPx: number | null,
   frameHeightPx: number,
+  centre?: BracketPoint | null,
 ): BracketGeometry {
   const scale = frameHeightPx > 0 ? rect.height / frameHeightPx : 1;
   const half = Math.max(BRACKET_MIN_HALF_PX, (bracketHalfPx ?? 0) * scale);
   const arm = Math.max(BRACKET_MIN_ARM_PX, BRACKET_ARM_FRACTION * half * 2);
-  const cx = rect.x + rect.width / 2;
-  const cy = rect.y + rect.height / 2;
+  const cx = centre ? centre.x : rect.x + rect.width / 2;
+  const cy = centre ? centre.y : rect.y + rect.height / 2;
   return {
     cx,
     cy,
@@ -118,6 +132,54 @@ export interface CommandBracketContext {
   displayUt: number;
   utSource: FrameUtSource | "override" | null;
   state: EffectiveCommandTrack;
+  /**
+   * The subject's anchor in the displayed frame: where the game projected
+   * the craft, whether it is in frame and whether something hides it.
+   * `null` without one (an older sidecar or plugin, or before the first
+   * stamped frame), when the box is centred on the frame instead.
+   */
+  subject?: FrameAnchor | null;
+  /**
+   * True while the aim lies off the frame (the view is still turning onto
+   * it): the box then sits on the frame's edge nearest the aim, with a
+   * chevron pointing on toward it.
+   */
+  aimOffscreen?: boolean;
+}
+
+/** Whether `p` lies inside the box `g`. */
+function holds(g: BracketGeometry, p: BracketPoint): boolean {
+  return p.x >= g.topLeft.x && p.x <= g.bottomRight.x && p.y >= g.topLeft.y && p.y <= g.bottomRight.y;
+}
+
+/** `g` moved so the whole box lies inside `rect`. */
+function clampToRect(g: BracketGeometry, rect: ContentRect): BracketGeometry {
+  const clamp = (v: number, lo: number, hi: number) => (lo > hi ? (lo + hi) / 2 : Math.min(hi, Math.max(lo, v)));
+  const cx = clamp(g.cx, rect.x + g.half, rect.x + rect.width - g.half);
+  const cy = clamp(g.cy, rect.y + g.half, rect.y + rect.height - g.half);
+  return {
+    ...g,
+    cx,
+    cy,
+    topLeft: { x: cx - g.half, y: cy - g.half },
+    bottomRight: { x: cx + g.half, y: cy + g.half },
+  };
+}
+
+/** A chevron just outside the box, pointing from its centre toward `toward`. */
+function edgeCue(g: BracketGeometry, toward: BracketPoint): string | null {
+  const dx = toward.x - g.cx;
+  const dy = toward.y - g.cy;
+  const len = Math.hypot(dx, dy);
+  if (!(len > 0)) return null;
+  const ux = dx / len;
+  const uy = dy / len;
+  const tipX = g.cx + ux * (g.half + g.arm);
+  const tipY = g.cy + uy * (g.half + g.arm);
+  const backX = tipX - ux * g.arm;
+  const backY = tipY - uy * g.arm;
+  const w = g.arm * 0.6;
+  return `M${backX - uy * w} ${backY + ux * w}L${tipX} ${tipY}L${backX + uy * w} ${backY - ux * w}`;
 }
 
 /**
@@ -143,8 +205,8 @@ export interface CommandBracketOverlay {
   readout?: (defaultText: string, ctx: CommandBracketContext) => string | null;
 }
 
-function cameraCornerStyle(state: EffectiveCommandTrack): CommandBracketCornerStyle {
-  return state.occluded
+function cameraCornerStyle(occluded: boolean): CommandBracketCornerStyle {
+  return occluded
     ? { colour: COMMAND_BRACKET_COLOURS.occluded, dashed: true }
     : { colour: COMMAND_BRACKET_COLOURS.clear, dashed: false };
 }
@@ -160,41 +222,6 @@ function applyCorner(
   };
 }
 
-/** Tracks the rendered box and intrinsic size of a video element. */
-function useVideoBox(video: HTMLVideoElement | null) {
-  const [box, setBox] = useState({ 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;
-}
-
 export interface CommandBracketsProps {
   state: EffectiveCommandTrack;
   displayUt: number;
@@ -204,14 +231,35 @@ export interface CommandBracketsProps {
   /** Frame aspect to assume until the video reports its own size. */
   fallbackSize?: { width: number; height: number } | null;
   overlay?: CommandBracketOverlay | null;
+  /**
+   * The subject's anchor in the displayed frame. While it is visible and no
+   * command lock is held the box sits on it and takes its size from it.
+   */
+  subject?: FrameAnchor | null;
+  /** The capture frame size `subject` is in (the stamp's width and height). */
+  subjectFrameSize?: { width: number; height: number } | null;
+  /**
+   * The aim anchor in the displayed frame. The aimed box sits on it rather
+   * than on the frame centre, so it stays on the aim while the view turns
+   * onto a moved one.
+   */
+  aim?: FrameAnchor | null;
 }
 
 /**
- * Target brackets for a command camera feed: the aim point sits at frame
- * centre, so the box is always centred on the displayed video. Both corners
- * show the camera axis by default; an overlay can restyle either and draw
- * its own marks. Without a fix, or over a blanked feed, the default corners
- * are left out but the overlay and readout still run.
+ * Target brackets for a command camera feed. With no command lock held and
+ * the subject's anchor visible in the displayed frame, the box sits on the
+ * craft where the game saw it, so it stays on the craft when an aim points
+ * elsewhere; while the aimed box is in frame and holds the craft it is drawn
+ * instead, since it frames the craft's whole extent as the view does. Otherwise (the anchor out of frame or occluded, which then
+ * carries no position, no anchor at all, or a command authority holding the
+ * lock) the box is the 1.11 one: on the aim (the frame centre, or the aim
+ * anchor while the view turns onto a moved aim), sized from the aimed range,
+ * red and dashed when the aim line is occluded. `ctx.subject` always
+ * carries the anchor, so a consumer can draw it as a second mark. An overlay
+ * can restyle either corner and draw its own marks. Without a fix, or over a
+ * blanked feed, the default corners are left out but the overlay and readout
+ * still run.
  */
 export function CommandBrackets({
   state,
@@ -220,6 +268,9 @@ export function CommandBrackets({
   video,
   fallbackSize,
   overlay,
+  subject,
+  subjectFrameSize,
+  aim,
 }: CommandBracketsProps) {
   const { boxW, boxH, mediaW, mediaH } = useVideoBox(video);
   const rect = containedContentRect(
@@ -228,7 +279,36 @@ export function CommandBrackets({
     mediaW || fallbackSize?.width || 0,
     mediaH || fallbackSize?.height || 0,
   );
-  const g = bracketGeometry(rect, state.bracketHalfPx, state.frameHeightPx || mediaH);
+  const frameW = subjectFrameSize?.width || mediaW || fallbackSize?.width || 0;
+  const frameH = subjectFrameSize?.height || mediaH || fallbackSize?.height || 0;
+  /* Under the lock the box is the authority's aim, as in 1.11. */
+  const point =
+    subject && !state.authority && frameW > 0 && frameH > 0 ? anchorPoint(subject) : null;
+  const placed = point !== null;
+  const aimPoint = aim && frameW > 0 && frameH > 0 ? anchorPoint(aim) : null;
+  const aimScreen = aimPoint ? frameToScreen(aimPoint, frameW, frameH, { ...rect, scale: 1 }) : null;
+  const aimOffscreen = !point && !!aimScreen && (!aim?.inFrame || !!aim?.behind);
+  const aimed = bracketGeometry(rect, state.bracketHalfPx, state.frameHeightPx || mediaH, aimScreen);
+  const subjectScreen = point ? frameToScreen(point, frameW, frameH, { ...rect, scale: 1 }) : null;
+  /*
+   * The aimed box, when it is in frame and holds the subject, frames the
+   * craft as the view does: around a craft and its open parachute rather
+   * than a sphere about its centre of mass.
+   */
+  const framed =
+    !!subjectScreen &&
+    !!aimScreen &&
+    !!aim?.inFrame &&
+    !aim?.behind &&
+    state.bracketHalfPx != null &&
+    holds(aimed, subjectScreen);
+  const unclamped =
+    subjectScreen && !framed
+      ? bracketGeometry(rect, subject?.apparentRadiusPx ?? null, frameH, subjectScreen)
+      : aimed;
+  /* An aim off the frame (mid-slew) keeps the box on the edge nearest it, with a cue pointing on. */
+  const g = aimOffscreen ? clampToRect(unclamped, rect) : unclamped;
+  const cue = aimOffscreen && aimScreen ? edgeCue(g, aimScreen) : null;
   const ctx: CommandBracketContext = {
     geometry: g,
     width: boxW,
@@ -236,23 +316,32 @@ export function CommandBrackets({
     displayUt,
     utSource: utSource ?? null,
     state,
+    subject: subject ?? null,
+    aimOffscreen,
   };
   const overrides =
     typeof overlay?.corners === "function" ? overlay.corners(ctx) : overlay?.corners;
-  const camera = cameraCornerStyle(state);
+  const camera = cameraCornerStyle(placed ? !!subject?.occluded : state.occluded);
   const topLeft = applyCorner(camera, overrides?.topLeft);
   const bottomRight = applyCorner(camera, overrides?.bottomRight);
   const { x: left, y: top } = g.topLeft;
   const { x: right, y: bottom } = g.bottomRight;
   const blanked = !!state.blank;
   const drawCorners = state.hasFix && !blanked;
-  const defaultReadout = blanked ? "" : commandReadout(state);
+  /* A feed waiting for its target says so itself; NO FIX would only repeat it. */
+  const defaultReadout = blanked || state.waitingForTarget ? "" : commandReadout(state);
   const readout = overlay?.readout ? overlay.readout(defaultReadout, ctx) : defaultReadout;
 
   return (
     <>
       {(drawCorners || overlay?.render) && (
-        <BracketSvg aria-hidden="true" data-camera-axis={state.camera} width={boxW} height={boxH}>
+        <BracketSvg
+          aria-hidden="true"
+          data-camera-axis={state.camera}
+          data-subject={subject ? (placed ? "placed" : "centred") : undefined}
+          width={boxW}
+          height={boxH}
+        >
           {drawCorners && !topLeft.hidden && (
             <path
               data-corner="topLeft"
@@ -273,6 +362,15 @@ export function CommandBrackets({
               style={{ stroke: bottomRight.colour }}
             />
           )}
+          {drawCorners && cue && (
+            <path
+              data-aim-cue=""
+              d={cue}
+              fill="none"
+              strokeWidth={g.stroke}
+              style={{ stroke: camera.colour }}
+            />
+          )}
           {overlay?.render && <g data-bracket-overlay="">{overlay.render(ctx)}</g>}
         </BracketSvg>
       )}
@@ -288,6 +386,25 @@ export function CommandBrackets({
   );
 }
 
+/**
+ * CommandBrackets fed with the subject's and the aim's anchors from each frame of
+ * `flightId` that `video` presents. Re-renders at the frame rate, which is
+ * why it is its own component.
+ */
+export function LiveCommandBrackets({
+  flightId,
+  ...props
+}: CommandBracketsProps & { flightId: number | null }) {
+  const frame = useDisplayedFrame(true, flightId, props.video);
+  const subject = findAnchor(frame?.anchors, COMMAND_SUBJECT_ANCHOR_ID, KERBCAST_ANCHOR_OWNER);
+  const aim = findAnchor(frame?.anchors, COMMAND_AIM_ANCHOR_ID, KERBCAST_ANCHOR_OWNER);
+  const size =
+    frame?.frameWidth && frame.frameHeight
+      ? { width: frame.frameWidth, height: frame.frameHeight }
+      : null;
+  return <CommandBrackets {...props} subject={subject} subjectFrameSize={size} aim={aim} />;
+}
+
 /** Reason a command feed is blanked, centred on black over the feed. */
 export function CommandBlank({ reason }: { reason: string }) {
   return (

package/src/KerbalFaceFeed.tsx

@@ -3,7 +3,7 @@
  *
  * 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
+ * surface 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).

package/src/RecordingsTray.test.tsx

@@ -153,6 +153,21 @@ describe("RecordingsTray - single clips", () => {
     expect(screen.getByText(/unsaved clips/i)).toBeTruthy();
   });
 
+  it("says why a clip stopped on its own, and nothing for one a person stopped", () => {
+    fakeStoreSeed.recordings = [
+      makeRecording({ recordingId: "rec-1", endedBy: "camera-gone" }),
+      makeRecording({ recordingId: "rec-2", endedBy: "disconnected" }),
+      makeRecording({ recordingId: "rec-3", endedBy: "feed-closed" }),
+      makeRecording({ recordingId: "rec-4", endedBy: "user" }),
+    ];
+    render(<RecordingsTray />);
+    expect(screen.getAllByText(/stopped:/i).map((el) => el.textContent)).toEqual([
+      "Stopped: the camera went away",
+      "Stopped: the connection was lost",
+      "Stopped: its feed was closed",
+    ]);
+  });
+
   it("falls back to 'Camera <flightId>' when no cameraLabel prop is given", () => {
     fakeStoreSeed.recordings = [makeRecording({ recordingId: "rec-1", flightId: 7 })];
     render(<RecordingsTray />);

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;
+}