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

package/dist/hooks/useReportDisplaySize.js

@@ -1,19 +1,86 @@
-import { useEffect, useId, useLayoutEffect, useState } from "react";
+import { useCallback, useEffect, useId, useLayoutEffect, useRef, useState } from "react";
 import { useKerbcastDisplaySizes } from "../context";
 /*
  * Debounce + bucket for self-measured display-size reporting. The first
  * measurement after mount reports promptly (so a feed never sits at a stale
- * resolution until it is resized); later churn is debounced. Sizes are ceiled
- * to a BUCKET_PX multiple: that meets-the-minimum-need (never under-serve),
- * yields an even value (H.264-friendly), and gives a material-change threshold
- * so a feed re-reports only when a resize crosses a bucket boundary.
+ * resolution until it is resized); later churn is debounced. Auto sets the
+ * resolution, never the shape: the request keeps the camera's configured
+ * aspect and is sized to the picture of that aspect that fits the box (the
+ * feed letterboxes with object-fit: contain). The width is ceiled to a
+ * BUCKET_PX multiple: that meets-the-minimum-need (never under-serve) and
+ * gives a material-change threshold so a feed re-reports only when a resize
+ * crosses a bucket boundary. The height follows at the aspect, rounded to
+ * even for H.264.
  */
 const DEBOUNCE_MS = 200;
 const BUCKET_PX = 16;
+/*
+ * A resolution change must never cause another one. A box sized from the
+ * stream (a frame kept at the video's aspect, a `<video>` at its intrinsic
+ * size) would otherwise close a loop: the stream sets the box, the box sets
+ * the request, the request sets the stream. A stream that arrives smaller
+ * than asked (adaptive quality, a sidecar cap) would then shrink the next
+ * request, and so on down.
+ *
+ * FOLLOW_MS: a box change that starts this soon after the stream changed
+ * shape, and matches what that change explains, is the stream's doing. It is
+ * adopted as the new baseline and not reported. Layout reacts to a stream
+ * change within a frame or two; this leaves room for a slow phone.
+ *
+ * SUSPECT_MS / HOLD_MS: the backstop for a follow the check above misses (a
+ * very late layout, or one that does not keep the stream's shape). A box
+ * change this close to a stream change may still be a loop, so only one such
+ * report is let through per HOLD_MS; further ones are refused. Box changes
+ * away from any stream change always report.
+ */
+const FOLLOW_MS = 1000;
+const SUSPECT_MS = 2500;
+const HOLD_MS = 5000;
+const ASPECT_TOLERANCE = 0.06;
+const MAGNITUDE_SLACK = 1.15;
 function bucket(px) {
     const b = Math.ceil(px / BUCKET_PX) * BUCKET_PX;
     return b < BUCKET_PX ? BUCKET_PX : b;
 }
+/** Shape of a camera whose configured capture size is not known. */
+export const DEFAULT_FEED_ASPECT = 16 / 9;
+/**
+ * Report size for a `width` x `height` box: the `aspect` picture that fits it,
+ * width bucketed. Never the box's own shape.
+ */
+export function displayReportSize(width, height, aspect = DEFAULT_FEED_ASPECT) {
+    const a = aspect > 0 && Number.isFinite(aspect) ? aspect : DEFAULT_FEED_ASPECT;
+    const fit = width > 0 && height > 0 ? Math.min(width, height * a) : width;
+    const w = bucket(fit);
+    return { width: w, height: Math.max(2, Math.round(w / a / 2) * 2) };
+}
+function spread(a, b) {
+    return a > b ? a / b : b / a;
+}
+/**
+ * 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 function followsStream(prev, box, change) {
+    const { to, from } = change;
+    if (!(to.width > 0) || !(to.height > 0))
+        return false;
+    if (!(prev.width > 0) || !(prev.height > 0))
+        return false;
+    const aspect = to.width / to.height;
+    const heightFits = Math.abs(box.height - box.width / aspect) <= Math.max(2, ASPECT_TOLERANCE * box.height);
+    const widthFits = Math.abs(box.width - box.height * aspect) <= Math.max(2, ASPECT_TOLERANCE * box.width);
+    if (!heightFits && !widthFits)
+        return false;
+    if (!from)
+        return true;
+    const explained = Math.max(spread(to.width * to.height, from.width * from.height), spread(aspect, from.width / from.height));
+    return spread(box.width * box.height, prev.width * prev.height) <= explained * MAGNITUDE_SLACK;
+}
 /**
  * Self-measure a feed element and drive the client's per-consumer
  * `reportDisplaySize` (via the context display-size registry, which collapses
@@ -23,21 +90,81 @@ function bucket(px) {
  * 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 function useReportDisplaySize(flightId, ref, { enabled = true, square = false } = {}) {
+export function useReportDisplaySize(flightId, ref, { enabled = true, square = false, aspect = DEFAULT_FEED_ASPECT, videoRef, streamSize, } = {}) {
     const displaySizes = useKerbcastDisplaySizes();
     const instanceId = useId();
     /*
-     * Track the element behind the ref as state so an element that mounts or is
-     * swapped after the first render (conditional render, a feed that appears
-     * once a stream arrives) is observed. Checked after every commit of the
-     * host component; the state only changes when the element does.
+     * Track the elements behind the refs as state so an element that mounts or
+     * is swapped after the first render (conditional render, a feed that appears
+     * once a stream arrives) is observed. Checked after every commit of the host
+     * component; the state only changes when the element does.
      */
     const [el, setEl] = useState(null);
+    const [video, setVideo] = useState(null);
     useLayoutEffect(() => {
         if (ref.current !== el)
             setEl(ref.current);
+        const v = videoRef?.current ?? null;
+        if (v !== video)
+            setVideo(v);
     });
+    const changes = useRef([]);
+    const lastStream = useRef(null);
+    const lastBySource = useRef({ video: null, render: null });
+    /*
+     * Each source is compared with its own last value, so the video and the
+     * sidecar's render size reporting the same new shape at different moments
+     * are both noted. The first render size is only a baseline: a layout built
+     * from it was already in place when the first measurement went out.
+     */
+    const noteStream = useCallback((source, width, height) => {
+        if (!(width > 0) || !(height > 0))
+            return;
+        const seen = lastBySource.current[source];
+        if (seen && seen.width === width && seen.height === height)
+            return;
+        const to = { width, height };
+        lastBySource.current[source] = to;
+        const from = lastStream.current;
+        lastStream.current = to;
+        if (!from && source === "render")
+            return;
+        const now = Date.now();
+        changes.current = changes.current.filter((c) => now - c.at <= SUSPECT_MS + DEBOUNCE_MS);
+        changes.current.push({ at: now, from, to });
+    }, []);
+    useEffect(() => {
+        if (!video)
+            return;
+        const sync = () => noteStream("video", video.videoWidth, video.videoHeight);
+        sync();
+        video.addEventListener("loadedmetadata", sync);
+        video.addEventListener("resize", sync);
+        return () => {
+            video.removeEventListener("loadedmetadata", sync);
+            video.removeEventListener("resize", sync);
+        };
+    }, [video, noteStream]);
+    /* A layout effect, so it is noted before the observer sees the box this commit lays out. */
+    const streamW = streamSize?.width ?? 0;
+    const streamH = streamSize?.height ?? 0;
+    useLayoutEffect(() => {
+        noteStream("render", streamW, streamH);
+    }, [streamW, streamH, noteStream]);
+    /*
+     * The aspect is read through a ref so the camera's configured size arriving
+     * after mount re-sizes the current request without a clear and re-register.
+     */
+    const aspectRef = useRef(aspect);
+    const reapply = useRef(null);
+    useEffect(() => {
+        aspectRef.current = aspect;
+        reapply.current?.();
+    }, [aspect]);
     useEffect(() => {
         if (flightId === null || !enabled)
             return;
@@ -47,32 +174,71 @@ export function useReportDisplaySize(flightId, ref, { enabled = true, square = f
         let lastW = -1;
         let lastH = -1;
         let firstReported = false;
-        const report = (width, height) => {
-            const side = square ? Math.min(width, height) : 0;
-            const bw = bucket(square ? side : width);
-            const bh = bucket(square ? side : height);
-            if (bw === lastW && bh === lastH)
+        let baseline = null;
+        let lastSuspectAt = Number.NEGATIVE_INFINITY;
+        const sizeFor = (box) => {
+            if (!square)
+                return displayReportSize(box.width, box.height, aspectRef.current);
+            const side = bucket(Math.min(box.width, box.height));
+            return { width: side, height: side };
+        };
+        const send = ({ width, height }) => {
+            lastW = width;
+            lastH = height;
+            displaySizes.report(flightId, instanceId, width, height);
+        };
+        /*
+         * Judged when the debounce settles, so a stream change noted a little after
+         * the observer fired (a host that commits the stream and the box in a
+         * different order) still counts.
+         */
+        const settle = (box, seenAt) => {
+            const prev = baseline;
+            baseline = box;
+            const now = Date.now();
+            const near = changes.current.filter((c) => c.at <= now && c.at >= seenAt - SUSPECT_MS);
+            if (prev && near.some((c) => c.at >= seenAt - FOLLOW_MS && followsStream(prev, box, c))) {
+                return;
+            }
+            const next = sizeFor(box);
+            if (next.width === lastW && next.height === lastH)
                 return;
-            lastW = bw;
-            lastH = bh;
-            displaySizes.report(flightId, instanceId, bw, bh);
+            if (near.length > 0) {
+                const held = now - lastSuspectAt < HOLD_MS;
+                lastSuspectAt = now;
+                if (held)
+                    return;
+            }
+            send(next);
         };
         const observer = new ResizeObserver((entries) => {
             const entry = entries[0];
             if (!entry)
                 return;
-            const { width, height } = entry.contentRect;
+            const box = { width: entry.contentRect.width, height: entry.contentRect.height };
             if (!firstReported) {
                 firstReported = true;
-                report(width, height);
+                baseline = box;
+                const next = sizeFor(box);
+                if (next.width !== lastW || next.height !== lastH)
+                    send(next);
                 return;
             }
+            const seenAt = Date.now();
             if (timer !== null)
                 clearTimeout(timer);
-            timer = setTimeout(() => report(width, height), DEBOUNCE_MS);
+            timer = setTimeout(() => settle(box, seenAt), DEBOUNCE_MS);
         });
         observer.observe(el);
+        reapply.current = () => {
+            if (!baseline)
+                return;
+            const next = sizeFor(baseline);
+            if (next.width !== lastW || next.height !== lastH)
+                send(next);
+        };
         return () => {
+            reapply.current = null;
             observer.disconnect();
             if (timer !== null)
                 clearTimeout(timer);

package/dist/hooks/useTargetBracketsPreference.d.ts

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

package/dist/hooks/useTargetBracketsPreference.js

@@ -0,0 +1,39 @@
+import { useCallback, useMemo, useState } from "react";
+const STORAGE_PREFIX = "kerbcast:target-brackets:";
+function readPreference(key) {
+    try {
+        return globalThis.localStorage?.getItem(STORAGE_PREFIX + key) !== "0";
+    }
+    catch {
+        return true;
+    }
+}
+function writePreference(key, on) {
+    try {
+        if (on)
+            globalThis.localStorage?.removeItem(STORAGE_PREFIX + key);
+        else
+            globalThis.localStorage?.setItem(STORAGE_PREFIX + key, "0");
+    }
+    catch {
+        /* Storage blocked or full: the toggle still works for this session. */
+    }
+}
+/**
+ * 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.
+ */
+export function useTargetBracketsPreference(key) {
+    const [overrides, setOverrides] = useState({});
+    const stored = useMemo(() => (key === null ? true : readPreference(key)), [key]);
+    const on = key !== null && key in overrides ? overrides[key] : stored;
+    const toggle = useCallback(() => {
+        if (key === null)
+            return;
+        const next = !on;
+        writePreference(key, next);
+        setOverrides((o) => ({ ...o, [key]: next }));
+    }, [key, on]);
+    return [on, toggle];
+}

package/dist/index.d.ts

@@ -10,6 +10,7 @@ export type { KerbcastProviderProps, KerbcastSubscriptions, KerbcastDisplaySizes
 export { useKerbcastCameras } from "./hooks/useKerbcastCameras";
 export { useKerbcastStream } from "./hooks/useKerbcastStream";
 export { useKerbcastClock } from "./hooks/useKerbcastClock";
+export { useDisplayedFrameUt } from "./hooks/useDisplayedFrameUt";
 export { useKerbcastInFlight } from "./hooks/useKerbcastInFlight";
 export { useReportDisplaySize } from "./hooks/useReportDisplaySize";
 export { useRecordings } from "./hooks/useRecordings";
@@ -22,6 +23,8 @@ export { getCameraLifecycle, isCameraDestroyed } from "./lifecycle";
 export type { CameraLifecycle } from "./lifecycle";
 export { CameraFeed } from "./CameraFeed";
 export type { CameraFeedHandle, CameraFeedProps, CameraStreamHook, FeedAction, } from "./CameraFeed";
+export { bracketGeometry, containedContentRect, COMMAND_BRACKET_COLOURS } from "./CommandBrackets";
+export type { BracketGeometry, BracketPoint, CommandBracketContext, CommandBracketCorner, CommandBracketCornerOverride, CommandBracketCornerOverrides, CommandBracketCornerStyle, CommandBracketOverlay, ContentRect, } from "./CommandBrackets";
 export { FeedActionBar } from "./FeedActionBar";
 export type { FeedActionBarEntry } from "./FeedActionBar";
 export { KerbalFaceFeed } from "./KerbalFaceFeed";

package/dist/index.js

@@ -11,6 +11,7 @@ export { KerbcastProvider, createClientSubscriptions, createClientDisplaySizes,
 export { useKerbcastCameras } from "./hooks/useKerbcastCameras";
 export { useKerbcastStream } from "./hooks/useKerbcastStream";
 export { useKerbcastClock } from "./hooks/useKerbcastClock";
+export { useDisplayedFrameUt } from "./hooks/useDisplayedFrameUt";
 export { useKerbcastInFlight } from "./hooks/useKerbcastInFlight";
 export { useReportDisplaySize } from "./hooks/useReportDisplaySize";
 export { useRecordings } from "./hooks/useRecordings";
@@ -24,6 +25,8 @@ export { buildCameraLabeler } from "./cameraLabels";
 export { getCameraLifecycle, isCameraDestroyed } from "./lifecycle";
 // CameraFeed component
 export { CameraFeed } from "./CameraFeed";
+// Target brackets geometry and the overlay API for drawing on top of them
+export { bracketGeometry, containedContentRect, COMMAND_BRACKET_COLOURS } from "./CommandBrackets";
 // FeedActionBar: the shared action row (tracking, fullscreen, PiP, quality,
 // close, REC) both CameraFeed and KerbalFaceFeed render, with the issue-#6
 // overflow (⋮) engine.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ksp-gonogo/kerbcast-react",
-  "version": "1.10.2",
+  "version": "1.11.0-rc.10",
   "description": "React components and hooks for kerbcast camera feeds.",
   "license": "MIT",
   "author": "Jon Pepler",
@@ -45,7 +45,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@ksp-gonogo/kerbcast": "^1.10.2"
+    "@ksp-gonogo/kerbcast": "^1.11.0-rc.10"
   },
   "peerDependencies": {
     "react": "^18 || ^19",