@uniai-fe/uds-templates 0.6.26 → 0.6.27

package/src/cctv/hooks/useRtcStream.ts

@@ -12,8 +12,10 @@ import {
 import {
   useCctvApiUrl,
   useCctvRtcStreamRegistry,
+  useCctvRtcStreamScheduler,
 } from "../components/Provider";
 import type {
+  CctvRtcStreamStage,
   CctvRtcReconnectTrigger,
   UseCctvRtcStreamParams,
   UseCctvRtcStreamReturn,
@@ -21,6 +23,7 @@ import type {
 import { cctvRtcLiveRegistryAtom } from "../jotai/rtc";
 import { getIsLive } from "../utils/video-state";
 import { useFormContext, useWatch } from "react-hook-form";
+import { useCctvRtcStreamScheduleStatus } from "./streamScheduler";
 
 const AUTO_RECONNECT_INTERVAL_MS = 3000;
 const POST_CONNECTED_RECONNECT_GRACE_MS = 5000;
@@ -77,9 +80,19 @@ const getPostConnectedReconnectReason = ({
   return null;
 };
 
+/**
+ * CCTV; base64url 문자열 decode
+ * @param {string} value base64url 인코딩 문자열
+ * @returns {string | null} decode된 문자열 또는 실패 시 null
+ * @desc
+ * JWT payload exp 확인용이며 실패를 throw하지 않아 token fallback age 판정으로 이어지게 한다.
+ */
 const decodeBase64Url = (value: string): string | null => {
   try {
+    // JWT payload는 base64url이라 브라우저 atob가 읽을 수 있는 base64 문자로 치환한다.
     const base64 = value.replace(/-/g, "+").replace(/_/g, "/");
+
+    // base64 길이가 4의 배수가 아니면 padding을 더해 decode 실패 가능성을 줄인다.
     const padded = base64.padEnd(Math.ceil(base64.length / 4) * 4, "=");
 
     return atob(padded);
@@ -88,14 +101,24 @@ const decodeBase64Url = (value: string): string | null => {
   }
 };
 
+/**
+ * CCTV; JWT 만료 시각 추출
+ * @param {string} token RTC token 문자열
+ * @returns {number | null} exp 기반 만료 시각(ms) 또는 확인 불가 시 null
+ * @desc
+ * token claim 구조를 신뢰하지 않고 exp가 유효한 number일 때만 신규 연결 재사용 기준으로 쓴다.
+ */
 const getJwtExpiresAt = (token: string): number | null => {
+  // JWT는 header.payload.signature 구조이며 exp는 payload에 있다.
   const payload = token.split(".")[1];
   if (!payload) return null;
 
+  // payload decode 실패 시 fallback max age 기준으로 넘긴다.
   const decodedPayload = decodeBase64Url(payload);
   if (!decodedPayload) return null;
 
   try {
+    // payload shape는 외부 token claim이므로 unknown으로 읽고 exp만 좁힌다.
     const parsedPayload = JSON.parse(decodedPayload) as { exp?: unknown };
     const exp = parsedPayload.exp;
 
@@ -105,6 +128,13 @@ const getJwtExpiresAt = (token: string): number | null => {
   }
 };
 
+/**
+ * CCTV; 신규 WHEP 연결에 token을 재사용할 수 있는지 판단
+ * @param {object} params token 판정 파라미터
+ * @param {number} params.dataUpdatedAt React Query token 갱신 시각(ms)
+ * @param {string} params.token RTC token 문자열
+ * @returns {boolean} 신규 연결 재사용 가능 여부
+ */
 const canUseTokenForNewConnection = ({
   dataUpdatedAt,
   token,
@@ -112,13 +142,16 @@ const canUseTokenForNewConnection = ({
   dataUpdatedAt: number;
   token: string;
 }): boolean => {
+  // JWT exp가 있으면 fallback age보다 exp claim을 우선한다.
   const expiresAt = getJwtExpiresAt(token);
   const now = Date.now();
 
   if (expiresAt) {
+    // 신규 WHEP 연결 중 만료되지 않도록 safety window를 둔다.
     return now + TOKEN_EXPIRY_SAFETY_MS < expiresAt;
   }
 
+  // exp 확인이 불가능한 token은 query 갱신 시각 기준 max age까지만 허용한다.
   return now - dataUpdatedAt <= CCTV_RTC_TOKEN_FALLBACK_MAX_AGE_MS;
 };
 
@@ -149,8 +182,17 @@ export function useCctvRtcStream({
 }: UseCctvRtcStreamParams): UseCctvRtcStreamReturn {
   // Provider를 통해 주입된 기본 토큰 발급 URL을 확보한다.
   const { tokenUrl: contextTokenUrl } = useCctvApiUrl();
+
+  // registry는 WHEP connection/MediaStream을 Provider scope에서 유지한다.
   const streamRegistry = useCctvRtcStreamRegistry();
+
+  // scheduler는 list item 렌더와 token/WHEP 시작 시점을 분리한다.
+  const streamScheduler = useCctvRtcStreamScheduler();
+
+  // live registry는 여러 hook instance가 같은 cam의 live 상태를 공유하는 Jotai atom이다.
   const setLiveRegistry = useSetAtom(cctvRtcLiveRegistryAtom);
+
+  // 같은 cam을 여러 위치에서 렌더할 수 있어 hook instance별 key를 한 번만 만든다.
   const instanceKeyRef = useRef<string | null>(null);
   if (!instanceKeyRef.current) {
     instanceKeyRef.current = Math.random().toString(36).slice(2);
@@ -158,9 +200,17 @@ export function useCctvRtcStream({
 
   // WebRTC MediaStream을 연결할 video 요소 ref.
   const videoRef = useRef<HTMLVideoElement | null>(null);
+
+  // 현재 hook instance가 attach 중인 streamKey를 기억해 stale token/refresh 분기를 구분한다.
   const activeStreamKeyRef = useRef<string | null>(null);
+
+  // stream identity는 token dataUpdatedAt을 제외한 카메라/사용자/endpoint 기준이다.
   const activeStreamIdentityKeyRef = useRef<string | null>(null);
+
+  // focus/visibility 자동 재연결이 짧은 시간에 반복되지 않도록 마지막 호출 시각을 저장한다.
   const lastAutoReconnectAtRef = useRef(0);
+
+  // stale token refetch를 같은 streamKeyCandidate마다 한 번만 수행하기 위한 guard다.
   const staleTokenRefreshKeyRef = useRef<string | null>(null);
 
   // RTCPeerConnectionState를 관찰해 UI에 노출하기 위한 상태값.
@@ -183,10 +233,42 @@ export function useCctvRtcStream({
   const endpointUsername =
     whepUsername === undefined ? tokenUsername : whepUsername;
 
+  // 카메라의 RTC 엔드포인트와 사용자명을 조합해 실제 WHEP endpoint를 계산한다.
+  const endpoint = useMemo(() => {
+    // cam_rtc가 없으면 WHEP endpoint를 만들 수 없어 이후 identity/token gate도 닫힌다.
+    if (!cam?.cam_rtc) return undefined;
+
+    // WHEP username override가 있으면 token username과 별개로 endpoint query에만 반영한다.
+    const query = endpointUsername
+      ? `?username=${encodeURIComponent(endpointUsername)}`
+      : "";
+
+    // cam_rtc 뒤의 slash 중복을 제거하고 WHEP path를 붙인다.
+    return `${cam.cam_rtc.replace(/\/$/, "")}/whep${query}`;
+  }, [cam?.cam_rtc, endpointUsername]);
+
+  const streamIdentityKey = useMemo(() => {
+    // identity 필수값이 모두 있어야 scheduler와 registry identity cleanup이 가능하다.
+    if (!tokenUsername || !cam?.company_id || !cam.cam_id || !endpoint)
+      return "";
+
+    // token 갱신 시각은 제외해 같은 카메라 stream family를 하나의 identity로 묶는다.
+    return [tokenUsername, cam.company_id, cam.cam_id, endpoint].join("|");
+  }, [cam?.cam_id, cam?.company_id, endpoint, tokenUsername]);
+
+  // scheduler grant 전에는 token query enabled가 false라 초기 token burst가 발생하지 않는다.
+  const streamScheduleStatus = useCctvRtcStreamScheduleStatus({
+    enabled: Boolean(streamIdentityKey && cam?.cam_online),
+    identityKey: streamIdentityKey,
+    scheduler: streamScheduler,
+  });
+  const isStreamStartGranted = streamScheduleStatus === "granted";
+
   // 카메라/회사/사용자 정보를 토대로 WHEP 토큰을 발급받는다.
   const tokenQuery = useQueryCctvRtcToken({
     company_id: cam?.company_id ?? "",
     cam_id: cam?.cam_id ?? "",
+    enabled: isStreamStartGranted,
     username: tokenUsername,
     url: tokenUrl ?? contextTokenUrl,
   });
@@ -195,19 +277,12 @@ export function useCctvRtcStream({
   const isTokenLoading = tokenQuery.isFetching;
   const isTokenError = tokenQuery.isError;
 
-  // 카메라의 RTC 엔드포인트와 사용자명을 조합해 실제 WHEP endpoint를 계산한다.
-  const endpoint = useMemo(() => {
-    if (!cam?.cam_rtc) return undefined;
-    const query = endpointUsername
-      ? `?username=${encodeURIComponent(endpointUsername)}`
-      : "";
-    return `${cam.cam_rtc.replace(/\/$/, "")}/whep${query}`;
-  }, [cam?.cam_rtc, endpointUsername]);
-
   const streamKeyCandidate = useMemo(() => {
+    // streamKey는 online 카메라와 endpoint/token이 모두 준비된 뒤에만 만들 수 있다.
     if (!cam?.cam_id || !cam.cam_online || !endpoint || !tokenQuery.data?.token)
       return "";
 
+    // token dataUpdatedAt을 포함해 명시 refetch 후에는 새 WHEP 연결 후보로 분리한다.
     return [
       tokenUsername,
       cam.company_id,
@@ -225,13 +300,8 @@ export function useCctvRtcStream({
     tokenUsername,
   ]);
 
-  const streamIdentityKey = useMemo(() => {
-    if (!cam?.cam_id || !endpoint) return "";
-
-    return [tokenUsername, cam.company_id, cam.cam_id, endpoint].join("|");
-  }, [cam?.cam_id, cam?.company_id, endpoint, tokenUsername]);
-
   useEffect(() => {
+    // identity가 바뀌면 이전 연결 성공 이력을 버려 reconnect gate를 초기 연결 상태로 되돌린다.
     setHasConnected(false);
   }, [streamIdentityKey]);
 
@@ -246,6 +316,7 @@ export function useCctvRtcStream({
   );
 
   useEffect(() => {
+    // 연결 이후 장애가 감지되고 현재 token/stream 작업이 없을 때만 reconnect timer를 연다.
     const canStartReconnectTimer =
       hasConnected &&
       Boolean(streamIdentityKey) &&
@@ -254,20 +325,24 @@ export function useCctvRtcStream({
       !isStreaming;
 
     if (!canStartReconnectTimer) {
+      // timer 조건이 사라지면 재연결 가능 표시도 즉시 닫는다.
       setPostConnectedReconnectReady(false);
       return;
     }
 
+    // 새 장애 reason이 들어올 때마다 grace/stagger 대기 상태부터 다시 시작한다.
     setPostConnectedReconnectReady(false);
     const reconnectDelayMs = getPostConnectedReconnectDelayMs(
       `${streamIdentityKey}|${reconnectReason}`,
     );
 
+    // cam identity 기반 delay 이후에만 UI/auto reconnect가 재시도할 수 있게 한다.
     const timeout = setTimeout(() => {
       setPostConnectedReconnectReady(true);
     }, reconnectDelayMs);
 
     return () => {
+      // 상태가 정상화되거나 identity가 바뀌면 이전 timer가 늦게 열리지 않게 취소한다.
       clearTimeout(timeout);
     };
   }, [
@@ -279,6 +354,7 @@ export function useCctvRtcStream({
   ]);
 
   const isPostConnectedRecoverableState =
+    // 이미 연결됐던 stream의 transient disconnected/failed는 화면을 바로 reset하지 않는다.
     hasConnected &&
     Boolean(streamIdentityKey) &&
     !isTokenError &&
@@ -286,6 +362,7 @@ export function useCctvRtcStream({
     DISPLAY_CONNECTED_DURING_RECOVERY_STATES.has(connectionState);
 
   const isPostConnectedReplacementLoading =
+    // token refetch 또는 새 stream start 중에도 기존 live 화면을 유지한다.
     hasConnected &&
     Boolean(streamIdentityKey) &&
     !isTokenError &&
@@ -294,6 +371,9 @@ export function useCctvRtcStream({
 
   const shouldPreserveConnectedDisplay =
     isPostConnectedReplacementLoading || isPostConnectedRecoverableState;
+  const isWaitingForStreamGrant =
+    // scheduler 대기 중에는 token loading으로 보이지 않게 별도 queued stage로 표시한다.
+    Boolean(streamIdentityKey && cam?.cam_online) && !isStreamStartGranted;
 
   // 반환 state는 CamList/Viewer/overlay의 live/error/message 계산에 직접 쓰인다.
   // post-connected recovery/replacement 중에는 canReconnect만 열고, 기존 화면은 유지해 UI reset 파동을 막는다.
@@ -303,13 +383,16 @@ export function useCctvRtcStream({
   const displayIsStreaming = shouldPreserveConnectedDisplay
     ? false
     : isStreaming;
-  const displayIsTokenLoading = shouldPreserveConnectedDisplay
-    ? false
-    : isTokenLoading;
+  const displayIsTokenLoading =
+    shouldPreserveConnectedDisplay || isWaitingForStreamGrant
+      ? false
+      : isTokenLoading;
 
   const hasReusableRegistryStream = useMemo(() => {
+    // streamKey 후보가 없으면 registry snapshot도 조회하지 않는다.
     if (!streamKeyCandidate) return false;
 
+    // 같은 Provider registry에 이미 시작/연결된 stream이 있으면 token freshness와 별개로 reattach할 수 있다.
     const snapshot = streamRegistry.getSnapshot(streamKeyCandidate);
 
     return Boolean(
@@ -320,10 +403,16 @@ export function useCctvRtcStream({
   }, [streamKeyCandidate, streamRegistry]);
 
   const canUseTokenForStream = useMemo(() => {
+    // token 또는 streamKey 후보가 없으면 WHEP start 조건이 닫힌다.
     if (!streamKeyCandidate || !tokenQuery.data?.token) return false;
+
+    // 현재 hook이 이미 붙어 있는 streamKey면 재판정 없이 유지한다.
     if (activeStreamKeyRef.current === streamKeyCandidate) return true;
+
+    // registry에 재사용 가능한 stream이 있으면 stale token이어도 새 WHEP POST 없이 attach만 한다.
     if (hasReusableRegistryStream) return true;
 
+    // 신규 WHEP POST는 token exp/fallback age를 통과해야만 허용한다.
     return canUseTokenForNewConnection({
       dataUpdatedAt: tokenQuery.dataUpdatedAt,
       token: tokenQuery.data.token,
@@ -335,14 +424,17 @@ export function useCctvRtcStream({
     tokenQuery.dataUpdatedAt,
   ]);
 
+  // streamKey가 빈 문자열이면 아래 stream effect가 WHEP start를 하지 않는다.
   const streamKey = canUseTokenForStream ? streamKeyCandidate : "";
 
   useEffect(() => {
+    // streamKey가 없거나 token을 그대로 쓸 수 있으면 stale refresh guard를 초기화한다.
     if (!streamKeyCandidate || canUseTokenForStream) {
       staleTokenRefreshKeyRef.current = null;
       return;
     }
 
+    // token이 없거나 이미 요청 중/에러 상태면 여기서 추가 refetch를 만들지 않는다.
     if (
       !tokenQuery.data?.token ||
       tokenQuery.isFetching ||
@@ -351,10 +443,12 @@ export function useCctvRtcStream({
       return;
     }
 
+    // 같은 stale stream 후보에 대해 refetch를 반복 호출하지 않는다.
     if (staleTokenRefreshKeyRef.current === streamKeyCandidate) {
       return;
     }
 
+    // stale token으로 WHEP start를 막고 token을 먼저 갱신한다.
     staleTokenRefreshKeyRef.current = streamKeyCandidate;
     void refetchRtcToken();
   }, [
@@ -369,14 +463,20 @@ export function useCctvRtcStream({
 
   // 토큰과 endpoint가 준비되면 WebRTC 스트림을 연결한다.
   useEffect(() => {
+    // effect 시작 시점의 video element를 고정해 cleanup/subscribe에서 같은 노드를 다룬다.
     const currentVideo = videoRef.current;
 
     // 토큰/카메라 에러로 전환되면 직전 MediaStream이 화면에 남지 않도록 비운다.
     if (tokenQuery.isError || !cam?.cam_online) {
+      // identity가 있으면 같은 카메라 family의 registry stream도 닫아 stale frame을 제거한다.
       if (streamIdentityKey) {
         streamRegistry.closeByIdentity(streamIdentityKey);
       }
+
+      // DOM video에는 registry cleanup과 별개로 srcObject 잔상을 즉시 비운다.
       if (currentVideo) currentVideo.srcObject = null;
+
+      // UI state도 초기 연결 전 상태로 되돌린다.
       setConnectionState("new");
       setStreamError(null);
       setStreaming(false);
@@ -387,23 +487,31 @@ export function useCctvRtcStream({
     if (!streamKey || !tokenQuery.data?.token || !endpoint || !currentVideo)
       return;
 
+    // 같은 identity에서 token dataUpdatedAt만 바뀌면 새 stream attach 이후 이전 stream을 닫는다.
     const previousStreamKey =
       activeStreamIdentityKeyRef.current === streamIdentityKey &&
       activeStreamKeyRef.current !== streamKey
         ? activeStreamKeyRef.current
         : null;
+
+    // track 수신 전 premature close를 막기 위해 실제 새 stream 확보 후 한 번만 이전 stream을 닫는다.
     let didClosePreviousStream = false;
 
     const closePreviousStreamAfterTrack = () => {
+      // 이전 stream이 없거나 이미 닫았다면 no-op으로 둔다.
       if (!previousStreamKey || didClosePreviousStream) return;
 
       didClosePreviousStream = true;
+
+      // 현재 streamKey는 보존하고 같은 identity의 이전 registry entry만 정리한다.
       streamRegistry.closeByIdentity(streamIdentityKey, streamKey);
     };
 
+    // 이후 effect 실행에서 같은 hook instance의 active stream을 판정할 수 있게 저장한다.
     activeStreamKeyRef.current = streamKey;
     activeStreamIdentityKeyRef.current = streamIdentityKey;
 
+    // registry.start는 같은 streamKey가 이미 있으면 새 WHEP POST 없이 기존 entry를 유지한다.
     streamRegistry.start({
       streamKey,
       identityKey: streamIdentityKey,
@@ -412,21 +520,32 @@ export function useCctvRtcStream({
       video: currentVideo,
     });
 
+    // 현재 video element를 registry entry에 붙여 MediaStream reattach 대상에 포함한다.
     const detachVideo = streamRegistry.attach(streamKey, currentVideo);
+
+    // registry snapshot 변경을 hook local state와 DOM video에 반영한다.
     const unsubscribe = streamRegistry.subscribe(streamKey, snapshot => {
       setConnectionState(snapshot.connectionState);
       setStreamError(snapshot.streamError);
       setStreaming(snapshot.isStreaming);
+
+      // 한 번이라도 connected가 되면 이후 장애를 post-connected recovery로 취급한다.
       if (snapshot.connectionState === "connected") {
         setHasConnected(true);
       }
+
+      // onTrack으로 MediaStream이 들어온 뒤에만 video.srcObject를 교체한다.
       if (snapshot.stream) {
         if (currentVideo.srcObject !== snapshot.stream) {
           currentVideo.srcObject = snapshot.stream;
         }
+
+        // 새 stream이 실제로 화면에 붙은 뒤 이전 token stream을 닫는다.
         closePreviousStreamAfterTrack();
       }
     });
+
+    // subscribe 직후 현재 snapshot을 즉시 반영해 기존 registry stream reattach 지연을 줄인다.
     const snapshot = streamRegistry.getSnapshot(streamKey);
     setConnectionState(snapshot.connectionState);
     setStreamError(snapshot.streamError);
@@ -434,9 +553,11 @@ export function useCctvRtcStream({
     if (snapshot.connectionState === "connected") setHasConnected(true);
 
     if (snapshot.stream) {
+      // 이미 registry에 MediaStream이 있으면 첫 render cycle에서도 즉시 video에 붙인다.
       if (currentVideo.srcObject !== snapshot.stream) {
         currentVideo.srcObject = snapshot.stream;
       }
+
       closePreviousStreamAfterTrack();
     }
 
@@ -456,16 +577,28 @@ export function useCctvRtcStream({
   ]);
 
   const reconnectStream = useCallback<CctvRtcReconnectTrigger>(
+    // public reconnect API는 React Query refetch를 그대로 감싸 token refresh trigger로 사용한다.
     options => refetchRtcToken(options),
     [refetchRtcToken],
   );
 
   const canReconnect = useMemo(() => {
+    // offline camera는 재연결 대상이 아니다.
     if (!cam?.cam_online) return false;
+
+    // 초기 연결 전 실패는 자동 reconnect UX가 아니라 일반 연결 오류로 둔다.
     if (!hasConnected) return false;
+
+    // identity가 없으면 어떤 registry stream을 재시도할지 알 수 없다.
     if (!streamIdentityKey) return false;
+
+    // 이미 token/stream 작업 중이면 중복 reconnect를 허용하지 않는다.
     if (isTokenLoading || isStreaming) return false;
+
+    // token/stream/failed 중 재연결 사유가 있어야 한다.
     if (!reconnectReason) return false;
+
+    // grace/stagger timer가 끝난 뒤에만 public reconnect 가능 상태를 연다.
     return isPostConnectedReconnectReady;
   }, [
     cam?.cam_online,
@@ -480,14 +613,20 @@ export function useCctvRtcStream({
   const refetchToken = reconnectStream;
 
   useEffect(() => {
+    // SSR/테스트 환경에서는 focus/visibility listener를 등록하지 않는다.
     if (typeof window === "undefined" || typeof document === "undefined")
       return;
 
     const reconnectOnFocus = () => {
+      // visibilitychange는 hidden 상태에서도 발생하므로 visible 복귀만 처리한다.
       if (document.visibilityState !== "visible") return;
+
+      // canReconnect gate가 닫혀 있으면 focus 복귀가 token refetch를 만들지 않는다.
       if (!canReconnect) return;
 
       const now = Date.now();
+
+      // 브라우저 focus와 visibilitychange가 연달아 들어와도 reconnect는 interval당 한 번만 호출한다.
       if (now - lastAutoReconnectAtRef.current < AUTO_RECONNECT_INTERVAL_MS)
         return;
 
@@ -495,17 +634,70 @@ export function useCctvRtcStream({
       void reconnectStream();
     };
 
+    // focus와 visibility 복귀 둘 다 장시간 미사용 후 재연결 trigger로 본다.
     window.addEventListener("focus", reconnectOnFocus);
     document.addEventListener("visibilitychange", reconnectOnFocus);
 
     return () => {
+      // hook unmount 시 전역 listener 누수를 막는다.
       window.removeEventListener("focus", reconnectOnFocus);
       document.removeEventListener("visibilitychange", reconnectOnFocus);
     };
   }, [canReconnect, reconnectStream]);
 
+  const streamStage = useMemo<CctvRtcStreamStage>(() => {
+    // cam이 없으면 hook consumer가 아직 stream 대상 없이 렌더된 상태다.
+    if (!cam) return "idle";
+
+    // offline camera는 scheduler/token/WHEP 대상에서 제외된 별도 상태로 표시한다.
+    if (!cam.cam_online) return "skipped-offline";
+
+    // token 또는 WHEP 에러는 다른 loading/queued 상태보다 우선한다.
+    if (isTokenError || streamError) return "error";
+
+    // post-connected 장애가 grace/stagger 이후 재연결 가능한 상태로 열린 경우다.
+    if (canReconnect) return "recovering";
+
+    // scheduler grant 전 대기 상태를 token-loading과 분리한다.
+    if (isWaitingForStreamGrant) return "queued";
+
+    // token query가 실제로 실행 중인 상태다.
+    if (displayIsTokenLoading) return "token-loading";
+
+    // WHEP offer/answer 또는 registry start가 진행 중인 상태다.
+    if (displayIsStreaming) return "connecting";
+
+    // UI 표시 기준 연결 상태가 connected면 live stage로 본다.
+    if (displayConnectionState === "connected") return "live";
+
+    // WebRTC가 아직 connected 전이면 사용자에게 연결 중으로 표시한다.
+    if (
+      displayConnectionState === "new" ||
+      displayConnectionState === "connecting" ||
+      displayConnectionState === "disconnected"
+    ) {
+      return "connecting";
+    }
+
+    // RTCPeerConnection failed는 streamError가 없어도 오류 stage로 승격한다.
+    if (displayConnectionState === "failed") return "error";
+
+    // 위 조건에 걸리지 않는 closed/unknown 계열은 기본 idle로 둔다.
+    return "idle";
+  }, [
+    cam,
+    canReconnect,
+    displayConnectionState,
+    displayIsStreaming,
+    displayIsTokenLoading,
+    isTokenError,
+    isWaitingForStreamGrant,
+    streamError,
+  ]);
+
   const liveState = useMemo(
     () =>
+      // live registry에는 cam이 있을 때만 util 판정 결과를 반영한다.
       cam
         ? getIsLive({
             cam,
@@ -527,11 +719,14 @@ export function useCctvRtcStream({
   );
 
   useEffect(() => {
+    // cam_id가 없으면 live registry key를 만들 수 없다.
     const camId = cam?.cam_id;
     if (!camId) return;
 
+    // 같은 cam을 여러 위치에서 렌더할 수 있어 instance 단위 live state를 보관한다.
     const instanceKey = instanceKeyRef.current as string;
     setLiveRegistry(prev => {
+      // jotai atom update는 기존 cam map을 얕은 복사해 React 변경 감지를 보장한다.
       const next = { ...prev };
       const perCam = { ...(next[camId] ?? {}) };
       perCam[instanceKey] = liveState;
@@ -541,15 +736,19 @@ export function useCctvRtcStream({
   }, [cam?.cam_id, liveState, setLiveRegistry]);
 
   useEffect(() => {
+    // unmount cleanup도 cam_id 기준이라 cam이 없으면 등록할 cleanup이 없다.
     const camId = cam?.cam_id;
     if (!camId) return;
 
     const instanceKey = instanceKeyRef.current as string;
     return () => {
+      // 현재 hook instance만 제거하고 같은 cam의 다른 렌더 위치는 유지한다.
       setLiveRegistry(prev => {
         const next = { ...prev };
         const perCam = { ...(next[camId] ?? {}) };
         delete perCam[instanceKey];
+
+        // 마지막 instance가 사라지면 cam entry 자체를 제거한다.
         if (Object.keys(perCam).length === 0) {
           delete next[camId];
         } else {
@@ -568,6 +767,7 @@ export function useCctvRtcStream({
     isStreaming: displayIsStreaming,
     isTokenLoading: displayIsTokenLoading,
     isTokenError,
+    streamStage,
     canReconnect,
     refetchToken,
     reconnectStream,

package/src/cctv/types/context.ts

@@ -55,6 +55,22 @@ export interface CctvApiUrlContext {
   tokenUrl?: string;
 }
 
+/**
+ * CCTV; RTC stream lazy loading 옵션
+ * @property {number} [batchSize] 한 번에 token/WHEP 시작 권한을 받을 stream 개수 (default: 4)
+ * @property {number} [batchIntervalMs] 다음 batch 시작까지 대기할 시간(ms) (default: 1200)
+ */
+export interface CctvRtcStreamOptions {
+  /**
+   * 한 번에 token/WHEP 시작 권한을 받을 stream 개수
+   */
+  batchSize?: number;
+  /**
+   * 다음 batch 시작까지 대기할 시간(ms)
+   */
+  batchIntervalMs?: number;
+}
+
 /**
  * CCTV; 실시간 영상보기 컨텍스트
  * @property {string} [company_id] 선택된 업체 id코드
@@ -125,6 +141,7 @@ export type CctvContext<ContextExtension extends object = object> =
  * @property {string} [username] CCTV 조회시 권한 확인을 위한 계정명
  * @property {string} [whepUsername] WHEP endpoint username 덮어쓰기 값
  * @property {ContextExtension} [defaultValues] 서비스 확장 context 기본값
+ * @property {CctvRtcStreamOptions} [streamOptions] stream lazy loading 옵션
  * @property {React.ReactNode} children
  */
 export type CctvProviderProps<ContextExtension extends object = object> =
@@ -142,6 +159,10 @@ export type CctvProviderProps<ContextExtension extends object = object> =
        * 서비스 확장 context 기본값
        */
       defaultValues?: ContextExtension;
+      /**
+       * stream lazy loading 옵션
+       */
+      streamOptions?: CctvRtcStreamOptions;
       /**
        * Provider 하위 콘텐츠
        */

package/src/cctv/types/hook.ts

@@ -20,6 +20,24 @@ export type CctvRtcReconnectTrigger = (
   options?: RefetchOptions,
 ) => Promise<QueryObserverResult<API_Res_CctvRtcToken>>;
 
+/**
+ * CCTV; RTC stream scheduler 상태
+ */
+export type CctvRtcStreamScheduleStatus = "idle" | "queued" | "granted";
+
+/**
+ * CCTV; RTC stream 표시 단계
+ */
+export type CctvRtcStreamStage =
+  | "idle"
+  | "queued"
+  | "token-loading"
+  | "connecting"
+  | "live"
+  | "recovering"
+  | "error"
+  | "skipped-offline";
+
 /**
  * CCTV; useCctvRtcStream params
  * @property {CctvCompanyCameraData} [cam] 스트리밍 카메라 정보
@@ -64,6 +82,7 @@ export interface UseCctvRtcStreamError {
  * @property {boolean} isTokenLoading UI 표시 기준 토큰 발급 요청 진행 여부
  * @property {boolean} isTokenError 토큰 발급 실패 여부
  * @property {string | null} streamError 스트림 오류 메시지
+ * @property {CctvRtcStreamStage} streamStage stream 표시 단계
  */
 export interface UseCctvRtcStreamState extends UseCctvRtcStreamError {
   /**
@@ -88,6 +107,10 @@ export interface UseCctvRtcStreamState extends UseCctvRtcStreamError {
    * 재발급 중에는 기존 화면과 live count를 유지하기 위해 false로 smoothing될 수 있다.
    */
   isTokenLoading: boolean;
+  /**
+   * stream 표시 단계
+   */
+  streamStage: CctvRtcStreamStage;
 }
 
 /**
@@ -98,6 +121,7 @@ export interface UseCctvRtcStreamState extends UseCctvRtcStreamError {
  * @property {boolean} isStreaming UI 표시 기준 startWhepStream 진행 여부
  * @property {boolean} isTokenLoading UI 표시 기준 토큰 발급 요청 진행 여부
  * @property {boolean} isTokenError 토큰 발급 실패 여부
+ * @property {CctvRtcStreamStage} streamStage stream 표시 단계
  * @property {boolean} canReconnect UDS 내부 허용 사유와 grace/stagger를 통과해 재연결 호출이 가능한지 여부
  * @property {() => Promise<void>} refetchToken 토큰 재발급 함수
  * @property {() => Promise<QueryObserverResult<API_Res_CctvRtcToken>>} reconnectStream 재연결 trigger 함수