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

package/dist/CommandBrackets.d.ts

@@ -1,4 +1,4 @@
-import { type EffectiveCommandTrack, type FrameUtSource } from "@ksp-gonogo/kerbcast";
+import { type EffectiveCommandTrack, type FrameAnchor, 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: {
@@ -22,7 +22,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. */
@@ -35,11 +38,12 @@ export interface BracketGeometry {
     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.
+ * 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 declare function bracketGeometry(rect: ContentRect, bracketHalfPx: number | null, frameHeightPx: number): BracketGeometry;
+export declare function bracketGeometry(rect: ContentRect, bracketHalfPx: number | null, frameHeightPx: number, centre?: BracketPoint | null): BracketGeometry;
 export type CommandBracketCorner = "topLeft" | "bottomRight";
 export interface CommandBracketCornerStyle {
     colour: string;
@@ -62,6 +66,19 @@ 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;
 }
 /**
  * Consumer additions to a command feed's brackets. Each part is optional and
@@ -95,15 +112,47 @@ export interface CommandBracketsProps {
         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 declare function CommandBrackets({ state, displayUt, utSource, video, fallbackSize, overlay, subject, subjectFrameSize, aim, }: CommandBracketsProps): import("react").JSX.Element;
+/**
+ * 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 declare function CommandBrackets({ state, displayUt, utSource, video, fallbackSize, overlay, }: CommandBracketsProps): import("react").JSX.Element;
+export declare function LiveCommandBrackets({ flightId, ...props }: CommandBracketsProps & {
+    flightId: number | null;
+}): import("react").JSX.Element;
 /** Reason a command feed is blanked, centred on black over the feed. */
 export declare function CommandBlank({ reason }: {
     reason: string;

package/dist/CommandBrackets.js

@@ -1,7 +1,8 @@
 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 { COMMAND_AIM_ANCHOR_ID, COMMAND_SUBJECT_ANCHOR_ID, KERBCAST_ANCHOR_OWNER, anchorPoint, commandReadout, findAnchor, frameToScreen, } from "@ksp-gonogo/kerbcast";
 import styled from "styled-components";
+import { useDisplayedFrame } from "./AnchorMarkers";
+import { useVideoBox } from "./videoBox";
 const BRACKET_STROKE_PX = 2;
 const BRACKET_MIN_HALF_PX = 14;
 const BRACKET_ARM_FRACTION = 0.3;
@@ -26,16 +27,17 @@ export function containedContentRect(boxWidth, boxHeight, mediaWidth, mediaHeigh
     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.
+ * 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, bracketHalfPx, frameHeightPx) {
+export function bracketGeometry(rect, bracketHalfPx, frameHeightPx, centre) {
     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,
@@ -46,8 +48,41 @@ export function bracketGeometry(rect, bracketHalfPx, frameHeightPx) {
         bottomRight: { x: cx + half, y: cy + half },
     };
 }
-function cameraCornerStyle(state) {
-    return state.occluded
+/** Whether `p` lies inside the box `g`. */
+function holds(g, p) {
+    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, rect) {
+    const clamp = (v, lo, hi) => (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, toward) {
+    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}`;
+}
+function cameraCornerStyle(occluded) {
+    return occluded
         ? { colour: COMMAND_BRACKET_COLOURS.occluded, dashed: true }
         : { colour: COMMAND_BRACKET_COLOURS.clear, dashed: false };
 }
@@ -58,50 +93,51 @@ function applyCorner(base, override) {
         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.
+ * 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, displayUt, utSource, video, fallbackSize, overlay, }) {
+export function CommandBrackets({ state, displayUt, utSource, video, fallbackSize, overlay, subject, subjectFrameSize, aim, }) {
     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 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 = {
         geometry: g,
         width: boxW,
@@ -109,18 +145,35 @@ export function CommandBrackets({ state, displayUt, utSource, video, fallbackSiz
         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 (_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 }))] }));
+    return (_jsxs(_Fragment, { children: [(drawCorners || overlay?.render) && (_jsxs(BracketSvg, { "aria-hidden": "true", "data-camera-axis": state.camera, "data-subject": subject ? (placed ? "placed" : "centred") : undefined, 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 } })), drawCorners && cue && (_jsx("path", { "data-aim-cue": "", d: cue, fill: "none", strokeWidth: g.stroke, style: { stroke: camera.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 }))] }));
+}
+/**
+ * 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 }) {
+    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 _jsx(CommandBrackets, { ...props, subject: subject, subjectFrameSize: size, aim: aim });
 }
 /** Reason a command feed is blanked, centred on black over the feed. */
 export function CommandBlank({ reason }) {

package/dist/KerbalFaceFeed.d.ts

@@ -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/dist/KerbalFaceFeed.js

@@ -4,7 +4,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  *
  * 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/dist/RecordingsTray.d.ts

@@ -21,6 +21,7 @@
  * labeller CameraFeed uses) so this stays decoupled from any particular
  * camera registry; omit it for a plain "Camera <flightId>" fallback.
  */
+import type { RecordingEndReason } from "@ksp-gonogo/kerbcast";
 export interface RecordingsTrayProps {
     /**
      * Resolve a flightId to a display label for a clip's camera name. Omit for
@@ -35,3 +36,8 @@ export interface RecordingsTrayProps {
  * `useRecordings()` directly, same requirement as `CameraFeed`).
  */
 export declare function RecordingsTray({ cameraLabel, className }: RecordingsTrayProps): import("react").JSX.Element;
+/**
+ * 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 declare function recordingEndNote(endedBy: RecordingEndReason): string | null;

package/dist/RecordingsTray.js

@@ -18,7 +18,7 @@ function ClipRow({ rec, label, url, onDiscard }) {
     const utRange = rec.utStart != null && rec.utEnd != null
         ? `${formatUt(rec.utStart)} - ${formatUt(rec.utEnd)}`
         : "no UT (out of flight)";
-    return (_jsxs(Clip, { children: [url ? (_jsx(ClipPreview, { controls: true, preload: "metadata", src: url, "aria-label": `Preview: ${label}` })) : (_jsx(ClipPreviewPlaceholder, { "aria-hidden": "true" })), _jsxs(ClipMeta, { children: [_jsx(ClipName, { children: label }), _jsx(ClipDetail, { children: utRange }), _jsxs(ClipDetail, { children: [formatDuration(rec.durationMs), " \u00B7 ", formatBytes(rec.byteSize)] })] }), _jsxs(ClipActions, { children: [url && (_jsx(TrayLink, { href: url, download: clipFileName(rec, label), children: "Download" })), onDiscard && (_jsx(TrayButton, { type: "button", "$danger": true, onClick: onDiscard, children: "Discard" }))] })] }));
+    return (_jsxs(Clip, { children: [url ? (_jsx(ClipPreview, { controls: true, preload: "metadata", src: url, "aria-label": `Preview: ${label}` })) : (_jsx(ClipPreviewPlaceholder, { "aria-hidden": "true" })), _jsxs(ClipMeta, { children: [_jsx(ClipName, { children: label }), _jsx(ClipDetail, { children: utRange }), _jsxs(ClipDetail, { children: [formatDuration(rec.durationMs), " \u00B7 ", formatBytes(rec.byteSize)] }), rec.endedBy && recordingEndNote(rec.endedBy) && (_jsx(ClipDetail, { children: recordingEndNote(rec.endedBy) }))] }), _jsxs(ClipActions, { children: [url && (_jsx(TrayLink, { href: url, download: clipFileName(rec, label), children: "Download" })), onDiscard && (_jsx(TrayButton, { type: "button", "$danger": true, onClick: onDiscard, children: "Discard" }))] })] }));
 }
 function GroupItem({ group, labelFor, objectUrls, onDiscardGroup }) {
     return (_jsxs(GroupCard, { "aria-label": `Grouped recording, ${group.recordings.length} feeds`, children: [_jsxs(GroupHeader, { children: [_jsxs(GroupHeaderText, { children: [_jsxs(GroupTitle, { children: ["Grouped recording \u00B7 ", group.recordings.length, " feeds"] }), group.commonUtWindow && (_jsxs(GroupMeta, { children: ["common UT ", formatUt(group.commonUtWindow[0]), " -", " ", formatUt(group.commonUtWindow[1])] }))] }), _jsxs(GroupActions, { children: [_jsx(TrayButton, { type: "button", onClick: () => downloadAll(group.recordings, objectUrls, labelFor), children: "Download all" }), _jsx(TrayButton, { type: "button", "$danger": true, onClick: onDiscardGroup, children: "Discard set" })] })] }), group.recordings.map((rec) => (_jsx(ClipRow, { rec: rec, label: labelFor(rec.flightId), url: objectUrls.get(rec.recordingId) }, rec.recordingId)))] }));
@@ -74,6 +74,22 @@ function useClipObjectUrls(clips) {
 function formatUt(ut) {
     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) {
+    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) {
     const totalSeconds = Math.max(0, Math.round(ms / 1000));
     const hours = Math.floor(totalSeconds / 3600);

package/dist/hooks/useCommandDisplayUt.d.ts

@@ -1,4 +1,4 @@
-import { type FrameUtSource, type CommandTrackEvent } from "@ksp-gonogo/kerbcast";
+import { type FrameUtSource, type CommandTrackEvent, type FrameCommandState } 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;
@@ -8,7 +8,15 @@ export declare function crossesEvent(events: readonly CommandTrackEvent[] | unde
 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 declare function commandShownKey(c: FrameCommandState | undefined): string;
 /**
  * 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
@@ -17,6 +25,11 @@ 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 declare function useCommandDisplayUt(enabled: boolean, override?: number, events?: readonly CommandTrackEvent[], flightId?: number | null, video?: HTMLVideoElement | null): CommandDisplayUt | null;
+export declare function useCommandDisplayUt(enabled: boolean, override?: number, events?: readonly CommandTrackEvent[], flightId?: number | null, video?: HTMLVideoElement | null, overrideCommand?: FrameCommandState | null): CommandDisplayUt | null;

package/dist/hooks/useCommandDisplayUt.js

@@ -22,6 +22,35 @@ export function crossesEvent(events, from, to) {
     const hi = Math.max(from, to);
     return events.some((e) => e.ut > lo && e.ut <= hi);
 }
+/**
+ * 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) {
+    if (!c)
+        return "";
+    const sig = (v) => (v == null ? "" : Number(v.toPrecision(3)));
+    const half = (v) => (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,
+    ]);
+}
 /**
  * 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
@@ -30,9 +59,14 @@ export function crossesEvent(events, from, to) {
  * 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, override, events, flightId, video) {
+export function useCommandDisplayUt(enabled, override, events, flightId, video, overrideCommand) {
     const client = useKerbcastClient();
     const sample = useRef({
         captureUt: client.clock.captureUt,
@@ -58,39 +92,46 @@ export function useCommandDisplayUt(enabled, override, events, flightId, video)
         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. */
+    /* 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")
+                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();
             }
         });
     }, [client, enabled, overriding, flightId, video]);
     const { captureUt, warpRate, at } = sample.current;
-    const exact = frame.current;
+    const seen = frame.current;
+    const withCommand = (d, c) => c ? { ...d, command: c } : d;
     const displayUt = 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"
+    const untilEdge = enabled && displayUt?.source === "estimated" && !seen
         ? msUntilNextEvent(events, displayUt.ut, warpRate)
         : null;
     /* Edges further out than a tick are caught by a later render's timer. */

package/dist/hooks/useKerbcastWaitingForSlot.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Whether this client wants camera `flightId` but has no video slot to carry
+ * it (see `KerbcastCameraHandle.waitingForSlot`). False for a null id.
+ */
+export declare function useKerbcastWaitingForSlot(flightId: number | null): boolean;

package/dist/hooks/useKerbcastWaitingForSlot.js

@@ -0,0 +1,20 @@
+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) {
+    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/dist/hooks/useTargetBracketsPreference.d.ts

@@ -1,6 +1,7 @@
 /**
  * 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 declare function useTargetBracketsPreference(key: string | null): [boolean, () => void];
+export declare function useTargetBracketsPreference(key: string | null, legacyKey?: string | null): [boolean, () => void];

package/dist/hooks/useTargetBracketsPreference.js

@@ -1,8 +1,20 @@
 import { useCallback, useMemo, useState } from "react";
 const STORAGE_PREFIX = "kerbcast:target-brackets:";
-function readPreference(key) {
+/* A preference saved under `legacyKey` moves to `key` the first time it is read. */
+function readPreference(key, legacyKey) {
     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 +34,12 @@ function writePreference(key, on) {
 /**
  * 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) {
+export function useTargetBracketsPreference(key, legacyKey = null) {
     const [overrides, setOverrides] = useState({});
-    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)