@uniai-fe/uds-templates 0.6.14 → 0.6.16

package/dist/styles.css

@@ -1796,7 +1796,7 @@
   flex-direction: column;
   align-items: center;
   justify-content: center;
-  gap: 2px;
+  gap: var(--spacing-gap-4);
 }
 
 .cctv-video-loading-icon {

package/package.json

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

package/src/cctv/hooks/streamRegistry.ts

@@ -1,12 +1,6 @@
 "use client";
 
 import { startWhepStream, type WhepStreamHandle } from "@uniai-fe/util-rtc";
-import {
-  getCctvDebugJwtMetadata,
-  getCctvDebugKeyLabel,
-  getCctvDebugUrlLabel,
-  logCctvDebugEvent,
-} from "../utils/debug";
 
 interface CctvRtcStreamSnapshot {
   connectionState: RTCPeerConnectionState;
@@ -32,8 +26,6 @@ interface CctvRtcStreamStartParams {
   video: HTMLVideoElement;
 }
 
-const WHEP_ERROR_BODY_PREVIEW_LIMIT = 1000;
-
 const getEntrySnapshot = (
   entry?: CctvRtcStreamEntry,
 ): CctvRtcStreamSnapshot => ({
@@ -63,69 +55,7 @@ const notifyEntry = (entry: CctvRtcStreamEntry) => {
   entry.listeners.forEach(listener => listener(snapshot));
 };
 
-const getWhepResponseBodyPreview = async (
-  response: Response,
-): Promise<string | null> => {
-  try {
-    const text = await response.clone().text();
-    return text.slice(0, WHEP_ERROR_BODY_PREVIEW_LIMIT);
-  } catch {
-    return null;
-  }
-};
-
-/**
- * WHEP 실패 body를 startWhepStream 외부에서 관찰하기 위한 fetch wrapper.
- * @desc
- * 성공 응답은 그대로 통과시키고, 실패 응답에서만 clone body를 읽어 debug log에 남긴다.
- */
-const createCctvDebugWhepFetcher =
-  ({
-    endpoint,
-    identityKey,
-    streamKey,
-    token,
-  }: {
-    endpoint: string;
-    identityKey: string;
-    streamKey: string;
-    token: string;
-  }): typeof fetch =>
-  async (input, init) => {
-    const response = await fetch(input, init);
-    if (response.ok) return response;
-
-    logCctvDebugEvent({
-      event: "whep:response-error",
-      level: "error",
-      payload: {
-        endpoint: getCctvDebugUrlLabel(endpoint),
-        identityKey: getCctvDebugKeyLabel(identityKey),
-        responseBody: await getWhepResponseBodyPreview(response),
-        status: response.status,
-        statusText: response.statusText,
-        streamKey: getCctvDebugKeyLabel(streamKey),
-        token: getCctvDebugJwtMetadata(token),
-      },
-      source: "streamRegistry",
-    });
-
-    return response;
-  };
-
 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();
@@ -187,15 +117,6 @@ 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 &&
@@ -211,21 +132,10 @@ export function createCctvRtcStreamRegistry(): CctvRtcStreamRegistry {
     start({ endpoint, identityKey, streamKey, token, video }) {
       const existingEntry = entries.get(streamKey);
       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",
@@ -246,58 +156,18 @@ export function createCctvRtcStreamRegistry(): CctvRtcStreamRegistry {
         video.playsInline = true;
         video.autoplay = true;
       }
-      logCctvDebugEvent({
-        event: "start:create-entry",
-        payload: {
-          attachedVideoCount: entry.attachedVideos.size,
-          endpoint: getCctvDebugUrlLabel(endpoint),
-          identityKey: getCctvDebugKeyLabel(identityKey),
-          streamKey: getCctvDebugKeyLabel(streamKey),
-          token: getCctvDebugJwtMetadata(token),
-        },
-        source: "streamRegistry",
-      });
 
       startWhepStream({
         endpoint,
-        fetcher: createCctvDebugWhepFetcher({
-          endpoint,
-          identityKey,
-          streamKey,
-          token,
-        }),
         token,
         video,
         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),
           );
@@ -307,16 +177,6 @@ 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 => {
@@ -328,17 +188,6 @@ 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 =>
             clearVideoIfAttachedStream(attachedVideo, entry.stream),
           );

package/src/cctv/hooks/useRtcStream.ts

@@ -19,11 +19,6 @@ 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";
 
@@ -138,7 +133,7 @@ const canUseTokenForNewConnection = ({
  * @desc
  * return {
  *   videoRef, // WebRTC MediaStream을 연결할 video 요소 ref
- *   connectionState, // RTCPeerConnectionState 상태값
+ *   connectionState, // UI 표시 기준 RTCPeerConnectionState 상태값
  *   streamError, // 스트림 시도 중 발생한 오류 메시지
  *   isStreaming, // UI 표시 기준 스트림 연결 절차 진행 여부
  *   isTokenLoading, // UI 표시 기준 토큰 발급 요청 진행 여부
@@ -236,23 +231,9 @@ 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);
-  }, [debugBasePayload, streamIdentityKey]);
+  }, [streamIdentityKey]);
 
   const reconnectReason = useMemo(
     () =>
@@ -282,45 +263,14 @@ export function useCctvRtcStream({
       `${streamIdentityKey}|${reconnectReason}`,
     );
 
-    logCctvDebugEvent({
-      event: "reconnect-gate:timer-start",
-      payload: {
-        ...debugBasePayload,
-        isStreaming,
-        isTokenLoading,
-        reconnectDelayMs,
-        reconnectReason,
-      },
-      source: "useRtcStream",
-    });
-
     const timeout = setTimeout(() => {
       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",
-      });
     };
   }, [
-    debugBasePayload,
     hasConnected,
     isStreaming,
     isTokenLoading,
@@ -328,6 +278,13 @@ export function useCctvRtcStream({
     streamIdentityKey,
   ]);
 
+  const isPostConnectedRecoverableState =
+    hasConnected &&
+    Boolean(streamIdentityKey) &&
+    !isTokenError &&
+    !streamError &&
+    DISPLAY_CONNECTED_DURING_RECOVERY_STATES.has(connectionState);
+
   const isPostConnectedReplacementLoading =
     hasConnected &&
     Boolean(streamIdentityKey) &&
@@ -336,13 +293,10 @@ export function useCctvRtcStream({
     (isTokenLoading || isStreaming);
 
   const shouldPreserveConnectedDisplay =
-    isPostConnectedReplacementLoading ||
-    (hasConnected &&
-      !isPostConnectedReconnectReady &&
-      DISPLAY_CONNECTED_DURING_RECOVERY_STATES.has(connectionState));
+    isPostConnectedReplacementLoading || isPostConnectedRecoverableState;
 
   // 반환 state는 CamList/Viewer/overlay의 live/error/message 계산에 직접 쓰인다.
-  // post-connected recovery/replacement 중에는 기존 화면을 유지해 UI reset 파동을 막는다.
+  // post-connected recovery/replacement 중에는 canReconnect만 열고, 기존 화면은 유지해 UI reset 파동을 막는다.
   const displayConnectionState = shouldPreserveConnectedDisplay
     ? "connected"
     : connectionState;
@@ -353,36 +307,6 @@ export function useCctvRtcStream({
     ? false
     : isTokenLoading;
 
-  const skippedDisconnectedDebugKeyRef = useRef<string | null>(null);
-
-  useEffect(() => {
-    if (
-      connectionState !== "disconnected" ||
-      !hasConnected ||
-      !streamIdentityKey
-    ) {
-      if (connectionState !== "disconnected") {
-        skippedDisconnectedDebugKeyRef.current = null;
-      }
-      return;
-    }
-
-    const skipKey = `${streamIdentityKey}|${activeStreamKeyRef.current ?? ""}`;
-    if (skippedDisconnectedDebugKeyRef.current === skipKey) return;
-
-    skippedDisconnectedDebugKeyRef.current = skipKey;
-    logCctvDebugEvent({
-      event: "reconnect-gate:skip-disconnected",
-      payload: {
-        ...debugBasePayload,
-        connectionState,
-        reason: "disconnected-observed-only",
-        streamKey: getCctvDebugKeyLabel(activeStreamKeyRef.current),
-      },
-      source: "useRtcStream",
-    });
-  }, [connectionState, debugBasePayload, hasConnected, streamIdentityKey]);
-
   const hasReusableRegistryStream = useMemo(() => {
     if (!streamKeyCandidate) return false;
 
@@ -432,19 +356,9 @@ 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,
@@ -459,15 +373,6 @@ 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);
       }
@@ -493,42 +398,12 @@ export function useCctvRtcStream({
       if (!previousStreamKey || didClosePreviousStream) return;
 
       didClosePreviousStream = true;
-      logCctvDebugEvent({
-        event: "stream-effect:close-previous-after-track",
-        payload: {
-          ...debugBasePayload,
-          previousStreamKey: getCctvDebugKeyLabel(previousStreamKey),
-          streamKey: getCctvDebugKeyLabel(streamKey),
-        },
-        source: "useRtcStream",
-      });
       streamRegistry.closeByIdentity(streamIdentityKey, streamKey);
     };
 
-    if (previousStreamKey) {
-      logCctvDebugEvent({
-        event: "stream-effect:prepare-replacement",
-        payload: {
-          ...debugBasePayload,
-          previousStreamKey: getCctvDebugKeyLabel(previousStreamKey),
-          streamKey: getCctvDebugKeyLabel(streamKey),
-        },
-        source: "useRtcStream",
-      });
-    }
-
     activeStreamKeyRef.current = streamKey;
     activeStreamIdentityKeyRef.current = streamIdentityKey;
 
-    logCctvDebugEvent({
-      event: "stream-effect:start",
-      payload: {
-        ...debugBasePayload,
-        streamKey: getCctvDebugKeyLabel(streamKey),
-      },
-      source: "useRtcStream",
-    });
-
     streamRegistry.start({
       streamKey,
       identityKey: streamIdentityKey,
@@ -543,14 +418,6 @@ export function useCctvRtcStream({
       setStreamError(snapshot.streamError);
       setStreaming(snapshot.isStreaming);
       if (snapshot.connectionState === "connected") {
-        logCctvDebugEvent({
-          event: "stream-effect:has-connected",
-          payload: {
-            ...debugBasePayload,
-            streamKey: getCctvDebugKeyLabel(streamKey),
-          },
-          source: "useRtcStream",
-        });
         setHasConnected(true);
       }
       if (snapshot.stream) {
@@ -575,19 +442,10 @@ 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,
@@ -597,52 +455,8 @@ 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",
-      });
-      return result;
-    },
+    options => refetchRtcToken(options),
     [refetchRtcToken],
   );
 
@@ -678,16 +492,6 @@ export function useCctvRtcStream({
         return;
 
       lastAutoReconnectAtRef.current = now;
-      logCctvDebugEvent({
-        event: "focus:auto-reconnect",
-        payload: {
-          ...debugBasePayload,
-          canReconnect,
-          connectionState,
-          reconnectReason,
-        },
-        source: "useRtcStream",
-      });
       void reconnectStream();
     };
 
@@ -698,13 +502,7 @@ export function useCctvRtcStream({
       window.removeEventListener("focus", reconnectOnFocus);
       document.removeEventListener("visibilitychange", reconnectOnFocus);
     };
-  }, [
-    canReconnect,
-    connectionState,
-    debugBasePayload,
-    reconnectReason,
-    reconnectStream,
-  ]);
+  }, [canReconnect, reconnectStream]);
 
   const liveState = useMemo(
     () =>
@@ -728,46 +526,6 @@ export function useCctvRtcStream({
     ],
   );
 
-  useEffect(() => {
-    logCctvDebugEvent({
-      event: "hook-state:update",
-      payload: {
-        ...debugBasePayload,
-        canReconnect,
-        connectionState,
-        displayConnectionState,
-        hasConnected,
-        isPostConnectedReplacementLoading,
-        isPostConnectedReconnectReady,
-        displayIsStreaming,
-        displayIsTokenLoading,
-        isStreaming,
-        isTokenError,
-        isTokenLoading,
-        liveState,
-        reconnectReason,
-        streamError,
-      },
-      source: "useRtcStream",
-    });
-  }, [
-    canReconnect,
-    connectionState,
-    debugBasePayload,
-    displayConnectionState,
-    displayIsStreaming,
-    displayIsTokenLoading,
-    hasConnected,
-    isPostConnectedReplacementLoading,
-    isPostConnectedReconnectReady,
-    isStreaming,
-    isTokenError,
-    isTokenLoading,
-    liveState,
-    reconnectReason,
-    streamError,
-  ]);
-
   useEffect(() => {
     const camId = cam?.cam_id;
     if (!camId) return;

package/src/cctv/styles/video.scss

@@ -137,7 +137,7 @@
   flex-direction: column;
   align-items: center;
   justify-content: center;
-  gap: 2px;
+  gap: var(--spacing-gap-4);
 }
 .cctv-video-loading-icon {
   flex: 0 0 auto;

package/src/cctv/types/hook.ts

@@ -59,7 +59,7 @@ export interface UseCctvRtcStreamError {
 
 /**
  * CCTV; useCctvRtcStream 연결 상태
- * @property {RTCPeerConnectionState} connectionState WebRTC 연결 상태
+ * @property {RTCPeerConnectionState} connectionState UI 표시 기준 WebRTC 연결 상태
  * @property {boolean} isStreaming UI 표시 기준 startWhepStream 진행 여부
  * @property {boolean} isTokenLoading UI 표시 기준 토큰 발급 요청 진행 여부
  * @property {boolean} isTokenError 토큰 발급 실패 여부
@@ -67,7 +67,11 @@ export interface UseCctvRtcStreamError {
  */
 export interface UseCctvRtcStreamState extends UseCctvRtcStreamError {
   /**
-   * WebRTC 연결 상태
+   * UI 표시 기준 WebRTC 연결 상태
+   * @desc
+   * 최초 연결 전에는 실제 PeerConnection 상태를 나타낸다. 이미 한 번 연결된 stream이
+   * recoverable `disconnected`/`failed` 상태에 들어가면 기존 화면과 live count 유지를 위해
+   * `connected`로 smoothing될 수 있다.
    */
   connectionState: RTCPeerConnectionState;
   /**
@@ -89,7 +93,7 @@ export interface UseCctvRtcStreamState extends UseCctvRtcStreamError {
 /**
  * CCTV; useCctvRtcStream return
  * @property {React.RefObject<HTMLVideoElement>} videoRef <video /> ref
- * @property {RTCPeerConnectionState} connectionState WebRTC 연결 상태
+ * @property {RTCPeerConnectionState} connectionState UI 표시 기준 WebRTC 연결 상태
  * @property {string | null} streamError 스트림 오류 메시지
  * @property {boolean} isStreaming UI 표시 기준 startWhepStream 진행 여부
  * @property {boolean} isTokenLoading UI 표시 기준 토큰 발급 요청 진행 여부
@@ -110,6 +114,7 @@ export interface UseCctvRtcStreamReturn extends UseCctvRtcStreamState {
    * 서비스 overlay가 reconnectStream()을 호출해도 되는 시점에 true가 된다.
    * post-connected `disconnected`는 자동 재연결 사유가 아니며,
    * token/stream 오류 또는 `failed`처럼 명확한 복구 사유만 true 전환 후보가 된다.
+   * recoverable `failed`에서는 화면이 live로 유지되는 동안에도 true가 될 수 있다.
    */
   canReconnect: boolean;
   /**

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

@@ -6,12 +6,13 @@ import type { UseCctvRtcStreamError, UseCctvRtcStreamState } from "./hook";
  * @property {CctvCompanyCameraData} [cam] 카메라 데이터
  * @property {boolean} [hasCamProp] 직접 cam prop을 받은 경우 true
  * @property {boolean} [isFetching] 서버에서 cam 리스트를 가져오는 중인지 여부
- * @property {RTCPeerConnectionState} connectionState WebRTC 연결 상태
+ * @property {RTCPeerConnectionState} connectionState UI 표시 기준 WebRTC 연결 상태
  * @property {boolean} isStreaming UI 표시 기준 startWhepStream 진행 여부
  * @property {boolean} isTokenLoading UI 표시 기준 토큰 발급 요청 진행 여부
  * @property {boolean} isTokenError 토큰 발급 실패 여부
  * @property {string | null} streamError 스트림 오류 메시지
- * @property {boolean} [canReconnect] UDS 내부 허용 사유와 grace/stagger를 통과해 재연결 호출이 가능한지 여부
+ * @property {boolean} [canReconnect] UDS 내부 허용 사유와 grace/stagger를 통과해 재연결 호출이 가능한지 여부.
+ * 오류 스타일 판정에는 직접 사용하지 않는다.
  */
 export interface CctvVideoOverlayMessageParams extends UseCctvRtcStreamState {
   /**
@@ -28,6 +29,8 @@ export interface CctvVideoOverlayMessageParams extends UseCctvRtcStreamState {
   isFetching?: boolean;
   /**
    * UDS 내부 허용 사유와 grace/stagger를 통과해 재연결 호출이 가능한지 여부
+   * @desc
+   * 재연결 trigger gate이며, 기본 error style 판정에는 직접 사용하지 않는다.
    */
   canReconnect?: boolean;
 }
@@ -35,7 +38,7 @@ export interface CctvVideoOverlayMessageParams extends UseCctvRtcStreamState {
 /**
  * CCTV; getIsLive() params
  * @property {CctvCompanyCameraData} [cam] 카메라 데이터
- * @property {RTCPeerConnectionState} connectionState WebRTC 연결 상태
+ * @property {RTCPeerConnectionState} connectionState UI 표시 기준 WebRTC 연결 상태
  * @property {boolean} isStreaming UI 표시 기준 startWhepStream 진행 여부
  * @property {boolean} isTokenLoading UI 표시 기준 토큰 발급 요청 진행 여부
  * @property {boolean} isTokenError 토큰 발급 실패 여부
@@ -53,7 +56,8 @@ export interface CctvVideoLiveParams extends UseCctvRtcStreamState {
  * @property {CctvCompanyCameraData} [cam] 카메라 데이터
  * @property {boolean} isTokenError 토큰 발급 실패 여부
  * @property {string | null} streamError 스트림 오류 메시지
- * @property {boolean} [canReconnect] UDS 내부 허용 사유와 grace/stagger를 통과해 재연결 호출이 가능한지 여부
+ * @property {boolean} [canReconnect] UDS 내부 허용 사유와 grace/stagger를 통과해 재연결 호출이 가능한지 여부.
+ * 오류 스타일 판정에는 직접 사용하지 않는다.
  */
 export interface CctvVideoErrorParams extends UseCctvRtcStreamError {
   /**
@@ -62,6 +66,8 @@ export interface CctvVideoErrorParams extends UseCctvRtcStreamError {
   cam?: CctvCompanyCameraData;
   /**
    * UDS 내부 허용 사유와 grace/stagger를 통과해 재연결 호출이 가능한지 여부
+   * @desc
+   * 재연결 trigger gate이며, 기본 error style 판정에는 직접 사용하지 않는다.
    */
   canReconnect?: boolean;
 }

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

@@ -31,7 +31,7 @@ const RTC_SESSION_ENDED_RECONNECT_STATES = new Set<RTCPeerConnectionState>([
  * @property {CctvCompanyCameraData} [cam] 카메라 데이터
  * @property {boolean} [hasCamProp] 직접 cam prop을 받은 경우 true
  * @property {boolean} [isFetching] 서버에서 cam 리스트를 가져오는 중인지 여부
- * @property {RTCPeerConnectionState} connectionState WebRTC 연결 상태
+ * @property {RTCPeerConnectionState} connectionState UI 표시 기준 WebRTC 연결 상태
  * @property {boolean} isStreaming UI 표시 기준 startWhepStream 진행 여부
  * @property {boolean} isTokenLoading UI 표시 기준 토큰 발급 요청 진행 여부
  * @property {boolean} isTokenError 토큰 발급 실패 여부
@@ -72,7 +72,7 @@ export function getOverlayMessage({
  * CCTV; 스트리밍 라이브 상태 판단
  * @param {CctvVideoLiveParams} params 상태 파라미터
  * @property {CctvCompanyCameraData} [cam] 카메라 데이터
- * @property {RTCPeerConnectionState} connectionState WebRTC 연결 상태
+ * @property {RTCPeerConnectionState} connectionState UI 표시 기준 WebRTC 연결 상태
  * @property {boolean} isStreaming UI 표시 기준 startWhepStream 진행 여부
  * @property {boolean} isTokenLoading UI 표시 기준 토큰 발급 요청 진행 여부
  * @property {boolean} isTokenError 토큰 발급 실패 여부
@@ -102,17 +102,16 @@ export function getIsLive({
  * @property {CctvCompanyCameraData} [cam] 카메라 데이터
  * @property {boolean} isTokenError 토큰 발급 실패 여부
  * @property {string | null} streamError 스트림 오류 메시지
+ * @property {boolean} [canReconnect] 재연결 trigger 가능 여부. 오류 표시 여부에는 직접 사용하지 않는다.
  * @returns {boolean} 에러 상태 여부 반환
  */
 export function getIsError({
   cam,
-  canReconnect,
   isTokenError,
   streamError,
 }: CctvVideoErrorParams): boolean {
   if (!cam) return true;
   if (!cam.cam_online) return true;
-  if (canReconnect) return true;
   if (isTokenError) return true;
   if (streamError) return true;
   return false;

package/src/cctv/utils/debug.ts

@@ -1,461 +0,0 @@
-"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 CctvDebugReconnectStartSummary {
-  at: string;
-  caller: string | null;
-  camId: string | null;
-  connectionState: string | null;
-  isPostConnectedReconnectReady: boolean | null;
-  reconnectReason: string | null;
-}
-
-export interface CctvDebugSummary {
-  connectionStateCounts: Record<string, number>;
-  eventCounts: Record<string, number>;
-  first: string | null;
-  generatedAt: string;
-  last: string | null;
-  reconnectCallers: Record<string, number>;
-  reconnectReasons: Record<string, number>;
-  reconnectStarts: CctvDebugReconnectStartSummary[];
-  total: number;
-}
-
-export interface CctvDebugJwtMetadata {
-  expiresAt: string | null;
-  expiresInSec: number | null;
-  headerAlg: string | null;
-  headerKid: string | null;
-  tokenLabel: string | null;
-  tokenPartCount: number;
-}
-
-export interface CctvDebugBuffer {
-  clear: () => void;
-  dump: () => CctvDebugEvent[];
-  enabled: true;
-  events: CctvDebugEvent[];
-  filter: (keywords?: readonly string[]) => CctvDebugEvent[];
-  limit: number;
-  sequence: number;
-  summary: () => CctvDebugSummary;
-}
-
-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_CONSOLE_QUERY_KEYS = [
-  "udsCctvDebugConsole",
-  "cctvDebugConsole",
-] as const;
-const DEBUG_CONSOLE_STORAGE_KEYS = [
-  "uds:cctv:debug:console",
-  "UDS_CCTV_DEBUG_CONSOLE",
-] as const;
-const DEBUG_ENABLED_VALUES = new Set(["1", "true", "yes", "on", "debug"]);
-const DEBUG_DISABLED_VALUES = new Set(["0", "false", "no", "off"]);
-const DEBUG_BUFFER_LIMIT = 1000;
-const DEBUG_DEFAULT_FILTER_KEYWORDS = [
-  "reconnect",
-  "close",
-  "rejected",
-  "connection-state:change",
-  "track:received",
-] as const;
-
-const isBrowser = (): boolean =>
-  typeof window !== "undefined" && typeof document !== "undefined";
-
-const getDebugValueOverride = (value: string | null): boolean | null => {
-  if (value === "") return true;
-  if (typeof value !== "string") return null;
-
-  const normalizedValue = value.toLowerCase();
-  if (DEBUG_ENABLED_VALUES.has(normalizedValue)) return true;
-  if (DEBUG_DISABLED_VALUES.has(normalizedValue)) return false;
-  return null;
-};
-
-const getDebugQueryOverride = (keys: readonly string[]): boolean | null => {
-  const query = new URLSearchParams(window.location.search);
-  for (const key of keys) {
-    if (!query.has(key)) continue;
-
-    const override = getDebugValueOverride(query.get(key));
-    if (override !== null) return override;
-  }
-
-  return null;
-};
-
-const getDebugStorageOverride = (keys: readonly string[]): boolean | null => {
-  for (const key of keys) {
-    try {
-      const override = getDebugValueOverride(window.localStorage.getItem(key));
-      if (override !== null) return override;
-    } catch {
-      return false;
-    }
-  }
-
-  return null;
-};
-
-const getDebugConsoleOverride = (): boolean | null => {
-  const queryOverride = getDebugQueryOverride(DEBUG_CONSOLE_QUERY_KEYS);
-  if (queryOverride !== null) return queryOverride;
-
-  return getDebugStorageOverride(DEBUG_CONSOLE_STORAGE_KEYS);
-};
-
-const isLocalhostDebugDefaultEnabled = (): boolean => {
-  const { hostname } = window.location;
-  return (
-    hostname === "localhost" ||
-    hostname === "127.0.0.1" ||
-    hostname === "[::1]" ||
-    hostname === "::1" ||
-    hostname.endsWith(".localhost")
-  );
-};
-
-const getPayloadString = (
-  payload: Record<string, unknown> | undefined,
-  key: string,
-): string | null => {
-  const value = payload?.[key];
-  return typeof value === "string" ? value : null;
-};
-
-const getPayloadBoolean = (
-  payload: Record<string, unknown> | undefined,
-  key: string,
-): boolean | null => {
-  const value = payload?.[key];
-  return typeof value === "boolean" ? value : null;
-};
-
-const getReconnectCaller = (
-  payload: Record<string, unknown> | undefined,
-): string | null => {
-  const callerStack = payload?.callerStack;
-  const stackLines = Array.isArray(callerStack)
-    ? callerStack.filter((line): line is string => typeof line === "string")
-    : typeof callerStack === "string"
-      ? callerStack.split("\n")
-      : [];
-
-  return (
-    stackLines
-      .find(
-        line =>
-          line.includes("CCTVManagerVideoOverlay") ||
-          line.includes("reconnectOnFocus"),
-      )
-      ?.trim() ?? null
-  );
-};
-
-const countBy = <T extends string>(
-  target: Record<T, number>,
-  key: T | null,
-): void => {
-  if (!key) return;
-  target[key] = (target[key] ?? 0) + 1;
-};
-
-const filterCctvDebugEvents = (
-  events: readonly CctvDebugEvent[],
-  keywords: readonly string[] = DEBUG_DEFAULT_FILTER_KEYWORDS,
-): CctvDebugEvent[] =>
-  events.filter(entry =>
-    keywords.some(keyword => entry.event.includes(keyword)),
-  );
-
-const summarizeCctvDebugEvents = (
-  events: readonly CctvDebugEvent[],
-): CctvDebugSummary => {
-  const eventCounts: Record<string, number> = {};
-  const connectionStateCounts: Record<string, number> = {};
-  const reconnectReasons: Record<string, number> = {};
-  const reconnectCallers: Record<string, number> = {};
-  const reconnectStarts: CctvDebugReconnectStartSummary[] = [];
-
-  for (const entry of events) {
-    countBy(eventCounts, entry.event);
-
-    if (entry.event === "connection-state:change") {
-      countBy(connectionStateCounts, getPayloadString(entry.payload, "state"));
-    }
-
-    if (entry.event !== "reconnect-stream:start") continue;
-
-    const reconnectReason = getPayloadString(entry.payload, "reconnectReason");
-    const caller = getReconnectCaller(entry.payload);
-
-    countBy(reconnectReasons, reconnectReason ?? "none");
-    countBy(reconnectCallers, caller ?? "unknown");
-    reconnectStarts.push({
-      at: entry.at,
-      caller,
-      camId: getPayloadString(entry.payload, "camId"),
-      connectionState: getPayloadString(entry.payload, "connectionState"),
-      isPostConnectedReconnectReady: getPayloadBoolean(
-        entry.payload,
-        "isPostConnectedReconnectReady",
-      ),
-      reconnectReason,
-    });
-  }
-
-  return {
-    connectionStateCounts,
-    eventCounts,
-    first: events[0]?.at ?? null,
-    generatedAt: new Date().toISOString(),
-    last: events[events.length - 1]?.at ?? null,
-    reconnectCallers,
-    reconnectReasons,
-    reconnectStarts,
-    total: events.length,
-  };
-};
-
-const decodeBase64UrlJson = (value: string): Record<string, unknown> | null => {
-  try {
-    const base64 = value.replace(/-/g, "+").replace(/_/g, "/");
-    const padded = base64.padEnd(Math.ceil(base64.length / 4) * 4, "=");
-    const parsed = JSON.parse(atob(padded));
-
-    return parsed && typeof parsed === "object" && !Array.isArray(parsed)
-      ? (parsed as Record<string, unknown>)
-      : null;
-  } catch {
-    return null;
-  }
-};
-
-const getJwtStringClaim = (
-  claims: Record<string, unknown> | null,
-  key: string,
-): string | null => {
-  const value = claims?.[key];
-  return typeof value === "string" ? value : null;
-};
-
-const getJwtExpiresAt = (
-  claims: Record<string, unknown> | null,
-): { expiresAt: string | null; expiresInSec: number | null } => {
-  const exp = claims?.exp;
-  if (typeof exp !== "number" || !Number.isFinite(exp)) {
-    return { expiresAt: null, expiresInSec: null };
-  }
-
-  const expiresAtMs = exp * 1000;
-  return {
-    expiresAt: new Date(expiresAtMs).toISOString(),
-    expiresInSec: Math.floor((expiresAtMs - Date.now()) / 1000),
-  };
-};
-
-const stringifyCctvDebugEvent = (entry: CctvDebugEvent): string => {
-  try {
-    return JSON.stringify(entry);
-  } catch {
-    return JSON.stringify({
-      at: entry.at,
-      event: entry.event,
-      level: entry.level,
-      seq: entry.seq,
-      source: entry.source,
-    });
-  }
-};
-
-/**
- * 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;
-  }
-};
-
-/**
- * JWT 원문 대신 헤더/만료시각과 hash label만 기록한다.
- * @desc
- * token signature mismatch를 추적하기 위한 메타 정보이며, Bearer token 원문과 payload claim은
- * debug log에 남기지 않는다.
- */
-export const getCctvDebugJwtMetadata = (
-  token: string | null | undefined,
-): CctvDebugJwtMetadata | null => {
-  if (!token) return null;
-
-  const [headerPart, payloadPart] = token.split(".");
-  const header = headerPart ? decodeBase64UrlJson(headerPart) : null;
-  const payload = payloadPart ? decodeBase64UrlJson(payloadPart) : null;
-  const { expiresAt, expiresInSec } = getJwtExpiresAt(payload);
-
-  return {
-    expiresAt,
-    expiresInSec,
-    headerAlg: getJwtStringClaim(header, "alg"),
-    headerKid: getJwtStringClaim(header, "kid"),
-    tokenLabel: getCctvDebugKeyLabel(token),
-    tokenPartCount: token.split(".").length,
-  };
-};
-
-/**
- * CCTV debug logging 활성화 여부를 확인한다.
- * @desc
- * production default는 off, localhost default는 ring buffer on이다.
- * console 출력은 별도 console flag를 켠 경우에만 활성화한다.
- */
-export const isCctvDebugEnabled = (): boolean => {
-  if (!isBrowser()) return false;
-
-  const queryOverride = getDebugQueryOverride(DEBUG_QUERY_KEYS);
-  if (queryOverride !== null) return queryOverride;
-
-  const consoleOverride = getDebugConsoleOverride();
-  if (consoleOverride === true) return true;
-
-  const storageOverride = getDebugStorageOverride(DEBUG_STORAGE_KEYS);
-  if (storageOverride !== null) return storageOverride;
-
-  return isLocalhostDebugDefaultEnabled();
-};
-
-const isCctvDebugConsoleEnabled = (): boolean => {
-  if (!isBrowser()) return false;
-
-  return getDebugConsoleOverride() === true;
-};
-
-/**
- * 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],
-    filter: keywords => filterCctvDebugEvents(buffer.events, keywords),
-    summary: () => summarizeCctvDebugEvents(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);
-  }
-
-  if (!isCctvDebugConsoleEnabled()) return;
-
-  const logger =
-    level === "error"
-      ? console.error
-      : level === "warn"
-        ? console.warn
-        : level === "info"
-          ? console.info
-          : console.debug;
-
-  logger.call(console, `[UDS:CCTV] ${stringifyCctvDebugEvent(entry)}`);
-};