@ksp-gonogo/kerbcast-react 1.6.3 → 1.8.0

package/dist/RecordingsTray.js

@@ -0,0 +1,279 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useCallback, useEffect, useMemo, useReducer, useRef } from "react";
+import styled from "styled-components";
+import { useRecordings } from "./hooks/useRecordings";
+/**
+ * The shared drawer. Requires a `KerbcastProvider` ancestor (it calls
+ * `useRecordings()` directly, same requirement as `CameraFeed`).
+ */
+export function RecordingsTray({ cameraLabel, className }) {
+    const store = useRecordings();
+    const labelFor = useCallback((flightId) => (cameraLabel ? cameraLabel(flightId) : `Camera ${flightId}`), [cameraLabel]);
+    const allClips = useMemo(() => [...store.recordings, ...store.groups.flatMap((g) => g.recordings)], [store.recordings, store.groups]);
+    const objectUrls = useClipObjectUrls(allClips);
+    const hasAny = store.recordings.length > 0 || store.groups.length > 0;
+    return (_jsx(Tray, { className: className, "aria-label": "Recordings", children: !hasAny ? (_jsx(Empty, { children: "No recordings yet. Press REC on a feed to start one." })) : (_jsxs(_Fragment, { children: [_jsx(Notice, { children: "Unsaved clips are lost on reload. Download what you want to keep." }), _jsxs(ClipList, { children: [store.recordings.map((rec) => (_jsx(ClipRow, { rec: rec, label: labelFor(rec.flightId), url: objectUrls.get(rec.recordingId), onDiscard: () => store.discard(rec.recordingId) }, rec.recordingId))), store.groups.map((group) => (_jsx(GroupItem, { group: group, labelFor: labelFor, objectUrls: objectUrls, onDiscardGroup: () => store.discardGroup(group.groupId) }, group.groupId)))] })] })) }));
+}
+function ClipRow({ rec, label, url, onDiscard }) {
+    const utRange = rec.utStart != null && rec.utEnd != null
+        ? `${formatUt(rec.utStart)} - ${formatUt(rec.utEnd)}`
+        : "no UT (out of flight)";
+    return (_jsxs(Clip, { children: [url ? (_jsx(ClipPreview, { controls: true, preload: "metadata", src: url, "aria-label": `Preview: ${label}` })) : (_jsx(ClipPreviewPlaceholder, { "aria-hidden": "true" })), _jsxs(ClipMeta, { children: [_jsx(ClipName, { children: label }), _jsx(ClipDetail, { children: utRange }), _jsxs(ClipDetail, { children: [formatDuration(rec.durationMs), " \u00B7 ", formatBytes(rec.byteSize)] })] }), _jsxs(ClipActions, { children: [url && (_jsx(TrayLink, { href: url, download: clipFileName(rec, label), children: "Download" })), onDiscard && (_jsx(TrayButton, { type: "button", "$danger": true, onClick: onDiscard, children: "Discard" }))] })] }));
+}
+function GroupItem({ group, labelFor, objectUrls, onDiscardGroup }) {
+    return (_jsxs(GroupCard, { "aria-label": `Grouped recording, ${group.recordings.length} feeds`, children: [_jsxs(GroupHeader, { children: [_jsxs(GroupHeaderText, { children: [_jsxs(GroupTitle, { children: ["Grouped recording \u00B7 ", group.recordings.length, " feeds"] }), group.commonUtWindow && (_jsxs(GroupMeta, { children: ["common UT ", formatUt(group.commonUtWindow[0]), " -", " ", formatUt(group.commonUtWindow[1])] }))] }), _jsxs(GroupActions, { children: [_jsx(TrayButton, { type: "button", onClick: () => downloadAll(group.recordings, objectUrls, labelFor), children: "Download all" }), _jsx(TrayButton, { type: "button", "$danger": true, onClick: onDiscardGroup, children: "Discard set" })] })] }), group.recordings.map((rec) => (_jsx(ClipRow, { rec: rec, label: labelFor(rec.flightId), url: objectUrls.get(rec.recordingId) }, rec.recordingId)))] }));
+}
+// ---------------------------------------------------------------------------
+// Object-URL lifecycle
+// ---------------------------------------------------------------------------
+/**
+ * Creates one `URL.createObjectURL` per clip and revokes it once the clip
+ * disappears from `clips` (discarded) or on unmount. The map itself lives in
+ * a ref (not state) so the unmount cleanup always sees every URL ever
+ * created, even ones added after the effect that captured it first ran; a
+ * cheap reducer bump re-renders the caller whenever the map actually changes.
+ */
+function useClipObjectUrls(clips) {
+    const mapRef = useRef(new Map());
+    const [, bump] = useReducer((c) => c + 1, 0);
+    useEffect(() => {
+        const map = mapRef.current;
+        const liveIds = new Set(clips.map((c) => c.recordingId));
+        let changed = false;
+        for (const [id, url] of map) {
+            if (!liveIds.has(id)) {
+                URL.revokeObjectURL(url);
+                map.delete(id);
+                changed = true;
+            }
+        }
+        for (const clip of clips) {
+            if (!map.has(clip.recordingId)) {
+                map.set(clip.recordingId, URL.createObjectURL(clip.blob));
+                changed = true;
+            }
+        }
+        if (changed)
+            bump();
+    }, [clips]);
+    useEffect(() => {
+        const map = mapRef.current;
+        return () => {
+            for (const url of map.values())
+                URL.revokeObjectURL(url);
+            map.clear();
+        };
+    }, []);
+    return mapRef.current;
+}
+// ---------------------------------------------------------------------------
+// Formatting + download helpers
+// ---------------------------------------------------------------------------
+/* KSP mission time (seconds); the tray shows the raw value rather than the
+   in-game calendar breakdown, which needs the epoch this component doesn't have. */
+function formatUt(ut) {
+    return `T+${Math.round(ut)}s`;
+}
+function formatDuration(ms) {
+    const totalSeconds = Math.max(0, Math.round(ms / 1000));
+    const hours = Math.floor(totalSeconds / 3600);
+    const minutes = Math.floor((totalSeconds % 3600) / 60);
+    const seconds = totalSeconds % 60;
+    const mm = hours > 0 ? minutes.toString().padStart(2, "0") : minutes.toString();
+    const ss = seconds.toString().padStart(2, "0");
+    return hours > 0 ? `${hours}:${mm}:${ss}` : `${mm}:${ss}`;
+}
+function formatBytes(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    const kb = bytes / 1024;
+    if (kb < 1024)
+        return `${kb.toFixed(1)} KB`;
+    return `${(kb / 1024).toFixed(1)} MB`;
+}
+function clipFileName(rec, label) {
+    const ext = /mp4/i.test(rec.mimeType) ? "mp4" : "webm";
+    const safeLabel = label.replace(/[^a-z0-9]+/gi, "-").replace(/^-+|-+$/g, "") || "clip";
+    return `${safeLabel}-${rec.recordingId}.${ext}`;
+}
+/* A set's "download all": one <a> per member, clicked in turn. Each still
+   downloads under its own clip filename (no zipping); good enough for an
+   operator who wants every feed of the moment without N separate clicks. */
+function downloadAll(members, urls, labelFor) {
+    for (const member of members) {
+        const url = urls.get(member.recordingId);
+        if (!url)
+            continue;
+        const a = document.createElement("a");
+        a.href = url;
+        a.download = clipFileName(member, labelFor(member.flightId));
+        document.body.appendChild(a);
+        a.click();
+        a.remove();
+    }
+}
+// ---------------------------------------------------------------------------
+// Styled components
+// ---------------------------------------------------------------------------
+const Tray = styled.div `
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  min-width: 260px;
+  max-height: min(70vh, 520px);
+  overflow-y: auto;
+  overflow-x: hidden;
+  padding: 10px;
+  background: var(--kerbcast-tray-bg, rgba(0, 0, 0, 0.85));
+  border: 1px solid var(--kerbcast-tray-border, rgba(255, 255, 255, 0.3));
+  border-radius: 6px;
+  color: var(--kerbcast-tray-text, #fff);
+  font-size: 12px;
+`;
+const Empty = styled.div `
+  padding: 16px 8px;
+  text-align: center;
+  color: var(--kerbcast-tray-text-muted, rgba(255, 255, 255, 0.65));
+  font-style: italic;
+`;
+const Notice = styled.div `
+  padding: 2px 2px 4px;
+  color: var(--kerbcast-tray-text-muted, rgba(255, 255, 255, 0.55));
+  font-size: 10.5px;
+  font-style: italic;
+  letter-spacing: 0.01em;
+`;
+const ClipList = styled.div `
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+`;
+const Clip = styled.div `
+  display: flex;
+  flex-wrap: wrap;
+  align-items: flex-start;
+  gap: 8px;
+  padding: 6px 0;
+  border-top: 1px solid var(--kerbcast-tray-border-subtle, rgba(255, 255, 255, 0.12));
+
+  &:first-child {
+    border-top: none;
+    padding-top: 0;
+  }
+`;
+const ClipPreview = styled.video `
+  width: 120px;
+  aspect-ratio: 16 / 9;
+  background: #000;
+  border-radius: 4px;
+  flex-shrink: 0;
+  object-fit: cover;
+`;
+const ClipPreviewPlaceholder = styled.div `
+  width: 120px;
+  aspect-ratio: 16 / 9;
+  background: rgba(255, 255, 255, 0.05);
+  border-radius: 4px;
+  flex-shrink: 0;
+`;
+const ClipMeta = styled.div `
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+  flex: 1 1 140px;
+  min-width: 0;
+`;
+const ClipName = styled.div `
+  font-weight: 600;
+  letter-spacing: 0.03em;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+`;
+const ClipDetail = styled.div `
+  color: var(--kerbcast-tray-text-muted, rgba(255, 255, 255, 0.65));
+  font-size: 11px;
+`;
+const ClipActions = styled.div `
+  display: flex;
+  flex-direction: column;
+  align-items: flex-start;
+  gap: 4px;
+  flex-shrink: 0;
+`;
+const trayButtonBase = `
+  padding: 3px 8px;
+  border-radius: 3px;
+  font-size: 11px;
+  letter-spacing: 0.03em;
+  text-decoration: none;
+  cursor: pointer;
+  white-space: nowrap;
+`;
+const TrayButton = styled.button `
+  ${trayButtonBase}
+  background: transparent;
+  border: 1px solid
+    ${(p) => p.$danger
+    ? "var(--kerbcast-tray-danger, #ff6b5e)"
+    : "var(--kerbcast-accent, #00ff88)"};
+  color: ${(p) => (p.$danger ? "var(--kerbcast-tray-danger, #ff6b5e)" : "var(--kerbcast-accent, #00ff88)")};
+
+  @media (hover: hover) {
+    &:hover {
+      background: ${(p) => p.$danger ? "rgba(255, 107, 94, 0.15)" : "var(--kerbcast-accent-wash, rgba(0, 255, 136, 0.15))"};
+    }
+  }
+`;
+const TrayLink = styled.a `
+  ${trayButtonBase}
+  display: inline-block;
+  background: transparent;
+  border: 1px solid var(--kerbcast-accent, #00ff88);
+  color: var(--kerbcast-accent, #00ff88);
+
+  @media (hover: hover) {
+    &:hover {
+      background: var(--kerbcast-accent-wash, rgba(0, 255, 136, 0.15));
+    }
+  }
+`;
+const GroupCard = styled.div `
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  padding: 8px;
+  background: var(--kerbcast-tray-surface-raised, rgba(255, 255, 255, 0.04));
+  border: 1px solid var(--kerbcast-tray-border-subtle, rgba(255, 255, 255, 0.12));
+  border-left: 2px solid var(--kerbcast-accent, #00ff88);
+  border-radius: 4px;
+
+  ${Clip} {
+    border-top-color: var(--kerbcast-tray-border-subtle, rgba(255, 255, 255, 0.12));
+  }
+`;
+const GroupHeader = styled.div `
+  display: flex;
+  flex-wrap: wrap;
+  align-items: flex-start;
+  justify-content: space-between;
+  gap: 8px;
+`;
+const GroupHeaderText = styled.div `
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+`;
+const GroupTitle = styled.div `
+  font-weight: 600;
+  letter-spacing: 0.03em;
+`;
+const GroupMeta = styled.div `
+  color: var(--kerbcast-tray-text-muted, rgba(255, 255, 255, 0.65));
+  font-size: 11px;
+`;
+const GroupActions = styled.div `
+  display: flex;
+  gap: 6px;
+  flex-shrink: 0;
+`;

package/dist/context.d.ts

@@ -11,17 +11,38 @@ export interface KerbcastSubscriptions {
 }
 /** Build the default refcounted subscriptions implementation for a client. */
 export declare function createClientSubscriptions(client: KerbcastClient): KerbcastSubscriptions;
+/**
+ * Collects each mounted feed's self-measured display size and drives the
+ * client's per-consumer `reportDisplaySize`. Multiple feeds can show the SAME
+ * camera at once (e.g. a tiny avatar and a spotlight of the same kerbal); the
+ * sidecar keys the auto-resolution max per CONSUMER, so those would clobber
+ * each other last-writer-wins. This collapses them at the client edge: it
+ * keeps the MAX display size across every mounted reporter for a flightId and
+ * sends one report per max-change. Co-located with the subscription refcount
+ * (same per-flightId lifetime) so one object owns everything this client is
+ * doing with camera N.
+ */
+export interface KerbcastDisplaySizes {
+    /** Register/update a reporter's measured size for a camera. */
+    report(flightId: number, instanceId: string, width: number, height: number): void;
+    /** Deregister a reporter (on unmount / flightId change). */
+    clear(flightId: number, instanceId: string): void;
+}
+/** Build the default per-flightId MAX display-size registry for a client. */
+export declare function createClientDisplaySizes(client: KerbcastClient): KerbcastDisplaySizes;
 export interface KerbcastProviderProps {
     client: KerbcastClient;
     /** Override the subscription manager. Defaults to a refcounted per-client impl. */
     subscriptions?: KerbcastSubscriptions;
+    /** Override the display-size registry. Defaults to a per-flightId MAX impl. */
+    displaySizes?: KerbcastDisplaySizes;
     children: ReactNode;
 }
 /**
  * Provide a `KerbcastClient` (and optional subscriptions override) to the
  * component subtree. Hooks and `CameraFeed` read both from this context.
  */
-export declare function KerbcastProvider({ client, subscriptions: subscriptionsProp, children, }: KerbcastProviderProps): React.JSX.Element;
+export declare function KerbcastProvider({ client, subscriptions: subscriptionsProp, displaySizes: displaySizesProp, children, }: KerbcastProviderProps): React.JSX.Element;
 /**
  * Return the `KerbcastClient` from the nearest `KerbcastProvider`.
  * Throws if called outside a provider.
@@ -32,3 +53,8 @@ export declare function useKerbcastClient(): KerbcastClient;
  * Throws if called outside a provider.
  */
 export declare function useKerbcastSubscriptions(): KerbcastSubscriptions;
+/**
+ * Return the `KerbcastDisplaySizes` registry from the nearest
+ * `KerbcastProvider`. Throws if called outside a provider.
+ */
+export declare function useKerbcastDisplaySizes(): KerbcastDisplaySizes;

package/dist/context.js

@@ -23,24 +23,79 @@ export function createClientSubscriptions(client) {
         },
     };
 }
+/** Build the default per-flightId MAX display-size registry for a client. */
+export function createClientDisplaySizes(client) {
+    // flightId -> (instanceId -> measured size)
+    const perCamera = new Map();
+    // Last size reported to the sidecar per flightId, so we send only on change.
+    const lastSent = new Map();
+    function recompute(flightId) {
+        const instances = perCamera.get(flightId);
+        if (!instances || instances.size === 0) {
+            // No reporters left. Drop bookkeeping and send nothing: the subscription
+            // release (unsubscribe -> sidecar remove_track -> forget_display_size)
+            // clears the sidecar side. Sending a spurious size here would fight it.
+            perCamera.delete(flightId);
+            lastSent.delete(flightId);
+            return;
+        }
+        let maxW = 0;
+        let maxH = 0;
+        for (const { w, h } of instances.values()) {
+            if (w > maxW)
+                maxW = w;
+            if (h > maxH)
+                maxH = h;
+        }
+        const prev = lastSent.get(flightId);
+        if (prev && prev.w === maxW && prev.h === maxH)
+            return;
+        lastSent.set(flightId, { w: maxW, h: maxH });
+        client.reportDisplaySize(flightId, maxW, maxH).catch(() => { });
+    }
+    return {
+        report(flightId, instanceId, width, height) {
+            let instances = perCamera.get(flightId);
+            if (!instances) {
+                instances = new Map();
+                perCamera.set(flightId, instances);
+            }
+            instances.set(instanceId, { w: width, h: height });
+            recompute(flightId);
+        },
+        clear(flightId, instanceId) {
+            const instances = perCamera.get(flightId);
+            if (!instances)
+                return;
+            instances.delete(instanceId);
+            recompute(flightId);
+        },
+    };
+}
 const KerbcastContext = createContext(null);
 /**
  * Provide a `KerbcastClient` (and optional subscriptions override) to the
  * component subtree. Hooks and `CameraFeed` read both from this context.
  */
-export function KerbcastProvider({ client, subscriptions: subscriptionsProp, children, }) {
+export function KerbcastProvider({ client, subscriptions: subscriptionsProp, displaySizes: displaySizesProp, children, }) {
     // Create default subscriptions once per client. A ref so the object is
     // stable across renders even if the parent re-renders.
     const defaultSubsRef = useRef(null);
     if (defaultSubsRef.current === null) {
         defaultSubsRef.current = createClientSubscriptions(client);
     }
+    // Same for the display-size registry: one per client, stable across renders.
+    const defaultSizesRef = useRef(null);
+    if (defaultSizesRef.current === null) {
+        defaultSizesRef.current = createClientDisplaySizes(client);
+    }
     const value = useMemo(() => ({
         client,
         subscriptions: subscriptionsProp ?? defaultSubsRef.current,
+        displaySizes: displaySizesProp ?? defaultSizesRef.current,
     }), 
     // eslint-disable-next-line react-hooks/exhaustive-deps
-    [client, subscriptionsProp]);
+    [client, subscriptionsProp, displaySizesProp]);
     return (_jsx(KerbcastContext.Provider, { value: value, children: children }));
 }
 // ---------------------------------------------------------------------------
@@ -68,3 +123,14 @@ export function useKerbcastSubscriptions() {
     }
     return ctx.subscriptions;
 }
+/**
+ * Return the `KerbcastDisplaySizes` registry from the nearest
+ * `KerbcastProvider`. Throws if called outside a provider.
+ */
+export function useKerbcastDisplaySizes() {
+    const ctx = useContext(KerbcastContext);
+    if (!ctx) {
+        throw new Error("useKerbcastDisplaySizes must be used inside a KerbcastProvider");
+    }
+    return ctx.displaySizes;
+}

package/dist/hooks/useRecordings.d.ts

@@ -0,0 +1,35 @@
+import type { ActiveRecordingInfo, GroupedRecordingHandle, RecordingHandle, StartRecordingOptions, StopGroupedRecordingOptions } from "@ksp-gonogo/kerbcast";
+export type { ActiveRecordingInfo };
+/**
+ * Reactive recordings store over the SDK's `client.recording` controller.
+ *
+ * Holds the in-session, in-memory clips: standalone singles in `recordings`,
+ * synchronised sets in `groups`, and the still-running ones in `active`. This
+ * is the headless data layer the recordings tray + REC controls sit on; it
+ * owns no chrome. All state is in-memory, so a page reload discards it (the UI
+ * guards navigation while unsaved clips exist).
+ */
+export interface RecordingsStore {
+    /** Finished standalone (non-grouped) clips, newest last. */
+    recordings: RecordingHandle[];
+    /** Finished grouped sets, newest last. */
+    groups: GroupedRecordingHandle[];
+    /** Recordings currently in progress (single + grouped members). */
+    active: ActiveRecordingInfo[];
+    /** Whether a feed currently has a recording in progress. */
+    isRecording(flightId: number): boolean;
+    start(flightId: number, opts?: StartRecordingOptions): string;
+    stop(recordingId: string): Promise<RecordingHandle>;
+    startGroup(flightIds: number[], opts?: StartRecordingOptions): string;
+    stopGroup(groupId: string, opts?: StopGroupedRecordingOptions): Promise<GroupedRecordingHandle>;
+    discard(recordingId: string): void;
+    discardGroup(groupId: string): void;
+}
+/**
+ * Subscribe a component to the recording store for the context client. The
+ * controller itself is the single source of truth for every call site;
+ * `useSyncExternalStore` re-renders this component whenever the controller's
+ * snapshot changes, no matter which call site (or which component) drove the
+ * change.
+ */
+export declare function useRecordings(): RecordingsStore;

package/dist/hooks/useRecordings.js

@@ -0,0 +1,33 @@
+import { useCallback, useSyncExternalStore } from "react";
+import { useKerbcastClient } from "../context";
+/**
+ * Subscribe a component to the recording store for the context client. The
+ * controller itself is the single source of truth for every call site;
+ * `useSyncExternalStore` re-renders this component whenever the controller's
+ * snapshot changes, no matter which call site (or which component) drove the
+ * change.
+ */
+export function useRecordings() {
+    const client = useKerbcastClient();
+    const controller = client.recording;
+    const snapshot = useSyncExternalStore(controller.subscribe, controller.getSnapshot);
+    const start = useCallback((flightId, opts) => controller.startRecording(flightId, opts), [controller]);
+    const stop = useCallback((recordingId) => controller.stopRecording(recordingId), [controller]);
+    const startGroup = useCallback((flightIds, opts) => controller.startGroupedRecording(flightIds, opts).groupId, [controller]);
+    const stopGroup = useCallback((groupId, opts) => controller.stopGroupedRecording(groupId, opts), [controller]);
+    const discard = useCallback((recordingId) => controller.discardRecording(recordingId), [controller]);
+    const discardGroup = useCallback((groupId) => controller.discardGroupedRecording(groupId), [controller]);
+    const isRecording = useCallback((flightId) => controller.isRecording(flightId), [controller]);
+    return {
+        recordings: snapshot.recordings,
+        groups: snapshot.groups,
+        active: snapshot.active,
+        isRecording,
+        start,
+        stop,
+        startGroup,
+        stopGroup,
+        discard,
+        discardGroup,
+    };
+}

package/dist/hooks/useReportDisplaySize.d.ts

@@ -0,0 +1,23 @@
+export interface ReportDisplaySizeOptions {
+    /**
+     * Report while mounted. Default true. Set false for a fixed-resolution feed
+     * that should not drive auto-resolution. This is a RESOLUTION concern only,
+     * independent of whether the feed shows its action UI.
+     */
+    enabled?: boolean;
+    /**
+     * Report a square (side x side, the min edge) rather than the raw w x h.
+     * Face cams are square; part cams are not.
+     */
+    square?: boolean;
+}
+/**
+ * Self-measure a feed element and drive the client's per-consumer
+ * `reportDisplaySize` (via the context display-size registry, which collapses
+ * multiple feeds of the same camera to one MAX report). Attach `ref` to the
+ * element whose rendered pixel box is the display size. Reporting follows the
+ * mount lifecycle: on unmount / `flightId` change / `enabled` flip it
+ * deregisters, and the sidecar's clear-on-departure (unsubscribe) does the
+ * server-side clear.
+ */
+export declare function useReportDisplaySize(flightId: number | null, ref: React.RefObject<Element | null>, { enabled, square }?: ReportDisplaySizeOptions): void;

package/dist/hooks/useReportDisplaySize.js

@@ -0,0 +1,71 @@
+import { useEffect, useId } from "react";
+import { useKerbcastDisplaySizes } from "../context";
+/*
+ * Debounce + bucket for self-measured display-size reporting. The first
+ * measurement after mount reports promptly (so a feed never sits at a stale
+ * resolution until it is resized); later churn is debounced. Sizes are ceiled
+ * to a BUCKET_PX multiple: that meets-the-minimum-need (never under-serve),
+ * yields an even value (H.264-friendly), and gives a material-change threshold
+ * so a feed re-reports only when a resize crosses a bucket boundary.
+ */
+const DEBOUNCE_MS = 200;
+const BUCKET_PX = 16;
+function bucket(px) {
+    const b = Math.ceil(px / BUCKET_PX) * BUCKET_PX;
+    return b < BUCKET_PX ? BUCKET_PX : b;
+}
+/**
+ * Self-measure a feed element and drive the client's per-consumer
+ * `reportDisplaySize` (via the context display-size registry, which collapses
+ * multiple feeds of the same camera to one MAX report). Attach `ref` to the
+ * element whose rendered pixel box is the display size. Reporting follows the
+ * mount lifecycle: on unmount / `flightId` change / `enabled` flip it
+ * deregisters, and the sidecar's clear-on-departure (unsubscribe) does the
+ * server-side clear.
+ */
+export function useReportDisplaySize(flightId, ref, { enabled = true, square = false } = {}) {
+    const displaySizes = useKerbcastDisplaySizes();
+    const instanceId = useId();
+    useEffect(() => {
+        if (flightId === null || !enabled)
+            return;
+        const el = ref.current;
+        if (!el)
+            return;
+        let timer = null;
+        let lastW = -1;
+        let lastH = -1;
+        let firstReported = false;
+        const report = (width, height) => {
+            const side = square ? Math.min(width, height) : 0;
+            const bw = bucket(square ? side : width);
+            const bh = bucket(square ? side : height);
+            if (bw === lastW && bh === lastH)
+                return;
+            lastW = bw;
+            lastH = bh;
+            displaySizes.report(flightId, instanceId, bw, bh);
+        };
+        const observer = new ResizeObserver((entries) => {
+            const entry = entries[0];
+            if (!entry)
+                return;
+            const { width, height } = entry.contentRect;
+            if (!firstReported) {
+                firstReported = true;
+                report(width, height);
+                return;
+            }
+            if (timer !== null)
+                clearTimeout(timer);
+            timer = setTimeout(() => report(width, height), DEBOUNCE_MS);
+        });
+        observer.observe(el);
+        return () => {
+            observer.disconnect();
+            if (timer !== null)
+                clearTimeout(timer);
+            displaySizes.clear(flightId, instanceId);
+        };
+    }, [displaySizes, flightId, ref, enabled, square, instanceId]);
+}

package/dist/index.d.ts

@@ -5,12 +5,16 @@
  * is a peer to @ksp-gonogo/kerbcast (the core SDK) and requires React 18+
  * and styled-components 6+ as peer dependencies.
  */
-export { KerbcastProvider, createClientSubscriptions, useKerbcastClient, useKerbcastSubscriptions, } from "./context";
-export type { KerbcastProviderProps, KerbcastSubscriptions } from "./context";
+export { KerbcastProvider, createClientSubscriptions, createClientDisplaySizes, useKerbcastClient, useKerbcastSubscriptions, useKerbcastDisplaySizes, } from "./context";
+export type { KerbcastProviderProps, KerbcastSubscriptions, KerbcastDisplaySizes, } from "./context";
 export { useKerbcastCameras } from "./hooks/useKerbcastCameras";
 export { useKerbcastStream } from "./hooks/useKerbcastStream";
 export { useKerbcastClock } from "./hooks/useKerbcastClock";
 export { useKerbcastInFlight } from "./hooks/useKerbcastInFlight";
+export { useReportDisplaySize } from "./hooks/useReportDisplaySize";
+export { useRecordings } from "./hooks/useRecordings";
+export type { RecordingsStore, ActiveRecordingInfo } from "./hooks/useRecordings";
+export { nowMs, formatElapsed } from "./timing";
 export { StandbyIcon } from "./StandbyIcon";
 export { buildCameraLabeler } from "./cameraLabels";
 export type { LabelableCamera } from "./cameraLabels";
@@ -18,3 +22,9 @@ export { getCameraLifecycle, isCameraDestroyed } from "./lifecycle";
 export type { CameraLifecycle } from "./lifecycle";
 export { CameraFeed } from "./CameraFeed";
 export type { CameraFeedHandle, CameraFeedProps, CameraStreamHook, FeedAction, } from "./CameraFeed";
+export { FeedActionBar } from "./FeedActionBar";
+export type { FeedActionBarEntry } from "./FeedActionBar";
+export { KerbalFaceFeed } from "./KerbalFaceFeed";
+export type { KerbalFaceFeedProps, KerbalFeedState } from "./KerbalFaceFeed";
+export { RecordingsTray } from "./RecordingsTray";
+export type { RecordingsTrayProps } from "./RecordingsTray";

package/dist/index.js

@@ -6,12 +6,16 @@
  * and styled-components 6+ as peer dependencies.
  */
 // Context and provider
-export { KerbcastProvider, createClientSubscriptions, useKerbcastClient, useKerbcastSubscriptions, } from "./context";
+export { KerbcastProvider, createClientSubscriptions, createClientDisplaySizes, useKerbcastClient, useKerbcastSubscriptions, useKerbcastDisplaySizes, } from "./context";
 // Hooks
 export { useKerbcastCameras } from "./hooks/useKerbcastCameras";
 export { useKerbcastStream } from "./hooks/useKerbcastStream";
 export { useKerbcastClock } from "./hooks/useKerbcastClock";
 export { useKerbcastInFlight } from "./hooks/useKerbcastInFlight";
+export { useReportDisplaySize } from "./hooks/useReportDisplaySize";
+export { useRecordings } from "./hooks/useRecordings";
+// Shared elapsed-timer helpers (REC badges, RecGroupBar's toolbar)
+export { nowMs, formatElapsed } from "./timing";
 // Shared standby glyph (used by CameraFeed + downstream dashboards)
 export { StandbyIcon } from "./StandbyIcon";
 // Camera label utilities
@@ -20,3 +24,11 @@ export { buildCameraLabeler } from "./cameraLabels";
 export { getCameraLifecycle, isCameraDestroyed } from "./lifecycle";
 // CameraFeed component
 export { CameraFeed } from "./CameraFeed";
+// FeedActionBar: the shared action row (tracking, fullscreen, PiP, quality,
+// close, REC) both CameraFeed and KerbalFaceFeed render, with the issue-#6
+// overflow (⋮) engine.
+export { FeedActionBar } from "./FeedActionBar";
+// KerbalFaceFeed — shared single-kerbal-face primitive
+export { KerbalFaceFeed } from "./KerbalFaceFeed";
+// RecordingsTray: a presentational drawer over the recordings store
+export { RecordingsTray } from "./RecordingsTray";

package/dist/menuPositioning.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Shared geometry + behaviour for a dropdown portaled to document.body.
+ * Used by CameraFeed's camera / quality / tracking menus and by
+ * FeedActionBar's overflow menu, so the anchoring, dismissal, and Escape
+ * handling live in exactly one place.
+ */
+export interface MenuAnchor {
+    maxWidth: number;
+    maxHeight: number;
+    align: "start" | "end";
+}
+export declare function computeMenuPosition(trigger: HTMLElement, anchor: MenuAnchor): React.CSSProperties;
+export declare function usePortalMenu({ maxWidth, maxHeight, align }: MenuAnchor): {
+    open: boolean;
+    toggle: () => void;
+    close: () => void;
+    position: import("react").CSSProperties | null;
+    menuRef: import("react").RefObject<HTMLDivElement>;
+    triggerRef: import("react").RefObject<HTMLButtonElement>;
+};