@camstack/ui-library 1.2.181 → 1.2.182

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

@@ -1,5 +1,5 @@
 import { ReactNode } from 'react';
-import { CamProfile } from '@camstack/types';
+import { CamProfile, WebrtcSessionDebug } from '@camstack/types';
 import { ReconnectAction } from './reconnect-schedule';
 import { AdaptiveHintsReport } from './adaptive-downlink';
 type WebkitPresentationMode = 'inline' | 'picture-in-picture' | 'fullscreen';
@@ -204,6 +204,19 @@ export interface CameraStreamPlayerProps {
      * loader. Best-effort: omit it to disable adaptive re-offer entirely.
      */
     getSessionState?: (sessionId: string) => Promise<SessionSignalingState>;
+    /**
+     * Poll the SERVER's account of this session for the stream-debug overlay —
+     * the rung `auto` actually resolved to, whether that rung is the camera's
+     * own encode or one this hub built, which node ingests it, whether the
+     * egress leg copies or re-encodes, and the cause + numbers of the ladder's
+     * last move (`webrtcSession.getSessionDebug`).
+     *
+     * The client can measure its own transport; it cannot see any of that, and
+     * "quality is stuck on low" is unanswerable without it. Called at ~1 Hz
+     * ONLY while `showStats` is true, and never when it is false. Omit it and
+     * the overlay shows its client half alone, saying so.
+     */
+    getSessionDebug?: (sessionId: string) => Promise<WebrtcSessionDebug>;
     /**
      * Re-offer signaling for an adaptive tier switch (client-offer mode).
      * Posts a fresh browser-built offer for an EXISTING `sessionId` against
@@ -274,5 +287,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, reoffer, posterUrl, hintsOverride, onAdaptiveHints, reconnectSignal, onControlChannel, onVideoElement, }: CameraStreamPlayerProps): import("react").JSX.Element;
+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 {};

package/dist/composites/index.d.ts

@@ -17,6 +17,10 @@ export * from './breadcrumb';
 export type { AdaptiveHintsReport, AdaptiveOfferPhase, } from './adaptive-downlink';
 export type { CameraStreamPlayerProps, ClientOfferResult, ClientStreamHints, PlayerConnectionState, PlayerWebrtcTarget, SessionSignalingState, SignalingResult, } from './camera-stream-player';
 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 { AutotrackSection } from './cap-settings/AutotrackSection';
 export { ConsumablesPanel } from './cap-settings/ConsumablesPanel';
 export type { CapSettingsComponentProps } from './cap-settings/index';

package/dist/composites/stream-debug/stream-debug-overlay.d.ts

@@ -0,0 +1,34 @@
+import { ReactNode } from 'react';
+import { WebrtcSessionDebug } from '@camstack/types';
+import { WebrtcDebugStats } from './webrtc-debug-stats.js';
+/**
+ * The stream-debug overlay: the CLIENT's transport measurements next to what
+ * the SERVER decided, over the live picture.
+ *
+ * Three things about this surface are requirements, not styling:
+ *
+ *  1. It must be legible over a FROZEN picture. The panel is opaque, not a
+ *     wash — a translucent overlay on a stuck bright frame is unreadable
+ *     exactly when it is needed.
+ *  2. Every number says WHEN it was measured. Two independent clocks feed
+ *     this (a 1 s `getStats()` poll and a 1 s server poll) and either can
+ *     stop. A stale poll that looks live is how a debug tool lies.
+ *  3. An UNKNOWN value renders as `—`, and a measured zero renders as `0`
+ *     (D393). In a tool whose whole job is telling a stalled decoder from a
+ *     stalled transport, "nobody measured" and "measured nothing" are
+ *     opposite conclusions.
+ */
+export interface StreamDebugOverlayProps {
+    /** The client half. Null before the first successful poll. */
+    readonly stats: WebrtcDebugStats | null;
+    /** The server half. Null when not wired, or before the first answer. */
+    readonly server: WebrtcSessionDebug | null;
+    /** Why the last server poll produced nothing. Shown verbatim. */
+    readonly serverError: string | null;
+    /** Whether a server poll is wired at all (vs. simply not configured). */
+    readonly serverWired: boolean;
+    /** Ticking clock, so the ages re-render between polls. */
+    readonly now: number;
+    readonly sessionId: string | null;
+}
+export declare function StreamDebugOverlay(props: StreamDebugOverlayProps): ReactNode;

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

@@ -0,0 +1,129 @@
+/**
+ * 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.
+ */
+/** One resolution the stream actually presented, and when it started. */
+export interface ResolutionMark {
+    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;
+}
+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;
+}
+/** 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;
+}
+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;
+}
+/**
+ * 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';
+export interface FreezeVerdict {
+    readonly kind: FreezeVerdictKind;
+    readonly label: string;
+}
+export declare function freezeVerdict(stats: WebrtcDebugStats | null): FreezeVerdict;

package/dist/generated/system-hooks.d.ts

@@ -2097,6 +2097,8 @@ export declare const useWebrtcSessionCloseSession: typeof trpc.webrtcSession.clo
 export declare const useWebrtcSessionHasAdaptiveBitrate: typeof trpc.webrtcSession.hasAdaptiveBitrate.useQuery;
 /** Generated alias around `trpc.webrtcSession.getSessionState.useQuery`. */
 export declare const useWebrtcSessionGetSessionState: typeof trpc.webrtcSession.getSessionState.useQuery;
+/** Generated alias around `trpc.webrtcSession.getSessionDebug.useQuery`. */
+export declare const useWebrtcSessionGetSessionDebug: typeof trpc.webrtcSession.getSessionDebug.useQuery;
 /** Generated alias around `trpc.zoneAnalytics.getCurrentSnapshot.useQuery`. */
 export declare const useZoneAnalyticsGetCurrentSnapshot: typeof trpc.zoneAnalytics.getCurrentSnapshot.useQuery;
 /** Generated alias around `trpc.zoneAnalytics.getCurrentSnapshotBatch.useQuery`. */

package/dist/hooks/use-device-webrtc.d.ts

@@ -1,4 +1,4 @@
-import { CamProfile } from '@camstack/types';
+import { CamProfile, WebrtcSessionDebug } from '@camstack/types';
 import { StreamChoice } from '../composites/stream-panel';
 import { ClientStreamHints, SignalingResult, ClientOfferResult } from '../composites/camera-stream-player';
 /**
@@ -114,6 +114,12 @@ export interface UseDeviceWebrtcTrpc {
                 epoch: number;
             } | null;
         }>;
+        /** The SERVER's account of a live session, for the stream-debug overlay.
+         *  Read-only; the overlay polls it at ~1 Hz only while it is visible. */
+        getSessionDebug: QueryFn<{
+            deviceId: number;
+            sessionId: string;
+        }, WebrtcSessionDebug>;
     };
     pipelineOrchestrator?: {
         getCameraMetrics: QueryFn<{
@@ -187,6 +193,14 @@ export interface DeviceWebrtcResult {
      * `{ pendingRenegotiation: null }` for non-adaptive / steady sessions.
      */
     readonly getSessionState: (sessionId: string) => Promise<SessionRenegotiationState>;
+    /**
+     * The SERVER half of the stream-debug overlay for a session. Unlike
+     * `getSessionState`, a failure here THROWS rather than resolving a benign
+     * default: this is a diagnostic read, and a swallowed error would render as
+     * a confident set of unknowns with no reason attached. The overlay catches
+     * it and shows the message.
+     */
+    readonly getSessionDebug: (sessionId: string) => Promise<WebrtcSessionDebug>;
 }
 /** Live signaling state for a session — the adaptive re-offer signal. */
 export interface SessionRenegotiationState {