@ksp-gonogo/kerbcast-react 1.12.0-rc.2 → 1.12.0-rc.4

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`.
@@ -184,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";
@@ -112,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 &&
@@ -139,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.
@@ -307,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;
@@ -777,7 +826,7 @@ const CameraFeedInner = forwardRef(function CameraFeedInner({ flightId: requeste
                                 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));
                             }) }), 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) => {

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

package/dist/context.js

@@ -1,8 +1,69 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { createContext, useContext, useMemo, useRef, } from "react";
-/** Build the default refcounted subscriptions implementation for a client. */
-export function createClientSubscriptions(client) {
+import { createContext, useContext, useMemo } from "react";
+/**
+ * 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 const KERBCAST_RELEASE_GRACE_MS = 2000;
+/**
+ * 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 function createClientSubscriptions(client, options = {}) {
+    return withGrace(createSubscriptionsCore(client), options.releaseGraceMs ?? KERBCAST_RELEASE_GRACE_MS);
+}
+function withGrace(core, graceMs) {
+    return {
+        acquire: (flightId) => core.acquire(flightId),
+        release: (flightId) => core.release(flightId, graceMs),
+    };
+}
+function createSubscriptionsCore(client) {
     const refcounts = new Map();
+    const pendingRelease = new Map();
+    const stopWatchingSlot = new Map();
+    function unsubscribeNow(flightId) {
+        stopWatchingSlot.get(flightId)?.();
+        stopWatchingSlot.delete(flightId);
+        client.unsubscribe(flightId).catch(() => { });
+    }
+    /*
+     * A slot kept for a feed that might come back is worth less than one a
+     * mounted feed is waiting for. While any held camera waits for a slot,
+     * releases skip the grace, and a camera that starts waiting ends every
+     * grace under way so the slots it frees can carry it.
+     */
+    function slotWanted() {
+        for (const flightId of refcounts.keys()) {
+            if (client.camera(flightId).waitingForSlot)
+                return true;
+        }
+        return false;
+    }
+    function watchSlot(flightId) {
+        if (stopWatchingSlot.has(flightId))
+            return;
+        stopWatchingSlot.set(flightId, client.camera(flightId).on("waiting", (waiting) => {
+            if (waiting)
+                flushPendingReleases();
+        }));
+    }
+    /*
+     * A connection that ends takes this client's slots with it, so a camera
+     * waiting out its grace has nothing left to keep. Unsubscribe it now, which
+     * also clears the client's own record that it wants the camera.
+     */
+    function flushPendingReleases() {
+        for (const [flightId, timer] of pendingRelease) {
+            clearTimeout(timer);
+            unsubscribeNow(flightId);
+        }
+        pendingRelease.clear();
+    }
     /*
      * A reconnect clears every slot binding on the client and the sidecar starts
      * the new peer empty, so re-subscribe each camera still held. Listeners fire
@@ -10,29 +71,81 @@ export function createClientSubscriptions(client) {
      * registry, so subscriptions go out first. The sidecar treats a repeat
      * subscribe for a bound camera as a re-announce, and a rejection (for
      * example a full slot pool) is swallowed like every other subscribe here.
+     * A camera only waiting out its grace is not held, so it is dropped rather
+     * than bound again on the new peer.
      */
     client.on("control-open", () => {
+        flushPendingReleases();
         for (const flightId of refcounts.keys()) {
             client.subscribe(flightId).catch(() => { });
         }
     });
+    client.on("state-change", (state) => {
+        if (state === "disconnected" || state === "failed")
+            flushPendingReleases();
+    });
+    /*
+     * A fresh subscribe made while a release is pending waits for a microtask
+     * and goes out after every release still pending is flushed. React runs
+     * every cleanup and effect of one commit in a single task, so a feed that
+     * remounts takes its camera back first and keeps the grace, while a feed
+     * switching cameras frees its old slot on the wire before asking for the
+     * new one. Otherwise a full pool would refuse the new camera, or grow by a
+     * re-offer, while the old one sat in its grace. With nothing pending the
+     * subscribe goes out at once.
+     */
+    const toSubscribe = new Set();
+    function subscribeQueued() {
+        flushPendingReleases();
+        for (const flightId of toSubscribe) {
+            client.subscribe(flightId).catch(() => { });
+        }
+        toSubscribe.clear();
+    }
     return {
         acquire(flightId) {
             const count = (refcounts.get(flightId) ?? 0) + 1;
             refcounts.set(flightId, count);
+            const pending = pendingRelease.get(flightId);
+            if (pending !== undefined) {
+                clearTimeout(pending);
+                pendingRelease.delete(flightId);
+                return;
+            }
             if (count === 1) {
-                client.subscribe(flightId).catch(() => { });
+                watchSlot(flightId);
+                if (pendingRelease.size === 0 && toSubscribe.size === 0) {
+                    client.subscribe(flightId).catch(() => { });
+                    return;
+                }
+                if (toSubscribe.size === 0)
+                    queueMicrotask(subscribeQueued);
+                toSubscribe.add(flightId);
             }
         },
-        release(flightId) {
+        release(flightId, graceMs) {
             const count = (refcounts.get(flightId) ?? 1) - 1;
-            if (count <= 0) {
-                refcounts.delete(flightId);
-                client.unsubscribe(flightId).catch(() => { });
-            }
-            else {
+            if (count > 0) {
                 refcounts.set(flightId, count);
+                return;
+            }
+            refcounts.delete(flightId);
+            if (toSubscribe.delete(flightId)) {
+                stopWatchingSlot.get(flightId)?.();
+                stopWatchingSlot.delete(flightId);
+                return;
             }
+            if (pendingRelease.has(flightId))
+                return;
+            /* A camera still waiting for a slot has no stream to keep. */
+            if (graceMs <= 0 || client.camera(flightId).waitingForSlot || slotWanted()) {
+                unsubscribeNow(flightId);
+                return;
+            }
+            pendingRelease.set(flightId, setTimeout(() => {
+                pendingRelease.delete(flightId);
+                unsubscribeNow(flightId);
+            }, graceMs));
         },
     };
 }
@@ -97,29 +210,41 @@ export function createClientDisplaySizes(client) {
     };
 }
 const KerbcastContext = createContext(null);
+const clientDefaults = new WeakMap();
+function defaultsOf(client) {
+    let defaults = clientDefaults.get(client);
+    if (!defaults) {
+        defaults = { core: null, subscriptions: new Map(), displaySizes: null };
+        clientDefaults.set(client, defaults);
+    }
+    return defaults;
+}
+function defaultSubscriptions(client, releaseGraceMs) {
+    const defaults = defaultsOf(client);
+    let subscriptions = defaults.subscriptions.get(releaseGraceMs);
+    if (!subscriptions) {
+        defaults.core ?? (defaults.core = createSubscriptionsCore(client));
+        subscriptions = withGrace(defaults.core, releaseGraceMs);
+        defaults.subscriptions.set(releaseGraceMs, subscriptions);
+    }
+    return subscriptions;
+}
+function defaultDisplaySizes(client) {
+    const defaults = defaultsOf(client);
+    defaults.displaySizes ?? (defaults.displaySizes = createClientDisplaySizes(client));
+    return defaults.displaySizes;
+}
 /**
  * Provide a `KerbcastClient` (and optional subscriptions override) to the
  * component subtree. Hooks and `CameraFeed` read both from this context.
  */
-export function KerbcastProvider({ client, subscriptions: subscriptionsProp, displaySizes: displaySizesProp, children, }) {
-    // Create default subscriptions once per client. A ref so the object is
-    // stable across renders even if the parent re-renders.
-    const defaultSubsRef = useRef(null);
-    if (defaultSubsRef.current === null) {
-        defaultSubsRef.current = createClientSubscriptions(client);
-    }
-    // Same for the display-size registry: one per client, stable across renders.
-    const defaultSizesRef = useRef(null);
-    if (defaultSizesRef.current === null) {
-        defaultSizesRef.current = createClientDisplaySizes(client);
-    }
+export function KerbcastProvider({ client, subscriptions: subscriptionsProp, displaySizes: displaySizesProp, releaseGraceMs = KERBCAST_RELEASE_GRACE_MS, children, }) {
     const value = useMemo(() => ({
         client,
-        subscriptions: subscriptionsProp ?? defaultSubsRef.current,
-        displaySizes: displaySizesProp ?? defaultSizesRef.current,
-    }), 
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-    [client, subscriptionsProp, displaySizesProp]);
+        /* Subscriptions first: their reconnect listener must run before the registry's. */
+        subscriptions: subscriptionsProp ?? defaultSubscriptions(client, releaseGraceMs),
+        displaySizes: displaySizesProp ?? defaultDisplaySizes(client),
+    }), [client, subscriptionsProp, displaySizesProp, releaseGraceMs]);
     return (_jsx(KerbcastContext.Provider, { value: value, children: children }));
 }
 // ---------------------------------------------------------------------------

package/dist/hooks/useCommandDisplayUt.d.ts

@@ -27,8 +27,9 @@ export declare function commandShownKey(c: FrameCommandState | undefined): strin
  * displayed UT reaches the next of `events`, so a state change lands on its
  * frame rather than on the next tick. The displayed frame's own command
  * state comes back as `command`, re-rendering when what it shows changes:
- * an exact frame's, an estimated one's (which lags the picture, so is never
- * early; its own UT is used too, so events and lists stay on that frame),
+ * an exact frame's, an estimated one's (which lags the picture while the
+ * element plays the stream as it arrives; its own UT is used too, so events
+ * and lists stay on that frame),
  * or with an override the host's own `overrideCommand`. `null` when
  * nothing is known.
  */

package/dist/hooks/useCommandDisplayUt.js

@@ -61,8 +61,9 @@ export function commandShownKey(c) {
  * displayed UT reaches the next of `events`, so a state change lands on its
  * frame rather than on the next tick. The displayed frame's own command
  * state comes back as `command`, re-rendering when what it shows changes:
- * an exact frame's, an estimated one's (which lags the picture, so is never
- * early; its own UT is used too, so events and lists stay on that frame),
+ * an exact frame's, an estimated one's (which lags the picture while the
+ * element plays the stream as it arrives; its own UT is used too, so events
+ * and lists stay on that frame),
  * or with an override the host's own `overrideCommand`. `null` when
  * nothing is known.
  */

package/dist/hooks/useKerbcastStream.d.ts

@@ -5,6 +5,8 @@
  *
  * While mounted with a non-null `flightId`, acquires a subscription slot via
  * the context `KerbcastSubscriptions`. Releases the slot when the component
- * unmounts or the `flightId` changes.
+ * unmounts or the `flightId` changes; the default subscriptions keep it for
+ * `KERBCAST_RELEASE_GRACE_MS`, so a remount in that time starts on the
+ * stream already flowing.
  */
 export declare function useKerbcastStream(flightId: number | null): MediaStream | null;

package/dist/hooks/useKerbcastStream.js

@@ -7,7 +7,9 @@ import { useKerbcastClient, useKerbcastSubscriptions } from "../context";
  *
  * While mounted with a non-null `flightId`, acquires a subscription slot via
  * the context `KerbcastSubscriptions`. Releases the slot when the component
- * unmounts or the `flightId` changes.
+ * unmounts or the `flightId` changes; the default subscriptions keep it for
+ * `KERBCAST_RELEASE_GRACE_MS`, so a remount in that time starts on the
+ * stream already flowing.
  */
 export function useKerbcastStream(flightId) {
     const client = useKerbcastClient();

package/dist/index.d.ts

@@ -5,8 +5,8 @@
  * is a peer to @ksp-gonogo/kerbcast (the core SDK) and requires React 18+
  * and styled-components 6+ as peer dependencies.
  */
-export { KerbcastProvider, createClientSubscriptions, createClientDisplaySizes, useKerbcastClient, useKerbcastSubscriptions, useKerbcastDisplaySizes, } from "./context";
-export type { KerbcastProviderProps, KerbcastSubscriptions, KerbcastDisplaySizes, } from "./context";
+export { KerbcastProvider, createClientSubscriptions, createClientDisplaySizes, KERBCAST_RELEASE_GRACE_MS, useKerbcastClient, useKerbcastSubscriptions, useKerbcastDisplaySizes, } from "./context";
+export type { KerbcastProviderProps, KerbcastSubscriptions, ClientSubscriptionsOptions, KerbcastDisplaySizes, } from "./context";
 export { useKerbcastCameras } from "./hooks/useKerbcastCameras";
 export { useKerbcastStream } from "./hooks/useKerbcastStream";
 export { useKerbcastClock } from "./hooks/useKerbcastClock";

package/dist/index.js

@@ -6,7 +6,7 @@
  * and styled-components 6+ as peer dependencies.
  */
 // Context and provider
-export { KerbcastProvider, createClientSubscriptions, createClientDisplaySizes, useKerbcastClient, useKerbcastSubscriptions, useKerbcastDisplaySizes, } from "./context";
+export { KerbcastProvider, createClientSubscriptions, createClientDisplaySizes, KERBCAST_RELEASE_GRACE_MS, useKerbcastClient, useKerbcastSubscriptions, useKerbcastDisplaySizes, } from "./context";
 // Hooks
 export { useKerbcastCameras } from "./hooks/useKerbcastCameras";
 export { useKerbcastStream } from "./hooks/useKerbcastStream";

package/package.json

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