@camstack/ui-library 1.2.100 → 1.2.101

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

@@ -18,6 +18,57 @@ export declare function stripDownlinkForColdStart<T extends {
 }>(hints: T): Omit<T, 'downlinkMbps'>;
 /** After a probe, only mid/high justify a make-before-break climb. */
 export declare function shouldUpgradeAfterProbe(mbps: number): boolean;
+/**
+ * The origin `/adaptive-probe` must be fetched from — the HUB, not the page.
+ *
+ * The page origin was the original assumption ("same-origin as the player",
+ * `adaptive-probe.routes.ts`) and it is only true for the web viewer and the
+ * iframe embed, both served by the hub. The NATIVE viewer loads this same
+ * player from an asset bundled with the app (`useNativeEmbedSource` resolves
+ * `assets/embed/camstack-embed.html` through `Image.resolveAssetSource`), so
+ * inside the WKWebView `window.location.origin` is `file://` — and
+ * `file:///adaptive-probe` is not a request any hub can answer. The probe
+ * therefore returned null on EVERY native connect, `downlinkMbps` was never
+ * sent, `pickAdaptiveTier` scored every session `default-low`, and
+ * `shouldUpgradeAfterProbe` was never even reached — so the make-before-break
+ * climb that the cold-start default depends on could not run. That is the
+ * whole of "the automatic quality always drops to low" on the app.
+ *
+ * The hub the player is already talking to is the `serverUrl` prop, so it
+ * wins; the page origin remains as the fallback for a host that passes a
+ * relative/empty `serverUrl`. Null means no probe is possible and the caller
+ * must skip it rather than fetch a URL that cannot exist.
+ */
+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';
+/**
+ * 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
+ * it would prove nothing about the client. This is the other half of that
+ * join: the inputs the hub scored, plus whether the downlink probe had an
+ * origin it could even reach.
+ */
+export interface AdaptiveHintsReport {
+    readonly phase: AdaptiveOfferPhase;
+    /** Null when no http(s) origin resolved — the probe did not run at all. */
+    readonly probeOrigin: string | null;
+    readonly viewportWidth?: number;
+    readonly viewportHeight?: number;
+    readonly devicePixelRatio?: number;
+    readonly downlinkMbps?: number;
+    readonly prefersTier?: string;
+}
+/**
+ * Identity of a decision, for "log once per CHANGE, not per tick".
+ *
+ * `downlinkMbps` is a fresh measurement on every probe and would otherwise
+ * make every offer look like a new decision. What the ladder actually consumes
+ * is the RUNG it maps to (`suggestedAdaptiveTier`), so two measurements that
+ * 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: {
     readonly fetchImpl: (url: string, init: {
         signal: AbortSignal;

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

@@ -1,6 +1,7 @@
 import { ReactNode } from 'react';
 import { CamProfile } from '@camstack/types';
 import { ReconnectAction } from './reconnect-schedule';
+import { AdaptiveHintsReport } from './adaptive-downlink';
 type WebkitPresentationMode = 'inline' | 'picture-in-picture' | 'fullscreen';
 declare global {
     interface HTMLVideoElement {
@@ -227,6 +228,21 @@ export interface CameraStreamPlayerProps {
      * Use for network simulation (benchmark) or manual tier forcing.
      */
     hintsOverride?: Partial<ClientStreamHints>;
+    /**
+     * Observer of the ADAPTIVE decision this client just made — fired once per
+     * decision CHANGE (see `adaptiveHintsKey`), never per tick.
+     *
+     * Deliberately the client's half only: the viewport it measured, the pixel
+     * ratio, the downlink it managed to measure (and the origin it probed, null
+     * when none was reachable), and the phase of the offer that carried them.
+     * The hub logs its own pick from the same inputs; duplicating that here
+     * would be a second opinion on someone else's decision. Hosts join the two
+     * halves — the RN viewer forwards this over the embed log bridge so a
+     * "quality is stuck on low" report carries what the app actually SENT.
+     *
+     * Inert unless wired.
+     */
+    onAdaptiveHints?: (report: AdaptiveHintsReport) => void;
     /**
      * Host-driven fast reconnect. Bump this number (monotonic) to force a
      * full reconnect WITHOUT remounting the player — used by the embed when
@@ -258,5 +274,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, 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, reoffer, posterUrl, hintsOverride, onAdaptiveHints, reconnectSignal, onControlChannel, onVideoElement, }: CameraStreamPlayerProps): import("react").JSX.Element;
 export {};

package/dist/composites/index.d.ts

@@ -12,6 +12,7 @@ export { AudioWaveform } from './audio-waveform';
 export type { BatteryBadgeProps, BatteryStatusLike } from './battery-badge';
 export { BatteryBadge } from './battery-badge';
 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 { AutotrackSection } from './cap-settings/AutotrackSection';

package/dist/index.cjs

@@ -24373,6 +24373,62 @@ function stripDownlinkForColdStart(hints) {
 function shouldUpgradeAfterProbe(mbps) {
 	return suggestedAdaptiveTier(mbps) !== "low";
 }
+/** An http(s) origin, or null for anything that cannot serve the probe. */
+function httpOrigin(value) {
+	if (value === void 0 || value === "") return null;
+	let parsed;
+	try {
+		parsed = new URL(value);
+	} catch {
+		return null;
+	}
+	if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return null;
+	return parsed.origin;
+}
+/**
+* The origin `/adaptive-probe` must be fetched from — the HUB, not the page.
+*
+* The page origin was the original assumption ("same-origin as the player",
+* `adaptive-probe.routes.ts`) and it is only true for the web viewer and the
+* iframe embed, both served by the hub. The NATIVE viewer loads this same
+* player from an asset bundled with the app (`useNativeEmbedSource` resolves
+* `assets/embed/camstack-embed.html` through `Image.resolveAssetSource`), so
+* inside the WKWebView `window.location.origin` is `file://` — and
+* `file:///adaptive-probe` is not a request any hub can answer. The probe
+* therefore returned null on EVERY native connect, `downlinkMbps` was never
+* sent, `pickAdaptiveTier` scored every session `default-low`, and
+* `shouldUpgradeAfterProbe` was never even reached — so the make-before-break
+* climb that the cold-start default depends on could not run. That is the
+* whole of "the automatic quality always drops to low" on the app.
+*
+* The hub the player is already talking to is the `serverUrl` prop, so it
+* wins; the page origin remains as the fallback for a host that passes a
+* relative/empty `serverUrl`. Null means no probe is possible and the caller
+* must skip it rather than fetch a URL that cannot exist.
+*/
+function resolveProbeOrigin(serverUrl, pageOrigin) {
+	return httpOrigin(serverUrl) ?? httpOrigin(pageOrigin);
+}
+/**
+* Identity of a decision, for "log once per CHANGE, not per tick".
+*
+* `downlinkMbps` is a fresh measurement on every probe and would otherwise
+* make every offer look like a new decision. What the ladder actually consumes
+* is the RUNG it maps to (`suggestedAdaptiveTier`), so two measurements that
+* pick the same rung are the same decision and must collapse to one line.
+*/
+function adaptiveHintsKey(report) {
+	const rung = report.downlinkMbps === void 0 ? "none" : suggestedAdaptiveTier(report.downlinkMbps);
+	return [
+		report.phase,
+		report.viewportWidth ?? "-",
+		report.viewportHeight ?? "-",
+		report.devicePixelRatio ?? "-",
+		rung,
+		report.prefersTier ?? "-",
+		report.probeOrigin ?? "unreachable"
+	].join("|");
+}
 async function measureDownlinkMbps(origin, deps) {
 	const base = origin.replace(/\/+$/, "");
 	const ctrl = new AbortController();
@@ -24455,9 +24511,19 @@ function computeClientHints(container) {
 }
 var downlinkCache = null;
 var DOWNLINK_TTL_MS = 3e4;
-async function measuredDownlinkMbps() {
-	if (typeof window === "undefined") return void 0;
-	const origin = window.location.origin;
+/**
+* Measure the downlink against the HUB, not the page. `serverUrl` is the hub
+* this player is already signalling to; the page origin is only a fallback,
+* and inside the native WKWebView it is `file://` — see `resolveProbeOrigin`
+* for the full account of what that cost.
+*/
+/** The origin the probe WILL use, for the client's own decision log. */
+function probeOriginFor(serverUrl) {
+	return resolveProbeOrigin(serverUrl, typeof window !== "undefined" ? window.location.origin : void 0);
+}
+async function measuredDownlinkMbps(serverUrl) {
+	const origin = probeOriginFor(serverUrl);
+	if (origin === null) return void 0;
 	if (downlinkCache && downlinkCache.origin === origin && Date.now() - downlinkCache.at < DOWNLINK_TTL_MS) return downlinkCache.mbps;
 	const mbps = await measureDownlinkMbps(origin, {
 		fetchImpl: (url, init) => fetch(url, init),
@@ -24480,7 +24546,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, reoffer, posterUrl, hintsOverride, reconnectSignal, onControlChannel, onVideoElement }) {
+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, 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);
@@ -24504,6 +24570,30 @@ function CameraStreamPlayer({ serverUrl, streamKey, label, autoPlay = true, mute
 		onVideoElementRef.current?.(videoRef.current);
 		return () => onVideoElementRef.current?.(null);
 	}, []);
+	/** Same pattern for the adaptive-decision observer — a ref so wiring it does
+	*  not re-create the mount-stable connect callbacks. */
+	const onAdaptiveHintsRef = (0, react$1.useRef)(onAdaptiveHints);
+	onAdaptiveHintsRef.current = onAdaptiveHints;
+	/** Last reported decision key — the "once per CHANGE, not per tick" latch. */
+	const lastAdaptiveKeyRef = (0, react$1.useRef)(null);
+	/**
+	* Report the hints THIS offer carried, when they differ from the last
+	* reported decision. Mount-stable (`[]` deps by contract) so the connect
+	* callbacks can call it without gaining a dependency.
+	*/
+	const reportAdaptiveHints = (0, react$1.useCallback)((phase, hints, probeOrigin) => {
+		const cb = onAdaptiveHintsRef.current;
+		if (!cb) return;
+		const report = {
+			phase,
+			probeOrigin,
+			...hints
+		};
+		const key = adaptiveHintsKey(report);
+		if (key === lastAdaptiveKeyRef.current) return;
+		lastAdaptiveKeyRef.current = key;
+		cb(report);
+	}, []);
 	/** The live session being polled for `pendingRenegotiation` (client-offer). */
 	const activeSessionIdRef = (0, react$1.useRef)(null);
 	/** Timer for the session-state (renegotiation) poll loop. */
@@ -24636,8 +24726,10 @@ function CameraStreamPlayer({ serverUrl, streamKey, label, autoPlay = true, mute
 		const abort = new AbortController();
 		connectAbortRef.current = abort;
 		try {
-			const probePromise = !withDownlink ? measuredDownlinkMbps() : void 0;
-			const { sessionId, sdpOffer, iceServers } = await createSession(mergePlayerHints(computeClientHints(containerRef.current), hintsOverride, withDownlink ? await measuredDownlinkMbps() : void 0, !withDownlink));
+			const probePromise = !withDownlink ? measuredDownlinkMbps(serverUrl) : void 0;
+			const mergedHints = mergePlayerHints(computeClientHints(containerRef.current), hintsOverride, withDownlink ? await measuredDownlinkMbps(serverUrl) : void 0, !withDownlink);
+			reportAdaptiveHints(withDownlink ? "probe-climb" : "cold-start", mergedHints, probeOriginFor(serverUrl));
+			const { sessionId, sdpOffer, iceServers } = await createSession(mergedHints);
 			sessionIdsRef.current.add(sessionId);
 			if (probePromise !== void 0) probePromise.then((mbps) => {
 				if (mbps === void 0 || !shouldUpgradeAfterProbe(mbps)) return;
@@ -24752,7 +24844,8 @@ function CameraStreamPlayer({ serverUrl, streamKey, label, autoPlay = true, mute
 		closeSession,
 		updateState,
 		onError,
-		hintsOverride
+		hintsOverride,
+		reportAdaptiveHints
 	]);
 	const connectWhep = (0, react$1.useCallback)(async () => {
 		if (!mountedRef.current) return;
@@ -24828,7 +24921,7 @@ function CameraStreamPlayer({ serverUrl, streamKey, label, autoPlay = true, mute
 		const ms = () => Math.round(performance.now() - t0);
 		const timing = {};
 		try {
-			const probePromise = !withDownlink ? measuredDownlinkMbps() : void 0;
+			const probePromise = !withDownlink ? measuredDownlinkMbps(serverUrl) : void 0;
 			const iceServers = await getIceServers?.();
 			timing.iceServersMs = ms();
 			if (!mountedRef.current || abort.signal.aborted) return;
@@ -24936,8 +25029,9 @@ function CameraStreamPlayer({ serverUrl, streamKey, label, autoPlay = true, mute
 			await pc.setLocalDescription(offer);
 			timing.localSetMs = ms();
 			if (!mountedRef.current || abort.signal.aborted) return;
-			const downlinkMbps = withDownlink ? await measuredDownlinkMbps() : void 0;
+			const downlinkMbps = withDownlink ? await measuredDownlinkMbps(serverUrl) : void 0;
 			const clientOfferHints = mergePlayerHints(computeClientHints(containerRef.current), hintsOverride, downlinkMbps, !withDownlink);
+			reportAdaptiveHints(withDownlink ? "probe-climb" : "cold-start", clientOfferHints, probeOriginFor(serverUrl));
 			const signalingStart = ms();
 			const { sessionId: sid, sdpAnswer } = await handleOffer(pc.localDescription?.sdp ?? offer.sdp ?? "", void 0, clientOfferHints);
 			timing.signalingRttMs = ms() - signalingStart;
@@ -24998,6 +25092,7 @@ function CameraStreamPlayer({ serverUrl, streamKey, label, autoPlay = true, mute
 			scheduleReconnect();
 		}
 	}, [
+		serverUrl,
 		handleOffer,
 		getIceServers,
 		addIceCandidate,
@@ -25008,7 +25103,8 @@ function CameraStreamPlayer({ serverUrl, streamKey, label, autoPlay = true, mute
 		updateState,
 		onError,
 		startSessionStatePoll,
-		hintsOverride
+		hintsOverride,
+		reportAdaptiveHints
 	]);
 	renegotiateRef.current = (0, react$1.useCallback)(async (sessionId, target) => {
 		const reofferFn = reoffer;
@@ -25115,12 +25211,13 @@ function CameraStreamPlayer({ serverUrl, streamKey, label, autoPlay = true, mute
 				pc.close();
 				return;
 			}
-			const downlinkMbps = await measuredDownlinkMbps();
+			const downlinkMbps = await measuredDownlinkMbps(serverUrl);
 			const reofferHints = {
 				...computeClientHints(containerRef.current),
 				...downlinkMbps !== void 0 ? { downlinkMbps } : {},
 				...hintsOverride
 			};
+			reportAdaptiveHints("renegotiate", reofferHints, probeOriginFor(serverUrl));
 			const { sessionId: sid, sdpAnswer } = await reofferFn(sessionId, pc.localDescription?.sdp ?? offer.sdp ?? "", target, reofferHints);
 			if (!mountedRef.current) {
 				pc.close();
@@ -25167,13 +25264,15 @@ function CameraStreamPlayer({ serverUrl, streamKey, label, autoPlay = true, mute
 			renegotiatingRef.current = false;
 		}
 	}, [
+		serverUrl,
 		reoffer,
 		getIceServers,
 		addIceCandidate,
 		getIceCandidates,
 		updateState,
 		startSessionStatePoll,
-		hintsOverride
+		hintsOverride,
+		reportAdaptiveHints
 	]);
 	const connect = useClientOffer ? connectClientOffer : useServerOffer ? connectServerOffer : connectWhep;
 	const connectRef = (0, react$1.useRef)(() => {});

package/dist/index.js

@@ -24349,6 +24349,62 @@ function stripDownlinkForColdStart(hints) {
 function shouldUpgradeAfterProbe(mbps) {
 	return suggestedAdaptiveTier(mbps) !== "low";
 }
+/** An http(s) origin, or null for anything that cannot serve the probe. */
+function httpOrigin(value) {
+	if (value === void 0 || value === "") return null;
+	let parsed;
+	try {
+		parsed = new URL(value);
+	} catch {
+		return null;
+	}
+	if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return null;
+	return parsed.origin;
+}
+/**
+* The origin `/adaptive-probe` must be fetched from — the HUB, not the page.
+*
+* The page origin was the original assumption ("same-origin as the player",
+* `adaptive-probe.routes.ts`) and it is only true for the web viewer and the
+* iframe embed, both served by the hub. The NATIVE viewer loads this same
+* player from an asset bundled with the app (`useNativeEmbedSource` resolves
+* `assets/embed/camstack-embed.html` through `Image.resolveAssetSource`), so
+* inside the WKWebView `window.location.origin` is `file://` — and
+* `file:///adaptive-probe` is not a request any hub can answer. The probe
+* therefore returned null on EVERY native connect, `downlinkMbps` was never
+* sent, `pickAdaptiveTier` scored every session `default-low`, and
+* `shouldUpgradeAfterProbe` was never even reached — so the make-before-break
+* climb that the cold-start default depends on could not run. That is the
+* whole of "the automatic quality always drops to low" on the app.
+*
+* The hub the player is already talking to is the `serverUrl` prop, so it
+* wins; the page origin remains as the fallback for a host that passes a
+* relative/empty `serverUrl`. Null means no probe is possible and the caller
+* must skip it rather than fetch a URL that cannot exist.
+*/
+function resolveProbeOrigin(serverUrl, pageOrigin) {
+	return httpOrigin(serverUrl) ?? httpOrigin(pageOrigin);
+}
+/**
+* Identity of a decision, for "log once per CHANGE, not per tick".
+*
+* `downlinkMbps` is a fresh measurement on every probe and would otherwise
+* make every offer look like a new decision. What the ladder actually consumes
+* is the RUNG it maps to (`suggestedAdaptiveTier`), so two measurements that
+* pick the same rung are the same decision and must collapse to one line.
+*/
+function adaptiveHintsKey(report) {
+	const rung = report.downlinkMbps === void 0 ? "none" : suggestedAdaptiveTier(report.downlinkMbps);
+	return [
+		report.phase,
+		report.viewportWidth ?? "-",
+		report.viewportHeight ?? "-",
+		report.devicePixelRatio ?? "-",
+		rung,
+		report.prefersTier ?? "-",
+		report.probeOrigin ?? "unreachable"
+	].join("|");
+}
 async function measureDownlinkMbps(origin, deps) {
 	const base = origin.replace(/\/+$/, "");
 	const ctrl = new AbortController();
@@ -24431,9 +24487,19 @@ function computeClientHints(container) {
 }
 var downlinkCache = null;
 var DOWNLINK_TTL_MS = 3e4;
-async function measuredDownlinkMbps() {
-	if (typeof window === "undefined") return void 0;
-	const origin = window.location.origin;
+/**
+* Measure the downlink against the HUB, not the page. `serverUrl` is the hub
+* this player is already signalling to; the page origin is only a fallback,
+* and inside the native WKWebView it is `file://` — see `resolveProbeOrigin`
+* for the full account of what that cost.
+*/
+/** The origin the probe WILL use, for the client's own decision log. */
+function probeOriginFor(serverUrl) {
+	return resolveProbeOrigin(serverUrl, typeof window !== "undefined" ? window.location.origin : void 0);
+}
+async function measuredDownlinkMbps(serverUrl) {
+	const origin = probeOriginFor(serverUrl);
+	if (origin === null) return void 0;
 	if (downlinkCache && downlinkCache.origin === origin && Date.now() - downlinkCache.at < DOWNLINK_TTL_MS) return downlinkCache.mbps;
 	const mbps = await measureDownlinkMbps(origin, {
 		fetchImpl: (url, init) => fetch(url, init),
@@ -24456,7 +24522,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, reoffer, posterUrl, hintsOverride, reconnectSignal, onControlChannel, onVideoElement }) {
+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, reoffer, posterUrl, hintsOverride, onAdaptiveHints, reconnectSignal, onControlChannel, onVideoElement }) {
 	const videoRef = useRef(null);
 	const containerRef = useRef(null);
 	const pcRef = useRef(null);
@@ -24480,6 +24546,30 @@ function CameraStreamPlayer({ serverUrl, streamKey, label, autoPlay = true, mute
 		onVideoElementRef.current?.(videoRef.current);
 		return () => onVideoElementRef.current?.(null);
 	}, []);
+	/** Same pattern for the adaptive-decision observer — a ref so wiring it does
+	*  not re-create the mount-stable connect callbacks. */
+	const onAdaptiveHintsRef = useRef(onAdaptiveHints);
+	onAdaptiveHintsRef.current = onAdaptiveHints;
+	/** Last reported decision key — the "once per CHANGE, not per tick" latch. */
+	const lastAdaptiveKeyRef = useRef(null);
+	/**
+	* Report the hints THIS offer carried, when they differ from the last
+	* reported decision. Mount-stable (`[]` deps by contract) so the connect
+	* callbacks can call it without gaining a dependency.
+	*/
+	const reportAdaptiveHints = useCallback((phase, hints, probeOrigin) => {
+		const cb = onAdaptiveHintsRef.current;
+		if (!cb) return;
+		const report = {
+			phase,
+			probeOrigin,
+			...hints
+		};
+		const key = adaptiveHintsKey(report);
+		if (key === lastAdaptiveKeyRef.current) return;
+		lastAdaptiveKeyRef.current = key;
+		cb(report);
+	}, []);
 	/** The live session being polled for `pendingRenegotiation` (client-offer). */
 	const activeSessionIdRef = useRef(null);
 	/** Timer for the session-state (renegotiation) poll loop. */
@@ -24612,8 +24702,10 @@ function CameraStreamPlayer({ serverUrl, streamKey, label, autoPlay = true, mute
 		const abort = new AbortController();
 		connectAbortRef.current = abort;
 		try {
-			const probePromise = !withDownlink ? measuredDownlinkMbps() : void 0;
-			const { sessionId, sdpOffer, iceServers } = await createSession(mergePlayerHints(computeClientHints(containerRef.current), hintsOverride, withDownlink ? await measuredDownlinkMbps() : void 0, !withDownlink));
+			const probePromise = !withDownlink ? measuredDownlinkMbps(serverUrl) : void 0;
+			const mergedHints = mergePlayerHints(computeClientHints(containerRef.current), hintsOverride, withDownlink ? await measuredDownlinkMbps(serverUrl) : void 0, !withDownlink);
+			reportAdaptiveHints(withDownlink ? "probe-climb" : "cold-start", mergedHints, probeOriginFor(serverUrl));
+			const { sessionId, sdpOffer, iceServers } = await createSession(mergedHints);
 			sessionIdsRef.current.add(sessionId);
 			if (probePromise !== void 0) probePromise.then((mbps) => {
 				if (mbps === void 0 || !shouldUpgradeAfterProbe(mbps)) return;
@@ -24728,7 +24820,8 @@ function CameraStreamPlayer({ serverUrl, streamKey, label, autoPlay = true, mute
 		closeSession,
 		updateState,
 		onError,
-		hintsOverride
+		hintsOverride,
+		reportAdaptiveHints
 	]);
 	const connectWhep = useCallback(async () => {
 		if (!mountedRef.current) return;
@@ -24804,7 +24897,7 @@ function CameraStreamPlayer({ serverUrl, streamKey, label, autoPlay = true, mute
 		const ms = () => Math.round(performance.now() - t0);
 		const timing = {};
 		try {
-			const probePromise = !withDownlink ? measuredDownlinkMbps() : void 0;
+			const probePromise = !withDownlink ? measuredDownlinkMbps(serverUrl) : void 0;
 			const iceServers = await getIceServers?.();
 			timing.iceServersMs = ms();
 			if (!mountedRef.current || abort.signal.aborted) return;
@@ -24912,8 +25005,9 @@ function CameraStreamPlayer({ serverUrl, streamKey, label, autoPlay = true, mute
 			await pc.setLocalDescription(offer);
 			timing.localSetMs = ms();
 			if (!mountedRef.current || abort.signal.aborted) return;
-			const downlinkMbps = withDownlink ? await measuredDownlinkMbps() : void 0;
+			const downlinkMbps = withDownlink ? await measuredDownlinkMbps(serverUrl) : void 0;
 			const clientOfferHints = mergePlayerHints(computeClientHints(containerRef.current), hintsOverride, downlinkMbps, !withDownlink);
+			reportAdaptiveHints(withDownlink ? "probe-climb" : "cold-start", clientOfferHints, probeOriginFor(serverUrl));
 			const signalingStart = ms();
 			const { sessionId: sid, sdpAnswer } = await handleOffer(pc.localDescription?.sdp ?? offer.sdp ?? "", void 0, clientOfferHints);
 			timing.signalingRttMs = ms() - signalingStart;
@@ -24974,6 +25068,7 @@ function CameraStreamPlayer({ serverUrl, streamKey, label, autoPlay = true, mute
 			scheduleReconnect();
 		}
 	}, [
+		serverUrl,
 		handleOffer,
 		getIceServers,
 		addIceCandidate,
@@ -24984,7 +25079,8 @@ function CameraStreamPlayer({ serverUrl, streamKey, label, autoPlay = true, mute
 		updateState,
 		onError,
 		startSessionStatePoll,
-		hintsOverride
+		hintsOverride,
+		reportAdaptiveHints
 	]);
 	renegotiateRef.current = useCallback(async (sessionId, target) => {
 		const reofferFn = reoffer;
@@ -25091,12 +25187,13 @@ function CameraStreamPlayer({ serverUrl, streamKey, label, autoPlay = true, mute
 				pc.close();
 				return;
 			}
-			const downlinkMbps = await measuredDownlinkMbps();
+			const downlinkMbps = await measuredDownlinkMbps(serverUrl);
 			const reofferHints = {
 				...computeClientHints(containerRef.current),
 				...downlinkMbps !== void 0 ? { downlinkMbps } : {},
 				...hintsOverride
 			};
+			reportAdaptiveHints("renegotiate", reofferHints, probeOriginFor(serverUrl));
 			const { sessionId: sid, sdpAnswer } = await reofferFn(sessionId, pc.localDescription?.sdp ?? offer.sdp ?? "", target, reofferHints);
 			if (!mountedRef.current) {
 				pc.close();
@@ -25143,13 +25240,15 @@ function CameraStreamPlayer({ serverUrl, streamKey, label, autoPlay = true, mute
 			renegotiatingRef.current = false;
 		}
 	}, [
+		serverUrl,
 		reoffer,
 		getIceServers,
 		addIceCandidate,
 		getIceCandidates,
 		updateState,
 		startSessionStatePoll,
-		hintsOverride
+		hintsOverride,
+		reportAdaptiveHints
 	]);
 	const connect = useClientOffer ? connectClientOffer : useServerOffer ? connectServerOffer : connectWhep;
 	const connectRef = useRef(() => {});

package/package.json

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