@camstack/ui-library 1.2.256 → 1.2.258

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

@@ -1,330 +1,330 @@
-import { ReactNode } from 'react';
-import { CamProfile, WebrtcSessionDebug } from '@camstack/types';
-import { ReconnectAction } from './reconnect-schedule';
-import { AdaptiveHintsReport, ApplyDownlinkProbe } 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';
+import { type JSX, type ReactNode } from "react";
+import type { CamProfile, WebrtcSessionDebug } from "@camstack/types";
+import { type ReconnectAction } from "./reconnect-schedule";
+import { type AdaptiveHintsReport, type ApplyDownlinkProbe } from "./adaptive-downlink";
+import { type ClientNetworkSample } from "./client-network-sample";
+import { type StreamDebugSample } from "./stream-debug/webrtc-debug-stats.js";
+type WebkitPresentationMode = "inline" | "picture-in-picture" | "fullscreen";
 declare global {
-    interface HTMLVideoElement {
-        webkitSetPresentationMode?: (mode: WebkitPresentationMode) => void;
-        readonly webkitPresentationMode?: WebkitPresentationMode;
-    }
+	interface HTMLVideoElement {
+		webkitSetPresentationMode?: (mode: WebkitPresentationMode) => void;
+		readonly webkitPresentationMode?: WebkitPresentationMode;
+	}
 }
-export type PlayerConnectionState = 'connecting' | 'playing' | 'error' | 'disconnected' | 'idle';
+export type PlayerConnectionState = "connecting" | "playing" | "error" | "disconnected" | "idle";
 /**
- * Discriminated WebRTC target — same shape as `WebrtcStreamTarget` on the
- * backend cap; the `profile` tier uses the canonical `CamProfile` enum.
- * Carried by `getSessionState`'s `pendingRenegotiation` and handed back to
- * `reoffer` verbatim during an adaptive re-offer.
- */
+* Discriminated WebRTC target — same shape as `WebrtcStreamTarget` on the
+* backend cap; the `profile` tier uses the canonical `CamProfile` enum.
+* Carried by `getSessionState`'s `pendingRenegotiation` and handed back to
+* `reoffer` verbatim during an adaptive re-offer.
+*/
 export type PlayerWebrtcTarget = {
-    readonly kind: 'adaptive';
+	readonly kind: "adaptive";
 } | {
-    readonly kind: 'profile';
-    readonly profile: CamProfile;
+	readonly kind: "profile";
+	readonly profile: CamProfile;
 } | {
-    readonly kind: 'cam-stream';
-    readonly camStreamId: string;
+	readonly kind: "cam-stream";
+	readonly camStreamId: string;
 };
 /** Live signaling state polled mid-stream — the adaptive re-offer signal. */
 export interface SessionSignalingState {
-    readonly pendingRenegotiation: {
-        readonly target: PlayerWebrtcTarget;
-        readonly epoch: number;
-    } | null;
+	readonly pendingRenegotiation: {
+		readonly target: PlayerWebrtcTarget;
+		readonly epoch: number;
+	} | null;
 }
 /**
- * Signaling function for WebRTC connection.
- * Called by the player to establish the WebRTC session.
- * Must return an RTCSessionDescription (the server's offer or answer depending on mode).
- *
- * Server-offer mode (default):
- *   1. signalingFn is called with streamId → returns { sessionId, sdpOffer }
- *   2. Player sets remote description (server offer), creates answer
- *   3. Player calls answerFn(sessionId, sdpAnswer) to complete
- *
- * WHEP mode (legacy):
- *   1. Player creates offer, gathers ICE
- *   2. signalingFn is called with the client SDP offer → returns sdpAnswer
- *   3. Player sets remote description (answer)
- */
+* Signaling function for WebRTC connection.
+* Called by the player to establish the WebRTC session.
+* Must return an RTCSessionDescription (the server's offer or answer depending on mode).
+*
+* Server-offer mode (default):
+*   1. signalingFn is called with streamId → returns { sessionId, sdpOffer }
+*   2. Player sets remote description (server offer), creates answer
+*   3. Player calls answerFn(sessionId, sdpAnswer) to complete
+*
+* WHEP mode (legacy):
+*   1. Player creates offer, gathers ICE
+*   2. signalingFn is called with the client SDP offer → returns sdpAnswer
+*   3. Player sets remote description (answer)
+*/
 export interface SignalingResult {
-    /** Server-offer mode: session ID + SDP offer from server */
-    sessionId: string;
-    sdpOffer: string;
-    /**
-     * ICE servers (STUN/TURN) the BROWSER should use, supplied by the server
-     * from its `turn-provider` cap. Critical for remote viewing: behind CGNAT
-     * (e.g. mobile data) the browser needs a TURN relay candidate or it has no
-     * reachable address and the stream stays black. Falls back to public STUN.
-     */
-    iceServers?: readonly RTCIceServer[];
+	/** Server-offer mode: session ID + SDP offer from server */
+	sessionId: string;
+	sdpOffer: string;
+	/**
+	* ICE servers (STUN/TURN) the BROWSER should use, supplied by the server
+	* from its `turn-provider` cap. Critical for remote viewing: behind CGNAT
+	* (e.g. mobile data) the browser needs a TURN relay candidate or it has no
+	* reachable address and the stream stays black. Falls back to public STUN.
+	*/
+	iceServers?: readonly RTCIceServer[];
 }
 /**
- * Client-offer mode result: the server's SDP answer to a browser-built
- * offer. The browser creates the offer advertising its FULL decode caps
- * (incl. H.264 High on iOS 18), the server answers by echoing the matching
- * codec, and the camera's native bytes pass through untouched — no
- * transcode. This is the dual of `SignalingResult`'s server-offer flow.
- */
+* Client-offer mode result: the server's SDP answer to a browser-built
+* offer. The browser creates the offer advertising its FULL decode caps
+* (incl. H.264 High on iOS 18), the server answers by echoing the matching
+* codec, and the camera's native bytes pass through untouched — no
+* transcode. This is the dual of `SignalingResult`'s server-offer flow.
+*/
 export interface ClientOfferResult {
-    sessionId: string;
-    sdpAnswer: string;
+	sessionId: string;
+	sdpAnswer: string;
 }
 /**
- * Client-side capabilities sent to the server at session creation.
- * The server uses these to pick the best native source for adaptive
- * streams (e.g. a 320×180 thumbnail player on a slow link gets the
- * camera's low stream rather than ffmpeg-transcoded 4K).
- *
- * All fields are optional — when omitted the server defaults to its
- * highest-quality registered source.
- */
+* Client-side capabilities sent to the server at session creation.
+* The server uses these to pick the best native source for adaptive
+* streams (e.g. a 320×180 thumbnail player on a slow link gets the
+* camera's low stream rather than ffmpeg-transcoded 4K).
+*
+* All fields are optional — when omitted the server defaults to its
+* highest-quality registered source.
+*/
 export interface ClientStreamHints {
-    viewportWidth?: number;
-    viewportHeight?: number;
-    devicePixelRatio?: number;
-    downlinkMbps?: number;
-    prefersTier?: string;
+	viewportWidth?: number;
+	viewportHeight?: number;
+	devicePixelRatio?: number;
+	downlinkMbps?: number;
+	prefersTier?: string;
 }
-export type { ClientNetworkSample } from './client-network-sample';
+export type { ClientNetworkSample } from "./client-network-sample";
 export interface CameraStreamPlayerProps {
-    /** Server base URL (e.g. window.location.origin) */
-    serverUrl: string;
-    /**
-     * Stable key used for React reconciliation (the player remounts when
-     * this changes), the snapshot filename, and WHEP fallback URL. The
-     * value is opaque to the player — no parsing, no semantic meaning.
-     * Typical values: a `StreamChoice.id` (`'profile:high'`, `'stream:native:main'`).
-     */
-    streamKey: string;
-    /** Human-readable label shown in overlay */
-    label?: string;
-    /** Auto-play on mount (default: true) */
-    autoPlay?: boolean;
-    /** Start muted (default: true) */
-    muted?: boolean;
-    /** Show toolbar controls (default: true) */
-    showControls?: boolean;
-    /** 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
-     *  existing host log bridge (`{type:'log', scope:'playback'}`), which always
-     *  ships — this is the client half of the recorded stutter census. */
-    onPlaybackStats?: (data: Record<string, unknown>) => void;
-    /**
-     * When provided, samples the inbound-video getStats() ~every 2s and reports
-     * the CLIENT's live network conditions (packet-loss %, jitter, downlink
-     * bitrate, RTT) so the caller can push them to the server's
-     * `networkQuality.reportClientStats`. This is what lets the broker's ADAPTIVE
-     * ladder actually downgrade "auto" under a poor link: without a client
-     * signal the server sees only coarse RTCP RR and tends to stay on the top
-     * 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:
-     * iceServersMs/offerCreatedMs/localSetMs/signalingRttMs/answerSetMs/
-     * iceConnectedMs/firstTrackMs — plus firstFrameMs when the first frame
-     * DECODES, reported separately as a patch call). Lets an embedding host
-     * (the RN app's WebView) ship the numbers to its own logs instead of them
-     * dying in the in-WebView console. Inert unless wired. */
-    onConnectTiming?: (timing: Record<string, number>) => void;
-    /** Additional CSS classes for the root container */
-    className?: string;
-    /** Called on connection state change */
-    onStateChange?: (state: PlayerConnectionState) => void;
-    /** Called on error */
-    onError?: (error: string) => void;
-    /**
-     * Observer of the auto-retry loop: called with every scheduled attempt and
-     * with the exhaustion edge. Hosts wire it to their log pipeline (tagged with
-     * the camera) — a retry loop nobody can see is how a camera stays dark
-     * while looking busy.
-     */
-    onReconnectAttempt?: (action: ReconnectAction) => void;
-    /** Custom overlay rendered on top of the video */
-    overlay?: ReactNode;
-    /**
-     * Create a WebRTC session (server-offer signaling). When provided,
-     * uses server-offer mode instead of WHEP. The caller closes over the
-     * target (profile / cam-stream / adaptive) and any device context;
-     * the player just hands it the auto-derived `hints` (viewport,
-     * downlink) so the server can score adaptive selections.
-     */
-    createSession?: (hints?: ClientStreamHints) => Promise<SignalingResult>;
-    /**
-     * Send the client's SDP answer (server-offer signaling).
-     * Required when createSession is provided.
-     */
-    sendAnswer?: (sessionId: string, sdpAnswer: string) => Promise<void>;
-    /**
-     * Client-offer signaling — PREFERRED over `createSession` when supplied.
-     * The player builds the SDP offer (advertising the browser's full native
-     * decode caps, incl. H.264 High on iOS 18) and this posts it to the
-     * server, which answers by echoing the matching codec. That lets a
-     * Main/High (incl. 4K) source pass through with NO transcode — the only
-     * path that lets iOS decode High. The caller closes over the target.
-     */
-    handleOffer?: (sdpOffer: string, sessionId?: string, hints?: ClientStreamHints) => Promise<ClientOfferResult>;
-    /**
-     * Fetch the browser-side ICE servers (STUN + TURN) for client-offer mode.
-     * Called BEFORE the offer is built so a remote/CGNAT viewer can gather a
-     * relay candidate. Best-effort — resolve `undefined` to use public STUN.
-     */
-    getIceServers?: () => Promise<readonly RTCIceServer[] | undefined>;
-    /** Trickle ICE — push a client-gathered candidate to the server. */
-    addIceCandidate?: (sessionId: string, candidate: RTCIceCandidateInit) => Promise<void>;
-    /** Trickle ICE — poll the server's gathered candidates for a session. */
-    getIceCandidates?: (sessionId: string) => Promise<{
-        candidates: RTCIceCandidateInit[];
-        done: boolean;
-    }>;
-    /** Explicitly close the WebRTC session on server (cleanup on unmount). */
-    closeSession?: (sessionId: string) => Promise<void>;
-    /**
-     * Poll the live signaling state of a session (client-offer mode only).
-     * After the server swaps the broker source to a different tier (adaptive
-     * downgrade), this returns a non-null `pendingRenegotiation` with the new
-     * target + a monotonic `epoch`. The player then transparently re-offers
-     * on the SAME sessionId — building a fresh PeerConnection in the
-     * background and only swapping the live `<video>` to the new stream once
-     * it delivers media, so the last decoded frame stays on screen with no
-     * 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>;
-    /**
-     * Hand the downlink probe to the session it was measured on
-     * (`webrtcSession.applyDownlinkProbe`, D733). The hub then moves THAT
-     * session to the probed rung — in place when it can — so a live open stays
-     * one session. Omit it (or talk to a hub that does not know the method) and
-     * the player keeps its legacy climb: a second, make-before-break session.
-     */
-    applyDownlinkProbe?: ApplyDownlinkProbe;
-    /**
-     * Re-offer signaling for an adaptive tier switch (client-offer mode).
-     * Posts a fresh browser-built offer for an EXISTING `sessionId` against
-     * the new `target` (from `getSessionState`'s `pendingRenegotiation`). The
-     * server closes the stale session and creates a fresh one under the same
-     * id, bound to the new tier's source. Distinct from `handleOffer`, whose
-     * target is fixed at the player's selected stream — a re-offer must carry
-     * the server-chosen downgrade target instead. Required (alongside
-     * `getSessionState`) for adaptive re-offer to run.
-     */
-    reoffer?: (sessionId: string, sdpOffer: string, target: PlayerWebrtcTarget, hints?: ClientStreamHints) => Promise<ClientOfferResult>;
-    /**
-     * Optional poster image (snapshot data-URL) shown by the <video> before
-     * the FIRST-EVER frame is decoded. Only a cold-start fallback — once a
-     * frame is showing, the player keeps the last decoded frame across
-     * renegotiations and never falls back to the poster. Caller-supplied.
-     */
-    posterUrl?: string;
-    /**
-     * Override client hints sent to the server at session creation.
-     * Values provided here replace the auto-computed browser values.
-     * 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
-     * the native shell detects a network change (Wi-Fi↔cellular) or returns
-     * from background. Because `cleanup()` no longer clears `srcObject`, the
-     * LAST DECODED FRAME stays on screen across the reconnect (no black
-     * flash, no covering loader). The initial value is ignored — only
-     * changes trigger a reconnect. Distinct from remounting via `streamKey`,
-     * which blanks the element.
-     */
-    reconnectSignal?: number;
-    /**
-     * Optional control data-channel hook (client-offer mode only). When
-     * provided, the player opens a `camstack-control` `RTCDataChannel` on the
-     * PeerConnection BEFORE building the offer (so it is negotiated into the
-     * m=application section) and hands the channel to this callback for each new
-     * connection. Used by the recorded-playback timeline embed to drive the
-     * broker's `TimelineSession` (seek / scrub-commit / play-rate / go-live) and
-     * receive server state/position over the SAME WebRTC session that carries the
-     * unified live-or-recorded `<video>` track. Omit it (the default) for a plain
-     * live player — no data channel is created and behaviour is unchanged.
-     */
-    onControlChannel?: (channel: RTCDataChannel) => void;
-    /**
-     * Optional handle to the player's `<video>` element, delivered once on mount
-     * (and `null` on unmount). Consumers that pace server-pushed frames by what
-     * the viewer actually RENDERED (`requestVideoFrameCallback`) need the
-     * element itself — the recorded-scrub receiver-credit acks are the use case.
-     */
-    onVideoElement?: (el: HTMLVideoElement | null) => void;
-    /**
-     * DIAGNOSTICS ONLY — the browser's ICE transport policy for every peer
-     * connection this player builds. Absent (always, in production) the policy
-     * is not set and the browser gathers host/srflx/relay as before. The WebRTC
-     * diagnostics set `'relay'` to prove whether a TURN-only path reaches the
-     * hub; see `peer-connection-config.ts` for why the player never does.
-     */
-    iceTransportPolicy?: RTCIceTransportPolicy;
-    /**
-     * Observer of every peer connection this player creates (first connect,
-     * reconnects, re-offers), handed over right after construction and before
-     * any signaling. For listeners only — the diagnostics read ICE / DTLS
-     * transitions and local candidates through `addEventListener`; a caller
-     * must never assign the `on*` handlers the player owns.
-     */
-    onPeerConnection?: (pc: RTCPeerConnection) => void;
+	/** Server base URL (e.g. window.location.origin) */
+	serverUrl: string;
+	/**
+	* Stable key used for React reconciliation (the player remounts when
+	* this changes), the snapshot filename, and WHEP fallback URL. The
+	* value is opaque to the player — no parsing, no semantic meaning.
+	* Typical values: a `StreamChoice.id` (`'profile:high'`, `'stream:native:main'`).
+	*/
+	streamKey: string;
+	/** Human-readable label shown in overlay */
+	label?: string;
+	/** Auto-play on mount (default: true) */
+	autoPlay?: boolean;
+	/** Start muted (default: true) */
+	muted?: boolean;
+	/** Show toolbar controls (default: true) */
+	showControls?: boolean;
+	/** 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
+	*  existing host log bridge (`{type:'log', scope:'playback'}`), which always
+	*  ships — this is the client half of the recorded stutter census. */
+	onPlaybackStats?: (data: Record<string, unknown>) => void;
+	/**
+	* When provided, samples the inbound-video getStats() ~every 2s and reports
+	* the CLIENT's live network conditions (packet-loss %, jitter, downlink
+	* bitrate, RTT) so the caller can push them to the server's
+	* `networkQuality.reportClientStats`. This is what lets the broker's ADAPTIVE
+	* ladder actually downgrade "auto" under a poor link: without a client
+	* signal the server sees only coarse RTCP RR and tends to stay on the top
+	* 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:
+	* iceServersMs/offerCreatedMs/localSetMs/signalingRttMs/answerSetMs/
+	* iceConnectedMs/firstTrackMs — plus firstFrameMs when the first frame
+	* DECODES, reported separately as a patch call). Lets an embedding host
+	* (the RN app's WebView) ship the numbers to its own logs instead of them
+	* dying in the in-WebView console. Inert unless wired. */
+	onConnectTiming?: (timing: Record<string, number>) => void;
+	/** Additional CSS classes for the root container */
+	className?: string;
+	/** Called on connection state change */
+	onStateChange?: (state: PlayerConnectionState) => void;
+	/** Called on error */
+	onError?: (error: string) => void;
+	/**
+	* Observer of the auto-retry loop: called with every scheduled attempt and
+	* with the exhaustion edge. Hosts wire it to their log pipeline (tagged with
+	* the camera) — a retry loop nobody can see is how a camera stays dark
+	* while looking busy.
+	*/
+	onReconnectAttempt?: (action: ReconnectAction) => void;
+	/** Custom overlay rendered on top of the video */
+	overlay?: ReactNode;
+	/**
+	* Create a WebRTC session (server-offer signaling). When provided,
+	* uses server-offer mode instead of WHEP. The caller closes over the
+	* target (profile / cam-stream / adaptive) and any device context;
+	* the player just hands it the auto-derived `hints` (viewport,
+	* downlink) so the server can score adaptive selections.
+	*/
+	createSession?: (hints?: ClientStreamHints) => Promise<SignalingResult>;
+	/**
+	* Send the client's SDP answer (server-offer signaling).
+	* Required when createSession is provided.
+	*/
+	sendAnswer?: (sessionId: string, sdpAnswer: string) => Promise<void>;
+	/**
+	* Client-offer signaling — PREFERRED over `createSession` when supplied.
+	* The player builds the SDP offer (advertising the browser's full native
+	* decode caps, incl. H.264 High on iOS 18) and this posts it to the
+	* server, which answers by echoing the matching codec. That lets a
+	* Main/High (incl. 4K) source pass through with NO transcode — the only
+	* path that lets iOS decode High. The caller closes over the target.
+	*/
+	handleOffer?: (sdpOffer: string, sessionId?: string, hints?: ClientStreamHints) => Promise<ClientOfferResult>;
+	/**
+	* Fetch the browser-side ICE servers (STUN + TURN) for client-offer mode.
+	* Called BEFORE the offer is built so a remote/CGNAT viewer can gather a
+	* relay candidate. Best-effort — resolve `undefined` to use public STUN.
+	*/
+	getIceServers?: () => Promise<readonly RTCIceServer[] | undefined>;
+	/** Trickle ICE — push a client-gathered candidate to the server. */
+	addIceCandidate?: (sessionId: string, candidate: RTCIceCandidateInit) => Promise<void>;
+	/** Trickle ICE — poll the server's gathered candidates for a session. */
+	getIceCandidates?: (sessionId: string) => Promise<{
+		candidates: RTCIceCandidateInit[];
+		done: boolean;
+	}>;
+	/** Explicitly close the WebRTC session on server (cleanup on unmount). */
+	closeSession?: (sessionId: string) => Promise<void>;
+	/**
+	* Poll the live signaling state of a session (client-offer mode only).
+	* After the server swaps the broker source to a different tier (adaptive
+	* downgrade), this returns a non-null `pendingRenegotiation` with the new
+	* target + a monotonic `epoch`. The player then transparently re-offers
+	* on the SAME sessionId — building a fresh PeerConnection in the
+	* background and only swapping the live `<video>` to the new stream once
+	* it delivers media, so the last decoded frame stays on screen with no
+	* 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>;
+	/**
+	* Hand the downlink probe to the session it was measured on
+	* (`webrtcSession.applyDownlinkProbe`, D733). The hub then moves THAT
+	* session to the probed rung — in place when it can — so a live open stays
+	* one session. Omit it (or talk to a hub that does not know the method) and
+	* the player keeps its legacy climb: a second, make-before-break session.
+	*/
+	applyDownlinkProbe?: ApplyDownlinkProbe;
+	/**
+	* Re-offer signaling for an adaptive tier switch (client-offer mode).
+	* Posts a fresh browser-built offer for an EXISTING `sessionId` against
+	* the new `target` (from `getSessionState`'s `pendingRenegotiation`). The
+	* server closes the stale session and creates a fresh one under the same
+	* id, bound to the new tier's source. Distinct from `handleOffer`, whose
+	* target is fixed at the player's selected stream — a re-offer must carry
+	* the server-chosen downgrade target instead. Required (alongside
+	* `getSessionState`) for adaptive re-offer to run.
+	*/
+	reoffer?: (sessionId: string, sdpOffer: string, target: PlayerWebrtcTarget, hints?: ClientStreamHints) => Promise<ClientOfferResult>;
+	/**
+	* Optional poster image (snapshot data-URL) shown by the <video> before
+	* the FIRST-EVER frame is decoded. Only a cold-start fallback — once a
+	* frame is showing, the player keeps the last decoded frame across
+	* renegotiations and never falls back to the poster. Caller-supplied.
+	*/
+	posterUrl?: string;
+	/**
+	* Override client hints sent to the server at session creation.
+	* Values provided here replace the auto-computed browser values.
+	* 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
+	* the native shell detects a network change (Wi-Fi↔cellular) or returns
+	* from background. Because `cleanup()` no longer clears `srcObject`, the
+	* LAST DECODED FRAME stays on screen across the reconnect (no black
+	* flash, no covering loader). The initial value is ignored — only
+	* changes trigger a reconnect. Distinct from remounting via `streamKey`,
+	* which blanks the element.
+	*/
+	reconnectSignal?: number;
+	/**
+	* Optional control data-channel hook (client-offer mode only). When
+	* provided, the player opens a `camstack-control` `RTCDataChannel` on the
+	* PeerConnection BEFORE building the offer (so it is negotiated into the
+	* m=application section) and hands the channel to this callback for each new
+	* connection. Used by the recorded-playback timeline embed to drive the
+	* broker's `TimelineSession` (seek / scrub-commit / play-rate / go-live) and
+	* receive server state/position over the SAME WebRTC session that carries the
+	* unified live-or-recorded `<video>` track. Omit it (the default) for a plain
+	* live player — no data channel is created and behaviour is unchanged.
+	*/
+	onControlChannel?: (channel: RTCDataChannel) => void;
+	/**
+	* Optional handle to the player's `<video>` element, delivered once on mount
+	* (and `null` on unmount). Consumers that pace server-pushed frames by what
+	* the viewer actually RENDERED (`requestVideoFrameCallback`) need the
+	* element itself — the recorded-scrub receiver-credit acks are the use case.
+	*/
+	onVideoElement?: (el: HTMLVideoElement | null) => void;
+	/**
+	* DIAGNOSTICS ONLY — the browser's ICE transport policy for every peer
+	* connection this player builds. Absent (always, in production) the policy
+	* is not set and the browser gathers host/srflx/relay as before. The WebRTC
+	* diagnostics set `'relay'` to prove whether a TURN-only path reaches the
+	* hub; see `peer-connection-config.ts` for why the player never does.
+	*/
+	iceTransportPolicy?: RTCIceTransportPolicy;
+	/**
+	* Observer of every peer connection this player creates (first connect,
+	* reconnects, re-offers), handed over right after construction and before
+	* any signaling. For listeners only — the diagnostics read ICE / DTLS
+	* transitions and local candidates through `addEventListener`; a caller
+	* must never assign the `on*` handlers the player owns.
+	*/
+	onPeerConnection?: (pc: RTCPeerConnection) => void;
 }
-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, applyDownlinkProbe, reoffer, posterUrl, hintsOverride, onAdaptiveHints, reconnectSignal, onControlChannel, onVideoElement, iceTransportPolicy, onPeerConnection, }: CameraStreamPlayerProps): import("react").JSX.Element;
+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, applyDownlinkProbe, reoffer, posterUrl, hintsOverride, onAdaptiveHints, reconnectSignal, onControlChannel, onVideoElement, iceTransportPolicy, onPeerConnection }: CameraStreamPlayerProps): JSX.Element;