@uniai-fe/uds-templates 0.6.9 → 0.6.10

package/package.json

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

package/src/cctv/hooks/useRtcStream.ts

@@ -32,16 +32,10 @@ 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";
+type CctvRtcReconnectReason = "tokenError" | "streamError" | "failed";
 
-const DISPLAY_CONNECTED_DURING_GRACE_STATES = new Set<RTCPeerConnectionState>([
-  "disconnected",
-  "failed",
-]);
+const DISPLAY_CONNECTED_DURING_RECOVERY_STATES =
+  new Set<RTCPeerConnectionState>(["disconnected", "failed"]);
 
 /**
  * 같은 회사/카메라 묶음이 동시에 재연결하지 않도록 identity 기반 지연값을 만든다.
@@ -70,6 +64,8 @@ const getPostConnectedReconnectDelayMs = (delayKey: string): number =>
  * @desc
  * `closed`는 `streamRegistry.closeByIdentity()`처럼 UDS가 의도적으로 닫을 때도 발생하므로
  * 자동 재연결 사유에 포함하지 않는다.
+ * `disconnected`는 ICE transient 상태에서도 발생하고 기존 MediaStream track이 살아 있을 수 있으므로,
+ * media-health 확인 없이 자동 재연결을 유발하지 않는다.
  */
 const getPostConnectedReconnectReason = ({
   connectionState,
@@ -83,7 +79,6 @@ const getPostConnectedReconnectReason = ({
   if (isTokenError) return "tokenError";
   if (streamError) return "streamError";
   if (connectionState === "failed") return "failed";
-  if (connectionState === "disconnected") return "disconnected";
   return null;
 };
 
@@ -336,12 +331,44 @@ export function useCctvRtcStream({
   const shouldPreserveConnectedDisplay =
     hasConnected &&
     !isPostConnectedReconnectReady &&
-    DISPLAY_CONNECTED_DURING_GRACE_STATES.has(connectionState);
+    DISPLAY_CONNECTED_DURING_RECOVERY_STATES.has(connectionState);
 
+  // 반환 state는 CamList/Viewer/overlay의 live/error/message 계산에 직접 쓰인다.
+  // post-connected disconnected는 자동 재연결 대신 기존 화면을 유지해 UI reset 파동을 막는다.
   const displayConnectionState = shouldPreserveConnectedDisplay
     ? "connected"
     : connectionState;
 
+  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;
 

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 UDS 내부 grace/stagger를 통과해 재연결 호출이 가능한지 여부
+ * @property {boolean} canReconnect UDS 내부 허용 사유와 grace/stagger를 통과해 재연결 호출이 가능한지 여부
  * @property {() => Promise<void>} refetchToken 토큰 재발급 함수
  * @property {() => Promise<QueryObserverResult<API_Res_CctvRtcToken>>} reconnectStream 재연결 trigger 함수
  */
@@ -98,10 +98,12 @@ export interface UseCctvRtcStreamReturn extends UseCctvRtcStreamState {
    */
   videoRef: React.RefObject<HTMLVideoElement | null>;
   /**
-   * UDS 내부 grace/stagger를 통과해 재연결 호출이 가능한지 여부
+   * UDS 내부 허용 사유와 grace/stagger를 통과해 재연결 호출이 가능한지 여부
    * @desc
    * 스트림 장애 감지 즉시 true가 되는 플래그가 아니라,
    * 서비스 overlay가 reconnectStream()을 호출해도 되는 시점에 true가 된다.
+   * post-connected `disconnected`는 자동 재연결 사유가 아니며,
+   * token/stream 오류 또는 `failed`처럼 명확한 복구 사유만 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] UDS 내부 grace/stagger를 통과해 재연결 호출이 가능한지 여부
+ * @property {boolean | undefined} [canReconnect] UDS 내부 허용 사유와 grace/stagger를 통과해 재연결 호출이 가능한지 여부
  * @property {CctvRtcReconnectTrigger | undefined} [reconnectStream] 재연결 trigger 함수
  */
 export interface CctvVideoRenderOverlayContext {
@@ -38,10 +38,11 @@ export interface CctvVideoRenderOverlayContext {
    */
   overlayMessage?: React.ReactNode;
   /**
-   * UDS 내부 grace/stagger를 통과해 재연결 호출이 가능한지 여부
+   * UDS 내부 허용 사유와 grace/stagger를 통과해 재연결 호출이 가능한지 여부
    * @desc
    * custom overlay에서 자동 재연결을 구현할 때 이 값이 true인 경우에만
    * reconnectStream()을 호출해야 한다.
+   * post-connected `disconnected`는 이 값만으로 자동 재연결하지 않는다.
    */
   canReconnect?: boolean;
   /**
@@ -129,7 +130,7 @@ export interface CctvVideoOverlayFooterProps {
  * @property {boolean} [isError] 에러 상태 여부
  * @property {boolean} [isLive] 영상이 정상적으로 재생 중인지 여부
  * @property {React.ReactNode} [overlayMessage] 에러/안내 메시지 콘텐츠
- * @property {boolean} [canReconnect] UDS 내부 grace/stagger를 통과해 재연결 호출이 가능한지 여부
+ * @property {boolean} [canReconnect] UDS 내부 허용 사유와 grace/stagger를 통과해 재연결 호출이 가능한지 여부
  * @property {CctvRtcReconnectTrigger} [reconnectStream] 재연결 trigger 함수
  */
 export interface CctvVideoStateProps {
@@ -146,7 +147,7 @@ export interface CctvVideoStateProps {
    */
   overlayMessage?: React.ReactNode;
   /**
-   * UDS 내부 grace/stagger를 통과해 재연결 호출이 가능한지 여부
+   * 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] UDS 내부 grace/stagger를 통과해 재연결 호출이 가능한지 여부
+ * @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를 통과해 재연결 호출이 가능한지 여부
+   * 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] UDS 내부 grace/stagger를 통과해 재연결 호출이 가능한지 여부
+ * @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를 통과해 재연결 호출이 가능한지 여부
+   * UDS 내부 허용 사유와 grace/stagger를 통과해 재연결 호출이 가능한지 여부
    */
   canReconnect?: boolean;
 }

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

@@ -62,10 +62,7 @@ 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;
-  }
+  // raw disconnected는 useCctvRtcStream에서 post-connected connected로 smoothing한다.
   if (isTokenLoading || isStreaming) return CCTV_MESSAGE.preparing;
   if (RTC_PREPARING_STATES.has(connectionState)) return CCTV_MESSAGE.preparing;
   return null;