@ksp-gonogo/kerbcast-react 1.10.3 → 1.11.0-rc.4

package/dist/CameraFeed.d.ts

@@ -1,5 +1,6 @@
 import type { CameraState, KerbcastClient } from "@ksp-gonogo/kerbcast";
 import { type FeedAction } from "./FeedActionBar";
+import { type CommandBracketOverlay } from "./CommandBrackets";
 /**
  * The consumer-supplied action shape, and the shared top-right action bar
  * both `CameraFeed` and `KerbalFaceFeed` render, live in `FeedActionBar`.
@@ -186,6 +187,26 @@ export interface CameraFeedProps {
      * {@link CameraStreamHook}.
      */
     useStream?: CameraStreamHook;
+    /**
+     * Draw target brackets and their readout over command camera feeds, with a
+     * per-feed "Target brackets" toggle in the action bar (on by default,
+     * remembered per camera in this browser). Default true. A blanked command
+     * feed shows its reason whatever this is set to.
+     */
+    enableTargetBrackets?: boolean;
+    /**
+     * Extra drawing, corner styling and readout text for this feed's target
+     * brackets. See {@link CommandBracketOverlay}.
+     */
+    targetBracketOverlay?: CommandBracketOverlay;
+    /**
+     * Mission UT the displayed video was captured at, for a host running its
+     * own delayed playout. Picks which command-track transition is in force and
+     * ages the readout. Defaults to the displayed frame's own capture UT where
+     * the browser reports frame RTP timestamps, else the client's capture
+     * clock interpolated to now.
+     */
+    displayUt?: number;
 }
 export interface CameraFeedHandle {
     stepCamera(delta: number): void;

package/dist/CameraFeed.js

@@ -1,16 +1,19 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
-import { PanZoomController, QualityPreset, TrackMode } from "@ksp-gonogo/kerbcast";
+import { CameraKind, CommandAimKind, CommandTargetEligibility, PanZoomController, QualityPreset, TrackMode, effectiveCommandTrack, formatCommandRange, } from "@ksp-gonogo/kerbcast";
 import { forwardRef, useCallback, useEffect, useId, useImperativeHandle, useMemo, useReducer, useRef, useState, } from "react";
 import { createPortal } from "react-dom";
 import styled, { css } from "styled-components";
 import { buildCameraLabeler } from "./cameraLabels";
 import { KerbcastProvider, useKerbcastClient } from "./context";
 import { ActionBarRow, FeedActionBar, OverlayIconButton, feedActionToEntry, } from "./FeedActionBar";
+import { CommandBlank, CommandBrackets } from "./CommandBrackets";
+import { useCommandDisplayUt } from "./hooks/useCommandDisplayUt";
 import { useKerbcastCameras } from "./hooks/useKerbcastCameras";
 import { useKerbcastInFlight } from "./hooks/useKerbcastInFlight";
 import { useKerbcastStream } from "./hooks/useKerbcastStream";
 import { useRecordings } from "./hooks/useRecordings";
 import { useReportDisplaySize } from "./hooks/useReportDisplaySize";
+import { useTargetBracketsPreference } from "./hooks/useTargetBracketsPreference";
 import { StandbyIcon } from "./StandbyIcon";
 import { isCameraDestroyed } from "./lifecycle";
 import { usePortalMenu } from "./menuPositioning";
@@ -59,7 +62,7 @@ function exitFullscreen() {
 // ---------------------------------------------------------------------------
 // Inner component (reads from context)
 // ---------------------------------------------------------------------------
-const CameraFeedInner = forwardRef(function CameraFeedInner({ flightId: requestedFlightId, onSelectCamera, cameraFilter, onDisplayedCameraChange, showDebugInfo = false, showStatic, inFlight: inFlightProp, showStandbyIcon = true, renderSize = "auto", emptyMessage = "No camera feeds - start a vessel with Hullcam parts installed", enableFullscreen = false, enablePictureInPicture = false, enableQualityControl = false, enableTracking = false, disableManualControls = false, enableRecording = false, recordFullResolution = false, actions, trailingActions, showActions = true, useStream, }, ref) {
+const CameraFeedInner = forwardRef(function CameraFeedInner({ flightId: requestedFlightId, onSelectCamera, cameraFilter, onDisplayedCameraChange, showDebugInfo = false, showStatic, inFlight: inFlightProp, showStandbyIcon = true, renderSize = "auto", emptyMessage = "No camera feeds - start a vessel with Hullcam parts installed", enableFullscreen = false, enablePictureInPicture = false, enableQualityControl = false, enableTracking = false, disableManualControls = false, enableRecording = false, recordFullResolution = false, actions, trailingActions, showActions = true, useStream, enableTargetBrackets = true, targetBracketOverlay, displayUt: displayUtProp, }, ref) {
     const client = useKerbcastClient();
     // Always called (rules of hooks); `enableRecording` only gates whether the
     // REC entry/badge render, not whether the store is subscribed.
@@ -146,6 +149,13 @@ const CameraFeedInner = forwardRef(function CameraFeedInner({ flightId: requeste
     const resolveStream = useStream ?? useKerbcastStream;
     const stream = resolveStream(flightId);
     const videoRef = useRef(null);
+    /* Mirrors videoRef as state so the bracket overlay can measure the element
+       once it mounts. Setting a ref never remounts the video. */
+    const [videoEl, setVideoEl] = useState(null);
+    const attachVideo = useCallback((el) => {
+        videoRef.current = el;
+        setVideoEl(el);
+    }, []);
     // The feed frame; fullscreen targets this and ResizeObserver measures it.
     const wrapRef = useRef(null);
     useEffect(() => {
@@ -245,6 +255,16 @@ const CameraFeedInner = forwardRef(function CameraFeedInner({ flightId: requeste
     const tracking = trackMode !== TrackMode.None;
     const manualDisabled = tracking;
     const supportsPitch = !!camera && camera.panPitchMax - camera.panPitchMin > 0;
+    /* Command camera feeds: target brackets, readout and blank label. */
+    const commandCamera = camera?.kind === CameraKind.Command && !isDestroyed ? camera : null;
+    const isCommandFeed = commandCamera !== null;
+    const commandTrack = commandCamera?.commandTrack ?? null;
+    const commandDisplayUt = useCommandDisplayUt(commandTrack !== null, displayUtProp, commandTrack?.events, commandCamera?.flightId ?? null, videoEl);
+    const commandState = commandTrack
+        ? effectiveCommandTrack(commandTrack, commandDisplayUt?.ut)
+        : null;
+    const [bracketsOn, toggleBrackets] = useTargetBracketsPreference(commandCamera ? (commandCamera.commandCentre?.stationId ?? String(commandCamera.flightId)) : null);
+    const targetBracketsAvailable = enableTargetBrackets && isCommandFeed;
     // -------------------------------------------------------------------------
     // Camera selection callbacks (Next/Prev, picker)
     // onSelectCamera is ONLY called on explicit user picks, never on auto-latch.
@@ -444,6 +464,32 @@ const CameraFeedInner = forwardRef(function CameraFeedInner({ flightId: requeste
         closeTrackingMenu();
     }, [client, flightId, trackMode, closeTrackingMenu]);
     // -------------------------------------------------------------------------
+    // Command camera target picker. Lists every craft the game offers; the
+    // ineligible ones stay visible but disabled with the game's reason, and
+    // the current target follows the published subjectPersistentId. Picking
+    // one aims the camera at it. Hidden while a command authority holds the
+    // aim lock, since only it can aim then.
+    // -------------------------------------------------------------------------
+    const commandTargets = commandCamera?.commandCentre?.targets ?? [];
+    const commandTargetId = commandCamera?.commandCentre?.subjectPersistentId ?? 0;
+    const commandLocked = commandCamera?.commandTrack?.authority != null;
+    const commandTargetAvailable = isCommandFeed && !disableManualControls && !commandLocked && commandTargets.length > 0;
+    const commandTargetMenuId = useId();
+    const commandTargetMenu = usePortalMenu({
+        maxWidth: MENU_MAX_WIDTH,
+        maxHeight: MENU_MAX_HEIGHT,
+        align: "end",
+    });
+    const closeCommandTargetMenu = commandTargetMenu.close;
+    const selectCommandTarget = useCallback((persistentId) => {
+        if (flightId === null)
+            return;
+        client
+            .setCommandAim(flightId, { kind: CommandAimKind.Vessel, persistentId })
+            .catch(() => { });
+        closeCommandTargetMenu();
+    }, [client, flightId, closeCommandTargetMenu]);
+    // -------------------------------------------------------------------------
     // REC control (opt-in). A stateful toggle that starts/stops a client-side
     // recording of this feed via the recordings store; state is read from the
     // store (isRecording), never held locally, so it stays correct if the
@@ -514,6 +560,11 @@ const CameraFeedInner = forwardRef(function CameraFeedInner({ flightId: requeste
     const pipLabel = isPip ? "Exit picture in picture" : "Picture in picture";
     const fullscreenLabel = isFullscreen ? "Exit fullscreen" : "Enter fullscreen";
     const recordingLabel = recordingActive ? "Stop recording" : "Start recording";
+    const bracketsLabel = "Target brackets";
+    const commandTargetName = commandTargets.find((t) => t.persistentId === commandTargetId)?.vesselName;
+    const commandTargetLabel = commandTargetName
+        ? `Watching ${commandTargetName}`
+        : "Choose target";
     const entries = [
         ...(actions?.map(feedActionToEntry) ?? []),
         ...(qualityAvailable
@@ -521,7 +572,8 @@ const CameraFeedInner = forwardRef(function CameraFeedInner({ flightId: requeste
                 {
                     id: "quality",
                     label: "Quality",
-                    stateful: false,
+                    /* Stays inline: its menu anchors on this button, which the overflow menu unmounts on click. */
+                    stateful: true,
                     render: () => (_jsxs(OverlayIconButton, { ref: qualityMenu.triggerRef, type: "button", "aria-label": "Quality", "aria-haspopup": "menu", "aria-expanded": qualityMenu.open, "aria-controls": qualityMenuId, title: qualityThrottled
                             ? "Quality (throttled by adaptive performance)"
                             : "Quality", "$active": qualityMenu.open, onClick: qualityMenu.toggle, children: [_jsx(QualityIcon, {}), qualityThrottled && _jsx(ThrottledDot, { "aria-hidden": "true" })] })),
@@ -538,6 +590,27 @@ const CameraFeedInner = forwardRef(function CameraFeedInner({ flightId: requeste
                 },
             ]
             : []),
+        ...(targetBracketsAvailable
+            ? [
+                {
+                    id: "target-brackets",
+                    label: bracketsLabel,
+                    stateful: true,
+                    render: () => (_jsx(OverlayIconButton, { type: "button", "aria-label": bracketsLabel, "aria-pressed": bracketsOn, title: bracketsLabel, "$active": bracketsOn, onClick: toggleBrackets, children: _jsx(TargetBracketsIcon, {}) })),
+                },
+            ]
+            : []),
+        ...(commandTargetAvailable
+            ? [
+                {
+                    id: "command-target",
+                    label: commandTargetLabel,
+                    /* Stays inline: its menu anchors on this button, which the overflow menu unmounts on click. */
+                    stateful: true,
+                    render: () => (_jsx(OverlayIconButton, { ref: commandTargetMenu.triggerRef, type: "button", "aria-label": "Choose target", "aria-haspopup": "menu", "aria-expanded": commandTargetMenu.open, "aria-controls": commandTargetMenuId, title: commandTargetLabel, "$active": commandTargetMenu.open, onClick: commandTargetMenu.toggle, children: _jsx(CommandTargetIcon, {}) })),
+                },
+            ]
+            : []),
         ...(trackingAvailable
             ? [
                 {
@@ -589,6 +662,8 @@ const CameraFeedInner = forwardRef(function CameraFeedInner({ flightId: requeste
             fullscreenAvailable ||
             qualityAvailable ||
             trackingAvailable ||
+            targetBracketsAvailable ||
+            commandTargetAvailable ||
             enableRecording);
     const hasActionBar = showActions &&
         (hasCameras ||
@@ -597,7 +672,7 @@ const CameraFeedInner = forwardRef(function CameraFeedInner({ flightId: requeste
             builtInActions);
     const stepButtons = hasCameras ? (_jsxs(StepButtons, { children: [_jsx(OverlayIconButton, { type: "button", "aria-label": "Previous camera", disabled: !canStep, onClick: () => stepCamera(-1), children: "\u2039" }), _jsx(OverlayIconButton, { type: "button", "aria-label": "Next camera", disabled: !canStep, onClick: () => stepCamera(1), children: "\u203A" })] })) : null;
     const actionBar = hasActionBar ? (_jsx(FeedActionBar, { leading: stepButtons, entries: entries })) : null;
-    return (_jsx(Stage, { ref: wrapRef, "$pinned": chromePinned, children: flightId === null ? (_jsxs(_Fragment, { children: [_jsx(Empty, { children: emptyMessage }), topOverlay, actionBar] })) : (_jsxs(_Fragment, { children: [_jsx(StyledVideo, { ref: videoRef, autoPlay: true, playsInline: true, muted: true, controls: false, onClick: () => setChromePinned((v) => !v) }), topOverlay, actionBar, qualityAvailable &&
+    return (_jsx(Stage, { ref: wrapRef, "$pinned": chromePinned, children: flightId === null ? (_jsxs(_Fragment, { children: [_jsx(Empty, { children: emptyMessage }), topOverlay, actionBar] })) : (_jsxs(_Fragment, { children: [_jsx(StyledVideo, { ref: attachVideo, autoPlay: true, playsInline: true, muted: true, controls: false, onClick: () => setChromePinned((v) => !v) }), topOverlay, actionBar, qualityAvailable &&
                     qualityMenu.open &&
                     qualityMenu.position &&
                     camera &&
@@ -605,7 +680,16 @@ const CameraFeedInner = forwardRef(function CameraFeedInner({ flightId: requeste
                     trackingMenu.open &&
                     trackingMenu.position &&
                     camera &&
-                    createPortal(_jsxs(QualityMenu, { ref: trackingMenu.menuRef, id: trackingMenuId, role: "menu", "aria-label": "Auto-track", style: trackingMenu.position, children: [_jsx(CameraMenuItem, { type: "button", role: "menuitemradio", "aria-checked": trackMode === TrackMode.ActiveVessel, "$selected": trackMode === TrackMode.ActiveVessel, onClick: () => selectTrack(TrackMode.ActiveVessel), children: "Track active vessel" }), _jsx(CameraMenuItem, { type: "button", role: "menuitemradio", "aria-checked": trackMode === TrackMode.Target, "$selected": trackMode === TrackMode.Target, onClick: () => selectTrack(TrackMode.Target), children: "Track target" })] }), document.body), outOfFlight ? (showStandbyIcon && (_jsx(StandbyOverlay, { role: "status", "aria-label": "Standby, no active flight", children: _jsx(StandbyIconWrap, { children: _jsx(StandbyIcon, { size: 40 }) }) }))) : (isDestroyed && (_jsx(SignalLostOverlay, { role: "status", "aria-label": "Signal lost", children: _jsx(SignalLostText, { "$animated": effectiveShowStatic, children: "SIGNAL LOST" }) }))), !outOfFlight && !effectiveShowStatic && isStale && !isDestroyed && (_jsxs(_Fragment, { children: [_jsx(StaleScrim, { "aria-hidden": "true" }), _jsxs(StaleBadge, { role: "status", "aria-label": "Feed stale", children: [_jsx(StaleIcon, {}), "Stale"] })] })), recordingActive && armingActive && (_jsxs(ArmingBadge, { role: "status", "aria-label": "Arming", children: [_jsx(ArmingDot, { "aria-hidden": "true" }), "ARMING"] })), recordingActive && !armingActive && (_jsxs(RecBadge, { role: "status", "aria-label": "Recording", children: [_jsx(RecDot, { "aria-hidden": "true" }), "REC ", formatElapsed(recordingElapsedMs)] })), showZoom && (_jsxs(ZoomControlsWrap, { "$disabled": manualDisabled, "aria-hidden": manualDisabled, children: [_jsx(ZoomButton, { type: "button", "aria-label": "Zoom in", "$pos": "top", disabled: manualDisabled, onPointerDown: () => controllerRef.current?.setZoomRate(1), onPointerUp: () => controllerRef.current?.setZoomRate(0), onPointerLeave: () => controllerRef.current?.setZoomRate(0), onPointerCancel: () => controllerRef.current?.setZoomRate(0), onClick: (e) => {
+                    createPortal(_jsxs(QualityMenu, { ref: trackingMenu.menuRef, id: trackingMenuId, role: "menu", "aria-label": "Auto-track", style: trackingMenu.position, children: [_jsx(CameraMenuItem, { type: "button", role: "menuitemradio", "aria-checked": trackMode === TrackMode.ActiveVessel, "$selected": trackMode === TrackMode.ActiveVessel, onClick: () => selectTrack(TrackMode.ActiveVessel), children: "Track active vessel" }), _jsx(CameraMenuItem, { type: "button", role: "menuitemradio", "aria-checked": trackMode === TrackMode.Target, "$selected": trackMode === TrackMode.Target, onClick: () => selectTrack(TrackMode.Target), children: "Track target" })] }), document.body), commandTargetAvailable &&
+                    commandTargetMenu.open &&
+                    commandTargetMenu.position &&
+                    createPortal(_jsx(CameraMenu, { ref: commandTargetMenu.menuRef, id: commandTargetMenuId, role: "menu", "aria-label": "Target", style: commandTargetMenu.position, children: commandTargets.map((t) => {
+                            const eligible = t.eligibility === CommandTargetEligibility.Ok;
+                            const current = t.persistentId === commandTargetId;
+                            return (_jsxs(CameraMenuItem, { type: "button", role: "menuitemradio", "aria-checked": current, "$selected": current, disabled: !eligible, title: eligible ? undefined : t.eligibilityText, onClick: () => selectCommandTarget(t.persistentId), children: [t.vesselName, t.rangeM != null ? ` · ${formatCommandRange(t.rangeM)}` : "", eligible ? "" : ` · ${t.eligibilityText}`] }, t.persistentId));
+                        }) }), document.body), commandState &&
+                    !outOfFlight &&
+                    (_jsxs(_Fragment, { children: [commandState.blank && _jsx(CommandBlank, { reason: commandState.blank }), targetBracketsAvailable && bracketsOn && (_jsx(CommandBrackets, { state: commandState, displayUt: commandDisplayUt?.ut ?? commandTrack.ut, utSource: commandDisplayUt?.source ?? null, video: videoEl, fallbackSize: camera ? { width: camera.renderWidth, height: camera.renderHeight } : null, overlay: targetBracketOverlay }))] })), outOfFlight ? (showStandbyIcon && (_jsx(StandbyOverlay, { role: "status", "aria-label": "Standby, no active flight", children: _jsx(StandbyIconWrap, { children: _jsx(StandbyIcon, { size: 40 }) }) }))) : (isDestroyed && (_jsx(SignalLostOverlay, { role: "status", "aria-label": "Signal lost", children: _jsx(SignalLostText, { "$animated": effectiveShowStatic, children: "SIGNAL LOST" }) }))), !outOfFlight && !effectiveShowStatic && isStale && !isDestroyed && (_jsxs(_Fragment, { children: [_jsx(StaleScrim, { "aria-hidden": "true" }), _jsxs(StaleBadge, { role: "status", "aria-label": "Feed stale", children: [_jsx(StaleIcon, {}), "Stale"] })] })), recordingActive && armingActive && (_jsxs(ArmingBadge, { role: "status", "aria-label": "Arming", children: [_jsx(ArmingDot, { "aria-hidden": "true" }), "ARMING"] })), recordingActive && !armingActive && (_jsxs(RecBadge, { role: "status", "aria-label": "Recording", children: [_jsx(RecDot, { "aria-hidden": "true" }), "REC ", formatElapsed(recordingElapsedMs)] })), showZoom && (_jsxs(ZoomControlsWrap, { "$disabled": manualDisabled, "aria-hidden": manualDisabled, children: [_jsx(ZoomButton, { type: "button", "aria-label": "Zoom in", "$pos": "top", disabled: manualDisabled, onPointerDown: () => controllerRef.current?.setZoomRate(1), onPointerUp: () => controllerRef.current?.setZoomRate(0), onPointerLeave: () => controllerRef.current?.setZoomRate(0), onPointerCancel: () => controllerRef.current?.setZoomRate(0), onClick: (e) => {
                                 if (e.detail === 0)
                                     controllerRef.current?.nudgeZoom(-1);
                             }, children: "+" }), _jsx(FovSlider, { type: "range", "aria-label": "Zoom", min: camera.fovMin, max: camera.fovMax, step: 0.5, value: sliderFov, disabled: manualDisabled, onChange: (e) => {
@@ -665,6 +749,14 @@ function FullscreenExitIcon() {
 function QualityIcon() {
     return (_jsxs("svg", { ...iconProps, children: [_jsx("path", { d: "M2 4.5h12M2 8h12M2 11.5h12" }), _jsx("circle", { cx: "10.5", cy: "4.5", r: "1.6", fill: "currentColor", stroke: "none" }), _jsx("circle", { cx: "5.5", cy: "8", r: "1.6", fill: "currentColor", stroke: "none" }), _jsx("circle", { cx: "8.5", cy: "11.5", r: "1.6", fill: "currentColor", stroke: "none" })] }));
 }
+/* Target brackets: the top-left and bottom-right corners around a centre dot. */
+function TargetBracketsIcon() {
+    return (_jsxs("svg", { ...iconProps, children: [_jsx("path", { d: "M2.5 7V2.5H7M13.5 9v4.5H9" }), _jsx("circle", { cx: "8", cy: "8", r: "1.2", fill: "currentColor", stroke: "none" })] }));
+}
+/* Command camera target: a craft silhouette inside a selection ring. */
+function CommandTargetIcon() {
+    return (_jsxs("svg", { ...iconProps, children: [_jsx("circle", { cx: "8", cy: "8", r: "6" }), _jsx("path", { d: "M8 4.5l1.6 4H6.4zM6.6 8.5l-.9 2.5M9.4 8.5l.9 2.5" })] }));
+}
 /* Auto-track: a crosshair / reticle. */
 function CrosshairIcon() {
     return (_jsxs("svg", { ...iconProps, children: [_jsx("circle", { cx: "8", cy: "8", r: "4.5" }), _jsx("path", { d: "M8 1v2.5M8 12.5V15M1 8h2.5M12.5 8H15" })] }));
@@ -941,6 +1033,15 @@ const CameraMenuItem = styled.button `
     outline: 2px solid var(--kerbcast-accent, #00ff88);
     outline-offset: -2px;
   }
+
+  &:disabled {
+    cursor: default;
+    color: rgba(255, 255, 255, 0.45);
+  }
+
+  &:disabled:not([aria-checked="true"]) {
+    background: transparent;
+  }
 `;
 const TopMeta = styled.div `
   font-size: 11px;

package/dist/CommandBrackets.d.ts

@@ -0,0 +1,110 @@
+import { type EffectiveCommandTrack, type FrameUtSource } from "@ksp-gonogo/kerbcast";
+import { type ReactNode } from "react";
+/** Default colours; each is overridable through the named CSS custom property. */
+export declare const COMMAND_BRACKET_COLOURS: {
+    readonly clear: "var(--kerbcast-bracket-clear, #4caf50)";
+    readonly occluded: "var(--kerbcast-bracket-occluded, #f44336)";
+};
+export interface ContentRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * Where `object-fit: contain` media actually lands inside its box. Falls back
+ * to the whole box while the media size is unknown.
+ */
+export declare function containedContentRect(boxWidth: number, boxHeight: number, mediaWidth: number, mediaHeight: number): ContentRect;
+export interface BracketPoint {
+    x: number;
+    y: number;
+}
+/** 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. */
+    cx: number;
+    cy: number;
+    /** Half the box side in display px. */
+    half: number;
+    /** Length of each corner stroke. */
+    arm: number;
+    stroke: number;
+    /** The box's top-left and bottom-right corner points. */
+    topLeft: BracketPoint;
+    bottomRight: BracketPoint;
+}
+/**
+ * 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.
+ */
+export declare function bracketGeometry(rect: ContentRect, bracketHalfPx: number | null, frameHeightPx: number): BracketGeometry;
+export type CommandBracketCorner = "topLeft" | "bottomRight";
+export interface CommandBracketCornerStyle {
+    colour: string;
+    dashed: boolean;
+}
+/** Changes to one default corner; unset fields keep the default. */
+export interface CommandBracketCornerOverride {
+    colour?: string;
+    dashed?: boolean;
+    hidden?: boolean;
+}
+export type CommandBracketCornerOverrides = Partial<Record<CommandBracketCorner, CommandBracketCornerOverride>>;
+/** Everything a bracket overlay needs to line up with the drawn brackets. */
+export interface CommandBracketContext {
+    geometry: BracketGeometry;
+    /** Size of the bracket SVG, the video element's box. */
+    width: number;
+    height: number;
+    /** Frame UT the brackets describe. */
+    displayUt: number;
+    utSource: FrameUtSource | "override" | null;
+    state: EffectiveCommandTrack;
+}
+/**
+ * Consumer additions to a command feed's brackets. Each part is optional and
+ * is called on every render with the context for the displayed frame.
+ */
+export interface CommandBracketOverlay {
+    /**
+     * SVG content drawn inside the bracket SVG above the default corners, in
+     * the same pixel space. Runs in every state, with or without a fix and
+     * over a blanked feed; `ctx.state` says which.
+     */
+    render?: (ctx: CommandBracketContext) => ReactNode;
+    /** Restyle or hide the default corners. */
+    corners?: CommandBracketCornerOverrides | ((ctx: CommandBracketContext) => CommandBracketCornerOverrides | null | undefined);
+    /**
+     * The readout text under the box. Receives the default text, which is
+     * empty while the feed is blanked; return a replacement (append to keep
+     * it), or null to hide the readout. Runs in every state.
+     */
+    readout?: (defaultText: string, ctx: CommandBracketContext) => string | null;
+}
+export interface CommandBracketsProps {
+    state: EffectiveCommandTrack;
+    displayUt: number;
+    /** Where `displayUt` came from, mirrored to the readout as `data-ut-source`. */
+    utSource?: FrameUtSource | "override" | null;
+    video: HTMLVideoElement | null;
+    /** Frame aspect to assume until the video reports its own size. */
+    fallbackSize?: {
+        width: number;
+        height: number;
+    } | null;
+    overlay?: CommandBracketOverlay | 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.
+ */
+export declare function CommandBrackets({ state, displayUt, utSource, video, fallbackSize, overlay, }: CommandBracketsProps): import("react").JSX.Element;
+/** Reason a command feed is blanked, centred on black over the feed. */
+export declare function CommandBlank({ reason }: {
+    reason: string;
+}): import("react").JSX.Element;

package/dist/CommandBrackets.js

@@ -0,0 +1,167 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { commandReadout, } from "@ksp-gonogo/kerbcast";
+import { useEffect, useState } from "react";
+import styled from "styled-components";
+const BRACKET_STROKE_PX = 2;
+const BRACKET_MIN_HALF_PX = 14;
+const BRACKET_ARM_FRACTION = 0.3;
+const BRACKET_MIN_ARM_PX = 6;
+const READOUT_GAP_PX = 11;
+/** Default colours; each is overridable through the named CSS custom property. */
+export const COMMAND_BRACKET_COLOURS = {
+    clear: "var(--kerbcast-bracket-clear, #4caf50)",
+    occluded: "var(--kerbcast-bracket-occluded, #f44336)",
+};
+/**
+ * Where `object-fit: contain` media actually lands inside its box. Falls back
+ * to the whole box while the media size is unknown.
+ */
+export function containedContentRect(boxWidth, boxHeight, mediaWidth, mediaHeight) {
+    if (mediaWidth <= 0 || mediaHeight <= 0 || boxWidth <= 0 || boxHeight <= 0) {
+        return { x: 0, y: 0, width: Math.max(0, boxWidth), height: Math.max(0, boxHeight) };
+    }
+    const scale = Math.min(boxWidth / mediaWidth, boxHeight / mediaHeight);
+    const width = mediaWidth * scale;
+    const height = mediaHeight * scale;
+    return { x: (boxWidth - width) / 2, y: (boxHeight - height) / 2, width, height };
+}
+/**
+ * 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.
+ */
+export function bracketGeometry(rect, bracketHalfPx, frameHeightPx) {
+    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;
+    return {
+        cx,
+        cy,
+        half,
+        arm,
+        stroke: BRACKET_STROKE_PX,
+        topLeft: { x: cx - half, y: cy - half },
+        bottomRight: { x: cx + half, y: cy + half },
+    };
+}
+function cameraCornerStyle(state) {
+    return state.occluded
+        ? { colour: COMMAND_BRACKET_COLOURS.occluded, dashed: true }
+        : { colour: COMMAND_BRACKET_COLOURS.clear, dashed: false };
+}
+function applyCorner(base, override) {
+    return {
+        colour: override?.colour ?? base.colour,
+        dashed: override?.dashed ?? base.dashed,
+        hidden: override?.hidden ?? false,
+    };
+}
+/** Tracks the rendered box and intrinsic size of a video element. */
+function useVideoBox(video) {
+    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;
+}
+/**
+ * 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.
+ */
+export function CommandBrackets({ state, displayUt, utSource, video, fallbackSize, overlay, }) {
+    const { boxW, boxH, mediaW, mediaH } = useVideoBox(video);
+    const rect = containedContentRect(boxW, boxH, mediaW || fallbackSize?.width || 0, mediaH || fallbackSize?.height || 0);
+    const g = bracketGeometry(rect, state.bracketHalfPx, state.frameHeightPx || mediaH);
+    const ctx = {
+        geometry: g,
+        width: boxW,
+        height: boxH,
+        displayUt,
+        utSource: utSource ?? null,
+        state,
+    };
+    const overrides = typeof overlay?.corners === "function" ? overlay.corners(ctx) : overlay?.corners;
+    const camera = cameraCornerStyle(state);
+    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);
+    const readout = overlay?.readout ? overlay.readout(defaultReadout, ctx) : defaultReadout;
+    return (_jsxs(_Fragment, { children: [(drawCorners || overlay?.render) && (_jsxs(BracketSvg, { "aria-hidden": "true", "data-camera-axis": state.camera, width: boxW, height: boxH, children: [drawCorners && !topLeft.hidden && (_jsx("path", { "data-corner": "topLeft", d: `M${left} ${top + g.arm}L${left} ${top}L${left + g.arm} ${top}`, fill: "none", strokeWidth: g.stroke, strokeDasharray: topLeft.dashed ? "3 2" : undefined, style: { stroke: topLeft.colour } })), drawCorners && !bottomRight.hidden && (_jsx("path", { "data-corner": "bottomRight", d: `M${right} ${bottom - g.arm}L${right} ${bottom}L${right - g.arm} ${bottom}`, fill: "none", strokeWidth: g.stroke, strokeDasharray: bottomRight.dashed ? "3 2" : undefined, style: { stroke: bottomRight.colour } })), overlay?.render && _jsx("g", { "data-bracket-overlay": "", children: overlay.render(ctx) })] })), readout && (_jsx(Readout, { "data-ut-source": utSource ?? undefined, style: { left: g.cx, top: bottom + READOUT_GAP_PX }, children: readout }))] }));
+}
+/** Reason a command feed is blanked, centred on black over the feed. */
+export function CommandBlank({ reason }) {
+    return (_jsx(BlankOverlay, { role: "status", "aria-label": "Feed blanked", children: _jsx(BlankText, { children: reason }) }));
+}
+const BracketSvg = styled.svg `
+  position: absolute;
+  top: 0;
+  left: 0;
+  z-index: 1;
+  overflow: visible;
+  pointer-events: none;
+`;
+const Readout = styled.div `
+  position: absolute;
+  z-index: 1;
+  transform: translateX(-50%);
+  white-space: nowrap;
+  color: #fff;
+  font-size: 10px;
+  font-weight: 600;
+  letter-spacing: 0.12em;
+  text-shadow: 0 1px 2px rgba(0, 0, 0, 0.9);
+  pointer-events: none;
+`;
+const BlankOverlay = styled.div `
+  position: absolute;
+  inset: 0;
+  z-index: 1;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: 1rem;
+  background: #000;
+  pointer-events: none;
+`;
+const BlankText = styled.span `
+  color: rgba(255, 255, 255, 0.85);
+  font-size: 0.85rem;
+  font-weight: 600;
+  letter-spacing: 0.12em;
+  text-align: center;
+  text-transform: uppercase;
+`;

package/dist/hooks/useCommandDisplayUt.d.ts

@@ -0,0 +1,22 @@
+import { type FrameUtSource, type CommandTrackEvent } from "@ksp-gonogo/kerbcast";
+export { MAX_UT_EXTRAPOLATION_MS, extrapolateCaptureUt } from "@ksp-gonogo/kerbcast";
+/** Real milliseconds until the first event after `displayUt`, or `null` when none is ahead. */
+export declare function msUntilNextEvent(events: readonly CommandTrackEvent[] | undefined, displayUt: number, warpRate: number): number | null;
+/** Whether an event's UT lies in `(from, to]`, i.e. moving the display from `from` to `to` changes the state in force. */
+export declare function crossesEvent(events: readonly CommandTrackEvent[] | undefined, from: number, to: number): boolean;
+/** 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 declare function useCommandDisplayUt(enabled: boolean, override?: number, events?: readonly CommandTrackEvent[], flightId?: number | null, video?: HTMLVideoElement | null): CommandDisplayUt | null;

package/dist/hooks/useCommandDisplayUt.js

@@ -0,0 +1,104 @@
+import { useEffect, useReducer, useRef } from "react";
+import { extrapolateCaptureUt, } 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, displayUt, warpRate) {
+    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, from, to) {
+    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. 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, override, events, flightId, video) {
+    const client = useKerbcastClient();
+    const sample = useRef({
+        captureUt: client.clock.captureUt,
+        warpRate: client.clock.warpRate,
+        at: nowMs(),
+    });
+    const frame = useRef(null);
+    const shown = useRef(null);
+    const eventsRef = useRef(events);
+    eventsRef.current = events;
+    const [, tick] = useReducer((c) => 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 = 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;
+}