@camstack/ui-library 1.2.200 → 1.2.202

package/dist/composites/adaptive-downlink.d.ts

@@ -3,9 +3,28 @@
  * Used as `hints.downlinkMbps` so adaptive selection is based on a measured
  * path, not viewport size or IP class. Failures return null (caller keeps
  * the default-low / ceiling path and may stay on the lowest rung).
+ *
+ * D635 (2026-09-25): the probe used to time a 128 KiB blob from the REQUEST,
+ * fired in parallel with `createSession` on a hub at ~80 % CPU. It read the
+ * LAN as 1.2–1.46 Mbps — the elapsed time was mostly waiting for the first
+ * byte, i.e. latency. It now (1) times the body from its FIRST byte, (2) reads
+ * a 1 MiB blob so the transfer dominates timer jitter, and (3) runs after the
+ * session's first decoded frame, never during session setup.
  */
 export declare const ADAPTIVE_PROBE_PATH = "/adaptive-probe";
+/**
+ * Whole-probe deadline, from the request. A probe cut here is still a
+ * measurement of whatever body arrived (see {@link measureDownlinkMbps}).
+ */
 export declare const ADAPTIVE_PROBE_TIMEOUT_MS = 2500;
+/**
+ * Fewest body bytes AFTER the first chunk that make a rate. 64 KiB: at the
+ * `high` threshold (8 Mbps) that is 65 ms of transfer — four times a 16 ms
+ * WebView timer tick. Less is a guess, and a guess is unknown, not slow.
+ */
+export declare const ADAPTIVE_PROBE_MIN_MEASURED_BYTES: number;
+/** How long the probe waits for the session's first decoded frame. */
+export declare const FIRST_FRAME_PROBE_TIMEOUT_MS = 15000;
 export type AdaptiveTier = 'high' | 'mid' | 'low';
 /** Mbps needed to attempt each rung (bitrate / 0.6 headroom, rounded). */
 export declare const DOWNLINK_HIGH_MBPS = 8;
@@ -42,7 +61,7 @@ export declare function shouldUpgradeAfterProbe(mbps: number): boolean;
 export declare function resolveProbeOrigin(serverUrl: string | undefined, pageOrigin: string | undefined): string | null;
 /** Which offer composed the hints. A climb and a cold start read identically
  *  in the hub's log; only the client knows which one it just sent. */
-export type AdaptiveOfferPhase = 'cold-start' | 'probe-climb' | 'renegotiate';
+export type AdaptiveOfferPhase = 'cold-start' | 'probe-climb' | 'renegotiate' | 'probe-refused';
 /**
  * What the CLIENT sent for one adaptive decision. Deliberately not the hub's
  * verdict — the hub already logs its own pick, and a client line that repeated
@@ -59,6 +78,8 @@ export interface AdaptiveHintsReport {
     readonly devicePixelRatio?: number;
     readonly downlinkMbps?: number;
     readonly prefersTier?: string;
+    /** For `probe-refused`: the HTTP status the hub answered the probe with (401/429…). */
+    readonly probeStatus?: number;
 }
 /**
  * Identity of a decision, for "log once per CHANGE, not per tick".
@@ -69,12 +90,83 @@ export interface AdaptiveHintsReport {
  * pick the same rung are the same decision and must collapse to one line.
  */
 export declare function adaptiveHintsKey(report: AdaptiveHintsReport): string;
-export declare function measureDownlinkMbps(origin: string, deps: {
+/** The slice of a body reader the probe uses (a `ReadableStreamDefaultReader` fits). */
+export interface ProbeBodyReader {
+    read(): Promise<{
+        readonly done: boolean;
+        readonly value?: Uint8Array;
+    }>;
+    cancel(): Promise<void>;
+}
+/** The slice of a fetch `Response` the probe uses. */
+export interface ProbeResponse {
+    readonly ok: boolean;
+    readonly status?: number;
+    readonly body?: {
+        getReader(): ProbeBodyReader;
+    } | null;
+    arrayBuffer(): Promise<ArrayBuffer>;
+}
+export interface DownlinkProbeDeps {
     readonly fetchImpl: (url: string, init: {
         signal: AbortSignal;
-    }) => Promise<{
-        ok: boolean;
-        arrayBuffer: () => Promise<ArrayBuffer>;
-    }>;
+    }) => Promise<ProbeResponse>;
+    readonly now: () => number;
+    /**
+     * The hub answered but refused (401 without a session, 429 rate-limited).
+     * The reading is still unknown — but a missing token must not be silent,
+     * or it is indistinguishable from a failed probe (review N3, D391).
+     */
+    readonly onRefused?: (status: number) => void;
+}
+export declare function measureDownlinkMbps(origin: string, deps: DownlinkProbeDeps): Promise<number | null>;
+export type FirstFrameOutcome = 'frame' | 'timeout' | 'aborted';
+export interface FirstFrameDeps {
+    /** The live video element's `readyState`, or null when there is none yet. */
+    readonly readyState: () => number | null;
+    readonly signal: AbortSignal;
+    readonly sleep: (ms: number) => Promise<void>;
     readonly now: () => number;
-}): Promise<number | null>;
+}
+/**
+ * Resolve once the session presents its first decoded frame — the moment
+ * session setup (createSession, ICE, DTLS, the first IDR) is over and a probe
+ * no longer competes with it for the hub or the link.
+ */
+export declare function waitForFirstFrame(deps: FirstFrameDeps, timeoutMs?: number): Promise<FirstFrameOutcome>;
+/**
+ * The cold-start probe: measure only once the first frame is up. No frame ⇒
+ * no measurement (undefined) — the session is failing for a reason a probe
+ * cannot fix, and a climb would only add a second connection to it.
+ */
+export interface ProbeAfterFirstFrameDeps {
+    readonly waitFrame: () => Promise<FirstFrameOutcome>;
+    readonly measure: () => Promise<number | undefined>;
+}
+export declare function probeAfterFirstFrame(deps: ProbeAfterFirstFrameDeps): Promise<number | undefined>;
+/** The latest probe for an origin, whatever it read or how old it is. */
+export interface LatestProbe {
+    readonly mbps: number;
+    readonly ageMs: number;
+}
+export interface DownlinkProbeStoreDeps {
+    readonly now: () => number;
+    /** How long a reading answers `measured`/`cached` without re-probing. */
+    readonly ttlMs: number;
+}
+export interface DownlinkProbeStore {
+    /**
+     * The cached reading while fresh, else ONE probe for the origin — concurrent
+     * callers share the probe in flight (review I6: a grid decoding together
+     * fired N 1 MiB probes, each reading the link ÷ N). Undefined = unknown.
+     */
+    measured(origin: string, measure: () => Promise<number | null>): Promise<number | undefined>;
+    /** The cached reading while fresh — never probes (review I5: renegotiation). */
+    cached(origin: string): number | undefined;
+    /** The newest reading whatever its age — what the telemetry reports (I4). */
+    latest(origin: string): LatestProbe | null;
+    /** True the FIRST time `origin` refuses with `status` in this app — say it once. */
+    firstRefusal(origin: string, status: number): boolean;
+}
+/** App-wide probe cache + single-flight, one per origin. */
+export declare function createDownlinkProbe(deps: DownlinkProbeStoreDeps): DownlinkProbeStore;

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 { ClientNetworkSample } from './client-network-sample';
 import { StreamDebugSample } from './stream-debug/webrtc-debug-stats.js';
 type WebkitPresentationMode = 'inline' | 'picture-in-picture' | 'fullscreen';
 declare global {
@@ -87,15 +88,7 @@ export interface ClientStreamHints {
     downlinkMbps?: number;
     prefersTier?: string;
 }
-/** Client-observed network conditions, sampled from the live PeerConnection.
- *  Matches the `networkQuality.reportClientStats` mutation input (minus
- *  `deviceId`, which the caller adds). */
-export interface ClientNetworkSample {
-    readonly rttMs: number;
-    readonly jitterMs: number;
-    readonly estimatedBandwidthKbps: number;
-    readonly packetLossPercent: number;
-}
+export type { ClientNetworkSample } from './client-network-sample';
 export interface CameraStreamPlayerProps {
     /** Server base URL (e.g. window.location.origin) */
     serverUrl: string;
@@ -147,6 +140,14 @@ export interface CameraStreamPlayerProps {
      * tier. Inert (zero behaviour change) unless a callback is passed; wire it
      * only for adaptive sessions. */
     onClientNetworkSample?: (sample: ClientNetworkSample) => void;
+    /**
+     * Bearer for `/adaptive-probe`, which requires a session (D635). A page the
+     * hub serves carries the session cookie and needs none; a host whose page
+     * cannot (the native app's `file://` embed) passes its token here. Absent
+     * and cookieless, the probe reads unknown and the broker's own ladder
+     * decides (try-climb on a clean path).
+     */
+    probeAuthToken?: string | null;
     /**
      * Cold-start phase breakdown, fired ONCE per connect when ICE reaches
      * connected (the same object the `[WebRTC timing]` console line prints:
@@ -302,5 +303,4 @@ export interface CameraStreamPlayerProps {
      */
     onVideoElement?: (el: HTMLVideoElement | null) => void;
 }
-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 {};
+export declare function CameraStreamPlayer({ serverUrl, streamKey, label, autoPlay, muted: initialMuted, showControls, showStats, onDebugStats, onPlaybackStats, onClientNetworkSample, probeAuthToken, 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;

package/dist/composites/client-network-sample.d.ts

@@ -0,0 +1,56 @@
+/**
+ * What the player reports to the broker every ~2 s
+ * (`networkQuality.reportClientStats`), as a pure step over two `getStats`
+ * readings — so the two ways it used to lie can be pinned (D635 round 3):
+ *
+ * - Across a PC swap (a tier change's make-before-break) the byte baseline was
+ *   the OLD connection's, so the new PC's first reading clamped to 0 kbps; and
+ *   while a renegotiation was in flight the reporter read a closing PC. Both
+ *   zeros were matched by the broker against real sends (review I1). A new PC
+ *   now re-baselines, and nothing is reported while renegotiating.
+ * - The downlink probe never reached the broker unless it justified a climb.
+ *   The sample now carries the latest probe whatever it read, with its age
+ *   (review I4), so "measured slow" is no longer indistinguishable from
+ *   "failed".
+ */
+/** Client-observed network conditions. Matches the `networkQuality.reportClientStats`
+ *  mutation input (minus `deviceId`, which the caller adds). */
+export interface ClientNetworkSample {
+    readonly rttMs: number;
+    readonly jitterMs: number;
+    readonly estimatedBandwidthKbps: number;
+    readonly packetLossPercent: number;
+    /** Latest `/adaptive-probe` reading, Mbps, whatever it read; absent = never / failed. */
+    readonly downlinkMbps?: number;
+    /** Age of that reading now, ms. */
+    readonly downlinkAgeMs?: number;
+}
+/** One inbound-video `getStats` reading, and the connection it came from. */
+export interface InboundReading {
+    /** The RTCPeerConnection read — identity only. */
+    readonly pc: object;
+    readonly lost: number;
+    readonly recv: number;
+    readonly bytes: number;
+    /** getStats timestamp, ms. */
+    readonly ts: number;
+    readonly rttS: number;
+    readonly jitterS: number;
+}
+/** The latest probe as the player holds it. */
+export interface ProbeReading {
+    readonly mbps: number;
+    readonly ageMs: number;
+}
+export interface SampleContext {
+    /** A renegotiation (tier change) is in flight: the PC being read is on its way out. */
+    readonly renegotiating: boolean;
+    readonly probe: ProbeReading | null;
+}
+export interface SampleStep {
+    /** The reading to diff the next one against; null = start over. */
+    readonly baseline: InboundReading | null;
+    /** What to report now; null = report nothing this window. */
+    readonly sample: ClientNetworkSample | null;
+}
+export declare function nextClientSample(prev: InboundReading | null, cur: InboundReading, ctx: SampleContext): SampleStep;

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

@@ -537,6 +537,8 @@ export declare const useDeviceManagerGetBindings: typeof trpc.deviceManager.getB
 export declare const useDeviceManagerGetBindingsBatch: typeof trpc.deviceManager.getBindingsBatch.useQuery;
 /** Generated alias around `trpc.deviceManager.getAllBindings.useQuery`. */
 export declare const useDeviceManagerGetAllBindings: typeof trpc.deviceManager.getAllBindings.useQuery;
+/** Generated alias around `trpc.deviceManager.listDeviceIdsByCaps.useQuery`. */
+export declare const useDeviceManagerListDeviceIdsByCaps: typeof trpc.deviceManager.listDeviceIdsByCaps.useQuery;
 /** Generated alias around `trpc.deviceManager.setWrapperActive.useMutation`. */
 export declare const useDeviceManagerSetWrapperActive: typeof trpc.deviceManager.setWrapperActive.useMutation;
 /** Generated alias around `trpc.deviceManager.listWrappersForCap.useQuery`. */