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

package/README.md

@@ -68,6 +68,19 @@ comments):
   feed, and whether it draws its own standby icon (set `false` when a
   container renders a single shared out-of-flight overlay).
 - `useStream`. Override how the stream is sourced. See below.
+- `renderSize`. `"auto"` (the default) measures the feed and asks the
+  sidecar for a matching resolution; `"none"` leaves resolution alone.
+
+`renderSize="auto"` picks the resolution, never the shape. The feed takes
+the camera's configured capture aspect (`CameraState.maxWidth` x
+`maxHeight`, from settings.cfg; 16:9 when unknown), centres itself at that
+aspect inside whatever box you give it, and asks for the size of that
+picture: width rounded up to a multiple of 16, height at the aspect. A
+resize that only follows the incoming stream is never reported back, so a
+frame you size from the video (or from `renderWidth`/`renderHeight`)
+cannot loop with the request. A resize within about a second of the stream
+changing that matches its new shape counts as following it. Layout changes
+outside that window always report.
 
 An imperative `CameraFeedHandle` (via `ref`) exposes `stepCamera`,
 `setPanAxis`, `setZoomRate`, `nudgePan`, and `nudgeZoom` for wiring feeds
@@ -89,10 +102,12 @@ quality follows how large it is shown (pass `reportSize={false}` to opt out).
 
 ## Hooks
 
-- `useReportDisplaySize(flightId, ref)`. Self-measure an element and drive the
-  client's per-consumer `reportDisplaySize` (auto-resolution). The feed
-  primitives use it internally; multiple views of one camera from a client
-  collapse to a single MAX report.
+- `useReportDisplaySize(flightId, ref, options)`. Self-measure an element and
+  drive the client's per-consumer `reportDisplaySize` (auto-resolution). The
+  feed primitives use it internally; multiple views of one camera from a
+  client collapse to a single MAX report. Pass `aspect` for the shape to ask
+  for (default 16:9), and `videoRef` / `streamSize` so a resize that follows
+  the stream is not reported.
 
 - `useKerbcastCameras(): CameraState[]`. The live camera registry,
   re-rendering as cameras appear, change, or are destroyed.

package/dist/CameraFeed.js

@@ -12,7 +12,7 @@ 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 { DEFAULT_FEED_ASPECT, useReportDisplaySize } from "./hooks/useReportDisplaySize";
 import { useTargetBracketsPreference } from "./hooks/useTargetBracketsPreference";
 import { StandbyIcon } from "./StandbyIcon";
 import { isCameraDestroyed } from "./lifecycle";
@@ -391,10 +391,29 @@ const CameraFeedInner = forwardRef(function CameraFeedInner({ flightId: requeste
     // -------------------------------------------------------------------------
     // Display-size reporting (auto-resolution). The feed self-measures its
     // rendered box and reports it per-consumer; the sidecar maxes across
-    // consumers. Reports the real w x h (part cams are not square). Disabled by
-    // `renderSize="none"`. See useReportDisplaySize for debounce / bucketing.
+    // consumers. Auto picks the resolution, never the shape: the request and
+    // the feed's own box keep the camera's configured capture aspect (16:9
+    // when unknown). Disabled by `renderSize="none"`. The video and the
+    // sidecar's render size let it ignore a resize that only follows the
+    // stream. See useReportDisplaySize for debounce / bucketing / the guard.
     // -------------------------------------------------------------------------
-    useReportDisplaySize(flightId, wrapRef, { enabled: renderSize === "auto" });
+    const baseW = camera?.maxWidth ?? 0;
+    const baseH = camera?.maxHeight ?? 0;
+    const hasBase = baseW > 0 && baseH > 0;
+    const feedAspect = hasBase ? baseW / baseH : DEFAULT_FEED_ASPECT;
+    const feedShape = useMemo(() => ({
+        "--kc-feed-w": hasBase ? baseW : 16,
+        "--kc-feed-h": hasBase ? baseH : 9,
+    }), [hasBase, baseW, baseH]);
+    const renderedW = camera?.renderWidth ?? 0;
+    const renderedH = camera?.renderHeight ?? 0;
+    const renderedSize = useMemo(() => ({ width: renderedW, height: renderedH }), [renderedW, renderedH]);
+    useReportDisplaySize(flightId, wrapRef, {
+        enabled: renderSize === "auto",
+        aspect: feedAspect,
+        videoRef,
+        streamSize: renderedSize,
+    });
     // -------------------------------------------------------------------------
     // UI state
     // -------------------------------------------------------------------------
@@ -672,41 +691,41 @@ 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: attachVideo, autoPlay: true, playsInline: true, muted: true, controls: false, onClick: () => setChromePinned((v) => !v) }), topOverlay, actionBar, qualityAvailable &&
-                    qualityMenu.open &&
-                    qualityMenu.position &&
-                    camera &&
-                    createPortal(_jsxs(QualityMenu, { ref: qualityMenu.menuRef, id: qualityMenuId, role: "menu", "aria-label": "Quality", style: qualityMenu.position, children: [_jsx(CameraMenuItem, { type: "button", role: "menuitemradio", "aria-checked": camera.viewerQuality == null, "$selected": camera.viewerQuality == null, onClick: () => selectQuality(null), children: "Auto" }), QUALITY_PRESETS.map(({ preset, label, scale }) => (_jsxs(CameraMenuItem, { type: "button", role: "menuitemradio", "aria-checked": camera.viewerQuality === preset, "$selected": camera.viewerQuality === preset, onClick: () => selectQuality(preset), children: [label, " (", presetDim(camera.operatorWidth, scale), "\u00D7", presetDim(camera.operatorHeight, scale), ")"] }, preset))), _jsxs(QualityMeta, { role: "status", children: ["now ", camera.renderWidth, "\u00D7", camera.renderHeight, qualityThrottled ? " · throttled" : ""] })] }), document.body), trackingAvailable &&
-                    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), 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) => {
-                                const v = Number(e.target.value);
-                                controllerRef.current?.fovSliderInput(v);
-                            }, onPointerDown: () => {
-                                controllerRef.current?.setFovSliderDragging(true);
-                            }, onPointerUp: () => {
-                                controllerRef.current?.setFovSliderDragging(false);
-                            }, onPointerCancel: () => {
-                                controllerRef.current?.setFovSliderDragging(false);
-                            } }), _jsx(ZoomButton, { type: "button", "aria-label": "Zoom out", "$pos": "bottom", 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: "\u2212" })] })), showPan && (_jsxs(PanControl, { role: "group", "aria-label": "Pan camera", "$disabled": manualDisabled, "aria-hidden": manualDisabled, children: [_jsx(PanArrow, { type: "button", "$dir": "up", "aria-label": "Pan up", disabled: manualDisabled || !supportsPitch, onClick: () => controllerRef.current?.nudgePan(0, 1), children: "\u25B2" }), _jsx(PanArrow, { type: "button", "$dir": "down", "aria-label": "Pan down", disabled: manualDisabled || !supportsPitch, onClick: () => controllerRef.current?.nudgePan(0, -1), children: "\u25BC" }), _jsx(PanArrow, { type: "button", "$dir": "left", "aria-label": "Pan left", disabled: manualDisabled, onClick: () => controllerRef.current?.nudgePan(-1, 0), children: "\u25C0" }), _jsx(PanArrow, { type: "button", "$dir": "right", "aria-label": "Pan right", disabled: manualDisabled, onClick: () => controllerRef.current?.nudgePan(1, 0), children: "\u25B6" }), _jsx(PanBall, { "aria-hidden": "true", title: "Drag to pan", onPointerDown: manualDisabled ? undefined : handleBallDown, onPointerMove: manualDisabled ? undefined : handleBallMove, onPointerUp: manualDisabled ? undefined : handleBallUp, onPointerCancel: manualDisabled ? undefined : handleBallUp, style: {
-                                transform: `translate(${ballPos.x}px, ${ballPos.y}px)`,
-                            } })] }))] })) }));
+    return (_jsx(FeedBox, { style: feedShape, children: _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 &&
+                        createPortal(_jsxs(QualityMenu, { ref: qualityMenu.menuRef, id: qualityMenuId, role: "menu", "aria-label": "Quality", style: qualityMenu.position, children: [_jsx(CameraMenuItem, { type: "button", role: "menuitemradio", "aria-checked": camera.viewerQuality == null, "$selected": camera.viewerQuality == null, onClick: () => selectQuality(null), children: "Auto" }), QUALITY_PRESETS.map(({ preset, label, scale }) => (_jsxs(CameraMenuItem, { type: "button", role: "menuitemradio", "aria-checked": camera.viewerQuality === preset, "$selected": camera.viewerQuality === preset, onClick: () => selectQuality(preset), children: [label, " (", presetDim(camera.operatorWidth, scale), "\u00D7", presetDim(camera.operatorHeight, scale), ")"] }, preset))), _jsxs(QualityMeta, { role: "status", children: ["now ", camera.renderWidth, "\u00D7", camera.renderHeight, qualityThrottled ? " · throttled" : ""] })] }), document.body), trackingAvailable &&
+                        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), 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) => {
+                                    const v = Number(e.target.value);
+                                    controllerRef.current?.fovSliderInput(v);
+                                }, onPointerDown: () => {
+                                    controllerRef.current?.setFovSliderDragging(true);
+                                }, onPointerUp: () => {
+                                    controllerRef.current?.setFovSliderDragging(false);
+                                }, onPointerCancel: () => {
+                                    controllerRef.current?.setFovSliderDragging(false);
+                                } }), _jsx(ZoomButton, { type: "button", "aria-label": "Zoom out", "$pos": "bottom", 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: "\u2212" })] })), showPan && (_jsxs(PanControl, { role: "group", "aria-label": "Pan camera", "$disabled": manualDisabled, "aria-hidden": manualDisabled, children: [_jsx(PanArrow, { type: "button", "$dir": "up", "aria-label": "Pan up", disabled: manualDisabled || !supportsPitch, onClick: () => controllerRef.current?.nudgePan(0, 1), children: "\u25B2" }), _jsx(PanArrow, { type: "button", "$dir": "down", "aria-label": "Pan down", disabled: manualDisabled || !supportsPitch, onClick: () => controllerRef.current?.nudgePan(0, -1), children: "\u25BC" }), _jsx(PanArrow, { type: "button", "$dir": "left", "aria-label": "Pan left", disabled: manualDisabled, onClick: () => controllerRef.current?.nudgePan(-1, 0), children: "\u25C0" }), _jsx(PanArrow, { type: "button", "$dir": "right", "aria-label": "Pan right", disabled: manualDisabled, onClick: () => controllerRef.current?.nudgePan(1, 0), children: "\u25B6" }), _jsx(PanBall, { "aria-hidden": "true", title: "Drag to pan", onPointerDown: manualDisabled ? undefined : handleBallDown, onPointerMove: manualDisabled ? undefined : handleBallMove, onPointerUp: manualDisabled ? undefined : handleBallUp, onPointerCancel: manualDisabled ? undefined : handleBallUp, style: {
+                                    transform: `translate(${ballPos.x}px, ${ballPos.y}px)`,
+                                } })] }))] })) }) }));
 });
 // ---------------------------------------------------------------------------
 // Public CameraFeed - wraps inner in a nested provider when client prop given
@@ -1207,7 +1226,26 @@ const Panel = styled.div `
   border-radius: 4px;
   overflow: hidden;
 `;
+/*
+ * Fills the host and centres the Stage at the camera's configured aspect
+ * (--kc-feed-w / --kc-feed-h), so the picture fills the Stage and the host's
+ * spare room sits outside it.
+ */
+const FeedBox = styled.div `
+  width: 100%;
+  height: 100%;
+  min-width: 0;
+  min-height: 0;
+  container-type: size;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+`;
 const Stage = styled(Panel) `
+  width: min(100cqw, 100cqh * var(--kc-feed-w) / var(--kc-feed-h));
+  height: auto;
+  aspect-ratio: var(--kc-feed-w) / var(--kc-feed-h);
+  flex: none;
   padding: 0;
   gap: 0;
   position: relative;

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/useReportDisplaySize.d.ts

@@ -1,8 +1,31 @@
-/** Report size for a `width` x `height` box: bucketed width, height at the box's aspect. */
-export declare function displayReportSize(width: number, height: number): {
+/** 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
@@ -11,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
@@ -25,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;

package/dist/hooks/useReportDisplaySize.js

@@ -1,28 +1,85 @@
-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. 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 from the
- * box's own aspect, rounded to even for H.264, so the frame fills the box
- * instead of letterboxing inside it.
+ * 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;
 }
-/** Report size for a `width` x `height` box: bucketed width, height at the box's aspect. */
-export function displayReportSize(width, height) {
-    const w = bucket(width);
-    if (!(width > 0) || !(height > 0))
-        return { width: w, height: bucket(height) };
-    const h = Math.max(2, Math.round((w * height) / width / 2) * 2);
-    return { width: w, height: h };
+/** 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
@@ -33,21 +90,81 @@ export function displayReportSize(width, height) {
  * 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;
@@ -57,33 +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 = bucket(Math.min(width, height));
-            const { width: bw, height: bh } = square
-                ? { width: side, height: side }
-                : displayReportSize(width, 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ksp-gonogo/kerbcast-react",
-  "version": "1.11.0-rc.4",
+  "version": "1.11.0",
   "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.11.0-rc.4"
+    "@ksp-gonogo/kerbcast": "^1.11.0"
   },
   "peerDependencies": {
     "react": "^18 || ^19",