@ksp-gonogo/kerbcast-react 1.6.2 → 1.7.0

package/CHANGELOG.md

@@ -1,5 +1,46 @@
 # Changelog
 
+## 1.7.0 - 2026-07-24
+
+Crew face cameras, auto-resolution, and camera targeting.
+
+### Added
+
+- `KerbalFaceFeed`: a single-kerbal face-camera primitive. Renders one crew
+  face in a square frame, keyed by `flightId`, and never remounts its `<video>`
+  on re-layout. Composable via `children` (name label, badge, custom overlays)
+  and an `actions` bar.
+- Low-level auto-resolution primitives, for CUSTOM feed surfaces only (not
+  needed for normal use, since the feed components self-measure):
+  `useReportDisplaySize`, `createClientDisplaySizes`, `useKerbcastDisplaySizes`,
+  the `KerbcastDisplaySizes` type, and a `displaySizes` override on
+  `KerbcastProvider`.
+- `showActions?: boolean` (default true) on `CameraFeed` and `KerbalFaceFeed` to
+  suppress the hover action bar without affecting resolution reporting.
+- `reportSize?: boolean` (default true) on `KerbalFaceFeed` to opt a
+  fixed-resolution face out of auto-resolution.
+- `enableTracking?: boolean` (default false) on `CameraFeed`: a tri-state
+  auto-track control (off / active-vessel / target) on pan+zoom cameras,
+  highlighted from the server-published `CameraState.trackMode`.
+- `cameraFilter?: (camera) => boolean` on `CameraFeed` to narrow the selectable
+  set (picker menu, stepper, auto-latch). Omit to consider every camera.
+- `--kerbcast-action-active` theme token: the fill for every active action-row
+  toggle (tracking, quality, PiP, fullscreen, custom). Defaults to
+  `var(--kerbcast-accent, #00ff88)`, so one knob recolours them all.
+
+### Changed
+
+- `KerbalFaceFeed` `size` is now LAYOUT-ONLY. It sets the element's size but no
+  longer requests a stream resolution: the primitive always self-measures its
+  rendered box and reports that (auto-resolution), so resolution follows how
+  large the feed is actually shown.
+- `CameraFeed` with `renderSize="auto"` (the default) now reports its measured
+  display size for auto-resolution instead of writing a 16:9 operator render
+  size. `renderSize="none"` opts out.
+- `CameraFeed` auto-disables its manual pan/zoom controls while the camera's
+  published `trackMode` is not `none` (they no-op against a live track and the
+  rate/drag path otherwise jitters).
+
 ## 0.12.0 - 2026-06-07
 
 Initial release. Versioned in lockstep with `@jonpepler/kerbcast` and the

package/README.md

@@ -73,8 +73,27 @@ An imperative `CameraFeedHandle` (via `ref`) exposes `stepCamera`,
 `setPanAxis`, `setZoomRate`, `nudgePan`, and `nudgeZoom` for wiring feeds
 to a gamepad or keyboard.
 
+`enableTracking` shows a tri-state auto-track control (off / active-vessel /
+target) on pan+zoom cameras, and `CameraFeed` disables its manual pan/zoom
+while a camera is tracking. `cameraFilter` narrows the selectable cameras
+(picker, stepper, auto-latch). `showActions={false}` hides the whole action
+bar without affecting resolution reporting.
+
+## `KerbalFaceFeed`
+
+A single-kerbal face-camera primitive: one crew face in a square frame, keyed
+by `flightId`, never remounting its `<video>` on re-layout. Compose a name
+label, badge, or overlay via `children`. `size` is LAYOUT-ONLY: the feed always
+self-measures its rendered box and reports that for auto-resolution, so stream
+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.
+
 - `useKerbcastCameras(): CameraState[]`. The live camera registry,
   re-rendering as cameras appear, change, or are destroyed.
 - `useKerbcastStream(flightId): MediaStream | null`. The video stream

package/dist/CameraFeed.d.ts

@@ -1,4 +1,4 @@
-import type { KerbcastClient } from "@ksp-gonogo/kerbcast";
+import type { CameraState, KerbcastClient } from "@ksp-gonogo/kerbcast";
 /**
  * A consumer-supplied action rendered into the feed's top-right action bar.
  * Lets a host page (e.g. the sidecar's spotlight toggle) inject controls
@@ -43,6 +43,13 @@ export interface CameraFeedProps {
      * buttons). Never called on auto-latch.
      */
     onSelectCamera?: (flightId: number) => void;
+    /**
+     * Restrict the cameras this feed can select / step through / auto-latch onto
+     * (the picker menu + stepper + fallback). Omit to consider every camera (the
+     * default). A host uses it to scope the selectable set — e.g. a part-grid tile
+     * offering only part cameras so crew cams stay in the crew bar.
+     */
+    cameraFilter?: (camera: CameraState) => boolean;
     /**
      * Called whenever the camera this feed actually displays changes — including
      * auto-latch and fallback picks, not just explicit selection. The argument
@@ -76,8 +83,12 @@ export interface CameraFeedProps {
      */
     showStandbyIcon?: boolean;
     /**
-     * "auto" (default): ResizeObserver drives `setRenderSize` at a 16:9 crop,
-     * debounced 500 ms. "none": no render-size feedback.
+     * "auto" (default): the feed self-measures its rendered pixel box and reports
+     * it to the sidecar via the per-consumer `reportDisplaySize` (auto-resolution;
+     * the sidecar maxes across consumers). "none": no reporting, for a
+     * fixed-resolution feed. This drives the AUTO signal, not the operator
+     * `setRenderSize` (which, with the quality presets, is the manual cap:
+     * effective = min(auto, cap)).
      */
     renderSize?: "auto" | "none";
     /** Message shown when no cameras are available. */
@@ -104,6 +115,16 @@ export interface CameraFeedProps {
      * false.
      */
     enableQualityControl?: boolean;
+    /**
+     * Show a built-in auto-track (crosshair) control, only on pan+zoom cameras.
+     * A tri-state toggle group (off / track active vessel / track target): the
+     * camera aims itself at the chosen moving vessel (and auto-zooms) with no kOS.
+     * State is SERVER-authoritative: the highlight reflects `CameraState.trackMode`
+     * published by the sidecar, never the local click, so two browsers agree.
+     * While tracking, the manual pan/zoom controls are disabled (the aim loop owns
+     * the gimbal + FoV). Default false.
+     */
+    enableTracking?: boolean;
     /**
      * Consumer-injected action buttons, rendered left of the built-in
      * fullscreen/PiP controls in the top-right action bar.
@@ -115,6 +136,13 @@ export interface CameraFeedProps {
      * button so it sits in the corner.
      */
     trailingActions?: FeedAction[];
+    /**
+     * Render the feed's action UI (the top-right action bar: camera stepper,
+     * custom actions, quality / fullscreen / PiP). Default true. Set false to
+     * suppress the whole bar (e.g. a small tile where hover controls add
+     * nothing). Does not affect display-size reporting.
+     */
+    showActions?: boolean;
     /**
      * Override how the displayed video stream is sourced for the resolved
      * flightId. Omit (the default) to use the built-in `useKerbcastStream` —

package/dist/CameraFeed.js

@@ -1,5 +1,5 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
-import { PanZoomController, QualityPreset } from "@ksp-gonogo/kerbcast";
+import { PanZoomController, QualityPreset, TrackMode } from "@ksp-gonogo/kerbcast";
 import { forwardRef, useCallback, useEffect, useId, useImperativeHandle, useMemo, useRef, useState, } from "react";
 import { createPortal } from "react-dom";
 import styled, { css } from "styled-components";
@@ -8,6 +8,7 @@ import { KerbcastProvider, useKerbcastClient } from "./context";
 import { useKerbcastCameras } from "./hooks/useKerbcastCameras";
 import { useKerbcastInFlight } from "./hooks/useKerbcastInFlight";
 import { useKerbcastStream } from "./hooks/useKerbcastStream";
+import { useReportDisplaySize } from "./hooks/useReportDisplaySize";
 import { StandbyIcon } from "./StandbyIcon";
 import { isCameraDestroyed } from "./lifecycle";
 // ---------------------------------------------------------------------------
@@ -109,10 +110,6 @@ function usePortalMenu({ maxWidth, maxHeight, align }) {
     }, []);
     return { open, toggle, close, position, menuRef, triggerRef };
 }
-/** Round n to the nearest even integer, minimum 2 (H.264 chroma requirement). */
-function toEvenPx(n) {
-    return Math.max(2, Math.round(n / 2) * 2);
-}
 /*
  * Viewer quality presets, in menu order. Scales mirror the sidecar's
  * QualityPreset mapping (fractions of the camera's operator render size);
@@ -149,9 +146,14 @@ function exitFullscreen() {
 // ---------------------------------------------------------------------------
 // Inner component (reads from context)
 // ---------------------------------------------------------------------------
-const CameraFeedInner = forwardRef(function CameraFeedInner({ flightId: requestedFlightId, onSelectCamera, onDisplayedCameraChange, showDebugInfo = false, showStatic, inFlight: inFlightProp, showStandbyIcon = true, renderSize = "auto", emptyMessage = "No camera feeds - start a vessel with Hullcam parts installed", enableFullscreen = false, enablePictureInPicture = false, enableQualityControl = false, actions, trailingActions, useStream, }, ref) {
+const CameraFeedInner = forwardRef(function CameraFeedInner({ flightId: requestedFlightId, onSelectCamera, cameraFilter, onDisplayedCameraChange, showDebugInfo = false, showStatic, inFlight: inFlightProp, showStandbyIcon = true, renderSize = "auto", emptyMessage = "No camera feeds - start a vessel with Hullcam parts installed", enableFullscreen = false, enablePictureInPicture = false, enableQualityControl = false, enableTracking = false, actions, trailingActions, showActions = true, useStream, }, ref) {
     const client = useKerbcastClient();
-    const cameras = useKerbcastCameras();
+    // The selectable set: every live camera, optionally narrowed by the host's
+    // cameraFilter (e.g. a part-grid tile offering only part cams). Drives the
+    // picker menu, the stepper, and the auto-latch fallback so none can land on
+    // a filtered-out camera.
+    const allCameras = useKerbcastCameras();
+    const cameras = useMemo(() => (cameraFilter ? allCameras.filter(cameraFilter) : allCameras), [allCameras, cameraFilter]);
     const inFlightFromClient = useKerbcastInFlight();
     const inFlight = inFlightProp ?? inFlightFromClient;
     const outOfFlight = inFlight === false;
@@ -316,6 +318,13 @@ const CameraFeedInner = forwardRef(function CameraFeedInner({ flightId: requeste
     const isDestroyed = camera ? isCameraDestroyed(camera) : false;
     const showPan = camera?.supportsPan && !isDestroyed;
     const showZoom = camera?.supportsZoom && !isDestroyed;
+    // Auto-track state is server-authoritative: driven purely by the published
+    // trackMode (absent -> none), never local click. While tracking, the aim
+    // loop owns the gimbal + FoV, so the manual pan/zoom controls are disabled
+    // (they jitter against the track and are no-ops in practice).
+    const trackMode = camera?.trackMode ?? TrackMode.None;
+    const tracking = trackMode !== TrackMode.None;
+    const manualDisabled = tracking;
     const supportsPitch = !!camera && camera.panPitchMax - camera.panPitchMin > 0;
     // -------------------------------------------------------------------------
     // Camera selection callbacks (Next/Prev, picker)
@@ -441,36 +450,12 @@ const CameraFeedInner = forwardRef(function CameraFeedInner({ flightId: requeste
         },
     }), [stepCamera, showZoom, showPan, supportsPitch]);
     // -------------------------------------------------------------------------
-    // Render-size feedback (ResizeObserver, 500 ms debounce, 16:9 crop)
+    // 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.
     // -------------------------------------------------------------------------
-    const resizeTimerRef = useRef(null);
-    useEffect(() => {
-        if (renderSize !== "auto" || flightId === null)
-            return;
-        const el = wrapRef.current;
-        if (!el)
-            return;
-        const cam = client.camera(flightId);
-        const observer = new ResizeObserver((entries) => {
-            const entry = entries[0];
-            if (!entry)
-                return;
-            const { width } = entry.contentRect;
-            if (resizeTimerRef.current !== null)
-                clearTimeout(resizeTimerRef.current);
-            resizeTimerRef.current = setTimeout(() => {
-                const w = toEvenPx(width);
-                const h = toEvenPx((width * 9) / 16);
-                void cam.setRenderSize(w, h);
-            }, 500);
-        });
-        observer.observe(el);
-        return () => {
-            observer.disconnect();
-            if (resizeTimerRef.current !== null)
-                clearTimeout(resizeTimerRef.current);
-        };
-    }, [client, flightId, renderSize]);
+    useReportDisplaySize(flightId, wrapRef, { enabled: renderSize === "auto" });
     // -------------------------------------------------------------------------
     // UI state
     // -------------------------------------------------------------------------
@@ -512,6 +497,33 @@ const CameraFeedInner = forwardRef(function CameraFeedInner({ flightId: requeste
         void client.camera(flightId).setQuality(preset);
         closeQualityMenu();
     }, [client, flightId, closeQualityMenu]);
+    // -------------------------------------------------------------------------
+    // Auto-track control (opt-in, pan+zoom cameras only). A crosshair button +
+    // menu with the two modes. Sends the intent; the highlight follows the
+    // server-published trackMode (above), so two browsers agree.
+    // -------------------------------------------------------------------------
+    const trackingAvailable = enableTracking &&
+        flightId !== null &&
+        camera !== null &&
+        camera.supportsPan === true &&
+        camera.supportsZoom === true &&
+        !isDestroyed;
+    const trackingMenuId = useId();
+    const trackingMenu = usePortalMenu({
+        maxWidth: QUALITY_MENU_MAX_WIDTH,
+        maxHeight: QUALITY_MENU_MAX_HEIGHT,
+        align: "end",
+    });
+    const closeTrackingMenu = trackingMenu.close;
+    const selectTrack = useCallback((mode) => {
+        if (flightId === null)
+            return;
+        // Tri-state: clicking the already-active mode hands aiming back (none).
+        // Decision reads the server-confirmed trackMode, not a local toggle.
+        const next = trackMode === mode ? TrackMode.None : mode;
+        void client.setTrackTarget(flightId, next);
+        closeTrackingMenu();
+    }, [client, flightId, trackMode, closeTrackingMenu]);
     const topOverlay = (_jsxs(TopOverlay, { children: [_jsx(TitleRow, { children: _jsx(TopTitle, { children: hasCameras ? (_jsxs(TitleButton, { ref: cameraMenu.triggerRef, type: "button", "aria-haspopup": "menu", "aria-expanded": cameraMenu.open, "aria-controls": menuId, onClick: cameraMenu.toggle, children: [_jsx(TitleButton__Text, { children: title }), _jsx(ChevronDownIcon, { "aria-hidden": "true" })] })) : (title) }) }), cameraMenu.open &&
                 hasCameras &&
                 cameraMenu.position &&
@@ -521,22 +533,32 @@ const CameraFeedInner = forwardRef(function CameraFeedInner({ flightId: requeste
                         }, children: [cameraLabel(c), " (", c.vesselName, ")", isCameraDestroyed(c) ? " - signal lost" : ""] }, c.flightId))) }), document.body), showDebugInfo &&
                 (camera ? (_jsxs(TopMeta, { children: [camera.vesselName, " \u00B7 ", camera.renderWidth, "\u00D7", camera.renderHeight, bitrateLabel, adaptiveLabel] })) : (_jsx(TopMeta, { children: "no cameras on this vessel" })))] }));
     const renderAction = (a) => (_jsx(OverlayIconButton, { type: "button", "aria-label": a.label, "aria-pressed": a.active ?? undefined, title: a.label, "$active": a.active ?? false, onClick: a.onClick, children: a.icon }, a.id));
-    const builtInActions = flightId !== null && (pipAvailable || fullscreenAvailable || qualityAvailable);
-    const hasActionBar = hasCameras ||
-        (actions && actions.length > 0) ||
-        (trailingActions && trailingActions.length > 0) ||
-        builtInActions;
+    const builtInActions = flightId !== null &&
+        (pipAvailable || fullscreenAvailable || qualityAvailable || trackingAvailable);
+    const hasActionBar = showActions &&
+        (hasCameras ||
+            (actions && actions.length > 0) ||
+            (trailingActions && trailingActions.length > 0) ||
+            builtInActions);
     const actionBar = hasActionBar ? (_jsxs(ActionBar, { children: [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" })] })), actions?.map(renderAction), qualityAvailable && (_jsxs(OverlayIconButton, { ref: qualityMenu.triggerRef, type: "button", "aria-label": "Quality", "aria-haspopup": "menu", "aria-expanded": qualityMenu.open, "aria-controls": qualityMenuId, title: qualityThrottled
                     ? "Quality (throttled by adaptive performance)"
-                    : "Quality", "$active": qualityMenu.open, onClick: qualityMenu.toggle, children: [_jsx(QualityIcon, {}), qualityThrottled && _jsx(ThrottledDot, { "aria-hidden": "true" })] })), flightId !== null && pipAvailable && (_jsx(OverlayIconButton, { type: "button", "aria-label": isPip ? "Exit picture in picture" : "Picture in picture", "aria-pressed": isPip, title: isPip ? "Exit picture in picture" : "Picture in picture", "$active": isPip, onClick: togglePip, children: _jsx(PictureInPictureIcon, {}) })), flightId !== null && fullscreenAvailable && (_jsx(OverlayIconButton, { type: "button", "aria-label": isFullscreen ? "Exit fullscreen" : "Enter fullscreen", "aria-pressed": isFullscreen, title: isFullscreen ? "Exit fullscreen" : "Enter fullscreen", "$active": isFullscreen, onClick: toggleFullscreen, children: isFullscreen ? _jsx(FullscreenExitIcon, {}) : _jsx(FullscreenEnterIcon, {}) })), trailingActions?.map(renderAction)] })) : null;
+                    : "Quality", "$active": qualityMenu.open, onClick: qualityMenu.toggle, children: [_jsx(QualityIcon, {}), qualityThrottled && _jsx(ThrottledDot, { "aria-hidden": "true" })] })), trackingAvailable && (_jsx(OverlayIconButton, { ref: trackingMenu.triggerRef, type: "button", "aria-label": "Auto-track", "aria-haspopup": "menu", "aria-expanded": trackingMenu.open, "aria-controls": trackingMenuId, "aria-pressed": tracking, title: tracking
+                    ? trackMode === TrackMode.Target
+                        ? "Auto-tracking target"
+                        : "Auto-tracking active vessel"
+                    : "Auto-track a vessel", "$active": tracking || trackingMenu.open, onClick: trackingMenu.toggle, children: _jsx(CrosshairIcon, {}) })), flightId !== null && pipAvailable && (_jsx(OverlayIconButton, { type: "button", "aria-label": isPip ? "Exit picture in picture" : "Picture in picture", "aria-pressed": isPip, title: isPip ? "Exit picture in picture" : "Picture in picture", "$active": isPip, onClick: togglePip, children: _jsx(PictureInPictureIcon, {}) })), flightId !== null && fullscreenAvailable && (_jsx(OverlayIconButton, { type: "button", "aria-label": isFullscreen ? "Exit fullscreen" : "Enter fullscreen", "aria-pressed": isFullscreen, title: isFullscreen ? "Exit fullscreen" : "Enter fullscreen", "$active": isFullscreen, onClick: toggleFullscreen, children: isFullscreen ? _jsx(FullscreenExitIcon, {}) : _jsx(FullscreenEnterIcon, {}) })), trailingActions?.map(renderAction)] })) : 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: videoRef, 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), 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"] })] })), showZoom && (_jsxs(ZoomControlsWrap, { children: [_jsx(ZoomButton, { type: "button", "aria-label": "Zoom in", "$pos": "top", onPointerDown: () => controllerRef.current?.setZoomRate(1), onPointerUp: () => controllerRef.current?.setZoomRate(0), onPointerLeave: () => controllerRef.current?.setZoomRate(0), onPointerCancel: () => controllerRef.current?.setZoomRate(0), onClick: (e) => {
+                    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), 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"] })] })), 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, onChange: (e) => {
+                            }, 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: () => {
@@ -545,10 +567,10 @@ const CameraFeedInner = forwardRef(function CameraFeedInner({ flightId: requeste
                                 controllerRef.current?.setFovSliderDragging(false);
                             }, onPointerCancel: () => {
                                 controllerRef.current?.setFovSliderDragging(false);
-                            } }), _jsx(ZoomButton, { type: "button", "aria-label": "Zoom out", "$pos": "bottom", onPointerDown: () => controllerRef.current?.setZoomRate(-1), onPointerUp: () => controllerRef.current?.setZoomRate(0), onPointerLeave: () => controllerRef.current?.setZoomRate(0), onPointerCancel: () => controllerRef.current?.setZoomRate(0), onClick: (e) => {
+                            } }), _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", children: [_jsx(PanArrow, { type: "button", "$dir": "up", "aria-label": "Pan up", disabled: !supportsPitch, onClick: () => controllerRef.current?.nudgePan(0, 1), children: "\u25B2" }), _jsx(PanArrow, { type: "button", "$dir": "down", "aria-label": "Pan down", disabled: !supportsPitch, onClick: () => controllerRef.current?.nudgePan(0, -1), children: "\u25BC" }), _jsx(PanArrow, { type: "button", "$dir": "left", "aria-label": "Pan left", onClick: () => controllerRef.current?.nudgePan(-1, 0), children: "\u25C0" }), _jsx(PanArrow, { type: "button", "$dir": "right", "aria-label": "Pan right", onClick: () => controllerRef.current?.nudgePan(1, 0), children: "\u25B6" }), _jsx(PanBall, { "aria-hidden": "true", title: "Drag to pan", onPointerDown: handleBallDown, onPointerMove: handleBallMove, onPointerUp: handleBallUp, onPointerCancel: handleBallUp, style: {
+                            }, 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)`,
                             } })] }))] })) }));
 });
@@ -593,6 +615,10 @@ function FullscreenExitIcon() {
 function QualityIcon() {
     return (_jsxs("svg", { ...iconProps, children: [_jsx("path", { d: "M2 4.5h12M2 8h12M2 11.5h12" }), _jsx("circle", { cx: "10.5", cy: "4.5", r: "1.6", fill: "currentColor", stroke: "none" }), _jsx("circle", { cx: "5.5", cy: "8", r: "1.6", fill: "currentColor", stroke: "none" }), _jsx("circle", { cx: "8.5", cy: "11.5", r: "1.6", fill: "currentColor", stroke: "none" })] }));
 }
+/* Auto-track: a crosshair / reticle. */
+function CrosshairIcon() {
+    return (_jsxs("svg", { ...iconProps, children: [_jsx("circle", { cx: "8", cy: "8", r: "4.5" }), _jsx("path", { d: "M8 1v2.5M8 12.5V15M1 8h2.5M12.5 8H15" })] }));
+}
 /* Stale badge: fading signal bars (tallest dimmed). */
 function StaleIcon() {
     return (_jsxs("svg", { viewBox: "0 0 16 16", width: 10, height: 10, fill: "currentColor", stroke: "none", "aria-hidden": "true", children: [_jsx("rect", { x: "2", y: "9", width: "2.5", height: "5" }), _jsx("rect", { x: "6.5", y: "6", width: "2.5", height: "8" }), _jsx("rect", { x: "11", y: "3", width: "2.5", height: "11", opacity: "0.35" })] }));
@@ -613,6 +639,9 @@ const PanControl = styled.div `
   transition: opacity 0.15s;
   touch-action: none;
 
+  /* Greyed + inert while auto-tracking owns the gimbal. */
+  ${(p) => p.$disabled && "pointer-events: none; filter: grayscale(1) opacity(0.4);"}
+
   @media (prefers-reduced-motion: reduce) {
     transition: none;
   }
@@ -692,6 +721,9 @@ const ZoomControlsWrap = styled.div `
   opacity: 0;
   transition: opacity 0.15s;
 
+  /* Greyed + inert while auto-tracking owns the FoV. */
+  ${(p) => p.$disabled && "pointer-events: none; filter: grayscale(1) opacity(0.4);"}
+
   @media (prefers-reduced-motion: reduce) {
     transition: none;
   }
@@ -990,12 +1022,17 @@ const OverlayIconButton = styled.button `
   align-items: center;
   justify-content: center;
   padding: 0;
+  /* Active-toggle fill (quality / tracking / PiP / fullscreen / custom actions
+     all share this button). Its own token so a consumer can recolour just the
+     action-row highlight without touching the general accent; defaults to
+     --kerbcast-accent, so the sidecar web page (which maps its accent onto that)
+     is unchanged. */
   background: ${(p) => p.$active
-    ? "var(--kerbcast-accent, #00ff88)"
+    ? "var(--kerbcast-action-active, var(--kerbcast-accent, #00ff88))"
     : "rgba(0, 0, 0, 0.5)"};
   border: 1px solid
     ${(p) => p.$active
-    ? "var(--kerbcast-accent, #00ff88)"
+    ? "var(--kerbcast-action-active, var(--kerbcast-accent, #00ff88))"
     : "rgba(255, 255, 255, 0.3)"};
   border-radius: 3px;
   color: ${(p) => (p.$active ? "#000" : "#fff")};
@@ -1005,7 +1042,7 @@ const OverlayIconButton = styled.button `
   @media (hover: hover) {
     &:hover {
       background: ${(p) => p.$active
-    ? "var(--kerbcast-accent, #00ff88)"
+    ? "var(--kerbcast-action-active, var(--kerbcast-accent, #00ff88))"
     : "rgba(0, 0, 0, 0.7)"};
       border-color: rgba(255, 255, 255, 0.6);
     }

package/dist/KerbalFaceFeed.d.ts

@@ -0,0 +1,82 @@
+/**
+ * KerbalFaceFeed — the shared single-kerbal-face primitive.
+ *
+ * Renders ONE kerbal's face-camera stream in a fixed SQUARE frame. It is the
+ * reusable building block a crew bar (kerbcast web) or a mission-control
+ * surface (gonogo) composes: identity-keyed by `flightId`, it binds the live
+ * `MediaStream` to a persistent `<video>` and NEVER remounts that element on
+ * re-layout (the "never remount a live feed" rule — the same srcObject-via-ref
+ * technique `CameraFeed` uses).
+ *
+ * Deliberately minimal chrome: just the square live face plus a standby glyph
+ * when there is no live signal. Everything else — name label, IVA/EVA badge,
+ * click behaviour, a "SIGNAL LOST" treatment — is layered OVER it by the
+ * wrapper via `children`, driven by the `onFeedStateChange` signal. A thin
+ * `actions` bar (the shared `FeedAction` shape) is rendered top-right when a
+ * wrapper supplies one, so declarative controls compose the same way they do
+ * on `CameraFeed`.
+ */
+import { FeedAction, CameraStreamHook } from "./CameraFeed";
+/**
+ * Coarse presentation state a wrapper reacts to for its own fallback/badge:
+ * - `live`: a stream is bound and playing.
+ * - `no-signal`: no stream yet (connecting, out of flight, or not visible).
+ * - `destroyed`: the camera's part/kerbal is gone (the wrapper renders SIGNAL
+ *   LOST; the last frame stays on-screen because the `<video>` is not cleared).
+ */
+export type KerbalFeedState = "live" | "no-signal" | "destroyed";
+export interface KerbalFaceFeedProps {
+    /** Wire-id (`CameraState.flightId`) of the kerbal face camera to display. */
+    flightId: number;
+    /**
+     * Explicit square side in px, for LAYOUT only. When omitted the feed fills
+     * its parent's width at a 1:1 aspect ratio. This does NOT drive resolution:
+     * the primitive always self-measures its rendered box and reports that to the
+     * sidecar (auto-resolution). Pass it to fix the element's size, not to
+     * request a stream resolution.
+     */
+    size?: number;
+    /**
+     * Report the self-measured display size to the sidecar to drive
+     * auto-resolution. Default true. Set false for a fixed-resolution feed that
+     * should not participate in auto-res. Independent of {@link showActions}
+     * (a resolution concern, not a UI one).
+     */
+    reportSize?: boolean;
+    /**
+     * Consumer action buttons, rendered as a minimal top-right bar (the shared
+     * {@link FeedAction} shape). Omit for no bar — the common case, since a crew
+     * bar usually composes its controls in `children` instead.
+     */
+    actions?: FeedAction[];
+    /**
+     * Render the feed's action UI (the top-right action bar). Default true. Set
+     * false to suppress the bar entirely (e.g. a tiny avatar where hover controls
+     * add nothing). Does not affect display-size reporting.
+     */
+    showActions?: boolean;
+    /**
+     * Overlay content layered OVER the square face: name label, IVA/EVA badge,
+     * click target, a custom destroyed treatment. Absolutely positioned to fill
+     * the frame; the primitive keeps its own chrome out of the way.
+     */
+    children?: React.ReactNode;
+    /**
+     * Fired whenever the derived feed state changes, so the wrapper can swap its
+     * fallback/badge without polling. Fires once on mount with the initial state.
+     */
+    onFeedStateChange?: (state: KerbalFeedState) => void;
+    /**
+     * Draw the built-in standby glyph while not `live`. Default true. Set false
+     * when the wrapper renders its own out-of-signal overlay (so it isn't drawn
+     * twice); the frame then just stays dark / holds the last frame.
+     */
+    showStandby?: boolean;
+    /**
+     * Override how the stream is sourced (delayed playout, alternate transport).
+     * Must be a stable reference passed consistently across renders — it is
+     * called as a hook. Omit to use the built-in {@link useKerbcastStream}.
+     */
+    useStream?: CameraStreamHook;
+}
+export declare function KerbalFaceFeed({ flightId, size, reportSize, actions, showActions, children, onFeedStateChange, showStandby, useStream, }: KerbalFaceFeedProps): import("react").JSX.Element;

package/dist/KerbalFaceFeed.js

@@ -0,0 +1,118 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * KerbalFaceFeed — the shared single-kerbal-face primitive.
+ *
+ * Renders ONE kerbal's face-camera stream in a fixed SQUARE frame. It is the
+ * reusable building block a crew bar (kerbcast web) or a mission-control
+ * surface (gonogo) composes: identity-keyed by `flightId`, it binds the live
+ * `MediaStream` to a persistent `<video>` and NEVER remounts that element on
+ * re-layout (the "never remount a live feed" rule — the same srcObject-via-ref
+ * technique `CameraFeed` uses).
+ *
+ * Deliberately minimal chrome: just the square live face plus a standby glyph
+ * when there is no live signal. Everything else — name label, IVA/EVA badge,
+ * click behaviour, a "SIGNAL LOST" treatment — is layered OVER it by the
+ * wrapper via `children`, driven by the `onFeedStateChange` signal. A thin
+ * `actions` bar (the shared `FeedAction` shape) is rendered top-right when a
+ * wrapper supplies one, so declarative controls compose the same way they do
+ * on `CameraFeed`.
+ */
+import { useEffect, useRef } from "react";
+import styled from "styled-components";
+import { useKerbcastStream } from "./hooks/useKerbcastStream";
+import { useKerbcastCameras } from "./hooks/useKerbcastCameras";
+import { useReportDisplaySize } from "./hooks/useReportDisplaySize";
+import { isCameraDestroyed } from "./lifecycle";
+import { StandbyIcon } from "./StandbyIcon";
+const Frame = styled.div `
+  position: relative;
+  ${(p) => (p.$size != null ? `width: ${p.$size}px; height: ${p.$size}px;` : "width: 100%;")}
+  aspect-ratio: 1 / 1;
+  overflow: hidden;
+  background: #000;
+  border-radius: 4px;
+`;
+const Face = styled.video `
+  width: 100%;
+  height: 100%;
+  /* Cover the square: the portrait fills the frame, cropping the excess,
+     rather than letterboxing — a face tile reads best edge-to-edge. */
+  object-fit: cover;
+  display: block;
+`;
+const StandbyLayer = styled.div `
+  position: absolute;
+  inset: 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  color: rgba(255, 255, 255, 0.35);
+  pointer-events: none;
+`;
+const DestroyedScrim = styled.div `
+  position: absolute;
+  inset: 0;
+  background: rgba(0, 0, 0, 0.45);
+  pointer-events: none;
+`;
+const OverlayLayer = styled.div `
+  position: absolute;
+  inset: 0;
+`;
+const ActionBar = styled.div `
+  position: absolute;
+  top: 4px;
+  right: 4px;
+  display: flex;
+  gap: 4px;
+  z-index: 2;
+`;
+const ActionButton = styled.button `
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 22px;
+  height: 22px;
+  padding: 0;
+  border: none;
+  border-radius: 3px;
+  cursor: pointer;
+  color: #fff;
+  background: ${(p) => (p.$active ? "rgba(255,255,255,0.28)" : "rgba(0,0,0,0.45)")};
+`;
+export function KerbalFaceFeed({ flightId, size, reportSize = true, actions, showActions = true, children, onFeedStateChange, showStandby = true, useStream, }) {
+    // Match CameraFeed: the built-in hook (which acquires/releases the
+    // subscription slot) runs only when no override is supplied.
+    const resolveStream = useStream ?? useKerbcastStream;
+    const stream = resolveStream(flightId);
+    // The camera's lifecycle comes from the registry snapshot; destroyed cameras
+    // linger in the list so the wrapper can show SIGNAL LOST.
+    const cameras = useKerbcastCameras();
+    const destroyed = cameras.some((c) => c.flightId === flightId && isCameraDestroyed(c));
+    const state = destroyed
+        ? "destroyed"
+        : stream
+            ? "live"
+            : "no-signal";
+    // Self-measure the square frame and report it to the sidecar (auto-res).
+    // 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 });
+    // 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;
+        }
+    }, [stream]);
+    // Notify the wrapper on every state transition (and once on mount).
+    const notify = useRef(onFeedStateChange);
+    notify.current = onFeedStateChange;
+    useEffect(() => {
+        notify.current?.(state);
+    }, [state]);
+    return (_jsxs(Frame, { ref: frameRef, "$size": size, "data-testid": "kerbal-face-feed", "data-feed-state": state, children: [_jsx(Face, { ref: videoRef, autoPlay: true, playsInline: true, muted: true, controls: false }), state === "destroyed" && _jsx(DestroyedScrim, {}), showStandby && state !== "live" && (_jsx(StandbyLayer, { children: _jsx(StandbyIcon, { size: Math.round((size ?? 96) * 0.32) }) })), showActions && actions && actions.length > 0 && (_jsx(ActionBar, { children: actions.map((a) => (_jsx(ActionButton, { type: "button", "aria-label": a.label, title: a.label, "aria-pressed": a.active, "$active": a.active, onClick: a.onClick, children: a.icon }, a.id))) })), children && _jsx(OverlayLayer, { children: children })] }));
+}