@ksp-gonogo/kerbcast-react 1.6.3 → 1.8.0

package/src/CameraFeed.tsx

@@ -1,5 +1,5 @@
-import type { KerbcastClient } from "@ksp-gonogo/kerbcast";
-import { PanZoomController, QualityPreset } from "@ksp-gonogo/kerbcast";
+import type { CameraState, KerbcastClient } from "@ksp-gonogo/kerbcast";
+import { PanZoomController, QualityPreset, TrackMode } from "@ksp-gonogo/kerbcast";
 import {
   forwardRef,
   useCallback,
@@ -7,6 +7,7 @@ import {
   useId,
   useImperativeHandle,
   useMemo,
+  useReducer,
   useRef,
   useState,
 } from "react";
@@ -14,11 +15,23 @@ import { createPortal } from "react-dom";
 import styled, { css } from "styled-components";
 import { buildCameraLabeler } from "./cameraLabels";
 import { KerbcastProvider, useKerbcastClient } from "./context";
+import {
+  ActionBarRow,
+  FeedActionBar,
+  OverlayIconButton,
+  feedActionToEntry,
+  type FeedAction,
+  type FeedActionBarEntry,
+} from "./FeedActionBar";
 import { useKerbcastCameras } from "./hooks/useKerbcastCameras";
 import { useKerbcastInFlight } from "./hooks/useKerbcastInFlight";
 import { useKerbcastStream } from "./hooks/useKerbcastStream";
+import { useRecordings } from "./hooks/useRecordings";
+import { useReportDisplaySize } from "./hooks/useReportDisplaySize";
 import { StandbyIcon } from "./StandbyIcon";
 import { isCameraDestroyed } from "./lifecycle";
+import { usePortalMenu } from "./menuPositioning";
+import { formatElapsed, nowMs } from "./timing";
 
 // ---------------------------------------------------------------------------
 // Tuning constants
@@ -28,129 +41,6 @@ const MENU_MAX_WIDTH = 260; // matches CameraMenu's CSS cap
 const MENU_MAX_HEIGHT = 300; // matches CameraMenu's min(40vh, 300px) cap
 const QUALITY_MENU_MAX_WIDTH = 220; // matches QualityMenu's CSS cap
 const QUALITY_MENU_MAX_HEIGHT = 220; // matches QualityMenu's min(40vh, 220px) cap
-const MENU_GAP = 4; // trigger-to-menu spacing
-const MENU_EDGE = 8; // minimum inset from the viewport edge
-
-/*
- * Geometry of a portaled dropdown: the CSS size caps of the menu (the
- * helper clamps as if the menu fills them) and which edge of the trigger
- * the menu hangs from: "start" lines the menu's left edge up with the
- * trigger's (camera picker), "end" lines the right edges up (quality
- * button at the action bar's corner).
- */
-interface MenuAnchor {
-  maxWidth: number;
-  maxHeight: number;
-  align: "start" | "end";
-}
-
-/*
- * Fixed-position style for a portaled menu, anchored to its trigger button.
- * Opens downward by default; flips above the trigger when there is not
- * enough room below but there is above, otherwise clamps to the viewport.
- */
-function computeMenuPosition(
-  trigger: HTMLElement,
-  anchor: MenuAnchor,
-): React.CSSProperties {
-  const rect = trigger.getBoundingClientRect();
-  const vw = window.innerWidth;
-  const vh = window.innerHeight;
-  const width = Math.min(anchor.maxWidth, vw - 2 * MENU_EDGE);
-  /* Inline offset from the aligned viewport edge, clamped so a full-width
-     menu still fits inside the opposite edge. */
-  const inset = Math.max(MENU_EDGE, vw - width - MENU_EDGE);
-  const inline: React.CSSProperties =
-    anchor.align === "start"
-      ? { left: Math.min(Math.max(rect.left, MENU_EDGE), inset) }
-      : { right: Math.min(Math.max(vw - rect.right, MENU_EDGE), inset) };
-  const menuH = Math.min(0.4 * vh, anchor.maxHeight);
-  const fitsBelow = rect.bottom + MENU_GAP + menuH <= vh - MENU_EDGE;
-  const fitsAbove = rect.top - MENU_GAP - menuH >= MENU_EDGE;
-  if (!fitsBelow && fitsAbove) {
-    return { ...inline, bottom: vh - rect.top + MENU_GAP };
-  }
-  const top = Math.min(
-    rect.bottom + MENU_GAP,
-    Math.max(MENU_EDGE, vh - MENU_EDGE - menuH),
-  );
-  return { ...inline, top };
-}
-
-/*
- * Shared behaviour for a dropdown portaled to document.body: fixed position
- * computed from the trigger's rect (so tile overflow cannot clip it),
- * re-anchored on window resize/scroll while open, Escape to close with focus
- * returned to the trigger, and portal-aware outside-pointer-down dismissal
- * (menuRef points at the portaled menu, so clicks inside it stay "inside").
- * One menu at a time falls out of the dismissal: opening another menu's
- * trigger is an outside press for this one.
- */
-function usePortalMenu({ maxWidth, maxHeight, align }: MenuAnchor) {
-  const [open, setOpen] = useState(false);
-  const [position, setPosition] = useState<React.CSSProperties | null>(null);
-  const menuRef = useRef<HTMLDivElement>(null);
-  const triggerRef = useRef<HTMLButtonElement>(null);
-
-  useEffect(() => {
-    if (!open) {
-      setPosition(null);
-      return;
-    }
-    const update = () => {
-      const trigger = triggerRef.current;
-      if (trigger) {
-        setPosition(computeMenuPosition(trigger, { maxWidth, maxHeight, align }));
-      }
-    };
-    update();
-    window.addEventListener("resize", update);
-    window.addEventListener("scroll", update, true);
-    return () => {
-      window.removeEventListener("resize", update);
-      window.removeEventListener("scroll", update, true);
-    };
-  }, [open, maxWidth, maxHeight, align]);
-
-  useEffect(() => {
-    if (!open) return;
-    const onKeyDown = (e: KeyboardEvent) => {
-      if (e.key === "Escape") {
-        e.stopPropagation();
-        setOpen(false);
-        triggerRef.current?.focus();
-      }
-    };
-    const onPointerDown = (e: PointerEvent) => {
-      if (
-        !menuRef.current?.contains(e.target as Node) &&
-        !triggerRef.current?.contains(e.target as Node)
-      ) {
-        setOpen(false);
-      }
-    };
-    document.addEventListener("keydown", onKeyDown);
-    document.addEventListener("pointerdown", onPointerDown);
-    return () => {
-      document.removeEventListener("keydown", onKeyDown);
-      document.removeEventListener("pointerdown", onPointerDown);
-    };
-  }, [open]);
-
-  const toggle = useCallback(() => setOpen((v) => !v), []);
-  /** Close after an item pick, returning focus to the trigger. */
-  const close = useCallback(() => {
-    setOpen(false);
-    triggerRef.current?.focus();
-  }, []);
-
-  return { open, toggle, close, position, menuRef, triggerRef };
-}
-
-/** Round n to the nearest even integer, minimum 2 (H.264 chroma requirement). */
-function toEvenPx(n: number): number {
-  return Math.max(2, Math.round(n / 2) * 2);
-}
 
 /*
  * Viewer quality presets, in menu order. Scales mirror the sidecar's
@@ -213,21 +103,11 @@ function exitFullscreen(): void {
 // ---------------------------------------------------------------------------
 
 /**
- * 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
- * without the library knowing what they do.
+ * The consumer-supplied action shape, and the shared top-right action bar
+ * both `CameraFeed` and `KerbalFaceFeed` render, live in `FeedActionBar`.
+ * Re-exported here since existing imports reference `./CameraFeed`.
  */
-export interface FeedAction {
-  /** Stable identity for the React key. */
-  id: string;
-  /** Accessible label; used for aria-label and the native tooltip. */
-  label: string;
-  /** Icon node, sized by the action bar (~14px). */
-  icon: React.ReactNode;
-  /** Toggle state: renders the button highlighted and sets aria-pressed. */
-  active?: boolean;
-  onClick: () => void;
-}
+export type { FeedAction } from "./FeedActionBar";
 
 /**
  * A hook that yields the live `MediaStream` for a resolved flightId. Must be
@@ -258,6 +138,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
@@ -291,8 +178,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. */
@@ -319,6 +210,39 @@ 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;
+  /**
+   * Show a built-in REC control in the action bar: a STATEFUL toggle (never
+   * overflow-eligible, per the #6 spec) that starts/stops a client-side
+   * recording of this feed via `useRecordings()`. Idle -> click starts
+   * (`start(flightId)`); active shows a red dot + a live elapsed timer on the
+   * tile -> click stops (`stop(recordingId)`) and the clip lands in the
+   * recordings store. Recording is purely client-local (this browser's own
+   * MediaRecorder, nothing server-authoritative) and read from the store
+   * (`isRecording(flightId)`), so it stays correct if toggled elsewhere (e.g.
+   * a REC+ grouped recording). Default false.
+   */
+  enableRecording?: boolean;
+  /**
+   * Record this feed at the operator's full render size for the duration of
+   * the built-in REC control's recording (overrides only the display-size
+   * demand; still yields to the adaptive framerate shed). Off by default.
+   * Threaded straight into `start(flightId, { forceFullResolution })`; has
+   * no effect unless `enableRecording` is also set. While the feed is armed
+   * (force sent, waiting for the resolution bump) the tile shows an
+   * "ARMING" pill under the title in place of the REC badge, then switches
+   * to the normal REC badge + elapsed timer once recording actually starts.
+   */
+  recordFullResolution?: boolean;
   /**
    * Consumer-injected action buttons, rendered left of the built-in
    * fullscreen/PiP controls in the top-right action bar.
@@ -326,10 +250,19 @@ export interface CameraFeedProps {
   actions?: FeedAction[];
   /**
    * Consumer-injected action buttons rendered at the far end of the action
-   * bar, right of the built-in controls — the natural home for a close/remove
-   * button so it sits in the corner.
+   * bar: the natural home for a close/remove button. Always pinned trailing
+   * (never overflow-eligible, never counted toward the overflow threshold),
+   * so it sits in the corner as a persistent, single-click control, right of
+   * the ⋮ overflow trigger when one is present.
    */
   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` —
@@ -357,6 +290,7 @@ const CameraFeedInner = forwardRef<CameraFeedHandle, CameraFeedProps>(
     {
       flightId: requestedFlightId,
       onSelectCamera,
+      cameraFilter,
       onDisplayedCameraChange,
       showDebugInfo = false,
       showStatic,
@@ -367,14 +301,29 @@ const CameraFeedInner = forwardRef<CameraFeedHandle, CameraFeedProps>(
       enableFullscreen = false,
       enablePictureInPicture = false,
       enableQualityControl = false,
+      enableTracking = false,
+      enableRecording = false,
+      recordFullResolution = false,
       actions,
       trailingActions,
+      showActions = true,
       useStream,
     },
     ref,
   ) {
     const client = useKerbcastClient();
-    const cameras = useKerbcastCameras();
+    // Always called (rules of hooks); `enableRecording` only gates whether the
+    // REC entry/badge render, not whether the store is subscribed.
+    const recordings = useRecordings();
+    // 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;
@@ -549,6 +498,14 @@ const CameraFeedInner = forwardRef<CameraFeedHandle, CameraFeedProps>(
     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;
 
@@ -576,7 +533,7 @@ const CameraFeedInner = forwardRef<CameraFeedHandle, CameraFeedProps>(
     );
 
     // -------------------------------------------------------------------------
-    // PanZoomController -- one per displayed camera
+    // PanZoomController: one per displayed camera
     // -------------------------------------------------------------------------
     const controllerRef = useRef<PanZoomController | null>(null);
     const [sliderFov, setSliderFov] = useState(60);
@@ -593,8 +550,8 @@ const CameraFeedInner = forwardRef<CameraFeedHandle, CameraFeedProps>(
       controllerRef.current = ctrl;
 
       const unsubSlider = ctrl.onSliderFov(setSliderFov);
-      // Seed the slider from the controller's initial (0) -- will be overwritten
-      // immediately by syncFromState in the camera-state effect below.
+      // Seed the slider from the controller's initial (0). It will be
+      // overwritten immediately by syncFromState in the camera-state effect below.
       setSliderFov(ctrl.sliderFov);
 
       return () => {
@@ -695,35 +652,12 @@ const CameraFeedInner = forwardRef<CameraFeedHandle, CameraFeedProps>(
     );
 
     // -------------------------------------------------------------------------
-    // 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<ReturnType<typeof setTimeout> | null>(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
@@ -776,6 +710,87 @@ const CameraFeedInner = forwardRef<CameraFeedHandle, CameraFeedProps>(
       [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: TrackMode) => {
+        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],
+    );
+
+    // -------------------------------------------------------------------------
+    // REC control (opt-in). A stateful toggle that starts/stops a client-side
+    // recording of this feed via the recordings store; state is read from the
+    // store (isRecording), never held locally, so it stays correct if the
+    // recording was started elsewhere (e.g. a REC+ grouped recording).
+    // -------------------------------------------------------------------------
+    const recordingActive =
+      enableRecording && flightId !== null && recordings.isRecording(flightId);
+    const activeRecording = recordingActive
+      ? recordings.active.find((a) => a.flightId === flightId)
+      : undefined;
+    /* True while a single forced recording is armed (force sent, waiting for
+       the feed to reach full resolution) but the recorder has not started
+       yet (see ActiveRecordingInfo.arming). Drives the ARMING pill below in
+       place of the REC badge. */
+    const armingActive = activeRecording?.arming === true;
+
+    // Ticks once a second while recording so the elapsed timer stays live;
+    // the timer itself is derived from activeRecording.startedAt each render.
+    const [, tickRecordingTimer] = useReducer((c: number) => c + 1, 0);
+    useEffect(() => {
+      if (!recordingActive) return;
+      const interval = setInterval(tickRecordingTimer, 1000);
+      return () => clearInterval(interval);
+    }, [recordingActive]);
+
+    const recordingElapsedMs = activeRecording ? nowMs() - activeRecording.startedAt : 0;
+
+    const toggleRecording = useCallback(() => {
+      if (flightId === null) return;
+      if (recordingActive) {
+        const active = recordings.active.find((a) => a.flightId === flightId);
+        if (active) {
+          void recordings.stop(active.recordingId).catch(() => {
+            /* A rejected stop shouldn't leave the REC toggle wedged; the
+               store's own state (active/recordings) is the source of truth
+               for whether it's still "recording", not this call's outcome. */
+          });
+        }
+        return;
+      }
+      try {
+        recordings.start(flightId, { forceFullResolution: recordFullResolution });
+      } catch {
+        /* no live track yet, or a race with a recording already in progress
+           elsewhere on this feed; the operator can retry once live. */
+      }
+    }, [flightId, recordingActive, recordings, recordFullResolution]);
+
     const topOverlay = (
       <TopOverlay>
         <TitleRow>
@@ -787,7 +802,9 @@ const CameraFeedInner = forwardRef<CameraFeedHandle, CameraFeedProps>(
                 aria-haspopup="menu"
                 aria-expanded={cameraMenu.open}
                 aria-controls={menuId}
-                onClick={cameraMenu.toggle}
+                disabled={recordingActive}
+                title={recordingActive ? "Stop recording to change camera" : undefined}
+                onClick={recordingActive ? undefined : cameraMenu.toggle}
               >
                 <TitleButton__Text>{title}</TitleButton__Text>
                 <ChevronDownIcon aria-hidden="true" />
@@ -842,97 +859,205 @@ const CameraFeedInner = forwardRef<CameraFeedHandle, CameraFeedProps>(
       </TopOverlay>
     );
 
-    const renderAction = (a: FeedAction) => (
-      <OverlayIconButton
-        key={a.id}
-        type="button"
-        aria-label={a.label}
-        aria-pressed={a.active ?? undefined}
-        title={a.label}
-        $active={a.active ?? false}
-        onClick={a.onClick}
-      >
-        {a.icon}
-      </OverlayIconButton>
-    );
-
-    const builtInActions =
-      flightId !== null && (pipAvailable || fullscreenAvailable || qualityAvailable);
-    const hasActionBar =
-      hasCameras ||
-      (actions && actions.length > 0) ||
-      (trailingActions && trailingActions.length > 0) ||
-      builtInActions;
-    const actionBar = hasActionBar ? (
-        <ActionBar>
-          {hasCameras && (
-            <StepButtons>
-              <OverlayIconButton
-                type="button"
-                aria-label="Previous camera"
-                disabled={!canStep}
-                onClick={() => stepCamera(-1)}
-              >
-                &#8249;
-              </OverlayIconButton>
-              <OverlayIconButton
-                type="button"
-                aria-label="Next camera"
-                disabled={!canStep}
-                onClick={() => stepCamera(1)}
-              >
-                &#8250;
-              </OverlayIconButton>
-            </StepButtons>
-          )}
-          {actions?.map(renderAction)}
-          {qualityAvailable && (
-            <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}
-            >
-              <QualityIcon />
-              {qualityThrottled && <ThrottledDot aria-hidden="true" />}
-            </OverlayIconButton>
-          )}
-          {flightId !== null && pipAvailable && (
-            <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}
-            >
-              <PictureInPictureIcon />
-            </OverlayIconButton>
-          )}
-          {flightId !== null && fullscreenAvailable && (
+    /*
+     * Built-in action-bar entries, in the bar's natural (fallback) order:
+     * consumer actions, quality, tracking, PiP, fullscreen, trailing actions.
+     * FeedActionBar partitions these into primary/overflow (see its own
+     * doc-comment); tracking is the only built-in marked `stateful` today,
+     * per #6's "stateful toggles stay primary" rule (REC joins it the same
+     * way).
+     */
+    const trackingLabel = tracking
+      ? trackMode === TrackMode.Target
+        ? "Auto-tracking target"
+        : "Auto-tracking active vessel"
+      : "Auto-track a vessel";
+    const pipLabel = isPip ? "Exit picture in picture" : "Picture in picture";
+    const fullscreenLabel = isFullscreen ? "Exit fullscreen" : "Enter fullscreen";
+    const recordingLabel = recordingActive ? "Stop recording" : "Start recording";
+
+    const entries: FeedActionBarEntry[] = [
+      ...(actions?.map(feedActionToEntry) ?? []),
+      ...(qualityAvailable
+        ? [
+            {
+              id: "quality",
+              label: "Quality",
+              stateful: false,
+              render: () => (
+                <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}
+                >
+                  <QualityIcon />
+                  {qualityThrottled && <ThrottledDot aria-hidden="true" />}
+                </OverlayIconButton>
+              ),
+            } satisfies FeedActionBarEntry,
+          ]
+        : []),
+      ...(enableRecording && flightId !== null
+        ? [
+            {
+              id: "record",
+              label: recordingLabel,
+              stateful: true,
+              render: () => (
+                <RecordActionButton
+                  type="button"
+                  aria-label={recordingLabel}
+                  aria-pressed={recordingActive}
+                  title={recordingLabel}
+                  $active={recordingActive}
+                  onClick={toggleRecording}
+                >
+                  <RecordIcon />
+                </RecordActionButton>
+              ),
+            } satisfies FeedActionBarEntry,
+          ]
+        : []),
+      ...(trackingAvailable
+        ? [
+            {
+              id: "tracking",
+              label: trackingLabel,
+              stateful: true,
+              render: () => (
+                <OverlayIconButton
+                  ref={trackingMenu.triggerRef}
+                  type="button"
+                  aria-label="Auto-track"
+                  aria-haspopup="menu"
+                  aria-expanded={trackingMenu.open}
+                  aria-controls={trackingMenuId}
+                  aria-pressed={tracking}
+                  title={trackingLabel}
+                  $active={tracking || trackingMenu.open}
+                  onClick={trackingMenu.toggle}
+                >
+                  <CrosshairIcon />
+                </OverlayIconButton>
+              ),
+            } satisfies FeedActionBarEntry,
+          ]
+        : []),
+      ...(flightId !== null && pipAvailable
+        ? [
+            {
+              id: "pip",
+              label: pipLabel,
+              stateful: false,
+              render: () => (
+                <OverlayIconButton
+                  type="button"
+                  aria-label={pipLabel}
+                  aria-pressed={isPip}
+                  title={pipLabel}
+                  $active={isPip}
+                  onClick={togglePip}
+                >
+                  <PictureInPictureIcon />
+                </OverlayIconButton>
+              ),
+            } satisfies FeedActionBarEntry,
+          ]
+        : []),
+      ...(flightId !== null && fullscreenAvailable
+        ? [
+            {
+              id: "fullscreen",
+              label: fullscreenLabel,
+              stateful: false,
+              render: () => (
+                <OverlayIconButton
+                  type="button"
+                  aria-label={fullscreenLabel}
+                  aria-pressed={isFullscreen}
+                  title={fullscreenLabel}
+                  $active={isFullscreen}
+                  onClick={toggleFullscreen}
+                >
+                  {isFullscreen ? <FullscreenExitIcon /> : <FullscreenEnterIcon />}
+                </OverlayIconButton>
+              ),
+            } satisfies FeedActionBarEntry,
+          ]
+        : []),
+      /* trailingActions is always the pinned-trailing (close/remove) slot,
+         regardless of what the consumer's FeedAction sets. See its own
+         doc-comment on CameraFeedProps. While a recording is active, closing
+         the feed would lose it, so the control stays visible but disabled
+         and inert rather than disappearing. */
+      ...(trailingActions?.map((a) => {
+        const entry = feedActionToEntry(a);
+        if (!recordingActive) return { ...entry, pinnedTrailing: true };
+        return {
+          ...entry,
+          pinnedTrailing: true,
+          render: () => (
             <OverlayIconButton
+              key={a.id}
               type="button"
-              aria-label={isFullscreen ? "Exit fullscreen" : "Enter fullscreen"}
-              aria-pressed={isFullscreen}
-              title={isFullscreen ? "Exit fullscreen" : "Enter fullscreen"}
-              $active={isFullscreen}
-              onClick={toggleFullscreen}
+              aria-label={a.label}
+              title="Stop recording to close this feed"
+              disabled
+              $active={a.active ?? false}
             >
-              {isFullscreen ? <FullscreenExitIcon /> : <FullscreenEnterIcon />}
+              {a.icon}
             </OverlayIconButton>
-          )}
-          {trailingActions?.map(renderAction)}
-        </ActionBar>
-      ) : null;
+          ),
+        };
+      }) ?? []),
+    ];
+
+    const builtInActions =
+      flightId !== null &&
+      (pipAvailable ||
+        fullscreenAvailable ||
+        qualityAvailable ||
+        trackingAvailable ||
+        enableRecording);
+    const hasActionBar =
+      showActions &&
+      (hasCameras ||
+        (actions && actions.length > 0) ||
+        (trailingActions && trailingActions.length > 0) ||
+        builtInActions);
+    const stepButtons = hasCameras ? (
+      <StepButtons>
+        <OverlayIconButton
+          type="button"
+          aria-label="Previous camera"
+          disabled={!canStep}
+          onClick={() => stepCamera(-1)}
+        >
+          &#8249;
+        </OverlayIconButton>
+        <OverlayIconButton
+          type="button"
+          aria-label="Next camera"
+          disabled={!canStep}
+          onClick={() => stepCamera(1)}
+        >
+          &#8250;
+        </OverlayIconButton>
+      </StepButtons>
+    ) : null;
+    const actionBar = hasActionBar ? (
+      <FeedActionBar leading={stepButtons} entries={entries} />
+    ) : null;
 
     return (
       <Stage ref={wrapRef} $pinned={chromePinned}>
@@ -995,6 +1120,39 @@ const CameraFeedInner = forwardRef<CameraFeedHandle, CameraFeedProps>(
                 </QualityMenu>,
                 document.body,
               )}
+            {trackingAvailable &&
+              trackingMenu.open &&
+              trackingMenu.position &&
+              camera &&
+              createPortal(
+                <QualityMenu
+                  ref={trackingMenu.menuRef}
+                  id={trackingMenuId}
+                  role="menu"
+                  aria-label="Auto-track"
+                  style={trackingMenu.position}
+                >
+                  <CameraMenuItem
+                    type="button"
+                    role="menuitemradio"
+                    aria-checked={trackMode === TrackMode.ActiveVessel}
+                    $selected={trackMode === TrackMode.ActiveVessel}
+                    onClick={() => selectTrack(TrackMode.ActiveVessel)}
+                  >
+                    Track active vessel
+                  </CameraMenuItem>
+                  <CameraMenuItem
+                    type="button"
+                    role="menuitemradio"
+                    aria-checked={trackMode === TrackMode.Target}
+                    $selected={trackMode === TrackMode.Target}
+                    onClick={() => selectTrack(TrackMode.Target)}
+                  >
+                    Track target
+                  </CameraMenuItem>
+                </QualityMenu>,
+                document.body,
+              )}
             {outOfFlight ? (
               showStandbyIcon && (
                 <StandbyOverlay role="status" aria-label="Standby, no active flight">
@@ -1021,12 +1179,25 @@ const CameraFeedInner = forwardRef<CameraFeedHandle, CameraFeedProps>(
                 </StaleBadge>
               </>
             )}
+            {recordingActive && armingActive && (
+              <ArmingBadge role="status" aria-label="Arming">
+                <ArmingDot aria-hidden="true" />
+                ARMING
+              </ArmingBadge>
+            )}
+            {recordingActive && !armingActive && (
+              <RecBadge role="status" aria-label="Recording">
+                <RecDot aria-hidden="true" />
+                REC {formatElapsed(recordingElapsedMs)}
+              </RecBadge>
+            )}
             {showZoom && (
-              <ZoomControlsWrap>
+              <ZoomControlsWrap $disabled={manualDisabled} aria-hidden={manualDisabled}>
                 <ZoomButton
                   type="button"
                   aria-label="Zoom in"
                   $pos="top"
+                  disabled={manualDisabled}
                   onPointerDown={() =>
                     controllerRef.current?.setZoomRate(1)
                   }
@@ -1046,6 +1217,7 @@ const CameraFeedInner = forwardRef<CameraFeedHandle, CameraFeedProps>(
                   max={camera.fovMax}
                   step={0.5}
                   value={sliderFov}
+                  disabled={manualDisabled}
                   onChange={(e) => {
                     const v = Number(e.target.value);
                     controllerRef.current?.fovSliderInput(v);
@@ -1064,6 +1236,7 @@ const CameraFeedInner = forwardRef<CameraFeedHandle, CameraFeedProps>(
                   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)}
@@ -1077,12 +1250,17 @@ const CameraFeedInner = forwardRef<CameraFeedHandle, CameraFeedProps>(
               </ZoomControlsWrap>
             )}
             {showPan && (
-              <PanControl role="group" aria-label="Pan camera">
+              <PanControl
+                role="group"
+                aria-label="Pan camera"
+                $disabled={manualDisabled}
+                aria-hidden={manualDisabled}
+              >
                 <PanArrow
                   type="button"
                   $dir="up"
                   aria-label="Pan up"
-                  disabled={!supportsPitch}
+                  disabled={manualDisabled || !supportsPitch}
                   onClick={() => controllerRef.current?.nudgePan(0, 1)}
                 >
                   &#9650;
@@ -1091,7 +1269,7 @@ const CameraFeedInner = forwardRef<CameraFeedHandle, CameraFeedProps>(
                   type="button"
                   $dir="down"
                   aria-label="Pan down"
-                  disabled={!supportsPitch}
+                  disabled={manualDisabled || !supportsPitch}
                   onClick={() => controllerRef.current?.nudgePan(0, -1)}
                 >
                   &#9660;
@@ -1100,6 +1278,7 @@ const CameraFeedInner = forwardRef<CameraFeedHandle, CameraFeedProps>(
                   type="button"
                   $dir="left"
                   aria-label="Pan left"
+                  disabled={manualDisabled}
                   onClick={() => controllerRef.current?.nudgePan(-1, 0)}
                 >
                   &#9664;
@@ -1108,6 +1287,7 @@ const CameraFeedInner = forwardRef<CameraFeedHandle, CameraFeedProps>(
                   type="button"
                   $dir="right"
                   aria-label="Pan right"
+                  disabled={manualDisabled}
                   onClick={() => controllerRef.current?.nudgePan(1, 0)}
                 >
                   &#9654;
@@ -1115,10 +1295,10 @@ const CameraFeedInner = forwardRef<CameraFeedHandle, CameraFeedProps>(
                 <PanBall
                   aria-hidden="true"
                   title="Drag to pan"
-                  onPointerDown={handleBallDown}
-                  onPointerMove={handleBallMove}
-                  onPointerUp={handleBallUp}
-                  onPointerCancel={handleBallUp}
+                  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)`,
                   }}
@@ -1211,6 +1391,16 @@ function QualityIcon() {
   );
 }
 
+/* Auto-track: a crosshair / reticle. */
+function CrosshairIcon() {
+  return (
+    <svg {...iconProps}>
+      <circle cx="8" cy="8" r="4.5" />
+      <path d="M8 1v2.5M8 12.5V15M1 8h2.5M12.5 8H15" />
+    </svg>
+  );
+}
+
 /* Stale badge: fading signal bars (tallest dimmed). */
 function StaleIcon() {
   return (
@@ -1238,11 +1428,20 @@ function PictureInPictureIcon() {
   );
 }
 
+/* REC: a plain filled dot, coloured by RecordActionButton's own $active state. */
+function RecordIcon() {
+  return (
+    <svg viewBox="0 0 16 16" width={14} height={14} fill="currentColor" stroke="none" aria-hidden="true">
+      <circle cx="8" cy="8" r="5" />
+    </svg>
+  );
+}
+
 // ---------------------------------------------------------------------------
 // Styled components
 // ---------------------------------------------------------------------------
 
-const PanControl = styled.div`
+const PanControl = styled.div<{ $disabled?: boolean }>`
   position: absolute;
   bottom: 10px;
   right: 10px;
@@ -1252,6 +1451,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;
   }
@@ -1322,7 +1524,7 @@ const PanBall = styled.div`
   }
 `;
 
-const ZoomControlsWrap = styled.div`
+const ZoomControlsWrap = styled.div<{ $disabled?: boolean }>`
   position: absolute;
   bottom: 8px;
   left: 8px;
@@ -1335,6 +1537,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;
   }
@@ -1560,21 +1765,114 @@ const ThrottledDot = styled.span`
   box-shadow: 0 0 0 1px rgba(0, 0, 0, 0.6);
 `;
 
-/* Top-right cluster of overlay controls (custom actions + fullscreen/PiP). */
-const ActionBar = styled.div`
+/* REC action-bar button: same shape as OverlayIconButton, its own red
+   $active colour (a coming-recording toggle should never read as the
+   green "on" of tracking/quality) via its own token so a consumer can
+   recolour it without touching --kerbcast-action-active. */
+const RecordActionButton = styled(OverlayIconButton)<{ $active?: boolean }>`
+  background: ${(p) =>
+    p.$active ? "var(--kerbcast-rec-active, #ff3b30)" : "rgba(0, 0, 0, 0.5)"};
+  border-color: ${(p) =>
+    p.$active ? "var(--kerbcast-rec-active, #ff3b30)" : "rgba(255, 255, 255, 0.3)"};
+  color: #fff;
+
+  @media (hover: hover) {
+    &:hover {
+      background: ${(p) =>
+        p.$active ? "var(--kerbcast-rec-active, #ff3b30)" : "rgba(0, 0, 0, 0.7)"};
+    }
+  }
+`;
+
+/* Persistent recording badge: red dot + elapsed timer, always visible while
+   recording (not hover chrome), same convention as StaleBadge. */
+const RecBadge = styled.div`
   position: absolute;
-  top: 6px;
-  right: 8px;
-  z-index: 3;
+  /* Sits just under the hover-gated title/source dropdown (both are top-left)
+     so an active recording stays visible without displacing that control. */
+  top: 28px;
+  left: 8px;
+  z-index: 2;
   display: flex;
   align-items: center;
-  gap: 4px;
-  opacity: 0;
+  gap: 5px;
+  padding: 2px 6px;
+  background: rgba(0, 0, 0, 0.6);
+  border: 1px solid var(--kerbcast-rec-active, #ff3b30);
+  border-radius: 3px;
+  color: #fff;
+  font-size: 10px;
+  font-weight: 600;
+  letter-spacing: 0.12em;
+  text-shadow: 0 1px 2px rgba(0, 0, 0, 0.9);
   pointer-events: none;
-  transition: opacity 0.15s;
+`;
 
-  @media (prefers-reduced-motion: reduce) {
-    transition: none;
+const RecDot = styled.span`
+  width: 7px;
+  height: 7px;
+  border-radius: 50%;
+  background: var(--kerbcast-rec-active, #ff3b30);
+  flex-shrink: 0;
+
+  @media (prefers-reduced-motion: no-preference) {
+    animation: rec-dot-pulse 1.6s ease-in-out infinite;
+  }
+
+  @keyframes rec-dot-pulse {
+    0%,
+    100% {
+      opacity: 1;
+    }
+    50% {
+      opacity: 0.4;
+    }
+  }
+`;
+
+/* Arming pill: same slot as RecBadge (a single forced recording shows one or
+   the other, never both), a muted amber so it never reads as the red
+   "recording is live" state: the feed hasn't actually started capturing
+   yet, it's waiting for the resolution bump. */
+const ArmingBadge = styled.div`
+  position: absolute;
+  top: 28px;
+  left: 8px;
+  z-index: 2;
+  display: flex;
+  align-items: center;
+  gap: 5px;
+  padding: 2px 6px;
+  background: rgba(0, 0, 0, 0.6);
+  border: 1px solid var(--kerbcast-arming-active, #d9a441);
+  border-radius: 3px;
+  color: #fff;
+  font-size: 10px;
+  font-weight: 600;
+  letter-spacing: 0.12em;
+  text-shadow: 0 1px 2px rgba(0, 0, 0, 0.9);
+  pointer-events: none;
+`;
+
+const ArmingDot = styled.span`
+  width: 7px;
+  height: 7px;
+  border-radius: 50%;
+  background: var(--kerbcast-arming-active, #d9a441);
+  flex-shrink: 0;
+
+  @media (prefers-reduced-motion: no-preference) {
+    animation: arming-dot-pulse 0.9s ease-in-out infinite;
+  }
+
+  @keyframes arming-dot-pulse {
+    0%,
+    100% {
+      opacity: 1;
+    }
+    50% {
+      opacity: 0.3;
+    }
   }
 `;
 
@@ -1609,14 +1907,14 @@ const Stage = styled(Panel)<{ $pinned: boolean }>`
   &:focus-within ${ZoomControlsWrap},
   &:hover ${PanControl},
   &:focus-within ${PanControl},
-  &:hover ${ActionBar},
-  &:focus-within ${ActionBar} {
+  &:hover ${ActionBarRow},
+  &:focus-within ${ActionBarRow} {
     opacity: 1;
   }
   &:hover ${TopOverlay},
   &:focus-within ${TopOverlay},
-  &:hover ${ActionBar},
-  &:focus-within ${ActionBar} {
+  &:hover ${ActionBarRow},
+  &:focus-within ${ActionBarRow} {
     pointer-events: auto;
   }
 
@@ -1627,7 +1925,7 @@ const Stage = styled(Panel)<{ $pinned: boolean }>`
         opacity: 1;
         pointer-events: auto;
       }
-      ${ActionBar} {
+      ${ActionBarRow} {
         opacity: 1;
         pointer-events: auto;
       }
@@ -1646,52 +1944,6 @@ const Empty = styled.div`
   text-align: center;
 `;
 
-const OverlayIconButton = styled.button<{ $active?: boolean }>`
-  position: relative;
-  width: 24px;
-  height: 24px;
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  padding: 0;
-  background: ${(p) =>
-    p.$active
-      ? "var(--kerbcast-accent, #00ff88)"
-      : "rgba(0, 0, 0, 0.5)"};
-  border: 1px solid
-    ${(p) =>
-      p.$active
-        ? "var(--kerbcast-accent, #00ff88)"
-        : "rgba(255, 255, 255, 0.3)"};
-  border-radius: 3px;
-  color: ${(p) => (p.$active ? "#000" : "#fff")};
-  cursor: pointer;
-  transition: background 0.12s, border-color 0.12s, color 0.12s;
-
-  @media (hover: hover) {
-    &:hover {
-      background: ${(p) =>
-        p.$active
-          ? "var(--kerbcast-accent, #00ff88)"
-          : "rgba(0, 0, 0, 0.7)"};
-      border-color: rgba(255, 255, 255, 0.6);
-    }
-  }
-
-  &:focus-visible {
-    outline: 2px solid var(--kerbcast-accent, #00ff88);
-    outline-offset: 2px;
-  }
-
-  &:disabled {
-    opacity: 0.4;
-  }
-
-  @media (prefers-reduced-motion: reduce) {
-    transition: none;
-  }
-`;
-
 const StyledVideo = styled.video`
   position: absolute;
   inset: 0;