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

package/README.md

@@ -52,7 +52,10 @@ Commonly used props (`CameraFeedProps` has the full set with doc
 comments):
 
 - `flightId: number | null`. The camera to show. `null` latches the
-  first live camera and re-picks if it dies.
+  first live camera and re-picks if it dies. A shown camera that drops
+  out of the camera list stays on screen for `KERBCAST_RELEASE_GRACE_MS`
+  before the feed falls back. A recording of it still ends at once
+  (`camera-gone`)
 - `onSelectCamera` / `onDisplayedCameraChange`. The user picked a
   camera, or the resolved camera changed (including auto-latch).
 - `enableFullscreen`, `enablePictureInPicture`, `enableQualityControl`.
@@ -82,6 +85,18 @@ 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.
 
+The feed frame (the element fullscreen targets) carries two attributes for
+hosts and tests:
+
+- `data-kc-signal`: `live`, `stalled` (no frame has left the decoder for
+  half a second, or none yet since the source attached) or `none` (no
+  source). It is measured after any encoded transform the host installs, so
+  a transform that holds frames back shows as `stalled` while it holds them.
+  The video keeps presenting frames while it shows static, so its frame
+  counts cannot tell a picture from static, and inbound-rtp `framesDecoded`
+  averaged over seconds misses gaps this short; this attribute can
+- `data-fullscreen`: present while the feed is fullscreen
+
 An imperative `CameraFeedHandle` (via `ref`) exposes `stepCamera`,
 `setPanAxis`, `setZoomRate`, `nudgePan`, and `nudgeZoom` for wiring feeds
 to a gamepad or keyboard.
@@ -172,7 +187,12 @@ quality follows how large it is shown (pass `reportSize={false}` to opt out).
   re-rendering as cameras appear, change, or are destroyed.
 - `useKerbcastStream(flightId): MediaStream | null`. The video stream
   for one camera, acquiring and releasing its subscription slot. This is
-  what `CameraFeed` uses internally.
+  what `CameraFeed` uses internally. A released slot is kept for
+  `KERBCAST_RELEASE_GRACE_MS` (2000 ms), so a feed that remounts inside
+  that window picks up the running stream instead of starting it again.
+  It is let go at once when a feed switches to another camera, or when a
+  feed is waiting for a slot. Pass `releaseGraceMs` to `KerbcastProvider`
+  (or to `createClientSubscriptions`) for a different grace, or 0 for none
 - `useKerbcastInFlight(): boolean | undefined`. Whether KSP is in a
   flight scene. `undefined` until the first signal arrives, so you can
   avoid flashing an out-of-flight state on connect.

package/dist/AnchorMarkers.d.ts

@@ -119,10 +119,15 @@ export declare function AnchorMarkers({ frame, video, overlay, fit }: AnchorMark
  * so a feed's other UI does not re-render at the frame rate.
  */
 export declare function useDisplayedFrame(enabled: boolean, flightId: number | null, video: HTMLVideoElement | null): DisplayedFrameUt | null;
-/** Self-subscribing markers for a feed: watches its displayed frames and draws their anchors. */
-export declare function LiveAnchorMarkers({ flightId, video, overlay, fit, }: {
+/**
+ * Self-subscribing markers for a feed: watches its displayed frames and
+ * draws their anchors, or draws `frame`'s while a host's own delayed
+ * playout gives it.
+ */
+export declare function LiveAnchorMarkers({ flightId, video, overlay, fit, frame: given, }: {
     flightId: number | null;
     video: HTMLVideoElement | null;
     overlay?: AnchorOverlay | null;
     fit?: FrameFit;
+    frame?: DisplayedFrameUt | null;
 }): import("react").JSX.Element;

package/dist/AnchorMarkers.js

@@ -135,9 +135,14 @@ export function useDisplayedFrame(enabled, flightId, video) {
     }, [client, enabled, flightId, video]);
     return frame;
 }
-/** Self-subscribing markers for a feed: watches its displayed frames and draws their anchors. */
-export function LiveAnchorMarkers({ flightId, video, overlay, fit, }) {
-    const frame = useDisplayedFrame(true, flightId, video);
+/**
+ * Self-subscribing markers for a feed: watches its displayed frames and
+ * draws their anchors, or draws `frame`'s while a host's own delayed
+ * playout gives it.
+ */
+export function LiveAnchorMarkers({ flightId, video, overlay, fit, frame: given, }) {
+    const watched = useDisplayedFrame(!given, flightId, video);
+    const frame = given ?? watched;
     return _jsx(AnchorMarkers, { frame: frame, video: video, overlay: overlay, fit: fit });
 }
 const MarkerSvg = styled.svg `

package/dist/CameraFeed.d.ts

@@ -28,7 +28,11 @@ export interface CameraFeedProps {
     client?: KerbcastClient;
     /**
      * KSP `Part.flightID` of the camera to display. `null` triggers
-     * auto-selection: the first live camera in the registry is latched.
+     * auto-selection: the first live camera in the registry is latched. A
+     * displayed camera that drops out of the list stays on screen, with its
+     * last known state, for `KERBCAST_RELEASE_GRACE_MS` before the feed falls
+     * back, so a momentary gap does not restart its stream. A recording of
+     * that camera still ends at once (`camera-gone`).
      */
     flightId: number | null;
     /**
@@ -218,19 +222,22 @@ export interface CameraFeedProps {
     noSlotLabel?: string | null;
     /**
      * Mission UT the displayed video was captured at, for a host running its
-     * own delayed playout. Picks which command-track transition is in force and
-     * ages the readout. Defaults to the displayed frame's own capture UT where
-     * the browser reports frame RTP timestamps, else the client's capture
-     * clock interpolated to now. While a command lock is held the brackets and
-     * readout come from the displayed frame's own state, which a UT alone does
-     * not carry: such a host passes `displayFrame` instead.
+     * own delayed playout: the capture UT of the frame its buffer last
+     * released. Picks which command-track transition is in force and ages the
+     * readout, and the brackets, readout and anchor markers come from the
+     * newest frame at or before it (`KerbcastClient.frameAt`), so they never
+     * run ahead of the picture. Before any frame that old is known they behave
+     * as without it. Defaults to the displayed frame's own capture UT where the
+     * browser reports frame RTP timestamps, else the client's capture clock
+     * interpolated to now.
      */
     displayUt?: number;
     /**
      * The frame a host's own delayed playout is showing, as
      * `watchDisplayedFrames` reported it when it arrived. Wins over
-     * `displayUt`: its `ut` picks the transition in force and its `command`
-     * draws the brackets and readout, so they never run ahead of the picture.
+     * `displayUt`: its `ut` picks the transition in force, its `command`
+     * draws the brackets and readout and its `anchors` the markers, so they
+     * never run ahead of the picture.
      */
     displayFrame?: DisplayedFrameUt | null;
     /**

package/dist/CameraFeed.js

@@ -4,7 +4,7 @@ import { forwardRef, useCallback, useEffect, useId, useImperativeHandle, useMemo
 import { createPortal } from "react-dom";
 import styled, { css } from "styled-components";
 import { buildCameraLabeler } from "./cameraLabels";
-import { KerbcastProvider, useKerbcastClient } from "./context";
+import { KERBCAST_RELEASE_GRACE_MS, KerbcastProvider, useKerbcastClient } from "./context";
 import { ActionBarRow, FeedActionBar, OverlayIconButton, feedActionToEntry, } from "./FeedActionBar";
 import { CommandBlank, LiveCommandBrackets } from "./CommandBrackets";
 import { LiveAnchorMarkers } from "./AnchorMarkers";
@@ -19,7 +19,7 @@ import { useTargetBracketsPreference } from "./hooks/useTargetBracketsPreference
 import { StandbyIcon } from "./StandbyIcon";
 import { isCameraDestroyed } from "./lifecycle";
 import { claimAnchors } from "./sharedAnchors";
-import { usePortalMenu } from "./menuPositioning";
+import { menuPortalRoot, usePortalMenu } from "./menuPositioning";
 import { formatElapsed, nowMs } from "./timing";
 // ---------------------------------------------------------------------------
 // Tuning constants
@@ -44,6 +44,15 @@ function presetDim(operatorDim, scale) {
     const v = Math.trunc(operatorDim * scale) & ~1;
     return v < 2 ? 2 : v;
 }
+function videoTrackId(source) {
+    if (!source || !("getVideoTracks" in source))
+        return undefined;
+    return source.getVideoTracks()[0]?.id;
+}
+function sameVideoTrack(a, b) {
+    const id = videoTrackId(a);
+    return id !== undefined && id === videoTrackId(b);
+}
 function isFullscreenSupported() {
     if (typeof document === "undefined")
         return false;
@@ -103,23 +112,47 @@ const CameraFeedInner = forwardRef(function CameraFeedInner({ flightId: requeste
     //
     // Resolution order:
     //   1. Explicit pick, if still present in the list (destroyed or not).
-    //   2. Auto: latch the currently-displayed camera. Keep showing it even if
+    //   2. Hold: the displayed camera, briefly missing from the list.
+    //   3. Auto: latch the currently-displayed camera. Keep showing it even if
     //      destroyed, but only while no other live camera exists (destroyed
     //      tombstones never leave the list on their own, so a destroyed latch
     //      would otherwise never release). Once a live camera is available,
     //      release the latch and auto-pick it.
-    //   3. Fresh auto-pick: prefer the first live camera; fall back to first
+    //   4. Fresh auto-pick: prefer the first live camera; fall back to first
     //      overall only when every camera is destroyed.
     // -------------------------------------------------------------------------
     const displayedRef = useRef(null);
+    const requestedRef = useRef(requestedFlightId);
+    const lastCameraRef = useRef(null);
+    /* The camera whose hold ran out, so it is let go until it is listed again. */
+    const [expiredHold, setExpiredHold] = useState(null);
+    /*
+     * The displayed camera dropping out of the list for an update or two (an
+     * empty snapshot at launch or revert, a host filter that skips it once)
+     * would otherwise switch the feed away and back, restarting the stream
+     * both times. Keep showing it, with its last known state, for
+     * KERBCAST_RELEASE_GRACE_MS. A new `flightId` prop is a real choice and
+     * switches at once, and a requested camera that is listed wins over a
+     * held one. The hold is the feed's alone: a recording of the camera
+     * still ends at once as camera-gone.
+     */
     const requestedStillPresent = requestedFlightId !== null &&
         cameras.some((c) => c.flightId === requestedFlightId);
+    const displayed = displayedRef.current;
+    const holding = !requestedStillPresent &&
+        displayed !== null &&
+        expiredHold !== displayed &&
+        requestedFlightId === requestedRef.current &&
+        !cameras.some((c) => c.flightId === displayed);
     let flightId;
     if (requestedStillPresent) {
         flightId = requestedFlightId;
     }
+    else if (holding) {
+        flightId = displayed;
+    }
     else {
-        const latched = displayedRef.current;
+        const latched = displayed;
         const latchedCamera = latched !== null ? cameras.find((c) => c.flightId === latched) : undefined;
         const anyLive = cameras.some((c) => !isCameraDestroyed(c));
         const latchedPresent = latchedCamera !== undefined &&
@@ -130,9 +163,31 @@ const CameraFeedInner = forwardRef(function CameraFeedInner({ flightId: requeste
                 cameras[0]?.flightId ??
                 null);
     }
-    const camera = flightId !== null
+    const listedCamera = flightId !== null
         ? (cameras.find((c) => c.flightId === flightId) ?? null)
         : null;
+    const camera = holding && lastCameraRef.current?.flightId === flightId
+        ? lastCameraRef.current
+        : listedCamera;
+    useEffect(() => {
+        if (listedCamera)
+            lastCameraRef.current = listedCamera;
+    }, [listedCamera]);
+    useEffect(() => {
+        if (!holding || displayed === null)
+            return;
+        const timer = setTimeout(() => setExpiredHold(displayed), KERBCAST_RELEASE_GRACE_MS);
+        return () => clearTimeout(timer);
+    }, [holding, displayed]);
+    /* Listed again, so a later gap gets a hold of its own. */
+    useEffect(() => {
+        if (expiredHold !== null && cameras.some((c) => c.flightId === expiredHold)) {
+            setExpiredHold(null);
+        }
+    }, [expiredHold, cameras]);
+    useEffect(() => {
+        requestedRef.current = requestedFlightId;
+    }, [requestedFlightId]);
     // Latest onDisplayedCameraChange, held in a ref so the commit effect below
     // fires only on a resolved-flightId change, not on every render when the
     // consumer passes an inline callback.
@@ -161,10 +216,17 @@ const CameraFeedInner = forwardRef(function CameraFeedInner({ flightId: requeste
     }, []);
     // The feed frame; fullscreen targets this and ResizeObserver measures it.
     const wrapRef = useRef(null);
+    /* Clearing to null on a switch to a camera with no stream yet stops the
+       previous camera's last frame lingering. A rebind can hand over a new
+       MediaStream around the same track; reassigning that would reset the
+       element and flash black, so it is skipped. */
     useEffect(() => {
-        if (videoRef.current && stream) {
-            videoRef.current.srcObject = stream;
-        }
+        const video = videoRef.current;
+        if (!video || video.srcObject === stream)
+            return;
+        if (sameVideoTrack(video.srcObject, stream))
+            return;
+        video.srcObject = stream;
     }, [stream]);
     // -------------------------------------------------------------------------
     // Stall presentation. The static is composited in-stream by the SDK's
@@ -186,6 +248,19 @@ const CameraFeedInner = forwardRef(function CameraFeedInner({ flightId: requeste
         setIsStale(cam.stalled);
         return cam.on("stall", setIsStale);
     }, [client, flightId]);
+    const [hasSource, setHasSource] = useState(false);
+    useEffect(() => {
+        if (flightId === null) {
+            setHasSource(false);
+            return;
+        }
+        const cam = client.camera(flightId);
+        setHasSource(cam.hasSource);
+        return cam.on("source", setHasSource);
+    }, [client, flightId]);
+    /* The in-stream static keeps the video element presenting frames, so a
+       frame count cannot tell a picture from static; this attribute can. */
+    const signal = flightId === null ? undefined : !hasSource ? "none" : isStale ? "stalled" : "live";
     // -------------------------------------------------------------------------
     // Fullscreen + Picture-in-Picture (opt-in, feature-detected)
     // -------------------------------------------------------------------------
@@ -224,6 +299,21 @@ const CameraFeedInner = forwardRef(function CameraFeedInner({ flightId: requeste
             v.removeEventListener("leavepictureinpicture", onLeave);
         };
     }, [pipAvailable, flightId]);
+    /* Browsers usually consume Escape to leave fullscreen themselves; this
+       covers hosts and embedded views that hand the key to the page instead. */
+    useEffect(() => {
+        if (!isFullscreen)
+            return;
+        const onKey = (e) => {
+            if (e.key === "Escape" &&
+                !e.defaultPrevented &&
+                currentFullscreenElement() === wrapRef.current) {
+                exitFullscreen();
+            }
+        };
+        document.addEventListener("keydown", onKey);
+        return () => document.removeEventListener("keydown", onKey);
+    }, [isFullscreen]);
     const toggleFullscreen = useCallback(() => {
         const el = wrapRef.current;
         if (!el)
@@ -263,7 +353,10 @@ const CameraFeedInner = forwardRef(function CameraFeedInner({ flightId: requeste
     const commandCamera = camera?.kind === CameraKind.Command && !isDestroyed ? camera : null;
     const isCommandFeed = commandCamera !== null;
     const commandTrack = commandCamera?.commandTrack ?? null;
-    const commandDisplayUt = useCommandDisplayUt(commandTrack !== null, displayFrame ? displayFrame.ut : displayUtProp, commandTrack?.events, commandCamera?.flightId ?? null, videoEl, displayFrame?.command);
+    /* A host on its own delay names the frame it shows, or its UT for the client to look the frame up by. */
+    const hostFrame = displayFrame ??
+        (displayUtProp !== undefined && flightId !== null ? client.frameAt(flightId, displayUtProp) : null);
+    const commandDisplayUt = useCommandDisplayUt(commandTrack !== null, displayFrame ? displayFrame.ut : displayUtProp, commandTrack?.events, commandCamera?.flightId ?? null, videoEl, hostFrame?.command);
     const commandState = commandTrack
         ? effectiveCommandTrack(commandTrack, commandDisplayUt?.ut, commandDisplayUt?.command)
         : null;
@@ -583,7 +676,7 @@ const CameraFeedInner = forwardRef(function CameraFeedInner({ flightId: requeste
                 createPortal(_jsx(CameraMenu, { ref: cameraMenu.menuRef, id: menuId, role: "menu", "aria-label": "Camera", style: cameraMenu.position, children: cameras.map((c) => (_jsxs(CameraMenuItem, { type: "button", role: "menuitemradio", "aria-checked": c.flightId === flightId, "$selected": c.flightId === flightId, onClick: () => {
                             onSelectCamera?.(c.flightId);
                             cameraMenu.close();
-                        }, children: [cameraLabel(c), " (", c.vesselName, ")", isCameraDestroyed(c) ? " - signal lost" : ""] }, c.flightId))) }), document.body), showDebugInfo &&
+                        }, children: [cameraLabel(c), " (", c.vesselName, ")", isCameraDestroyed(c) ? " - signal lost" : ""] }, c.flightId))) }), menuPortalRoot()), showDebugInfo &&
                 (camera ? (_jsxs(TopMeta, { children: [camera.vesselName, " \u00B7 ", camera.renderWidth, "\u00D7", camera.renderHeight, bitrateLabel, adaptiveLabel] })) : (_jsx(TopMeta, { children: "no cameras on this vessel" })))] }));
     /*
      * Built-in action-bar entries, in the bar's natural (fallback) order:
@@ -677,8 +770,11 @@ const CameraFeedInner = forwardRef(function CameraFeedInner({ flightId: requeste
                 {
                     id: "fullscreen",
                     label: fullscreenLabel,
+                    /* While fullscreen the exit stays inline, never in the ⋮ menu,
+                       so it can be the one control the Stage keeps visible. */
                     stateful: false,
-                    render: () => (_jsx(OverlayIconButton, { type: "button", "aria-label": fullscreenLabel, "aria-pressed": isFullscreen, title: fullscreenLabel, "$active": isFullscreen, onClick: toggleFullscreen, children: isFullscreen ? _jsx(FullscreenExitIcon, {}) : _jsx(FullscreenEnterIcon, {}) })),
+                    inline: isFullscreen,
+                    render: () => (_jsx(OverlayIconButton, { type: "button", "data-kc-fullscreen-exit": isFullscreen || undefined, "aria-label": fullscreenLabel, "aria-pressed": isFullscreen, title: fullscreenLabel, "$active": isFullscreen, onClick: toggleFullscreen, children: isFullscreen ? _jsx(FullscreenExitIcon, {}) : _jsx(FullscreenEnterIcon, {}) })),
                 },
             ]
             : []),
@@ -713,24 +809,24 @@ 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(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 &&
+    return (_jsx(FeedBox, { style: feedShape, children: _jsx(Stage, { ref: wrapRef, "$pinned": chromePinned, "$fullscreen": isFullscreen, "data-fullscreen": isFullscreen || undefined, "data-kc-signal": signal, 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 &&
+                        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" : ""] })] }), menuPortalRoot()), 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 &&
+                        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" })] }), menuPortalRoot()), 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 &&
+                            }) }), menuPortalRoot()), commandState &&
                         !outOfFlight &&
-                        (_jsxs(_Fragment, { children: [commandState.blank && _jsx(CommandBlank, { reason: commandState.blank }), commandState.waitingForTarget && !commandState.blank && !isDestroyed && waitingForTargetLabel && (_jsx(WaitingBadge, { role: "status", children: waitingForTargetLabel })), targetBracketsAvailable && bracketsOn && (_jsx(LiveCommandBrackets, { flightId: commandCamera?.flightId ?? null, state: commandState, displayUt: commandDisplayUt?.ut ?? commandTrack.ut, utSource: commandDisplayUt?.source ?? null, video: videoEl, fallbackSize: camera ? { width: camera.renderWidth, height: camera.renderHeight } : null, overlay: targetBracketOverlay }))] })), waitingForSlot && !outOfFlight && !isDestroyed && noSlotLabel && (_jsx(NoSlotNotice, { role: "status", children: noSlotLabel })), drawsAnchors && !outOfFlight && !isDestroyed && !commandState?.blank && (_jsx(LiveAnchorMarkers, { flightId: flightId, video: videoEl, overlay: anchorOverlay })), 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 && !savingActive && (_jsxs(RecBadge, { role: "status", "aria-label": "Recording", children: [_jsx(RecDot, { "aria-hidden": "true" }), "REC ", formatElapsed(recordingElapsedMs)] })), recordingActive && savingActive && (_jsx(RecBadge, { role: "status", "aria-label": "Saving recording", children: "SAVING" })), 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) => {
+                        (_jsxs(_Fragment, { children: [commandState.blank && _jsx(CommandBlank, { reason: commandState.blank }), commandState.waitingForTarget && !commandState.blank && !isDestroyed && waitingForTargetLabel && (_jsx(WaitingBadge, { role: "status", children: waitingForTargetLabel })), targetBracketsAvailable && bracketsOn && (_jsx(LiveCommandBrackets, { flightId: commandCamera?.flightId ?? null, frame: hostFrame, state: commandState, displayUt: commandDisplayUt?.ut ?? commandTrack.ut, utSource: commandDisplayUt?.source ?? null, video: videoEl, fallbackSize: camera ? { width: camera.renderWidth, height: camera.renderHeight } : null, overlay: targetBracketOverlay }))] })), waitingForSlot && !outOfFlight && !isDestroyed && noSlotLabel && (_jsx(NoSlotNotice, { role: "status", children: noSlotLabel })), drawsAnchors && !outOfFlight && !isDestroyed && !commandState?.blank && (_jsx(LiveAnchorMarkers, { flightId: flightId, video: videoEl, overlay: anchorOverlay, frame: hostFrame })), 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 && !savingActive && (_jsxs(RecBadge, { role: "status", "aria-label": "Recording", children: [_jsx(RecDot, { "aria-hidden": "true" }), "REC ", formatElapsed(recordingElapsedMs)] })), recordingActive && savingActive && (_jsx(RecBadge, { role: "status", "aria-label": "Saving recording", children: "SAVING" })), 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) => {
@@ -1033,8 +1129,9 @@ const StepButtons = styled.div `
   flex-shrink: 0;
 `;
 const CameraMenu = styled.div `
-  /* Portaled to document.body: fixed position (set inline from the trigger
-     rect) keeps it clear of the tile's overflow clipping. */
+  /* Portaled to document.body (the fullscreen element while fullscreen):
+     fixed position (set inline from the trigger rect) keeps it clear of the
+     tile's overflow clipping. */
   position: fixed;
   z-index: 1000;
   max-width: min(260px, calc(100vw - 16px));
@@ -1090,7 +1187,7 @@ const TopMeta = styled.div `
   color: rgba(255, 255, 255, 0.78);
   text-shadow: 0 1px 2px rgba(0, 0, 0, 0.9);
 `;
-/* The quality picker: portaled to document.body like CameraMenu, hung from
+/* The quality picker: portaled like CameraMenu, hung from
    its action-bar trigger (fixed position set inline from the trigger rect)
    so tile clipping cannot cut it off and it survives the hover-revealed
    chrome fading while the pointer is over the menu. */
@@ -1307,6 +1404,30 @@ const Stage = styled(Panel) `
         opacity: 1;
       }
     `}
+
+  /* Fullscreen has no hover on touch and may have no pointer at all, so the
+     exit button stays visible in its usual slot while the rest of the bar
+     keeps its hover/focus/tap reveal. */
+  ${(p) => p.$fullscreen &&
+    !p.$pinned &&
+    css `
+      ${ActionBarRow} {
+        opacity: 1;
+        pointer-events: auto;
+      }
+      ${ActionBarRow} > * {
+        transition: opacity 0.15s;
+      }
+      &:not(:hover):not(:focus-within) ${ActionBarRow} > :not([data-kc-fullscreen-exit]) {
+        opacity: 0;
+        pointer-events: none;
+      }
+      @media (prefers-reduced-motion: reduce) {
+        ${ActionBarRow} > * {
+          transition: none;
+        }
+      }
+    `}
 `;
 const Empty = styled.div `
   color: #888;

package/dist/CommandBrackets.d.ts

@@ -1,4 +1,4 @@
-import { type EffectiveCommandTrack, type FrameAnchor, type FrameUtSource } from "@ksp-gonogo/kerbcast";
+import { type DisplayedFrameUt, 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: {
@@ -150,8 +150,10 @@ export declare function CommandBrackets({ state, displayUt, utSource, video, fal
  * `flightId` that `video` presents. Re-renders at the frame rate, which is
  * why it is its own component.
  */
-export declare function LiveCommandBrackets({ flightId, ...props }: CommandBracketsProps & {
+export declare function LiveCommandBrackets({ flightId, frame: given, ...props }: CommandBracketsProps & {
     flightId: number | null;
+    /** The frame a host's own delayed playout shows; while set, the video's own frames are not watched. */
+    frame?: DisplayedFrameUt | null;
 }): import("react").JSX.Element;
 /** Reason a command feed is blanked, centred on black over the feed. */
 export declare function CommandBlank({ reason }: {

package/dist/CommandBrackets.js

@@ -166,8 +166,9 @@ export function CommandBrackets({ state, displayUt, utSource, video, fallbackSiz
  * `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);
+export function LiveCommandBrackets({ flightId, frame: given, ...props }) {
+    const watched = useDisplayedFrame(!given, flightId, props.video);
+    const frame = given ?? watched;
     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

package/dist/FeedActionBar.d.ts

@@ -68,6 +68,7 @@ export interface FeedAction {
 }
 interface Partitionable {
     stateful?: boolean;
+    inline?: boolean;
     order?: number;
     pinnedTrailing?: boolean;
 }
@@ -97,6 +98,12 @@ export interface FeedActionBarEntry {
     id: string;
     label: string;
     stateful?: boolean;
+    /**
+     * Keeps a non-stateful entry out of the ⋮ menu without changing the split:
+     * it still counts as non-stateful toward the overflow threshold, so the
+     * rest of the bar lays out exactly as it would without the flag.
+     */
+    inline?: boolean;
     order?: number;
     pinnedTrailing?: boolean;
     render: () => React.ReactNode;

package/dist/FeedActionBar.js

@@ -29,7 +29,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Fragment, useId } from "react";
 import { createPortal } from "react-dom";
 import styled from "styled-components";
-import { usePortalMenu } from "./menuPositioning";
+import { menuPortalRoot, usePortalMenu } from "./menuPositioning";
 // ---------------------------------------------------------------------------
 // Partition logic (pure, unit-tested independently of any rendering)
 // ---------------------------------------------------------------------------
@@ -56,8 +56,8 @@ export function partitionActionBarEntries(entries) {
         return { primary: overflowable, overflow: [], pinnedTrailing };
     }
     return {
-        primary: overflowable.filter((e) => e.stateful),
-        overflow: nonStateful,
+        primary: overflowable.filter((e) => e.stateful || e.inline),
+        overflow: nonStateful.filter((e) => !e.inline),
         pinnedTrailing,
     };
 }
@@ -108,7 +108,7 @@ export function FeedActionBar({ leading, entries, className }) {
                     // the entry's own button click handler, so this closes the
                     // menu once the action has actually fired rather than
                     // pre-empting it.
-                    _jsxs(OverflowMenuItem, { onClick: closeOverflowMenu, children: [e.render(), _jsx(OverflowMenuItemLabel, { "aria-hidden": "true", children: e.label })] }, e.id))) }), document.body), pinnedTrailing.map((e) => (_jsx(Fragment, { children: e.render() }, e.id)))] }));
+                    _jsxs(OverflowMenuItem, { onClick: closeOverflowMenu, children: [e.render(), _jsx(OverflowMenuItemLabel, { "aria-hidden": "true", children: e.label })] }, e.id))) }), menuPortalRoot()), pinnedTrailing.map((e) => (_jsx(Fragment, { children: e.render() }, e.id)))] }));
 }
 // ---------------------------------------------------------------------------
 // Icons

package/dist/context.d.ts

@@ -9,8 +9,27 @@ export interface KerbcastSubscriptions {
     acquire(flightId: number): void;
     release(flightId: number): void;
 }
-/** Build the default refcounted subscriptions implementation for a client. */
-export declare function createClientSubscriptions(client: KerbcastClient): KerbcastSubscriptions;
+/**
+ * How long a camera's slot is kept after its last holder releases it, in
+ * milliseconds. A feed that remounts inside this window (a layout change, a
+ * scene switch re-rendering the tree) takes the slot back with its stream
+ * still flowing, instead of freeing it and waiting for a fresh keyframe.
+ */
+export declare const KERBCAST_RELEASE_GRACE_MS = 2000;
+export interface ClientSubscriptionsOptions {
+    /**
+     * Delay before a released camera is unsubscribed. Defaults to
+     * {@link KERBCAST_RELEASE_GRACE_MS}; 0 unsubscribes at once.
+     */
+    releaseGraceMs?: number;
+}
+/**
+ * Build the default refcounted subscriptions implementation for a client.
+ * When the last holder of a camera releases it the unsubscribe waits
+ * `releaseGraceMs`, and an acquire inside that window keeps the slot with no
+ * message sent either way.
+ */
+export declare function createClientSubscriptions(client: KerbcastClient, options?: ClientSubscriptionsOptions): KerbcastSubscriptions;
 /**
  * Collects each mounted feed's self-measured display size and drives the
  * client's per-consumer `reportDisplaySize`. Multiple feeds can show the SAME
@@ -36,13 +55,18 @@ export interface KerbcastProviderProps {
     subscriptions?: KerbcastSubscriptions;
     /** Override the display-size registry. Defaults to a per-flightId MAX impl. */
     displaySizes?: KerbcastDisplaySizes;
+    /**
+     * Release grace for the default subscriptions, in milliseconds. Defaults to
+     * {@link KERBCAST_RELEASE_GRACE_MS}. Ignored when `subscriptions` is given.
+     */
+    releaseGraceMs?: number;
     children: ReactNode;
 }
 /**
  * Provide a `KerbcastClient` (and optional subscriptions override) to the
  * component subtree. Hooks and `CameraFeed` read both from this context.
  */
-export declare function KerbcastProvider({ client, subscriptions: subscriptionsProp, displaySizes: displaySizesProp, children, }: KerbcastProviderProps): React.JSX.Element;
+export declare function KerbcastProvider({ client, subscriptions: subscriptionsProp, displaySizes: displaySizesProp, releaseGraceMs, children, }: KerbcastProviderProps): React.JSX.Element;
 /**
  * Return the `KerbcastClient` from the nearest `KerbcastProvider`.
  * Throws if called outside a provider.