@evolve.ui/core-components 1.0.1 → 1.1.0

package/src/WebRTCPlayer/hooks/useWebRTCStream.ts

@@ -0,0 +1,571 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+import { NativeWebRTCAdaptor } from '../adaptor/NativeWebRTCAdaptor';
+import {
+    DEFAULT_PATH,
+    DEFAULT_WS_PORT,
+    DEFAULT_WSS_PORT,
+    FETCH_STREAM_ID_TIMEOUT,
+    PING_INTERVAL,
+    RECONNECT_INTERVAL,
+    WebRTCConfig,
+    WebRTCConnectionState,
+    WebRTCErrorToken,
+    WebRTCPlayerState,
+} from '../types';
+
+/**
+ * Races a value/promise against a timeout, resolving to `undefined` if the
+ * timeout wins. Used to prevent a hung host-supplied fetchStreamId() from
+ * permanently blocking the reconnect loop.
+ */
+const withTimeout = async <T>(value: Promise<T> | T, ms: number): Promise<T | undefined> => {
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const valuePromise = Promise.resolve(value);
+    // If the timeout wins the race, the value promise is left dangling. Attach a
+    // no-op catch so a late rejection doesn't surface as an unhandledRejection.
+    // (An early rejection still propagates through Promise.race to the caller.)
+    valuePromise.catch(() => undefined);
+    try {
+        return await Promise.race([
+            valuePromise,
+            new Promise<undefined>((resolve) => {
+                timer = setTimeout(() => {
+                    resolve(undefined);
+                }, ms);
+            }),
+        ]);
+    } finally {
+        if (timer) {
+            clearTimeout(timer);
+        }
+    }
+};
+
+/**
+ * Maps adaptor error tokens to user-facing copy so raw identifiers like
+ * `IceConnectionFailed` never reach the error overlay. Keyed off the shared
+ * WebRTCErrorToken constants so this map can't drift from what the adaptor emits.
+ */
+const FRIENDLY_ERROR_MESSAGES = new Map<string, string>([
+    [WebRTCErrorToken.failedToCreateAnswer, 'Connection lost'],
+    [WebRTCErrorToken.failedToSetLocalDescription, 'Connection lost'],
+    [WebRTCErrorToken.failedToSetRemoteDescription, 'Connection lost'],
+    [WebRTCErrorToken.iceConnectionFailed, 'Connection lost'],
+    [WebRTCErrorToken.peerConnectionFailed, 'Connection lost'],
+    [WebRTCErrorToken.webSocketError, 'Connection lost'],
+    [WebRTCErrorToken.webSocketNotConnected, 'Connection lost'],
+    [WebRTCErrorToken.webSocketNotSupported, 'Your browser does not support live streaming'],
+]);
+
+const toFriendlyError = (raw: string): string => FRIENDLY_ERROR_MESSAGES.get(raw) ?? raw;
+
+/**
+ * Custom hook for managing WebRTC stream connections to Ant Media Server
+ *
+ * This hook handles the complete lifecycle of a WebRTC stream connection including:
+ * - WebSocket connection management
+ * - RTCPeerConnection setup and negotiation
+ * - Stream state management (loading, playing, error, reconnecting)
+ * - Automatic reconnection on connection failure
+ * - Proper cleanup on unmount
+ *
+ * @param config - Configuration object for the WebRTC connection
+ * @returns WebRTC player state including video ref, loading state, playing state, error, and mute controls
+ *
+ * @example
+ * ```tsx
+ * const { videoRef, loading, playing, error } = useWebRTCStream({
+ *   streamId: 'my-stream-id',
+ *   hostname: 'media.example.com'
+ * });
+ *
+ * return (
+ *   <video ref={videoRef} autoPlay playsInline />
+ * );
+ * ```
+ */
+export const useWebRTCStream = ({
+    debug = false,
+    fetchStreamId,
+    hostname,
+    streamId,
+    wsPort = DEFAULT_WS_PORT,
+    wssPort = DEFAULT_WSS_PORT,
+}: WebRTCConfig): WebRTCPlayerState => {
+    const videoRef = useRef<HTMLVideoElement>(null);
+    const [loading, setLoading] = useState(true);
+    const [error, setError] = useState<string | null>(null);
+    const [connectionState, setConnectionState] = useState<WebRTCConnectionState>('idle');
+
+    const webRTCAdaptorRef = useRef<NativeWebRTCAdaptor | null>(null);
+    const reconnectIntervalRef = useRef<ReturnType<typeof setInterval> | null>(null);
+    const pingIntervalRef = useRef<ReturnType<typeof setInterval> | null>(null);
+    const isReconnectingRef = useRef(false);
+    // True while the component is mounted; lets async init bail after an await if
+    // the component has since unmounted (avoids setState/adaptor build post-teardown).
+    const isMountedRef = useRef(true);
+    // Monotonic token identifying the current connection attempt. Each
+    // initializeWebRTC() call claims a fresh token; if a newer attempt starts
+    // (reconnect tick, streamId prop change), the older one becomes stale and
+    // bails at the next checkpoint instead of building an adaptor or mutating
+    // shared state — preventing overlapping adaptors and stale-id connects.
+    const initTokenRef = useRef(0);
+    // Holds the latest initializeWebRTC so the reconnect loop never calls a stale
+    // closure (and so handleError/handleCallback don't need to depend on it).
+    /* istanbul ignore next -- @preserve: the default initializer is never invoked; an effect overwrites this ref on first commit, and no reconnect (the only caller) can fire before the mount effect creates an adaptor. */
+    const initializeWebRTCRef = useRef<() => void | Promise<void>>(() => undefined);
+    // The stream ID the adaptor is currently using. Defaults to the streamId prop
+    // and is refreshed by fetchStreamId() before each reconnect attempt.
+    const activeStreamIdRef = useRef(streamId);
+    // Latest fetchStreamId, held in a ref so the reconnect path always calls the
+    // current one without needing it in any dependency array.
+    const fetchStreamIdRef = useRef(fetchStreamId);
+    fetchStreamIdRef.current = fetchStreamId;
+
+    /**
+     * Generates the WebSocket URL based on the current page protocol
+     */
+    const getWebSocketUrl = useCallback(() => {
+        const isSecure = window.location.protocol === 'https:';
+        const protocol = isSecure ? 'wss' : 'ws';
+        const port = isSecure ? wssPort : wsPort;
+        const url = `${protocol}://${hostname}:${port}${DEFAULT_PATH}`;
+
+        if (debug) {
+            // eslint-disable-next-line no-console
+            console.log('[WebRTC] Generated WebSocket URL:', {
+                hostname,
+                isSecure,
+                location: window.location.protocol,
+                port,
+                protocol,
+                url,
+            });
+        }
+
+        return url;
+    }, [hostname, wsPort, wssPort, debug]);
+
+    /**
+     * Clears reconnection interval
+     */
+    const stopReconnecting = useCallback(() => {
+        if (reconnectIntervalRef.current) {
+            clearInterval(reconnectIntervalRef.current);
+            reconnectIntervalRef.current = null;
+        }
+        isReconnectingRef.current = false;
+    }, []);
+
+    /**
+     * Starts the reconnection loop if one is not already running.
+     *
+     * Any failure signal (WebSocket error, WebSocket close, or the stream
+     * finishing) funnels through here so that a dropped connection always
+     * triggers recovery. The loop is idempotent — guarded by isReconnectingRef —
+     * and is cleared by stopReconnecting() once the stream re-initializes or
+     * starts playing again.
+     *
+     * The loop retries indefinitely (no max-attempt cap) by design: a live stream
+     * can resume minutes after dropping, so we keep attempting every
+     * RECONNECT_INTERVAL until it returns or the component unmounts.
+     */
+    const startReconnecting = useCallback(() => {
+        if (isReconnectingRef.current) {
+            return;
+        }
+
+        if (debug) {
+            // eslint-disable-next-line no-console
+            console.log(`[WebRTC] Starting reconnection attempts (every ${RECONNECT_INTERVAL}ms)`);
+        }
+
+        isReconnectingRef.current = true;
+        reconnectIntervalRef.current = setInterval(() => {
+            if (debug) {
+                // eslint-disable-next-line no-console
+                console.log('[WebRTC] 🔄 Attempting to reconnect...');
+            }
+            // initializeWebRTC sets the 'reconnecting' state while isReconnectingRef is true.
+            void initializeWebRTCRef.current();
+        }, RECONNECT_INTERVAL);
+    }, [debug]);
+
+    /**
+     * Starts ping interval to keep connection alive
+     */
+    const startPinging = useCallback(() => {
+        if (pingIntervalRef.current) {
+            clearInterval(pingIntervalRef.current);
+        }
+
+        pingIntervalRef.current = setInterval(() => {
+            const activeStreamId = activeStreamIdRef.current;
+            if (webRTCAdaptorRef.current && activeStreamId) {
+                try {
+                    webRTCAdaptorRef.current.ping(activeStreamId);
+                } catch (err) {
+                    if (debug) {
+                        // eslint-disable-next-line no-console
+                        console.error('Error sending ping:', err);
+                    }
+                }
+            }
+        }, PING_INTERVAL);
+    }, [debug]);
+
+    /**
+     * Stops ping interval
+     */
+    const stopPinging = useCallback(() => {
+        if (pingIntervalRef.current) {
+            clearInterval(pingIntervalRef.current);
+            pingIntervalRef.current = null;
+        }
+    }, []);
+
+    /**
+     * Handles WebRTC adaptor callbacks
+     */
+    const handleCallback = useCallback(
+        (info: string, obj?: unknown) => {
+            // A late callback can arrive after unmount (e.g. closeWebSocket() during
+            // cleanup triggers onclose). Ignore it so we don't setState or re-arm the
+            // reconnect interval on a torn-down component.
+            if (!isMountedRef.current) {
+                return;
+            }
+
+            if (debug) {
+                // eslint-disable-next-line no-console
+                console.log(`[WebRTC] Callback: ${info}`, obj);
+            }
+
+            switch (info) {
+                case 'initialized':
+                    if (debug) {
+                        // eslint-disable-next-line no-console
+                        console.log('[WebRTC] ✅ Initialized - WebSocket connected, starting playback');
+                    }
+                    setConnectionState('connected');
+                    setLoading(true);
+                    stopReconnecting();
+                    startPinging();
+                    // Start playing the stream using the ID the adaptor connected with
+                    if (webRTCAdaptorRef.current && activeStreamIdRef.current) {
+                        if (debug) {
+                            // eslint-disable-next-line no-console
+                            console.log(`[WebRTC] Calling play() for streamId: ${activeStreamIdRef.current}`);
+                        }
+                        webRTCAdaptorRef.current.play(activeStreamIdRef.current);
+                    }
+                    break;
+
+                case 'play_started':
+                    if (debug) {
+                        // eslint-disable-next-line no-console
+                        console.log('[WebRTC] ✅ Play started - Stream is now playing');
+                    }
+                    setConnectionState('playing');
+                    setLoading(false);
+                    // setPlaying(true);
+                    setError(null);
+                    stopReconnecting();
+                    break;
+
+                case 'play_finished':
+                    if (debug) {
+                        // eslint-disable-next-line no-console
+                        console.log('[WebRTC] ⚠️ Play finished - Stream ended');
+                    }
+                    setConnectionState('error');
+                    setError('Stream ended');
+                    // A finished stream is treated as a recoverable failure: the
+                    // stream may simply have restarted on the server. Attempt to
+                    // reconnect rather than leaving the player dead.
+                    startReconnecting();
+                    break;
+
+                case 'closed':
+                    if (debug) {
+                        // eslint-disable-next-line no-console
+                        console.log('[WebRTC] ❌ Connection closed');
+                    }
+                    setConnectionState('error');
+                    setError('Connection closed');
+                    // A dropped WebSocket is reported via callback('closed'), NOT
+                    // callbackError, so the reconnect loop must be started here too
+                    // — otherwise a network failure leaves the player stuck.
+                    startReconnecting();
+                    break;
+
+                case 'publish_started':
+                case 'publish_finished':
+                case 'ice_connection_state_changed':
+                case 'updated_stats':
+                case 'data_received':
+                default:
+                    if (debug) {
+                        // eslint-disable-next-line no-console
+                        console.log(`[WebRTC] Unhandled callback: ${info}`, obj);
+                    }
+            }
+        },
+        [debug, startPinging, stopReconnecting, startReconnecting]
+    );
+
+    /**
+     * Handles WebRTC adaptor errors
+     */
+    const handleError = useCallback(
+        (errorMessage: string, errorObject?: unknown) => {
+            // Ignore late errors from an adaptor that outlived the component.
+            if (!isMountedRef.current) {
+                return;
+            }
+
+            // eslint-disable-next-line no-console
+            console.error('[WebRTC] ❌ Error:', errorMessage, errorObject);
+            setConnectionState('error');
+            setLoading(false);
+            setError(toFriendlyError(errorMessage));
+
+            // Start reconnection attempts if not already reconnecting
+            startReconnecting();
+        },
+        [startReconnecting]
+    );
+
+    /**
+     * Initializes the WebRTC adaptor
+     */
+    const initializeWebRTC = useCallback(async () => {
+        if (!activeStreamIdRef.current) {
+            // eslint-disable-next-line no-console
+            console.error('[WebRTC] ❌ No stream ID provided');
+            setError('No stream ID provided');
+            return;
+        }
+
+        // Claim this attempt. Any later attempt bumps the token, marking this one
+        // stale. `isCurrent()` is checked after every await so a superseded or
+        // unmounted attempt bails before mutating shared state / building an adaptor.
+        const token = ++initTokenRef.current;
+        const isCurrent = () => token === initTokenRef.current && isMountedRef.current;
+
+        // Clean up existing adaptor (using the ID it was created with, before we
+        // potentially swap in a freshly fetched one below).
+        if (webRTCAdaptorRef.current) {
+            if (debug) {
+                // eslint-disable-next-line no-console
+                console.log('[WebRTC] Cleaning up existing adaptor');
+            }
+            try {
+                stopPinging();
+                webRTCAdaptorRef.current.stop(activeStreamIdRef.current);
+                webRTCAdaptorRef.current.closeWebSocket();
+            } catch (err) {
+                // eslint-disable-next-line no-console
+                console.error('[WebRTC] Error cleaning up previous adaptor:', err);
+            }
+            webRTCAdaptorRef.current = null;
+        }
+
+        // Preserve the 'reconnecting' state across the rebuild so the UI can
+        // surface it; a first-time connect uses 'connecting'.
+        const reconnecting = isReconnectingRef.current;
+        setConnectionState(reconnecting ? 'reconnecting' : 'connecting');
+        // On a reconnect tick keep `loading` false: the error overlay (and its
+        // "Attempting to reconnect…" caption) is gated behind `!loading`, and the
+        // failure handler that started the loop has already set `error`, so leaving
+        // loading false is what makes the reconnecting UI visible. Only a first-time
+        // connect shows the loading spinner.
+        setLoading(!reconnecting);
+
+        // On reconnect, give the host a chance to supply a fresh stream ID — a
+        // restarted stream is usually issued a new ID, so reusing the old one
+        // would just reconnect to a dead stream. Bounded by a timeout so a hung
+        // callback can't wedge the reconnect loop.
+        if (isReconnectingRef.current && fetchStreamIdRef.current) {
+            try {
+                const freshStreamId = await withTimeout(fetchStreamIdRef.current(), FETCH_STREAM_ID_TIMEOUT);
+                // A newer attempt (e.g. a streamId prop change) may have superseded
+                // us during the await. Don't clobber its ID or continue this build.
+                if (!isCurrent()) {
+                    return;
+                }
+                if (freshStreamId) {
+                    if (debug && freshStreamId !== activeStreamIdRef.current) {
+                        // eslint-disable-next-line no-console
+                        console.log(`[WebRTC] Refreshed stream ID: ${activeStreamIdRef.current} -> ${freshStreamId}`);
+                    }
+                    activeStreamIdRef.current = freshStreamId;
+                }
+            } catch (err) {
+                // eslint-disable-next-line no-console
+                console.error('[WebRTC] fetchStreamId failed, reusing current stream ID:', err);
+                if (!isCurrent()) {
+                    return;
+                }
+            }
+        }
+
+        // Final checkpoint before building: bail if unmounted or superseded.
+        if (!isCurrent()) {
+            if (debug) {
+                // eslint-disable-next-line no-console
+                console.log('[WebRTC] Initialization superseded or unmounted, aborting');
+            }
+            return;
+        }
+
+        const activeStreamId = activeStreamIdRef.current;
+
+        if (debug) {
+            // eslint-disable-next-line no-console
+            console.log(`[WebRTC] 🚀 Initializing WebRTC for streamId: ${activeStreamId}`);
+        }
+
+        try {
+            const websocketUrl = getWebSocketUrl();
+
+            // Ensure video element has an ID before creating adaptor
+            if (videoRef.current && !videoRef.current.id) {
+                videoRef.current.id = 'webrtc-video-' + activeStreamId;
+            }
+            const videoId = videoRef.current?.id || 'webrtc-video';
+
+            if (debug) {
+                // eslint-disable-next-line no-console
+                console.log('[WebRTC] Creating WebRTCAdaptor with config:', {
+                    isPlayMode: true,
+                    remoteVideoId: videoId,
+                    streamId: activeStreamId,
+                    websocket_url: websocketUrl,
+                });
+            }
+
+            webRTCAdaptorRef.current = new NativeWebRTCAdaptor({
+                callback: handleCallback,
+                callbackError: handleError,
+                debug,
+                peerconnection_config: {
+                    iceServers: [{ urls: 'stun:stun.l.google.com:19302' }],
+                },
+                remoteVideoId: videoId,
+                sdp_constraints: {
+                    offerToReceiveAudio: true,
+                    offerToReceiveVideo: true,
+                },
+                websocket_url: websocketUrl,
+            });
+
+            if (debug) {
+                // eslint-disable-next-line no-console
+                console.log('[WebRTC] ✅ WebRTCAdaptor created, waiting for connection...');
+            }
+        } catch (err) {
+            // eslint-disable-next-line no-console
+            console.error('[WebRTC] ❌ Failed to initialize WebRTC:', err);
+            handleError('Failed to initialize WebRTC', err);
+        }
+    }, [debug, getWebSocketUrl, handleCallback, handleError, stopPinging]);
+
+    /**
+     * Track mount status so async init can bail after an await once the component
+     * has unmounted. Kept separate from the streamId-scoped cleanup effect below
+     * so a prop change never flips this to unmounted.
+     */
+    useEffect(() => {
+        isMountedRef.current = true;
+        return () => {
+            isMountedRef.current = false;
+        };
+    }, []);
+
+    /**
+     * Keep the ref pointed at the latest initializeWebRTC so the reconnect loop
+     * always reconnects with the current streamId/config rather than a closure
+     * captured when the loop first started.
+     */
+    useEffect(() => {
+        initializeWebRTCRef.current = initializeWebRTC;
+    }, [initializeWebRTC]);
+
+    /**
+     * Initialize WebRTC connection on mount or when streamId changes
+     */
+    useEffect(() => {
+        if (streamId) {
+            if (debug) {
+                // eslint-disable-next-line no-console
+                console.log('[WebRTC] StreamId changed or component mounted, scheduling initialization');
+            }
+            // A streamId prop change is authoritative and supersedes any ID
+            // previously fetched during reconnection.
+            activeStreamIdRef.current = streamId;
+            // Small delay to ensure video element is mounted
+            const timeoutId = setTimeout(() => {
+                void initializeWebRTC();
+            }, 100);
+
+            return () => {
+                clearTimeout(timeoutId);
+            };
+        }
+        return undefined;
+    }, [streamId, initializeWebRTC, debug]);
+
+    /**
+     * Cleanup on unmount
+     */
+    useEffect(() => {
+        return () => {
+            if (debug) {
+                // eslint-disable-next-line no-console
+                console.log('[WebRTC] 🧹 Cleaning up on unmount');
+            }
+            stopReconnecting();
+            stopPinging();
+
+            if (webRTCAdaptorRef.current && activeStreamIdRef.current) {
+                try {
+                    webRTCAdaptorRef.current.stop(activeStreamIdRef.current);
+                    webRTCAdaptorRef.current.closeWebSocket();
+                    if (debug) {
+                        // eslint-disable-next-line no-console
+                        console.log('[WebRTC] ✅ Cleanup complete');
+                    }
+                } catch (err) {
+                    // eslint-disable-next-line no-console
+                    console.error('[WebRTC] Error during cleanup:', err);
+                }
+            }
+
+            webRTCAdaptorRef.current = null;
+        };
+    }, [streamId, debug, stopReconnecting, stopPinging]);
+
+    /**
+     * Assign the stream to the video element when it's available
+     */
+    useEffect(() => {
+        if (videoRef.current && webRTCAdaptorRef.current) {
+            const remoteVideo = videoRef.current;
+
+            // The Ant Media adaptor will set the srcObject automatically
+            // We just need to ensure the video element has the correct ID
+            if (!remoteVideo.id) {
+                remoteVideo.id = 'webrtc-video-' + streamId;
+            }
+        }
+    }, [streamId]);
+
+    return {
+        connectionState,
+        error,
+        loading,
+        videoRef: videoRef as React.RefObject<HTMLVideoElement>,
+    };
+};

package/src/WebRTCPlayer/index.ts

@@ -0,0 +1,22 @@
+/**
+ * WebRTC video player for streaming from Ant Media Server
+ *
+ * @module
+ * Components:
+ * - WebRTCPlayer: Complete WebRTC video player with connection management and UI
+ *
+ * Hooks:
+ * - useWebRTCStream: Custom hook for managing WebRTC stream connections
+ *
+ * Types:
+ * - WebRTCPlayerProps: Props for the WebRTCPlayer component
+ * - WebRTCConfig: Configuration for WebRTC connections
+ * - WebRTCPlayerState: State returned by useWebRTCStream hook
+ * - WebRTCConnectionState: Connection state enum
+ */
+
+export { WebRTCPlayer } from './WebRTCPlayer';
+export type { WebRTCPlayerProps } from './WebRTCPlayer';
+export { useWebRTCStream } from './hooks/useWebRTCStream';
+export type { WebRTCConfig, WebRTCPlayerState, WebRTCConnectionState } from './types';
+export { DEFAULT_WS_PORT, DEFAULT_WSS_PORT, DEFAULT_PATH, RECONNECT_INTERVAL, PING_INTERVAL } from './types';

package/src/WebRTCPlayer/types.ts

@@ -0,0 +1,95 @@
+/**
+ * Configuration constants for WebRTC player
+ */
+export const DEFAULT_WS_PORT = 5080;
+export const DEFAULT_WSS_PORT = 5443;
+export const DEFAULT_PATH = '/WebRTCAppEE/websocket';
+// Interval between reconnect attempts. The reconnect loop retries indefinitely
+// (no max-attempt cap) by design: a live stream can resume minutes after
+// dropping, so the player keeps attempting until the stream returns or the
+// component unmounts.
+export const RECONNECT_INTERVAL = 5000; // 5 seconds
+export const PING_INTERVAL = 30000; // 30 seconds
+// Cap on how long to wait for a host-supplied fetchStreamId() before falling back
+// to the current ID, so a hung callback can't permanently block reconnection.
+// INVARIANT: must stay strictly below RECONNECT_INTERVAL. The reconnect loop
+// awaits fetchStreamId() on each tick, so a timeout >= the interval would let the
+// next tick start while the previous one is still awaiting, producing overlapping
+// reconnect attempts.
+export const FETCH_STREAM_ID_TIMEOUT = 3000; // 3 seconds
+
+/**
+ * WebRTC connection state
+ */
+export type WebRTCConnectionState = 'idle' | 'connecting' | 'connected' | 'playing' | 'error' | 'reconnecting';
+
+/**
+ * Error tokens emitted by NativeWebRTCAdaptor via its callbackError channel.
+ * Exported so the adaptor (producer) and the hook's friendly-message map
+ * (consumer) reference the same literals and can't silently drift apart — a
+ * rename here is a compile error on both sides rather than a silent fallthrough.
+ */
+export const WebRTCErrorToken = {
+    failedToCreateAnswer: 'Failed to create answer',
+    failedToSetLocalDescription: 'Failed to set local description',
+    failedToSetRemoteDescription: 'Failed to set remote description',
+    iceConnectionFailed: 'IceConnectionFailed',
+    peerConnectionFailed: 'PeerConnectionFailed',
+    webSocketError: 'WebSocket error',
+    webSocketNotConnected: 'WebSocketNotConnected',
+    webSocketNotSupported: 'WebSocketNotSupported',
+} as const;
+
+export type WebRTCErrorToken = (typeof WebRTCErrorToken)[keyof typeof WebRTCErrorToken];
+
+/**
+ * WebRTC adaptor callback information types
+ */
+export type WebRTCCallbackInfo =
+    | 'initialized'
+    | 'play_started'
+    | 'play_finished'
+    | 'publish_started'
+    | 'publish_finished'
+    | 'closed'
+    | 'ice_connection_state_changed'
+    | 'updated_stats'
+    | 'data_received';
+
+/**
+ * Configuration for WebRTC player
+ */
+export type WebRTCConfig = {
+    /** Whether to enable debug logging */
+    debug?: boolean;
+    /**
+     * Optional callback invoked before each reconnect attempt to obtain a fresh
+     * stream ID. A stream that restarts on the server is often issued a new ID,
+     * so reconnecting with the original `streamId` would target a dead stream.
+     * Return the latest ID (sync or async); return a falsy value to keep the
+     * current one. Errors are swallowed and the current ID is reused.
+     */
+    fetchStreamId?: () => string | Promise<string>;
+    /** WebRTC server hostname */
+    hostname: string;
+    /** Stream ID from Ant Media Server */
+    streamId: string;
+    /** WebSocket port for non-SSL connections */
+    wsPort?: number;
+    /** WebSocket port for SSL connections */
+    wssPort?: number;
+};
+
+/**
+ * WebRTC player state returned by the hook
+ */
+export type WebRTCPlayerState = {
+    /** Current connection state */
+    connectionState: WebRTCConnectionState;
+    /** Error message if connection failed */
+    error: string | null;
+    /** Whether the stream is currently loading/connecting */
+    loading: boolean;
+    /** Reference to attach to video element */
+    videoRef: React.RefObject<HTMLVideoElement>;
+};

package/src/breakpoints/index.tsx

@@ -0,0 +1 @@
+export * from './utils';