@camstack/ui-library 1.2.256 → 1.2.258

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

@@ -1,151 +1,166 @@
-import { WebrtcSessionDebug } from '@camstack/types';
+/**
+* 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 type { WebrtcSessionDebug } from "@camstack/types";
 /** One resolution the stream actually presented, and when it started. */
 export interface ResolutionMark {
-    readonly width: number;
-    readonly height: number;
-    readonly at: number;
+	readonly width: number;
+	readonly height: number;
+	readonly at: number;
 }
 /** Deltas over the interval between the previous sample and this one. */
 export interface WebrtcDebugWindow {
-    /** Length of the window, from the RTP report clock. Null on the first
-     *  sample and whenever the report timestamp did not advance. */
-    readonly spanMs: number | null;
-    readonly kbps: number | null;
-    readonly packetsReceived: number | null;
-    readonly packetsLost: number | null;
-    readonly lossPercent: number | null;
-    /** 0 here is the load-bearing value: the transport is delivering and the
-     *  decoder emitted nothing. */
-    readonly framesDecoded: number | null;
-    readonly framesDropped: number | null;
-    readonly freezeCount: number | null;
-    readonly freezeMs: number | null;
-    readonly nackCount: number | null;
-    readonly pliCount: number | null;
-    /** Mean decode time per frame decoded IN THIS WINDOW. */
-    readonly decodeMs: number | null;
+	/** Length of the window, from the RTP report clock. Null on the first
+	*  sample and whenever the report timestamp did not advance. */
+	readonly spanMs: number | null;
+	readonly kbps: number | null;
+	readonly packetsReceived: number | null;
+	readonly packetsLost: number | null;
+	readonly lossPercent: number | null;
+	/** 0 here is the load-bearing value: the transport is delivering and the
+	*  decoder emitted nothing. */
+	readonly framesDecoded: number | null;
+	readonly framesDropped: number | null;
+	readonly freezeCount: number | null;
+	readonly freezeMs: number | null;
+	readonly nackCount: number | null;
+	readonly pliCount: number | null;
+	/** Mean decode time per frame decoded IN THIS WINDOW. */
+	readonly decodeMs: number | null;
 }
 export interface WebrtcDebugStats {
-    /** Wall clock at which this sample was taken — the overlay prints its age
-     *  so a stale poll can never be mistaken for a live one. */
-    readonly at: number;
-    /** Whether an inbound-rtp video report existed at all. `false` means every
-     *  inbound field below is null because nothing was measured. */
-    readonly hasInboundVideo: boolean;
-    readonly width: number | null;
-    readonly height: number | null;
-    readonly fps: number | null;
-    readonly codec: string | null;
-    readonly codecProfileLevelId: string | null;
-    readonly jitterMs: number | null;
-    readonly packetsReceived: number | null;
-    readonly packetsLost: number | null;
-    readonly lossPercent: number | null;
-    readonly nackCount: number | null;
-    readonly pliCount: number | null;
-    readonly framesDecoded: number | null;
-    readonly framesDropped: number | null;
-    readonly freezeCount: number | null;
-    readonly totalFreezeMs: number | null;
-    readonly avgDecodeMs: number | null;
-    readonly rttMs: number | null;
-    readonly availableIncomingKbps: number | null;
-    readonly localCandidateType: string | null;
-    readonly remoteCandidateType: string | null;
-    /** `local/remote` candidate types of the selected pair, e.g. `srflx/host`. */
-    readonly candidatePairType: string | null;
-    readonly candidateProtocol: string | null;
-    readonly iceConnectionState: string | null;
-    readonly dtlsState: string | null;
-    readonly window: WebrtcDebugWindow;
-    /** Every resolution the stream presented, oldest first, newest last. */
-    readonly resolutionLog: readonly ResolutionMark[];
-    /** Raw counters carried forward so the NEXT sample can window them. */
-    readonly raw: RawCounters;
+	/** Wall clock at which this sample was taken — the overlay prints its age
+	*  so a stale poll can never be mistaken for a live one. */
+	readonly at: number;
+	/** Whether an inbound-rtp video report existed at all. `false` means every
+	*  inbound field below is null because nothing was measured. */
+	readonly hasInboundVideo: boolean;
+	readonly width: number | null;
+	readonly height: number | null;
+	readonly fps: number | null;
+	readonly codec: string | null;
+	readonly codecProfileLevelId: string | null;
+	readonly jitterMs: number | null;
+	readonly packetsReceived: number | null;
+	readonly packetsLost: number | null;
+	readonly lossPercent: number | null;
+	readonly nackCount: number | null;
+	readonly pliCount: number | null;
+	readonly framesDecoded: number | null;
+	readonly framesDropped: number | null;
+	readonly freezeCount: number | null;
+	readonly totalFreezeMs: number | null;
+	readonly avgDecodeMs: number | null;
+	readonly rttMs: number | null;
+	readonly availableIncomingKbps: number | null;
+	readonly localCandidateType: string | null;
+	readonly remoteCandidateType: string | null;
+	/** `local/remote` candidate types of the selected pair, e.g. `srflx/host`. */
+	readonly candidatePairType: string | null;
+	readonly candidateProtocol: string | null;
+	readonly iceConnectionState: string | null;
+	readonly dtlsState: string | null;
+	readonly window: WebrtcDebugWindow;
+	/** Every resolution the stream presented, oldest first, newest last. */
+	readonly resolutionLog: readonly ResolutionMark[];
+	/** Raw counters carried forward so the NEXT sample can window them. */
+	readonly raw: RawCounters;
 }
 /** The cumulative counters a window is computed from. */
 export interface RawCounters {
-    /** The RTP report clock (`RTCStats.timestamp`), not the wall clock. */
-    readonly timestamp: number | null;
-    readonly bytesReceived: number | null;
-    readonly packetsReceived: number | null;
-    readonly packetsLost: number | null;
-    readonly framesDecoded: number | null;
-    readonly framesDropped: number | null;
-    readonly freezeCount: number | null;
-    readonly totalFreezesDurationS: number | null;
-    readonly totalDecodeTimeS: number | null;
-    readonly nackCount: number | null;
-    readonly pliCount: number | null;
+	/** The RTP report clock (`RTCStats.timestamp`), not the wall clock. */
+	readonly timestamp: number | null;
+	readonly bytesReceived: number | null;
+	readonly packetsReceived: number | null;
+	readonly packetsLost: number | null;
+	readonly framesDecoded: number | null;
+	readonly framesDropped: number | null;
+	readonly freezeCount: number | null;
+	readonly totalFreezesDurationS: number | null;
+	readonly totalDecodeTimeS: number | null;
+	readonly nackCount: number | null;
+	readonly pliCount: number | null;
 }
 export interface DeriveWebrtcDebugStatsInput {
-    readonly report: RTCStatsReport;
-    readonly prev: WebrtcDebugStats | null;
-    /** Wall clock — `Date.now()` in production, fixed in tests. */
-    readonly now: number;
-    readonly iceConnectionState: string | null;
-    readonly dtlsState: string | null;
+	readonly report: RTCStatsReport;
+	readonly prev: WebrtcDebugStats | null;
+	/** Wall clock — `Date.now()` in production, fixed in tests. */
+	readonly now: number;
+	readonly iceConnectionState: string | null;
+	readonly dtlsState: string | null;
 }
 /**
- * Derive one debug sample. Immutable: `prev` is read, never mutated, and the
- * returned object is the input for the next call.
- */
+* Derive one debug sample. Immutable: `prev` is read, never mutated, and the
+* returned object is the input for the next call.
+*/
 export declare function deriveWebrtcDebugStats(input: DeriveWebrtcDebugStatsInput): WebrtcDebugStats;
 /**
- * The one question this overlay exists to answer while a camera is frozen:
- * did the BYTES stop, or did the DECODER stop?
- *
- * The open investigation is a `mid` stream that freezes until the user hits
- * pause/play. Those two causes need opposite fixes and look identical on the
- * screen; they differ only here, in one window's worth of counters:
- *  - bytes arriving, no frame out  ⇒ the decoder is wedged (pause/play
- *    rebuilds it, which is exactly the reported workaround);
- *  - nothing arriving              ⇒ the transport stopped, and the server
- *    half of the overlay says whether the broker was still sending.
- *
- * Every other case is `unknown`, deliberately. A verdict guessed from a
- * missing byte rate is worse than no verdict — it is the thing an operator
- * will trust and stop measuring.
- */
-export type FreezeVerdictKind = 'unknown' | 'decoding' | 'decoder-stall' | 'transport-stall' | 'frozen-unknown';
+* The one question this overlay exists to answer while a camera is frozen:
+* did the BYTES stop, or did the DECODER stop?
+*
+* The open investigation is a `mid` stream that freezes until the user hits
+* pause/play. Those two causes need opposite fixes and look identical on the
+* screen; they differ only here, in one window's worth of counters:
+*  - bytes arriving, no frame out  ⇒ the decoder is wedged (pause/play
+*    rebuilds it, which is exactly the reported workaround);
+*  - nothing arriving              ⇒ the transport stopped, and the server
+*    half of the overlay says whether the broker was still sending.
+*
+* Every other case is `unknown`, deliberately. A verdict guessed from a
+* missing byte rate is worse than no verdict — it is the thing an operator
+* will trust and stop measuring.
+*/
+export type FreezeVerdictKind = "unknown" | "decoding" | "decoder-stall" | "transport-stall" | "frozen-unknown";
 export interface FreezeVerdict {
-    readonly kind: FreezeVerdictKind;
-    readonly label: string;
+	readonly kind: FreezeVerdictKind;
+	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.
- */
+* 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;
+	/** 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;
 }