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

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

@@ -91,11 +91,11 @@ export function KerbalFaceFeed({ flightId, size, reportSize = true, actions, sho
     // Reporting follows the mount lifecycle; the registry collapses multiple
     // feeds of the same kerbal to one MAX report.
     const frameRef = useRef(null);
-    useReportDisplaySize(flightId, frameRef, { square: true, enabled: reportSize });
+    const videoRef = useRef(null);
+    useReportDisplaySize(flightId, frameRef, { square: true, enabled: reportSize, videoRef });
     // Bind the stream to the persistent <video> without remounting it — the
     // element stays mounted across every re-layout / prop change, only its
     // srcObject is (re)assigned. A stall (stream -> null) leaves the last frame.
-    const videoRef = useRef(null);
     useEffect(() => {
         if (videoRef.current && stream) {
             videoRef.current.srcObject = stream;

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

package/dist/hooks/useDisplayedFrameUt.d.ts

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

package/dist/hooks/useDisplayedFrameUt.js

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

package/dist/hooks/useReportDisplaySize.d.ts

@@ -1,3 +1,31 @@
+/** Shape of a camera whose configured capture size is not known. */
+export declare const DEFAULT_FEED_ASPECT: number;
+/**
+ * Report size for a `width` x `height` box: the `aspect` picture that fits it,
+ * width bucketed. Never the box's own shape.
+ */
+export declare function displayReportSize(width: number, height: number, aspect?: number): {
+    width: number;
+    height: number;
+};
+export interface Size {
+    width: number;
+    height: number;
+}
+/** The stream changing from `from` (null when nothing was known before) to `to`. */
+export interface StreamChange {
+    from: Size | null;
+    to: Size;
+}
+/**
+ * Whether a box going from `prev` to `box` is explained by `change`: the new
+ * box has the new stream's aspect, and it grew or shrank no more than the
+ * stream's own change in size or aspect accounts for. A layout that fits the
+ * stream into a fixed tile changes with the aspect; one that shows the video
+ * at its own size changes with the size. A box that jumps further (entering
+ * fullscreen at the same aspect) is a layout change.
+ */
+export declare function followsStream(prev: Size, box: Size, change: StreamChange): boolean;
 export interface ReportDisplaySizeOptions {
     /**
      * Report while mounted. Default true. Set false for a fixed-resolution feed
@@ -6,10 +34,25 @@ export interface ReportDisplaySizeOptions {
      */
     enabled?: boolean;
     /**
-     * Report a square (side x side, the min edge) rather than the raw w x h.
-     * Face cams are square; part cams are not.
+     * Report a square (side x side, the min edge) rather than a picture at
+     * `aspect`. Face cams are square; part cams are not.
      */
     square?: boolean;
+    /**
+     * Width over height of the picture to ask for, normally the camera's
+     * configured capture size. Default 16:9. Ignored when `square` is set.
+     */
+    aspect?: number;
+    /**
+     * The `<video>` playing this camera. Its resolution changes are watched so a
+     * box resize that only follows the stream is not reported back.
+     */
+    videoRef?: React.RefObject<HTMLVideoElement | null>;
+    /**
+     * The size the sidecar says it is rendering this camera at, for the same
+     * purpose: a layout may size itself from this rather than from the video.
+     */
+    streamSize?: Size | null;
 }
 /**
  * Self-measure a feed element and drive the client's per-consumer
@@ -20,5 +63,8 @@ export interface ReportDisplaySizeOptions {
  * mount lifecycle: on unmount / `flightId` change / `enabled` flip it
  * deregisters, and the sidecar's clear-on-departure (unsubscribe) does the
  * server-side clear.
+ *
+ * A box resize that follows a change in the incoming stream is not reported,
+ * so a layout sized from the stream cannot feed it back into its own request.
  */
-export declare function useReportDisplaySize(flightId: number | null, ref: React.RefObject<Element | null>, { enabled, square }?: ReportDisplaySizeOptions): void;
+export declare function useReportDisplaySize(flightId: number | null, ref: React.RefObject<Element | null>, { enabled, square, aspect, videoRef, streamSize, }?: ReportDisplaySizeOptions): void;