@ksp-gonogo/kerbcast-react 1.6.3 → 1.8.0

package/dist/FeedActionBar.d.ts

@@ -0,0 +1,133 @@
+/**
+ * FeedActionBar: the shared top-right action row rendered by BOTH
+ * `CameraFeed` and `KerbalFaceFeed`, so a single overflow engine serves every
+ * feed surface (part cams, crew faces, and any future host).
+ *
+ * Partition rule (issue #6 UI spec): stateful toggles (their at-rest state
+ * must stay visible, e.g. auto-track, the coming REC) are PRIMARY and always
+ * inline. Non-stateful actions (quality, PiP, fullscreen, plain consumer
+ * actions) are overflow-eligible: they collapse into a ⋮ menu ONLY once the
+ * row is genuinely crowded (total enabled >= 4 AND >= 2 non-stateful
+ * eligible): a single item never collapses, since that would cost a click
+ * to reach the one control that exists. Order is stable (an explicit `order`
+ * wins, otherwise entries keep the relative position their caller gave them)
+ * so chips don't reflow as buttons enable/disable around them.
+ *
+ * Close/remove is a THIRD category: `pinnedTrailing`. It is never
+ * overflow-eligible, never counted toward the overflow threshold, and always
+ * renders last (to the right of the ⋮ trigger itself), so dismissing a
+ * feed always stays a single, persistent, rightmost click. Bar order is:
+ * [stateful primaries] … [⋮ overflow, non-stateful] [pinned trailing close].
+ *
+ * Deliberately minimal: an entry is just (id, label, stateful?, order?,
+ * pinnedTrailing?, render). The interactive node itself (icon, aria
+ * attributes, onClick, any submenu it opens) is built by the caller
+ * (CameraFeed / KerbalFaceFeed) exactly as before; this component only
+ * decides WHERE it goes.
+ */
+/**
+ * A consumer-supplied action rendered into a feed's action bar. Lets a host
+ * page (e.g. the sidecar's spotlight toggle) inject controls without the
+ * library knowing what they do.
+ */
+export interface FeedAction {
+    /** Stable identity for the React key. */
+    id: string;
+    /** Accessible label; used for aria-label, the native tooltip, and the overflow-menu row's visible text. */
+    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;
+    /**
+     * Whether this action is a stateful toggle: stays PRIMARY / always
+     * inline so its at-rest state is visible, never collapses into the ⋮
+     * overflow. Defaults to `active !== undefined`. Override when a
+     * tri-state/menu-driven action's "active" isn't a plain boolean, or to force
+     * a boolean toggle to be overflow-eligible anyway.
+     */
+    stateful?: boolean;
+    /**
+     * Stable sort key for the action bar (lower sorts first). Actions without
+     * an explicit order keep their natural (array) position; this exists so a
+     * consumer can pin an action to a specific slot instead. Chips never
+     * reflow as buttons enable/disable; this is what keeps that stable.
+     */
+    order?: number;
+    /**
+     * Marks this as the bar's pinned-trailing (close/remove) slot: it is NEVER
+     * overflow-eligible, is excluded entirely from the overflow-threshold count
+     * (both the total and the non-stateful-eligible count), and always renders
+     * last (to the right of the ⋮ trigger), so dismissing a feed is always a
+     * single, persistent, rightmost click. `CameraFeed`'s `trailingActions`
+     * prop sets this automatically; a `KerbalFaceFeed`/`actions`-only consumer
+     * sets it explicitly on its close action.
+     */
+    pinnedTrailing?: boolean;
+}
+interface Partitionable {
+    stateful?: boolean;
+    order?: number;
+    pinnedTrailing?: boolean;
+}
+/**
+ * Sort a list of action-bar entries into (primary, overflow, pinnedTrailing).
+ * `entries` must already be filtered down to the currently-enabled set:
+ * this function has no notion of "disabled", only "present".
+ *
+ * `pinnedTrailing` entries (close/remove) are pulled out FIRST and excluded
+ * entirely from the overflow-threshold count. Both the total and the
+ * non-stateful-eligible count run only over the remaining entries, then
+ * always returned as their own group, to be rendered last (see
+ * `FeedActionBar`, which places them after the ⋮ trigger).
+ */
+export declare function partitionActionBarEntries<T extends Partitionable>(entries: readonly T[]): {
+    primary: T[];
+    overflow: T[];
+    pinnedTrailing: T[];
+};
+/**
+ * One slot in the bar. `render` produces the actual interactive element
+ * (unchanged whether it lands inline or inside the overflow menu) so callers
+ * keep full control of refs / aria attributes / submenus; FeedActionBar only
+ * decides placement and, in the overflow menu, adds the visible label.
+ */
+export interface FeedActionBarEntry {
+    id: string;
+    label: string;
+    stateful?: boolean;
+    order?: number;
+    pinnedTrailing?: boolean;
+    render: () => React.ReactNode;
+}
+/**
+ * Adapt a plain consumer/public `FeedAction` (id/label/icon/active/onClick,
+ * plus the optional stateful?/order?/pinnedTrailing? flags) into a bar entry,
+ * rendered as the standard icon button. `stateful` defaults to
+ * `active !== undefined` per the #6 spec (stateful toggles, meaning
+ * `active !== undefined`, stay primary).
+ */
+export declare function feedActionToEntry(action: FeedAction): FeedActionBarEntry;
+export interface FeedActionBarProps {
+    /** Non-partitioned content rendered before the partitioned entries (e.g. the camera step buttons). */
+    leading?: React.ReactNode;
+    entries: FeedActionBarEntry[];
+    /** Forwarded to the root row; lets a host `styled(FeedActionBar)` override layout (e.g. KerbalFaceFeed's smaller, always-visible bar). */
+    className?: string;
+}
+/**
+ * Shared top-right action row. Renders `leading`, then the partitioned
+ * entries: stateful ones always inline, non-stateful ones inline until the
+ * row is crowded enough to warrant a ⋮ overflow menu, then the pinned
+ * trailing (close/remove) entries: always last, to the right of the ⋮.
+ */
+export declare function FeedActionBar({ leading, entries, className }: FeedActionBarProps): import("react").JSX.Element | null;
+/** Icon-button shared by every action-bar entry (built-in or consumer). */
+export declare const OverlayIconButton: import("styled-components/dist/types").IStyledComponentBase<"web", import("styled-components").FastOmit<import("styled-components").FastOmit<import("react").DetailedHTMLProps<import("react").ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>, "$active"> & {
+    $active?: boolean;
+}, never> & Partial<Pick<import("styled-components").FastOmit<import("react").DetailedHTMLProps<import("react").ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>, "$active"> & {
+    $active?: boolean;
+}, never>>> & string;
+export declare const ActionBarRow: import("styled-components/dist/types").IStyledComponentBase<"web", import("styled-components").FastOmit<import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, never> & Partial<Pick<import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, never>>> & string;
+export {};

package/dist/FeedActionBar.js

@@ -0,0 +1,225 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * FeedActionBar: the shared top-right action row rendered by BOTH
+ * `CameraFeed` and `KerbalFaceFeed`, so a single overflow engine serves every
+ * feed surface (part cams, crew faces, and any future host).
+ *
+ * Partition rule (issue #6 UI spec): stateful toggles (their at-rest state
+ * must stay visible, e.g. auto-track, the coming REC) are PRIMARY and always
+ * inline. Non-stateful actions (quality, PiP, fullscreen, plain consumer
+ * actions) are overflow-eligible: they collapse into a ⋮ menu ONLY once the
+ * row is genuinely crowded (total enabled >= 4 AND >= 2 non-stateful
+ * eligible): a single item never collapses, since that would cost a click
+ * to reach the one control that exists. Order is stable (an explicit `order`
+ * wins, otherwise entries keep the relative position their caller gave them)
+ * so chips don't reflow as buttons enable/disable around them.
+ *
+ * Close/remove is a THIRD category: `pinnedTrailing`. It is never
+ * overflow-eligible, never counted toward the overflow threshold, and always
+ * renders last (to the right of the ⋮ trigger itself), so dismissing a
+ * feed always stays a single, persistent, rightmost click. Bar order is:
+ * [stateful primaries] … [⋮ overflow, non-stateful] [pinned trailing close].
+ *
+ * Deliberately minimal: an entry is just (id, label, stateful?, order?,
+ * pinnedTrailing?, render). The interactive node itself (icon, aria
+ * attributes, onClick, any submenu it opens) is built by the caller
+ * (CameraFeed / KerbalFaceFeed) exactly as before; this component only
+ * decides WHERE it goes.
+ */
+import { Fragment, useId } from "react";
+import { createPortal } from "react-dom";
+import styled from "styled-components";
+import { usePortalMenu } from "./menuPositioning";
+// ---------------------------------------------------------------------------
+// Partition logic (pure, unit-tested independently of any rendering)
+// ---------------------------------------------------------------------------
+const OVERFLOW_MIN_TOTAL = 4;
+const OVERFLOW_MIN_NON_STATEFUL = 2;
+/**
+ * Sort a list of action-bar entries into (primary, overflow, pinnedTrailing).
+ * `entries` must already be filtered down to the currently-enabled set:
+ * this function has no notion of "disabled", only "present".
+ *
+ * `pinnedTrailing` entries (close/remove) are pulled out FIRST and excluded
+ * entirely from the overflow-threshold count. Both the total and the
+ * non-stateful-eligible count run only over the remaining entries, then
+ * always returned as their own group, to be rendered last (see
+ * `FeedActionBar`, which places them after the ⋮ trigger).
+ */
+export function partitionActionBarEntries(entries) {
+    const sorted = [...entries].sort((a, b) => (a.order ?? Number.POSITIVE_INFINITY) - (b.order ?? Number.POSITIVE_INFINITY));
+    const pinnedTrailing = sorted.filter((e) => e.pinnedTrailing);
+    const overflowable = sorted.filter((e) => !e.pinnedTrailing);
+    const nonStateful = overflowable.filter((e) => !e.stateful);
+    const overflowActive = overflowable.length >= OVERFLOW_MIN_TOTAL && nonStateful.length >= OVERFLOW_MIN_NON_STATEFUL;
+    if (!overflowActive) {
+        return { primary: overflowable, overflow: [], pinnedTrailing };
+    }
+    return {
+        primary: overflowable.filter((e) => e.stateful),
+        overflow: nonStateful,
+        pinnedTrailing,
+    };
+}
+/**
+ * Adapt a plain consumer/public `FeedAction` (id/label/icon/active/onClick,
+ * plus the optional stateful?/order?/pinnedTrailing? flags) into a bar entry,
+ * rendered as the standard icon button. `stateful` defaults to
+ * `active !== undefined` per the #6 spec (stateful toggles, meaning
+ * `active !== undefined`, stay primary).
+ */
+export function feedActionToEntry(action) {
+    return {
+        id: action.id,
+        label: action.label,
+        stateful: action.stateful ?? action.active !== undefined,
+        order: action.order,
+        pinnedTrailing: action.pinnedTrailing,
+        render: () => (_jsx(OverlayIconButton, { type: "button", "aria-label": action.label, "aria-pressed": action.active ?? undefined, title: action.label, "$active": action.active ?? false, onClick: action.onClick, children: action.icon }, action.id)),
+    };
+}
+// ---------------------------------------------------------------------------
+// The bar itself
+// ---------------------------------------------------------------------------
+const OVERFLOW_MENU_MAX_WIDTH = 200;
+const OVERFLOW_MENU_MAX_HEIGHT = 240;
+/**
+ * Shared top-right action row. Renders `leading`, then the partitioned
+ * entries: stateful ones always inline, non-stateful ones inline until the
+ * row is crowded enough to warrant a ⋮ overflow menu, then the pinned
+ * trailing (close/remove) entries: always last, to the right of the ⋮.
+ */
+export function FeedActionBar({ leading, entries, className }) {
+    const { primary, overflow, pinnedTrailing } = partitionActionBarEntries(entries);
+    const menuId = useId();
+    const overflowMenu = usePortalMenu({
+        maxWidth: OVERFLOW_MENU_MAX_WIDTH,
+        maxHeight: OVERFLOW_MENU_MAX_HEIGHT,
+        align: "end",
+    });
+    const closeOverflowMenu = overflowMenu.close;
+    if (!leading && entries.length === 0)
+        return null;
+    return (_jsxs(ActionBarRow, { className: className, children: [leading, primary.map((e) => (_jsx(Fragment, { children: e.render() }, e.id))), overflow.length > 0 && (_jsx(OverlayIconButton, { ref: overflowMenu.triggerRef, type: "button", "aria-label": "More actions", "aria-haspopup": "menu", "aria-expanded": overflowMenu.open, "aria-controls": menuId, title: "More actions", "$active": overflowMenu.open, onClick: overflowMenu.toggle, children: _jsx(MoreIcon, {}) })), overflow.length > 0 &&
+                overflowMenu.open &&
+                overflowMenu.position &&
+                createPortal(_jsx(OverflowMenu, { ref: overflowMenu.menuRef, id: menuId, role: "menu", "aria-label": "More actions", style: overflowMenu.position, children: overflow.map((e) => (
+                    // The wrapping row's onClick fires in the BUBBLE phase, after
+                    // the entry's own button click handler, so this closes the
+                    // menu once the action has actually fired rather than
+                    // pre-empting it.
+                    _jsxs(OverflowMenuItem, { onClick: closeOverflowMenu, children: [e.render(), _jsx(OverflowMenuItemLabel, { "aria-hidden": "true", children: e.label })] }, e.id))) }), document.body), pinnedTrailing.map((e) => (_jsx(Fragment, { children: e.render() }, e.id)))] }));
+}
+// ---------------------------------------------------------------------------
+// Icons
+// ---------------------------------------------------------------------------
+/* Overflow trigger: vertical ellipsis (three dots). */
+function MoreIcon() {
+    return (_jsxs("svg", { viewBox: "0 0 16 16", width: 14, height: 14, fill: "currentColor", stroke: "none", "aria-hidden": "true", children: [_jsx("circle", { cx: "8", cy: "3", r: "1.4" }), _jsx("circle", { cx: "8", cy: "8", r: "1.4" }), _jsx("circle", { cx: "8", cy: "13", r: "1.4" })] }));
+}
+// ---------------------------------------------------------------------------
+// Styled components
+// ---------------------------------------------------------------------------
+/** Icon-button shared by every action-bar entry (built-in or consumer). */
+export const OverlayIconButton = styled.button `
+  position: relative;
+  width: 24px;
+  height: 24px;
+  display: flex;
+  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-action-active, var(--kerbcast-accent, #00ff88))"
+    : "rgba(0, 0, 0, 0.5)"};
+  border: 1px solid
+    ${(p) => p.$active
+    ? "var(--kerbcast-action-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-action-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;
+  }
+`;
+/* Top-right cluster of overlay controls (custom actions + built-ins + overflow). */
+export const ActionBarRow = styled.div `
+  position: absolute;
+  top: 6px;
+  right: 8px;
+  z-index: 3;
+  display: flex;
+  align-items: center;
+  gap: 4px;
+  opacity: 0;
+  pointer-events: none;
+  transition: opacity 0.15s;
+
+  @media (prefers-reduced-motion: reduce) {
+    transition: none;
+  }
+`;
+/* The ⋮ overflow dropdown: same portal/anchor contract as CameraFeed's other
+   menus (fixed position set inline from the trigger rect) so tile clipping
+   cannot cut it off. */
+const OverflowMenu = styled.div `
+  position: fixed;
+  z-index: 1000;
+  min-width: 140px;
+  max-width: min(200px, calc(100vw - 16px));
+  max-height: min(40vh, 240px);
+  display: flex;
+  flex-direction: column;
+  padding: 4px;
+  gap: 2px;
+  background: rgba(0, 0, 0, 0.85);
+  border: 1px solid rgba(255, 255, 255, 0.3);
+  border-radius: 4px;
+  overflow-x: hidden;
+  overflow-y: auto;
+`;
+const OverflowMenuItem = styled.div `
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 2px 4px;
+  border-radius: 3px;
+
+  @media (hover: hover) {
+    &:hover {
+      background: rgba(255, 255, 255, 0.1);
+    }
+  }
+`;
+const OverflowMenuItemLabel = styled.span `
+  font-size: 11px;
+  letter-spacing: 0.04em;
+  color: #fff;
+  white-space: nowrap;
+`;

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 { CameraStreamHook, FeedAction } 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,111 @@
+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 { FeedActionBar, feedActionToEntry } from "./FeedActionBar";
+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;
+`;
+/*
+ * The shared FeedActionBar is hover-revealed by default (CameraFeed's larger
+ * frame fades it in on hover/focus). A tiny face tile has no such affordance,
+ * so this override keeps the original always-visible, corner-hugging look;
+ * layout/button styling (flex row, gap, the shared OverlayIconButton) still
+ * comes from FeedActionBar itself.
+ */
+const KerbalActionBarRow = styled(FeedActionBar) `
+  top: 4px;
+  right: 4px;
+  opacity: 1;
+  pointer-events: auto;
+`;
+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(KerbalActionBarRow, { entries: actions.map(feedActionToEntry) })), children && _jsx(OverlayLayer, { children: children })] }));
+}

package/dist/RecordingsTray.d.ts

@@ -0,0 +1,37 @@
+/**
+ * RecordingsTray: a presentational drawer over the client-side recordings
+ * store (`useRecordings()`). Lists finished single clips and grouped SETS,
+ * with a play/preview, a download, and a discard per clip; a group also gets
+ * a download-all + a discard-set. Recording is client-local and in-memory (no
+ * sidecar, no server state), so this is where an operator saves a clip before
+ * a page reload discards it. The tray shows a quiet reminder of that.
+ *
+ * Deliberately dumb: it owns no recording logic, only formatting and the
+ * per-clip object-URL lifecycle (create on first render, revoke on discard or
+ * unmount). Starting/stopping recordings is CameraFeed's REC control (or a
+ * host's own REC+ grouped flow); this component only ever reads the store and
+ * calls its discard/discardGroup actions.
+ *
+ * Every `RecordingHandle` (standalone or a grouped member) carries its own
+ * `flightId`, so camera names come straight off the clip, with no dependency
+ * on the store's transient `active` list. That matters because the tray
+ * commonly mounts after a recording has already finished (its `active` entry
+ * long gone by then). A host supplies the flightId -> label step via
+ * `cameraLabel` (e.g. `buildCameraLabeler(useKerbcastCameras())`, the same
+ * labeller CameraFeed uses) so this stays decoupled from any particular
+ * camera registry; omit it for a plain "Camera <flightId>" fallback.
+ */
+export interface RecordingsTrayProps {
+    /**
+     * Resolve a flightId to a display label for a clip's camera name. Omit for
+     * a plain "Camera <flightId>" fallback.
+     */
+    cameraLabel?: (flightId: number) => string;
+    /** Forwarded to the root panel; lets a host lay out/size the tray. */
+    className?: string;
+}
+/**
+ * The shared drawer. Requires a `KerbcastProvider` ancestor (it calls
+ * `useRecordings()` directly, same requirement as `CameraFeed`).
+ */
+export declare function RecordingsTray({ cameraLabel, className }: RecordingsTrayProps): import("react").JSX.Element;