@uniai-fe/uds-templates 0.6.7 → 0.6.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniai-fe/uds-templates",
-  "version": "0.6.7",
+  "version": "0.6.9",
   "description": "UNIAI Design System; UI Templates Package",
   "type": "module",
   "private": false,

package/src/cctv/hooks/streamRegistry.ts

@@ -1,6 +1,11 @@
 "use client";
 
 import { startWhepStream, type WhepStreamHandle } from "@uniai-fe/util-rtc";
+import {
+  getCctvDebugKeyLabel,
+  getCctvDebugUrlLabel,
+  logCctvDebugEvent,
+} from "../utils/debug";
 
 interface CctvRtcStreamSnapshot {
   connectionState: RTCPeerConnectionState;
@@ -47,6 +52,18 @@ const notifyEntry = (entry: CctvRtcStreamEntry) => {
 };
 
 const closeEntry = (entry: CctvRtcStreamEntry) => {
+  logCctvDebugEvent({
+    event: "entry:close",
+    payload: {
+      attachedVideoCount: entry.attachedVideos.size,
+      connectionState: entry.connectionState,
+      identityKey: getCctvDebugKeyLabel(entry.identityKey),
+      isStreaming: entry.isStreaming,
+      streamKey: getCctvDebugKeyLabel(entry.streamKey),
+      streamTrackCount: entry.stream?.getTracks().length ?? 0,
+    },
+    source: "streamRegistry",
+  });
   entry.controller?.abort();
   entry.controller = null;
   entry.handle?.close();
@@ -110,6 +127,15 @@ export function createCctvRtcStreamRegistry(): CctvRtcStreamRegistry {
       entries.clear();
     },
     closeByIdentity(identityKey, exceptStreamKey) {
+      logCctvDebugEvent({
+        event: "identity:close",
+        payload: {
+          entryCount: entries.size,
+          exceptStreamKey: getCctvDebugKeyLabel(exceptStreamKey),
+          identityKey: getCctvDebugKeyLabel(identityKey),
+        },
+        source: "streamRegistry",
+      });
       entries.forEach(entry => {
         if (
           entry.identityKey === identityKey &&
@@ -124,9 +150,22 @@ export function createCctvRtcStreamRegistry(): CctvRtcStreamRegistry {
     },
     start({ endpoint, identityKey, streamKey, token, video }) {
       const existingEntry = entries.get(streamKey);
-      if (existingEntry) return;
+      if (existingEntry) {
+        logCctvDebugEvent({
+          event: "start:reuse-existing",
+          payload: {
+            connectionState: existingEntry.connectionState,
+            identityKey: getCctvDebugKeyLabel(identityKey),
+            isStreaming: existingEntry.isStreaming,
+            streamKey: getCctvDebugKeyLabel(streamKey),
+          },
+          source: "streamRegistry",
+        });
+        return;
+      }
 
       const controller = new AbortController();
+      const startedAt = Date.now();
       const entry: CctvRtcStreamEntry = {
         attachedVideos: new Set([video]),
         connectionState: "connecting",
@@ -142,6 +181,16 @@ export function createCctvRtcStreamRegistry(): CctvRtcStreamRegistry {
 
       entries.set(streamKey, entry);
       attachVideo(video, null);
+      logCctvDebugEvent({
+        event: "start:create-entry",
+        payload: {
+          attachedVideoCount: entry.attachedVideos.size,
+          endpoint: getCctvDebugUrlLabel(endpoint),
+          identityKey: getCctvDebugKeyLabel(identityKey),
+          streamKey: getCctvDebugKeyLabel(streamKey),
+        },
+        source: "streamRegistry",
+      });
 
       startWhepStream({
         endpoint,
@@ -150,10 +199,33 @@ export function createCctvRtcStreamRegistry(): CctvRtcStreamRegistry {
         signal: controller.signal,
         onConnectionStateChange: state => {
           entry.connectionState = state;
+          logCctvDebugEvent({
+            event: "connection-state:change",
+            payload: {
+              elapsedMs: Date.now() - startedAt,
+              identityKey: getCctvDebugKeyLabel(identityKey),
+              state,
+              streamKey: getCctvDebugKeyLabel(streamKey),
+            },
+            source: "streamRegistry",
+          });
           notifyEntry(entry);
         },
         onTrack: event => {
           entry.stream = event.streams[0] ?? null;
+          logCctvDebugEvent({
+            event: "track:received",
+            payload: {
+              elapsedMs: Date.now() - startedAt,
+              identityKey: getCctvDebugKeyLabel(identityKey),
+              streamId: entry.stream?.id ?? null,
+              streamKey: getCctvDebugKeyLabel(streamKey),
+              trackId: event.track.id,
+              trackKind: event.track.kind,
+              trackReadyState: event.track.readyState,
+            },
+            source: "streamRegistry",
+          });
           entry.attachedVideos.forEach(attachedVideo =>
             attachVideo(attachedVideo, entry.stream),
           );
@@ -163,6 +235,16 @@ export function createCctvRtcStreamRegistry(): CctvRtcStreamRegistry {
         .then(handle => {
           entry.handle = handle;
           entry.isStreaming = false;
+          logCctvDebugEvent({
+            event: "start:resolved",
+            level: "info",
+            payload: {
+              elapsedMs: Date.now() - startedAt,
+              identityKey: getCctvDebugKeyLabel(identityKey),
+              streamKey: getCctvDebugKeyLabel(streamKey),
+            },
+            source: "streamRegistry",
+          });
           notifyEntry(entry);
         })
         .catch(error => {
@@ -174,6 +256,17 @@ export function createCctvRtcStreamRegistry(): CctvRtcStreamRegistry {
             error instanceof Error
               ? error.message
               : "스트림 연결에 실패했습니다.";
+          logCctvDebugEvent({
+            event: "start:rejected",
+            level: "error",
+            payload: {
+              elapsedMs: Date.now() - startedAt,
+              errorMessage: entry.streamError,
+              identityKey: getCctvDebugKeyLabel(identityKey),
+              streamKey: getCctvDebugKeyLabel(streamKey),
+            },
+            source: "streamRegistry",
+          });
           entry.attachedVideos.forEach(attachedVideo =>
             attachVideo(attachedVideo, null),
           );

package/src/cctv/hooks/useRtcStream.ts

@@ -19,27 +19,73 @@ import type {
   UseCctvRtcStreamReturn,
 } from "../types";
 import { cctvRtcLiveRegistryAtom } from "../jotai/rtc";
+import {
+  getCctvDebugKeyLabel,
+  getCctvDebugStackTrace,
+  logCctvDebugEvent,
+} from "../utils/debug";
 import { getIsLive } from "../utils/video-state";
 import { useFormContext, useWatch } from "react-hook-form";
 
 const AUTO_RECONNECT_INTERVAL_MS = 3000;
-const DISCONNECTED_RECONNECT_GRACE_MS = 5000;
-const DISCONNECTED_RECONNECT_STAGGER_MS = 5000;
+const POST_CONNECTED_RECONNECT_GRACE_MS = 5000;
+const POST_CONNECTED_RECONNECT_STAGGER_MS = 5000;
 const TOKEN_EXPIRY_SAFETY_MS = 30 * 1000;
 
+type CctvRtcReconnectReason =
+  | "tokenError"
+  | "streamError"
+  | "failed"
+  | "disconnected";
+
+const DISPLAY_CONNECTED_DURING_GRACE_STATES = new Set<RTCPeerConnectionState>([
+  "disconnected",
+  "failed",
+]);
+
+/**
+ * 같은 회사/카메라 묶음이 동시에 재연결하지 않도록 identity 기반 지연값을 만든다.
+ * @desc
+ * 이 값은 보안용 난수가 아니라 UI/네트워크 부하를 분산하기 위한 안정 해시다.
+ */
 const getStableStaggerMs = (value: string): number => {
   let hash = 0;
 
   for (let i = 0; i < value.length; i += 1) {
     hash =
-      (hash * 31 + value.charCodeAt(i)) % DISCONNECTED_RECONNECT_STAGGER_MS;
+      (hash * 31 + value.charCodeAt(i)) % POST_CONNECTED_RECONNECT_STAGGER_MS;
   }
 
   return hash;
 };
 
-const getDisconnectedReconnectDelayMs = (identityKey: string): number =>
-  DISCONNECTED_RECONNECT_GRACE_MS + getStableStaggerMs(identityKey);
+/**
+ * 최초 연결 이후 끊김/실패가 감지됐을 때 자동 재연결 노출 전 대기시간을 계산한다.
+ */
+const getPostConnectedReconnectDelayMs = (delayKey: string): number =>
+  POST_CONNECTED_RECONNECT_GRACE_MS + getStableStaggerMs(delayKey);
+
+/**
+ * 재연결이 필요한 장애 사유를 UDS 내부 기준으로 정규화한다.
+ * @desc
+ * `closed`는 `streamRegistry.closeByIdentity()`처럼 UDS가 의도적으로 닫을 때도 발생하므로
+ * 자동 재연결 사유에 포함하지 않는다.
+ */
+const getPostConnectedReconnectReason = ({
+  connectionState,
+  isTokenError,
+  streamError,
+}: {
+  connectionState: RTCPeerConnectionState;
+  isTokenError: boolean;
+  streamError: string | null;
+}): CctvRtcReconnectReason | null => {
+  if (isTokenError) return "tokenError";
+  if (streamError) return "streamError";
+  if (connectionState === "failed") return "failed";
+  if (connectionState === "disconnected") return "disconnected";
+  return null;
+};
 
 const decodeBase64Url = (value: string): string | null => {
   try {
@@ -102,7 +148,7 @@ const canUseTokenForNewConnection = ({
  *   isStreaming, // 현재 스트림 연결 절차가 진행 중인지 여부
  *   isTokenLoading, // 토큰 발급 요청이 진행 중인지 여부
  *   isTokenError, // 토큰 발급 요청이 실패했는지 여부
- *   canReconnect, // 재연결 가능한 종료 상태 여부
+ *   canReconnect, // UDS 내부 grace/stagger 이후 재연결 호출이 가능한지 여부
  *   refetchToken, // 토큰 발급을 재시도하는 함수
  *   reconnectStream, // 재연결 trigger 함수
  * }
@@ -137,7 +183,7 @@ export function useCctvRtcStream({
   // 현재 스트림 연결 절차가 진행 중인지 여부.
   const [isStreaming, setStreaming] = useState(false);
   const [hasConnected, setHasConnected] = useState(false);
-  const [isDisconnectedReconnectReady, setDisconnectedReconnectReady] =
+  const [isPostConnectedReconnectReady, setPostConnectedReconnectReady] =
     useState(false);
 
   // react-hook-form 컨텍스트에서 token username과 WHEP username override를 추적한다.
@@ -195,37 +241,106 @@ export function useCctvRtcStream({
     return [tokenUsername, cam.company_id, cam.cam_id, endpoint].join("|");
   }, [cam?.cam_id, cam?.company_id, endpoint, tokenUsername]);
 
+  const debugBasePayload = useMemo(
+    () => ({
+      camId: cam?.cam_id,
+      companyId: cam?.company_id,
+      streamIdentityKey: getCctvDebugKeyLabel(streamIdentityKey),
+    }),
+    [cam?.cam_id, cam?.company_id, streamIdentityKey],
+  );
+
   useEffect(() => {
+    logCctvDebugEvent({
+      event: "identity:reset-has-connected",
+      payload: debugBasePayload,
+      source: "useRtcStream",
+    });
     setHasConnected(false);
-  }, [streamIdentityKey]);
+  }, [debugBasePayload, streamIdentityKey]);
+
+  const reconnectReason = useMemo(
+    () =>
+      getPostConnectedReconnectReason({
+        connectionState,
+        isTokenError,
+        streamError,
+      }),
+    [connectionState, isTokenError, streamError],
+  );
 
   useEffect(() => {
-    if (
-      connectionState !== "disconnected" ||
-      !hasConnected ||
-      !streamIdentityKey
-    ) {
-      setDisconnectedReconnectReady(false);
+    const canStartReconnectTimer =
+      hasConnected &&
+      Boolean(streamIdentityKey) &&
+      Boolean(reconnectReason) &&
+      !isTokenLoading &&
+      !isStreaming;
+
+    if (!canStartReconnectTimer) {
+      setPostConnectedReconnectReady(false);
       return;
     }
 
-    setDisconnectedReconnectReady(false);
+    setPostConnectedReconnectReady(false);
+    const reconnectDelayMs = getPostConnectedReconnectDelayMs(
+      `${streamIdentityKey}|${reconnectReason}`,
+    );
+
+    logCctvDebugEvent({
+      event: "reconnect-gate:timer-start",
+      payload: {
+        ...debugBasePayload,
+        isStreaming,
+        isTokenLoading,
+        reconnectDelayMs,
+        reconnectReason,
+      },
+      source: "useRtcStream",
+    });
 
     const timeout = setTimeout(() => {
-      setDisconnectedReconnectReady(true);
-    }, getDisconnectedReconnectDelayMs(streamIdentityKey));
+      setPostConnectedReconnectReady(true);
+      logCctvDebugEvent({
+        event: "reconnect-gate:ready",
+        payload: {
+          ...debugBasePayload,
+          reconnectDelayMs,
+          reconnectReason,
+        },
+        source: "useRtcStream",
+      });
+    }, reconnectDelayMs);
 
     return () => {
       clearTimeout(timeout);
+      logCctvDebugEvent({
+        event: "reconnect-gate:timer-cancel",
+        payload: {
+          ...debugBasePayload,
+          reconnectDelayMs,
+          reconnectReason,
+        },
+        source: "useRtcStream",
+      });
     };
-  }, [connectionState, hasConnected, streamIdentityKey]);
+  }, [
+    debugBasePayload,
+    hasConnected,
+    isStreaming,
+    isTokenLoading,
+    reconnectReason,
+    streamIdentityKey,
+  ]);
 
-  const displayConnectionState =
-    connectionState === "disconnected" &&
+  const shouldPreserveConnectedDisplay =
     hasConnected &&
-    !isDisconnectedReconnectReady
-      ? "connected"
-      : connectionState;
+    !isPostConnectedReconnectReady &&
+    DISPLAY_CONNECTED_DURING_GRACE_STATES.has(connectionState);
+
+  const displayConnectionState = shouldPreserveConnectedDisplay
+    ? "connected"
+    : connectionState;
 
   const hasReusableRegistryStream = useMemo(() => {
     if (!streamKeyCandidate) return false;
@@ -276,12 +391,23 @@ export function useCctvRtcStream({
     }
 
     staleTokenRefreshKeyRef.current = streamKeyCandidate;
+    logCctvDebugEvent({
+      event: "token:stale-refetch",
+      payload: {
+        ...debugBasePayload,
+        dataUpdatedAt: tokenQuery.dataUpdatedAt,
+        streamKey: getCctvDebugKeyLabel(streamKeyCandidate),
+      },
+      source: "useRtcStream",
+    });
     void refetchRtcToken();
   }, [
     canUseTokenForStream,
+    debugBasePayload,
     refetchRtcToken,
     streamKeyCandidate,
     tokenQuery.data?.token,
+    tokenQuery.dataUpdatedAt,
     tokenQuery.isError,
     tokenQuery.isFetching,
   ]);
@@ -292,6 +418,15 @@ export function useCctvRtcStream({
 
     // 토큰/카메라 에러로 전환되면 직전 MediaStream이 화면에 남지 않도록 비운다.
     if (tokenQuery.isError || !cam?.cam_online) {
+      logCctvDebugEvent({
+        event: "stream-effect:cleanup-token-or-offline",
+        payload: {
+          ...debugBasePayload,
+          camOnline: cam?.cam_online,
+          isTokenError: tokenQuery.isError,
+        },
+        source: "useRtcStream",
+      });
       if (streamIdentityKey) {
         streamRegistry.closeByIdentity(streamIdentityKey);
       }
@@ -310,12 +445,30 @@ export function useCctvRtcStream({
       activeStreamIdentityKeyRef.current === streamIdentityKey &&
       activeStreamKeyRef.current !== streamKey
     ) {
+      logCctvDebugEvent({
+        event: "stream-effect:close-previous-identity",
+        payload: {
+          ...debugBasePayload,
+          activeStreamKey: getCctvDebugKeyLabel(activeStreamKeyRef.current),
+          nextStreamKey: getCctvDebugKeyLabel(streamKey),
+        },
+        source: "useRtcStream",
+      });
       streamRegistry.closeByIdentity(streamIdentityKey, streamKey);
     }
 
     activeStreamKeyRef.current = streamKey;
     activeStreamIdentityKeyRef.current = streamIdentityKey;
 
+    logCctvDebugEvent({
+      event: "stream-effect:start",
+      payload: {
+        ...debugBasePayload,
+        streamKey: getCctvDebugKeyLabel(streamKey),
+      },
+      source: "useRtcStream",
+    });
+
     streamRegistry.start({
       streamKey,
       identityKey: streamIdentityKey,
@@ -329,7 +482,17 @@ export function useCctvRtcStream({
       setConnectionState(snapshot.connectionState);
       setStreamError(snapshot.streamError);
       setStreaming(snapshot.isStreaming);
-      if (snapshot.connectionState === "connected") setHasConnected(true);
+      if (snapshot.connectionState === "connected") {
+        logCctvDebugEvent({
+          event: "stream-effect:has-connected",
+          payload: {
+            ...debugBasePayload,
+            streamKey: getCctvDebugKeyLabel(streamKey),
+          },
+          source: "useRtcStream",
+        });
+        setHasConnected(true);
+      }
       if (snapshot.stream && currentVideo.srcObject !== snapshot.stream) {
         currentVideo.srcObject = snapshot.stream;
       }
@@ -346,10 +509,19 @@ export function useCctvRtcStream({
 
     // effect cleanup: current video attach만 해제하고 registry stream은 유지한다.
     return () => {
+      logCctvDebugEvent({
+        event: "stream-effect:detach-video",
+        payload: {
+          ...debugBasePayload,
+          streamKey: getCctvDebugKeyLabel(streamKey),
+        },
+        source: "useRtcStream",
+      });
       unsubscribe();
       detachVideo();
     };
   }, [
+    debugBasePayload,
     endpoint,
     streamIdentityKey,
     streamKey,
@@ -359,10 +531,56 @@ export function useCctvRtcStream({
     cam?.cam_online,
   ]);
 
+  const debugReconnectStateRef = useRef({
+    connectionState,
+    debugBasePayload,
+    isPostConnectedReconnectReady,
+    reconnectReason,
+    streamError,
+  });
+  debugReconnectStateRef.current = {
+    connectionState,
+    debugBasePayload,
+    isPostConnectedReconnectReady,
+    reconnectReason,
+    streamError,
+  };
+
   const reconnectStream = useCallback<CctvRtcReconnectTrigger>(
     async options => {
+      const debugState = debugReconnectStateRef.current;
+      logCctvDebugEvent({
+        event: "reconnect-stream:start",
+        payload: {
+          ...debugState.debugBasePayload,
+          connectionState: debugState.connectionState,
+          callerStack: getCctvDebugStackTrace(),
+          isPostConnectedReconnectReady:
+            debugState.isPostConnectedReconnectReady,
+          reconnectReason: debugState.reconnectReason,
+          streamError: debugState.streamError,
+        },
+        source: "useRtcStream",
+      });
       const result = await refetchRtcToken(options);
+      const resultDebugState = debugReconnectStateRef.current;
+      logCctvDebugEvent({
+        event: "reconnect-stream:token-result",
+        level: result.isSuccess ? "info" : "warn",
+        payload: {
+          ...resultDebugState.debugBasePayload,
+          isError: result.isError,
+          isSuccess: result.isSuccess,
+          status: result.status,
+        },
+        source: "useRtcStream",
+      });
       if (result.isSuccess && streamIdentityKey) {
+        logCctvDebugEvent({
+          event: "reconnect-stream:close-identity",
+          payload: resultDebugState.debugBasePayload,
+          source: "useRtcStream",
+        });
         streamRegistry.closeByIdentity(streamIdentityKey);
       }
       return result;
@@ -375,20 +593,15 @@ export function useCctvRtcStream({
     if (!hasConnected) return false;
     if (!streamIdentityKey) return false;
     if (isTokenLoading || isStreaming) return false;
-    if (isTokenError || streamError) return true;
-    if (connectionState === "failed") return true;
-    if (connectionState === "disconnected") return isDisconnectedReconnectReady;
-    if (connectionState === "closed") return true;
-    return false;
+    if (!reconnectReason) return false;
+    return isPostConnectedReconnectReady;
   }, [
     cam?.cam_online,
-    connectionState,
     hasConnected,
-    isDisconnectedReconnectReady,
+    isPostConnectedReconnectReady,
     isStreaming,
-    isTokenError,
     isTokenLoading,
-    streamError,
+    reconnectReason,
     streamIdentityKey,
   ]);
 
@@ -407,6 +620,16 @@ export function useCctvRtcStream({
         return;
 
       lastAutoReconnectAtRef.current = now;
+      logCctvDebugEvent({
+        event: "focus:auto-reconnect",
+        payload: {
+          ...debugBasePayload,
+          canReconnect,
+          connectionState,
+          reconnectReason,
+        },
+        source: "useRtcStream",
+      });
       void reconnectStream();
     };
 
@@ -417,7 +640,13 @@ export function useCctvRtcStream({
       window.removeEventListener("focus", reconnectOnFocus);
       document.removeEventListener("visibilitychange", reconnectOnFocus);
     };
-  }, [canReconnect, reconnectStream]);
+  }, [
+    canReconnect,
+    connectionState,
+    debugBasePayload,
+    reconnectReason,
+    reconnectStream,
+  ]);
 
   const liveState = useMemo(
     () =>
@@ -441,6 +670,40 @@ export function useCctvRtcStream({
     ],
   );
 
+  useEffect(() => {
+    logCctvDebugEvent({
+      event: "hook-state:update",
+      payload: {
+        ...debugBasePayload,
+        canReconnect,
+        connectionState,
+        displayConnectionState,
+        hasConnected,
+        isPostConnectedReconnectReady,
+        isStreaming,
+        isTokenError,
+        isTokenLoading,
+        liveState,
+        reconnectReason,
+        streamError,
+      },
+      source: "useRtcStream",
+    });
+  }, [
+    canReconnect,
+    connectionState,
+    debugBasePayload,
+    displayConnectionState,
+    hasConnected,
+    isPostConnectedReconnectReady,
+    isStreaming,
+    isTokenError,
+    isTokenLoading,
+    liveState,
+    reconnectReason,
+    streamError,
+  ]);
+
   useEffect(() => {
     const camId = cam?.cam_id;
     if (!camId) return;

package/src/cctv/types/hook.ts

@@ -88,7 +88,7 @@ export interface UseCctvRtcStreamState extends UseCctvRtcStreamError {
  * @property {boolean} isStreaming startWhepStream 진행 여부
  * @property {boolean} isTokenLoading 토큰 발급 요청 진행 여부
  * @property {boolean} isTokenError 토큰 발급 실패 여부
- * @property {boolean} canReconnect 재연결 가능한 종료 상태 여부
+ * @property {boolean} canReconnect UDS 내부 grace/stagger를 통과해 재연결 호출이 가능한지 여부
  * @property {() => Promise<void>} refetchToken 토큰 재발급 함수
  * @property {() => Promise<QueryObserverResult<API_Res_CctvRtcToken>>} reconnectStream 재연결 trigger 함수
  */
@@ -98,7 +98,10 @@ export interface UseCctvRtcStreamReturn extends UseCctvRtcStreamState {
    */
   videoRef: React.RefObject<HTMLVideoElement | null>;
   /**
-   * 재연결 가능한 종료 상태 여부
+   * UDS 내부 grace/stagger를 통과해 재연결 호출이 가능한지 여부
+   * @desc
+   * 스트림 장애 감지 즉시 true가 되는 플래그가 아니라,
+   * 서비스 overlay가 reconnectStream()을 호출해도 되는 시점에 true가 된다.
    */
   canReconnect: boolean;
   /**

package/src/cctv/types/props.ts

@@ -9,7 +9,7 @@ import type { CctvRtcReconnectTrigger } from "./hook";
  * @property {boolean | undefined} [isError] 영상 에러 상태 여부
  * @property {boolean | undefined} [isLive] 영상 live 상태 여부
  * @property {React.ReactNode} [overlayMessage] 기본 안내/에러 메시지 콘텐츠
- * @property {boolean | undefined} [canReconnect] 재연결 가능한 종료 상태 여부
+ * @property {boolean | undefined} [canReconnect] UDS 내부 grace/stagger를 통과해 재연결 호출이 가능한지 여부
  * @property {CctvRtcReconnectTrigger | undefined} [reconnectStream] 재연결 trigger 함수
  */
 export interface CctvVideoRenderOverlayContext {
@@ -38,7 +38,10 @@ export interface CctvVideoRenderOverlayContext {
    */
   overlayMessage?: React.ReactNode;
   /**
-   * 재연결 가능한 종료 상태 여부
+   * UDS 내부 grace/stagger를 통과해 재연결 호출이 가능한지 여부
+   * @desc
+   * custom overlay에서 자동 재연결을 구현할 때 이 값이 true인 경우에만
+   * reconnectStream()을 호출해야 한다.
    */
   canReconnect?: boolean;
   /**
@@ -126,7 +129,7 @@ export interface CctvVideoOverlayFooterProps {
  * @property {boolean} [isError] 에러 상태 여부
  * @property {boolean} [isLive] 영상이 정상적으로 재생 중인지 여부
  * @property {React.ReactNode} [overlayMessage] 에러/안내 메시지 콘텐츠
- * @property {boolean} [canReconnect] 재연결 가능한 종료 상태 여부
+ * @property {boolean} [canReconnect] UDS 내부 grace/stagger를 통과해 재연결 호출이 가능한지 여부
  * @property {CctvRtcReconnectTrigger} [reconnectStream] 재연결 trigger 함수
  */
 export interface CctvVideoStateProps {
@@ -143,7 +146,7 @@ export interface CctvVideoStateProps {
    */
   overlayMessage?: React.ReactNode;
   /**
-   * 재연결 가능한 종료 상태 여부
+   * UDS 내부 grace/stagger를 통과해 재연결 호출이 가능한지 여부
    */
   canReconnect?: boolean;
   /**

package/src/cctv/types/video-state.ts

@@ -11,7 +11,7 @@ import type { UseCctvRtcStreamError, UseCctvRtcStreamState } from "./hook";
  * @property {boolean} isTokenLoading 토큰 발급 요청 진행 여부
  * @property {boolean} isTokenError 토큰 발급 실패 여부
  * @property {string | null} streamError 스트림 오류 메시지
- * @property {boolean} [canReconnect] 재연결 가능한 종료 상태 여부
+ * @property {boolean} [canReconnect] UDS 내부 grace/stagger를 통과해 재연결 호출이 가능한지 여부
  */
 export interface CctvVideoOverlayMessageParams extends UseCctvRtcStreamState {
   /**
@@ -27,7 +27,7 @@ export interface CctvVideoOverlayMessageParams extends UseCctvRtcStreamState {
    */
   isFetching?: boolean;
   /**
-   * 재연결 가능한 종료 상태 여부
+   * UDS 내부 grace/stagger를 통과해 재연결 호출이 가능한지 여부
    */
   canReconnect?: boolean;
 }
@@ -53,7 +53,7 @@ export interface CctvVideoLiveParams extends UseCctvRtcStreamState {
  * @property {CctvCompanyCameraData} [cam] 카메라 데이터
  * @property {boolean} isTokenError 토큰 발급 실패 여부
  * @property {string | null} streamError 스트림 오류 메시지
- * @property {boolean} [canReconnect] 재연결 가능한 종료 상태 여부
+ * @property {boolean} [canReconnect] UDS 내부 grace/stagger를 통과해 재연결 호출이 가능한지 여부
  */
 export interface CctvVideoErrorParams extends UseCctvRtcStreamError {
   /**
@@ -61,7 +61,7 @@ export interface CctvVideoErrorParams extends UseCctvRtcStreamError {
    */
   cam?: CctvCompanyCameraData;
   /**
-   * 재연결 가능한 종료 상태 여부
+   * UDS 내부 grace/stagger를 통과해 재연결 호출이 가능한지 여부
    */
   canReconnect?: boolean;
 }

package/src/cctv/utils/debug.ts

@@ -0,0 +1,179 @@
+"use client";
+
+export type CctvDebugEventLevel = "debug" | "info" | "warn" | "error";
+
+export interface CctvDebugEvent {
+  at: string;
+  event: string;
+  level: CctvDebugEventLevel;
+  payload?: Record<string, unknown>;
+  seq: number;
+  source: string;
+}
+
+export interface CctvDebugBuffer {
+  clear: () => void;
+  dump: () => CctvDebugEvent[];
+  enabled: true;
+  events: CctvDebugEvent[];
+  limit: number;
+  sequence: number;
+}
+
+declare global {
+  interface Window {
+    __UDS_CCTV_DEBUG__?: CctvDebugBuffer;
+  }
+}
+
+const DEBUG_QUERY_KEYS = ["udsCctvDebug", "cctvDebug"] as const;
+const DEBUG_STORAGE_KEYS = ["uds:cctv:debug", "UDS_CCTV_DEBUG"] as const;
+const DEBUG_ENABLED_VALUES = new Set(["1", "true", "yes", "on", "debug"]);
+const DEBUG_BUFFER_LIMIT = 1000;
+
+const isBrowser = (): boolean =>
+  typeof window !== "undefined" && typeof document !== "undefined";
+
+const isDebugValueEnabled = (value: string | null): boolean =>
+  value === "" ||
+  (typeof value === "string" && DEBUG_ENABLED_VALUES.has(value));
+
+/**
+ * identity/stream key를 원문 대신 추적 가능한 hash label로 바꾼다.
+ */
+export const getCctvDebugKeyLabel = (
+  value: string | null | undefined,
+): string | null => {
+  if (!value) return null;
+
+  let hash = 0;
+  for (let i = 0; i < value.length; i += 1) {
+    hash = (hash * 31 + value.charCodeAt(i)) >>> 0;
+  }
+
+  return `hash:${hash.toString(36)}|len:${value.length}`;
+};
+
+/**
+ * endpoint는 query string을 제거한 origin/path만 기록한다.
+ */
+export const getCctvDebugUrlLabel = (
+  value: string | null | undefined,
+): string | null => {
+  if (!value) return null;
+
+  try {
+    const url = new URL(value);
+    return `${url.origin}${url.pathname}`;
+  } catch {
+    return value.split("?")[0] ?? null;
+  }
+};
+
+/**
+ * CCTV debug logging 활성화 여부를 확인한다.
+ * @desc
+ * production default는 off다. `?udsCctvDebug=1` 또는
+ * `localStorage.setItem("uds:cctv:debug", "1")`로 runtime에서 켤 수 있다.
+ */
+export const isCctvDebugEnabled = (): boolean => {
+  if (!isBrowser()) return false;
+
+  const query = new URLSearchParams(window.location.search);
+  for (const key of DEBUG_QUERY_KEYS) {
+    if (query.has(key) && isDebugValueEnabled(query.get(key))) return true;
+  }
+
+  for (const key of DEBUG_STORAGE_KEYS) {
+    try {
+      if (isDebugValueEnabled(window.localStorage.getItem(key))) return true;
+    } catch {
+      return false;
+    }
+  }
+
+  return false;
+};
+
+/**
+ * reconnect 호출 주체를 좁히기 위한 stack trace 일부를 만든다.
+ */
+export const getCctvDebugStackTrace = (): string[] | null => {
+  if (!isCctvDebugEnabled()) return null;
+
+  const stack = new Error().stack;
+  if (!stack) return null;
+
+  return stack
+    .split("\n")
+    .slice(2, 8)
+    .map(line => line.trim());
+};
+
+const getCctvDebugBuffer = (): CctvDebugBuffer | null => {
+  if (!isCctvDebugEnabled()) return null;
+
+  const existingBuffer = window.__UDS_CCTV_DEBUG__;
+  if (existingBuffer) return existingBuffer;
+
+  const buffer: CctvDebugBuffer = {
+    enabled: true,
+    events: [],
+    limit: DEBUG_BUFFER_LIMIT,
+    sequence: 0,
+    clear: () => {
+      buffer.events.splice(0, buffer.events.length);
+      buffer.sequence = 0;
+    },
+    dump: () => [...buffer.events],
+  };
+
+  window.__UDS_CCTV_DEBUG__ = buffer;
+  return buffer;
+};
+
+/**
+ * CCTV runtime 진단 이벤트를 ring buffer와 console에 남긴다.
+ * @desc
+ * 토큰 값은 payload에 넣지 않는다. 이 logger는 debug flag가 켜진 경우에만 동작한다.
+ */
+export const logCctvDebugEvent = ({
+  event,
+  level = "debug",
+  payload,
+  source,
+}: {
+  event: string;
+  level?: CctvDebugEventLevel;
+  payload?: Record<string, unknown>;
+  source: string;
+}): void => {
+  const buffer = getCctvDebugBuffer();
+  if (!buffer) return;
+
+  const entry: CctvDebugEvent = {
+    at: new Date().toISOString(),
+    event,
+    level,
+    payload,
+    seq: buffer.sequence + 1,
+    source,
+  };
+
+  buffer.sequence = entry.seq;
+  buffer.events.push(entry);
+  if (buffer.events.length > buffer.limit) {
+    buffer.events.splice(0, buffer.events.length - buffer.limit);
+  }
+
+  const logger =
+    level === "error"
+      ? console.error
+      : level === "warn"
+        ? console.warn
+        : level === "info"
+          ? console.info
+          : console.debug;
+
+  logger.call(console, "[UDS:CCTV]", entry);
+};

package/src/cctv/utils/video-state.ts

@@ -62,6 +62,10 @@ export function getOverlayMessage({
   if (canReconnect && RTC_SESSION_ENDED_RECONNECT_STATES.has(connectionState)) {
     return CCTV_MESSAGE.sessionEnded;
   }
+  // grace/stagger가 끝난 disconnected는 더 이상 준비 상태가 아니라 재연결 대상 장애다.
+  if (canReconnect && connectionState === "disconnected") {
+    return CCTV_MESSAGE.offline;
+  }
   if (isTokenLoading || isStreaming) return CCTV_MESSAGE.preparing;
   if (RTC_PREPARING_STATES.has(connectionState)) return CCTV_MESSAGE.preparing;
   return null;