@ksp-gonogo/kerbcast-react 1.6.3 → 1.8.0

package/CHANGELOG.md

@@ -1,5 +1,59 @@
 # Changelog
 
+## Unreleased (next minor)
+
+### Added
+
+- `useRecordings`: a reactive recordings store over the SDK's
+  `client.recording` controller. Exposes finished standalone clips
+  (`recordings`), synchronised sets (`groups`), and in-progress recordings
+  (`active`, for a REC dot + elapsed timer), plus `start` / `stop` /
+  `startGroup` / `stopGroup` / `discard` / `discardGroup` / `isRecording`. This
+  is the headless data layer the recordings tray + REC controls sit on; it owns
+  no chrome and keeps grouped clips out of the singles list
+- `RecordingsStore` and `ActiveRecordingInfo` types
+
+## 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,20 +1,11 @@
-import type { KerbcastClient } from "@ksp-gonogo/kerbcast";
+import type { CameraState, KerbcastClient } from "@ksp-gonogo/kerbcast";
+import { type FeedAction } from "./FeedActionBar";
 /**
- * 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
  * a stable reference (the same function identity every render) and called
@@ -43,6 +34,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 +74,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 +106,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.
@@ -111,10 +146,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` —