@camstack/ui-library 1.2.185 → 1.2.187

package/dist/composites/camera-stream-player.d.ts

@@ -2,6 +2,7 @@ import { ReactNode } from 'react';
 import { CamProfile, WebrtcSessionDebug } from '@camstack/types';
 import { ReconnectAction } from './reconnect-schedule';
 import { AdaptiveHintsReport } from './adaptive-downlink';
+import { StreamDebugSample } from './stream-debug/webrtc-debug-stats.js';
 type WebkitPresentationMode = 'inline' | 'picture-in-picture' | 'fullscreen';
 declare global {
     interface HTMLVideoElement {
@@ -116,6 +117,20 @@ export interface CameraStreamPlayerProps {
     /** Show a live client-side WebRTC stats overlay (bitrate/fps/res/RTT),
      *  computed from the PeerConnection's getStats(). Default: false. */
     showStats?: boolean;
+    /**
+     * Report the same measurements to a HOST instead of (or as well as) drawing
+     * them.
+     *
+     * The overlay is a DOM layer, and in the native app the player lives inside a
+     * WebView whose touches the RN gesture layer owns — so the panel that opens
+     * on a tap can never be opened there. The numbers still have to reach the
+     * operator, so they travel out to whoever mounted the player and are rendered
+     * in its own UI, next to the battery and link details.
+     *
+     * Wiring this turns the two 1 Hz polls on by itself: a host that asked for
+     * samples wants them whether or not the in-picture overlay is drawn.
+     */
+    onDebugStats?: (sample: StreamDebugSample) => void;
     /** When provided, polls inbound-video getStats() every 5 s during playback
      *  and reports per-window health metrics (frames received/decoded/dropped,
      *  freezes, jitter, playback-clock advance). The embed forwards these over the
@@ -287,5 +302,5 @@ export interface CameraStreamPlayerProps {
      */
     onVideoElement?: (el: HTMLVideoElement | null) => void;
 }
-export declare function CameraStreamPlayer({ serverUrl, streamKey, label, autoPlay, muted: initialMuted, showControls, showStats, onPlaybackStats, onClientNetworkSample, onConnectTiming, className, onStateChange, onError, onReconnectAttempt, overlay, createSession, sendAnswer, handleOffer, getIceServers, addIceCandidate, getIceCandidates, closeSession, getSessionState, getSessionDebug, reoffer, posterUrl, hintsOverride, onAdaptiveHints, reconnectSignal, onControlChannel, onVideoElement, }: CameraStreamPlayerProps): import("react").JSX.Element;
+export declare function CameraStreamPlayer({ serverUrl, streamKey, label, autoPlay, muted: initialMuted, showControls, showStats, onDebugStats, onPlaybackStats, onClientNetworkSample, onConnectTiming, className, onStateChange, onError, onReconnectAttempt, overlay, createSession, sendAnswer, handleOffer, getIceServers, addIceCandidate, getIceCandidates, closeSession, getSessionState, getSessionDebug, reoffer, posterUrl, hintsOverride, onAdaptiveHints, reconnectSignal, onControlChannel, onVideoElement, }: CameraStreamPlayerProps): import("react").JSX.Element;
 export {};

package/dist/composites/index.d.ts

@@ -20,7 +20,7 @@ export { CameraStreamPlayer } from './camera-stream-player';
 export { StreamDebugOverlay } from './stream-debug/stream-debug-overlay';
 export type { StreamDebugOverlayProps } from './stream-debug/stream-debug-overlay';
 export { deriveWebrtcDebugStats, freezeVerdict, } from './stream-debug/webrtc-debug-stats';
-export type { DeriveWebrtcDebugStatsInput, FreezeVerdict, FreezeVerdictKind, ResolutionMark, WebrtcDebugStats, WebrtcDebugWindow, } from './stream-debug/webrtc-debug-stats';
+export type { DeriveWebrtcDebugStatsInput, FreezeVerdict, FreezeVerdictKind, ResolutionMark, StreamDebugSample, WebrtcDebugStats, WebrtcDebugWindow, } from './stream-debug/webrtc-debug-stats';
 export { AutotrackSection } from './cap-settings/AutotrackSection';
 export { ConsumablesPanel } from './cap-settings/ConsumablesPanel';
 export type { CapSettingsComponentProps } from './cap-settings/index';

package/dist/composites/stream-debug/webrtc-debug-stats.d.ts

@@ -1,18 +1,4 @@
-/**
- * Pure derivation of the stream-debug overlay's CLIENT half from one
- * `RTCPeerConnection.getStats()` report.
- *
- * Why it is pure: this is the surface an operator reads while a camera is
- * frozen, and the numbers it shows decide whether the stall is in the
- * transport or in the decoder. A derivation that can only be exercised by
- * mounting a player and waiting for a real freeze is a derivation nobody
- * checks. Everything here is a function of (report, previous sample, clock).
- *
- * D393 — a measurement that FAILED is `null`, never `0`. A stat the browser
- * did not report is absent, and "absent" must never render as "zero" in a
- * debug tool: `freezeCount: 0` means the decoder measured no freeze,
- * `freezeCount: null` means nobody measured. Those are opposite conclusions.
- */
+import { WebrtcSessionDebug } from '@camstack/types';
 /** One resolution the stream actually presented, and when it started. */
 export interface ResolutionMark {
     readonly width: number;
@@ -127,3 +113,39 @@ export interface FreezeVerdict {
     readonly label: string;
 }
 export declare function freezeVerdict(stats: WebrtcDebugStats | null): FreezeVerdict;
+/**
+ * One reported sample: both halves of the stream-debug answer, plus the session
+ * they describe.
+ *
+ * It exists because the overlay cannot always be the surface. In the native app
+ * the player lives inside a WebView whose touches belong to the RN gesture
+ * layer, so the in-picture panel can never be opened there — the numbers have
+ * to leave the player and be drawn by the host, next to the battery and link
+ * details where the operator already looks.
+ *
+ * Everything in it is nullable for the same reason it is nullable everywhere
+ * else in this file: a measurement that did not happen is not a zero.
+ */
+export interface StreamDebugSample {
+    /** When this sample was taken, by the reporting player's clock. */
+    readonly at: number;
+    /**
+     * The verdict, computed HERE.
+     *
+     * The host that renders this sample is not always a web page — the native
+     * app draws it in React Native — and `@camstack/ui-library` is a DOM
+     * component library whose bundle a React Native app must not import (it
+     * reaches for browser globals and for `Array.prototype.toSorted`, which
+     * Hermes does not have). Sending the verdict rather than the function that
+     * derives it keeps that boundary one-way.
+     */
+    readonly verdict: FreezeVerdictKind;
+    /** The session both halves describe; `null` before the player has one. */
+    readonly sessionId: string | null;
+    readonly stats: WebrtcDebugStats | null;
+    readonly server: WebrtcSessionDebug | null;
+    /** Why the last server poll produced nothing, verbatim. */
+    readonly serverError: string | null;
+    /** Whether the player was given a way to ask the server at all. */
+    readonly serverWired: boolean;
+}

package/dist/index.cjs

@@ -27667,7 +27667,7 @@ function mergePlayerHints(autoHints, override, downlinkMbps, coldStart) {
 	return coldStart ? stripDownlinkForColdStart(merged) : merged;
 }
 var FIRST_FRAME_TIMEOUT_MS = 8e3;
-function CameraStreamPlayer({ serverUrl, streamKey, label, autoPlay = true, muted: initialMuted = true, showControls = true, showStats = false, onPlaybackStats, onClientNetworkSample, onConnectTiming, className = "", onStateChange, onError, onReconnectAttempt, overlay, createSession, sendAnswer, handleOffer, getIceServers, addIceCandidate, getIceCandidates, closeSession, getSessionState, getSessionDebug, reoffer, posterUrl, hintsOverride, onAdaptiveHints, reconnectSignal, onControlChannel, onVideoElement }) {
+function CameraStreamPlayer({ serverUrl, streamKey, label, autoPlay = true, muted: initialMuted = true, showControls = true, showStats = false, onDebugStats, onPlaybackStats, onClientNetworkSample, onConnectTiming, className = "", onStateChange, onError, onReconnectAttempt, overlay, createSession, sendAnswer, handleOffer, getIceServers, addIceCandidate, getIceCandidates, closeSession, getSessionState, getSessionDebug, reoffer, posterUrl, hintsOverride, onAdaptiveHints, reconnectSignal, onControlChannel, onVideoElement }) {
 	const videoRef = (0, react$1.useRef)(null);
 	const containerRef = (0, react$1.useRef)(null);
 	const pcRef = (0, react$1.useRef)(null);
@@ -28568,13 +28568,14 @@ function CameraStreamPlayer({ serverUrl, streamKey, label, autoPlay = true, mute
 	const [serverDebug, setServerDebug] = (0, react$1.useState)(null);
 	const [serverDebugError, setServerDebugError] = (0, react$1.useState)(null);
 	const [debugNow, setDebugNow] = (0, react$1.useState)(() => Date.now());
+	const debugWanted = showStats || onDebugStats !== void 0;
 	(0, react$1.useEffect)(() => {
 		if (!showStats) return;
 		const id = setInterval(() => setDebugNow(Date.now()), 500);
 		return () => clearInterval(id);
 	}, [showStats]);
 	(0, react$1.useEffect)(() => {
-		if (!showStats) {
+		if (!debugWanted) {
 			setDebugStats(null);
 			return;
 		}
@@ -28605,9 +28606,9 @@ function CameraStreamPlayer({ serverUrl, streamKey, label, autoPlay = true, mute
 			cancelled = true;
 			clearInterval(id);
 		};
-	}, [showStats]);
+	}, [debugWanted]);
 	(0, react$1.useEffect)(() => {
-		if (!showStats || !getSessionDebug) {
+		if (!debugWanted || !getSessionDebug) {
 			setServerDebug(null);
 			setServerDebugError(null);
 			return;
@@ -28637,7 +28638,32 @@ function CameraStreamPlayer({ serverUrl, streamKey, label, autoPlay = true, mute
 			cancelled = true;
 			clearInterval(id);
 		};
-	}, [showStats, getSessionDebug]);
+	}, [debugWanted, getSessionDebug]);
+	const onDebugStatsRef = (0, react$1.useRef)(onDebugStats);
+	onDebugStatsRef.current = onDebugStats;
+	(0, react$1.useEffect)(() => {
+		if (onDebugStats === void 0) return;
+		const emit = () => {
+			onDebugStatsRef.current?.({
+				at: Date.now(),
+				verdict: freezeVerdict(debugStatsRef.current).kind,
+				sessionId: activeSessionIdRef.current,
+				stats: debugStatsRef.current,
+				server: serverDebugRef.current,
+				serverError: serverDebugErrorRef.current,
+				serverWired: getSessionDebug !== void 0
+			});
+		};
+		emit();
+		const id = setInterval(emit, 1e3);
+		return () => clearInterval(id);
+	}, [onDebugStats === void 0, getSessionDebug]);
+	const debugStatsRef = (0, react$1.useRef)(null);
+	debugStatsRef.current = debugStats;
+	const serverDebugRef = (0, react$1.useRef)(null);
+	serverDebugRef.current = serverDebug;
+	const serverDebugErrorRef = (0, react$1.useRef)(null);
+	serverDebugErrorRef.current = serverDebugError;
 	const netPrev = (0, react$1.useRef)(null);
 	(0, react$1.useEffect)(() => {
 		if (!onClientNetworkSample) {

package/dist/index.js

@@ -27643,7 +27643,7 @@ function mergePlayerHints(autoHints, override, downlinkMbps, coldStart) {
 	return coldStart ? stripDownlinkForColdStart(merged) : merged;
 }
 var FIRST_FRAME_TIMEOUT_MS = 8e3;
-function CameraStreamPlayer({ serverUrl, streamKey, label, autoPlay = true, muted: initialMuted = true, showControls = true, showStats = false, onPlaybackStats, onClientNetworkSample, onConnectTiming, className = "", onStateChange, onError, onReconnectAttempt, overlay, createSession, sendAnswer, handleOffer, getIceServers, addIceCandidate, getIceCandidates, closeSession, getSessionState, getSessionDebug, reoffer, posterUrl, hintsOverride, onAdaptiveHints, reconnectSignal, onControlChannel, onVideoElement }) {
+function CameraStreamPlayer({ serverUrl, streamKey, label, autoPlay = true, muted: initialMuted = true, showControls = true, showStats = false, onDebugStats, onPlaybackStats, onClientNetworkSample, onConnectTiming, className = "", onStateChange, onError, onReconnectAttempt, overlay, createSession, sendAnswer, handleOffer, getIceServers, addIceCandidate, getIceCandidates, closeSession, getSessionState, getSessionDebug, reoffer, posterUrl, hintsOverride, onAdaptiveHints, reconnectSignal, onControlChannel, onVideoElement }) {
 	const videoRef = useRef(null);
 	const containerRef = useRef(null);
 	const pcRef = useRef(null);
@@ -28544,13 +28544,14 @@ function CameraStreamPlayer({ serverUrl, streamKey, label, autoPlay = true, mute
 	const [serverDebug, setServerDebug] = useState(null);
 	const [serverDebugError, setServerDebugError] = useState(null);
 	const [debugNow, setDebugNow] = useState(() => Date.now());
+	const debugWanted = showStats || onDebugStats !== void 0;
 	useEffect(() => {
 		if (!showStats) return;
 		const id = setInterval(() => setDebugNow(Date.now()), 500);
 		return () => clearInterval(id);
 	}, [showStats]);
 	useEffect(() => {
-		if (!showStats) {
+		if (!debugWanted) {
 			setDebugStats(null);
 			return;
 		}
@@ -28581,9 +28582,9 @@ function CameraStreamPlayer({ serverUrl, streamKey, label, autoPlay = true, mute
 			cancelled = true;
 			clearInterval(id);
 		};
-	}, [showStats]);
+	}, [debugWanted]);
 	useEffect(() => {
-		if (!showStats || !getSessionDebug) {
+		if (!debugWanted || !getSessionDebug) {
 			setServerDebug(null);
 			setServerDebugError(null);
 			return;
@@ -28613,7 +28614,32 @@ function CameraStreamPlayer({ serverUrl, streamKey, label, autoPlay = true, mute
 			cancelled = true;
 			clearInterval(id);
 		};
-	}, [showStats, getSessionDebug]);
+	}, [debugWanted, getSessionDebug]);
+	const onDebugStatsRef = useRef(onDebugStats);
+	onDebugStatsRef.current = onDebugStats;
+	useEffect(() => {
+		if (onDebugStats === void 0) return;
+		const emit = () => {
+			onDebugStatsRef.current?.({
+				at: Date.now(),
+				verdict: freezeVerdict(debugStatsRef.current).kind,
+				sessionId: activeSessionIdRef.current,
+				stats: debugStatsRef.current,
+				server: serverDebugRef.current,
+				serverError: serverDebugErrorRef.current,
+				serverWired: getSessionDebug !== void 0
+			});
+		};
+		emit();
+		const id = setInterval(emit, 1e3);
+		return () => clearInterval(id);
+	}, [onDebugStats === void 0, getSessionDebug]);
+	const debugStatsRef = useRef(null);
+	debugStatsRef.current = debugStats;
+	const serverDebugRef = useRef(null);
+	serverDebugRef.current = serverDebug;
+	const serverDebugErrorRef = useRef(null);
+	serverDebugErrorRef.current = serverDebugError;
 	const netPrev = useRef(null);
 	useEffect(() => {
 		if (!onClientNetworkSample) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/ui-library",
-  "version": "1.2.185",
+  "version": "1.2.187",
   "type": "module",
   "main": "dist/index.cjs",
   "module": "dist/index.js",