@uniai-fe/uds-templates 0.6.13 → 0.6.15

package/package.json

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

package/src/cctv/hooks/streamRegistry.ts

@@ -49,6 +49,15 @@ const attachVideo = (video: HTMLVideoElement, stream: MediaStream | null) => {
   video.srcObject = stream;
 };
 
+const clearVideoIfAttachedStream = (
+  video: HTMLVideoElement,
+  stream: MediaStream | null,
+) => {
+  if (stream && video.srcObject === stream) {
+    video.srcObject = null;
+  }
+};
+
 const notifyEntry = (entry: CctvRtcStreamEntry) => {
   const snapshot = getEntrySnapshot(entry);
   entry.listeners.forEach(listener => listener(snapshot));
@@ -125,9 +134,7 @@ const closeEntry = (entry: CctvRtcStreamEntry) => {
   entry.isStreaming = false;
 
   entry.attachedVideos.forEach(video => {
-    if (!entry.stream || video.srcObject === entry.stream) {
-      video.srcObject = null;
-    }
+    clearVideoIfAttachedStream(video, entry.stream);
   });
 
   notifyEntry(entry);
@@ -166,13 +173,13 @@ export function createCctvRtcStreamRegistry(): CctvRtcStreamRegistry {
       }
 
       entry.attachedVideos.add(video);
-      attachVideo(video, entry.stream);
+      if (entry.stream || !video.srcObject) {
+        attachVideo(video, entry.stream);
+      }
 
       return () => {
         entry.attachedVideos.delete(video);
-        if (!entry.stream || video.srcObject === entry.stream) {
-          video.srcObject = null;
-        }
+        clearVideoIfAttachedStream(video, entry.stream);
       };
     },
     closeAll() {
@@ -233,7 +240,12 @@ export function createCctvRtcStreamRegistry(): CctvRtcStreamRegistry {
       };
 
       entries.set(streamKey, entry);
-      attachVideo(video, null);
+      if (!video.srcObject) {
+        attachVideo(video, null);
+      } else {
+        video.playsInline = true;
+        video.autoplay = true;
+      }
       logCctvDebugEvent({
         event: "start:create-entry",
         payload: {
@@ -328,7 +340,7 @@ export function createCctvRtcStreamRegistry(): CctvRtcStreamRegistry {
             source: "streamRegistry",
           });
           entry.attachedVideos.forEach(attachedVideo =>
-            attachVideo(attachedVideo, null),
+            clearVideoIfAttachedStream(attachedVideo, entry.stream),
           );
           notifyEntry(entry);
         });

package/src/cctv/hooks/useRtcStream.ts

@@ -138,10 +138,10 @@ const canUseTokenForNewConnection = ({
  * @desc
  * return {
  *   videoRef, // WebRTC MediaStream을 연결할 video 요소 ref
- *   connectionState, // RTCPeerConnectionState 상태값
+ *   connectionState, // UI 표시 기준 RTCPeerConnectionState 상태값
  *   streamError, // 스트림 시도 중 발생한 오류 메시지
- *   isStreaming, // 현재 스트림 연결 절차가 진행 중인지 여부
- *   isTokenLoading, // 토큰 발급 요청이 진행 중인지 여부
+ *   isStreaming, // UI 표시 기준 스트림 연결 절차 진행 여부
+ *   isTokenLoading, // UI 표시 기준 토큰 발급 요청 진행 여부
  *   isTokenError, // 토큰 발급 요청이 실패했는지 여부
  *   canReconnect, // UDS 내부 grace/stagger 이후 재연결 호출이 가능한지 여부
  *   refetchToken, // 토큰 발급을 재시도하는 함수
@@ -328,16 +328,34 @@ export function useCctvRtcStream({
     streamIdentityKey,
   ]);
 
-  const shouldPreserveConnectedDisplay =
+  const isPostConnectedRecoverableState =
     hasConnected &&
-    !isPostConnectedReconnectReady &&
+    Boolean(streamIdentityKey) &&
+    !isTokenError &&
+    !streamError &&
     DISPLAY_CONNECTED_DURING_RECOVERY_STATES.has(connectionState);
 
+  const isPostConnectedReplacementLoading =
+    hasConnected &&
+    Boolean(streamIdentityKey) &&
+    !isTokenError &&
+    !streamError &&
+    (isTokenLoading || isStreaming);
+
+  const shouldPreserveConnectedDisplay =
+    isPostConnectedReplacementLoading || isPostConnectedRecoverableState;
+
   // 반환 state는 CamList/Viewer/overlay의 live/error/message 계산에 직접 쓰인다.
-  // post-connected disconnected는 자동 재연결 대신 기존 화면을 유지해 UI reset 파동을 막는다.
+  // post-connected recovery/replacement 중에는 canReconnect만 열고, 기존 화면은 유지해 UI reset 파동을 막는다.
   const displayConnectionState = shouldPreserveConnectedDisplay
     ? "connected"
     : connectionState;
+  const displayIsStreaming = shouldPreserveConnectedDisplay
+    ? false
+    : isStreaming;
+  const displayIsTokenLoading = shouldPreserveConnectedDisplay
+    ? false
+    : isTokenLoading;
 
   const skippedDisconnectedDebugKeyRef = useRef<string | null>(null);
 
@@ -468,20 +486,39 @@ export function useCctvRtcStream({
     if (!streamKey || !tokenQuery.data?.token || !endpoint || !currentVideo)
       return;
 
-    if (
+    const previousStreamKey =
       activeStreamIdentityKeyRef.current === streamIdentityKey &&
       activeStreamKeyRef.current !== streamKey
-    ) {
+        ? activeStreamKeyRef.current
+        : null;
+    let didClosePreviousStream = false;
+
+    const closePreviousStreamAfterTrack = () => {
+      if (!previousStreamKey || didClosePreviousStream) return;
+
+      didClosePreviousStream = true;
       logCctvDebugEvent({
-        event: "stream-effect:close-previous-identity",
+        event: "stream-effect:close-previous-after-track",
         payload: {
           ...debugBasePayload,
-          activeStreamKey: getCctvDebugKeyLabel(activeStreamKeyRef.current),
-          nextStreamKey: getCctvDebugKeyLabel(streamKey),
+          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;
@@ -520,8 +557,11 @@ export function useCctvRtcStream({
         });
         setHasConnected(true);
       }
-      if (snapshot.stream && currentVideo.srcObject !== snapshot.stream) {
-        currentVideo.srcObject = snapshot.stream;
+      if (snapshot.stream) {
+        if (currentVideo.srcObject !== snapshot.stream) {
+          currentVideo.srcObject = snapshot.stream;
+        }
+        closePreviousStreamAfterTrack();
       }
     });
     const snapshot = streamRegistry.getSnapshot(streamKey);
@@ -530,8 +570,11 @@ export function useCctvRtcStream({
     setStreaming(snapshot.isStreaming);
     if (snapshot.connectionState === "connected") setHasConnected(true);
 
-    if (snapshot.stream && currentVideo.srcObject !== snapshot.stream) {
-      currentVideo.srcObject = snapshot.stream;
+    if (snapshot.stream) {
+      if (currentVideo.srcObject !== snapshot.stream) {
+        currentVideo.srcObject = snapshot.stream;
+      }
+      closePreviousStreamAfterTrack();
     }
 
     // effect cleanup: current video attach만 해제하고 registry stream은 유지한다.
@@ -602,17 +645,9 @@ export function useCctvRtcStream({
         },
         source: "useRtcStream",
       });
-      if (result.isSuccess && streamIdentityKey) {
-        logCctvDebugEvent({
-          event: "reconnect-stream:close-identity",
-          payload: resultDebugState.debugBasePayload,
-          source: "useRtcStream",
-        });
-        streamRegistry.closeByIdentity(streamIdentityKey);
-      }
       return result;
     },
-    [refetchRtcToken, streamIdentityKey, streamRegistry],
+    [refetchRtcToken],
   );
 
   const canReconnect = useMemo(() => {
@@ -681,18 +716,18 @@ export function useCctvRtcStream({
         ? getIsLive({
             cam,
             connectionState: displayConnectionState,
-            isTokenLoading,
+            isTokenLoading: displayIsTokenLoading,
             isTokenError,
-            isStreaming,
+            isStreaming: displayIsStreaming,
             streamError,
           })
         : false,
     [
       cam,
       displayConnectionState,
-      isTokenLoading,
+      displayIsTokenLoading,
       isTokenError,
-      isStreaming,
+      displayIsStreaming,
       streamError,
     ],
   );
@@ -706,7 +741,11 @@ export function useCctvRtcStream({
         connectionState,
         displayConnectionState,
         hasConnected,
+        isPostConnectedReplacementLoading,
+        isPostConnectedRecoverableState,
         isPostConnectedReconnectReady,
+        displayIsStreaming,
+        displayIsTokenLoading,
         isStreaming,
         isTokenError,
         isTokenLoading,
@@ -721,7 +760,11 @@ export function useCctvRtcStream({
     connectionState,
     debugBasePayload,
     displayConnectionState,
+    displayIsStreaming,
+    displayIsTokenLoading,
     hasConnected,
+    isPostConnectedReplacementLoading,
+    isPostConnectedRecoverableState,
     isPostConnectedReconnectReady,
     isStreaming,
     isTokenError,
@@ -770,8 +813,8 @@ export function useCctvRtcStream({
     videoRef,
     connectionState: displayConnectionState,
     streamError,
-    isStreaming,
-    isTokenLoading,
+    isStreaming: displayIsStreaming,
+    isTokenLoading: displayIsTokenLoading,
     isTokenError,
     canReconnect,
     refetchToken,

package/src/cctv/types/hook.ts

@@ -59,23 +59,33 @@ export interface UseCctvRtcStreamError {
 
 /**
  * CCTV; useCctvRtcStream 연결 상태
- * @property {RTCPeerConnectionState} connectionState WebRTC 연결 상태
- * @property {boolean} isStreaming startWhepStream 진행 여부
- * @property {boolean} isTokenLoading 토큰 발급 요청 진행 여부
+ * @property {RTCPeerConnectionState} connectionState UI 표시 기준 WebRTC 연결 상태
+ * @property {boolean} isStreaming UI 표시 기준 startWhepStream 진행 여부
+ * @property {boolean} isTokenLoading UI 표시 기준 토큰 발급 요청 진행 여부
  * @property {boolean} isTokenError 토큰 발급 실패 여부
  * @property {string | null} streamError 스트림 오류 메시지
  */
 export interface UseCctvRtcStreamState extends UseCctvRtcStreamError {
   /**
-   * WebRTC 연결 상태
+   * UI 표시 기준 WebRTC 연결 상태
+   * @desc
+   * 최초 연결 전에는 실제 PeerConnection 상태를 나타낸다. 이미 한 번 연결된 stream이
+   * recoverable `disconnected`/`failed` 상태에 들어가면 기존 화면과 live count 유지를 위해
+   * `connected`로 smoothing될 수 있다.
    */
   connectionState: RTCPeerConnectionState;
   /**
-   * startWhepStream 진행 여부
+   * UI 표시 기준 startWhepStream 진행 여부
+   * @desc
+   * 최초 연결 전에는 실제 진행 상태를 나타낸다. 이미 한 번 연결된 stream을 교체하는 동안에는
+   * 기존 화면과 live count를 유지하기 위해 false로 smoothing될 수 있다.
    */
   isStreaming: boolean;
   /**
-   * 토큰 발급 요청 진행 여부
+   * UI 표시 기준 토큰 발급 요청 진행 여부
+   * @desc
+   * 최초 연결 전에는 실제 요청 상태를 나타낸다. 이미 한 번 연결된 stream의 재연결 token
+   * 재발급 중에는 기존 화면과 live count를 유지하기 위해 false로 smoothing될 수 있다.
    */
   isTokenLoading: boolean;
 }
@@ -83,10 +93,10 @@ 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 startWhepStream 진행 여부
- * @property {boolean} isTokenLoading 토큰 발급 요청 진행 여부
+ * @property {boolean} isStreaming UI 표시 기준 startWhepStream 진행 여부
+ * @property {boolean} isTokenLoading UI 표시 기준 토큰 발급 요청 진행 여부
  * @property {boolean} isTokenError 토큰 발급 실패 여부
  * @property {boolean} canReconnect UDS 내부 허용 사유와 grace/stagger를 통과해 재연결 호출이 가능한지 여부
  * @property {() => Promise<void>} refetchToken 토큰 재발급 함수
@@ -104,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 {boolean} isStreaming startWhepStream 진행 여부
- * @property {boolean} isTokenLoading 토큰 발급 요청 진행 여부
+ * @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,9 +38,9 @@ export interface CctvVideoOverlayMessageParams extends UseCctvRtcStreamState {
 /**
  * CCTV; getIsLive() params
  * @property {CctvCompanyCameraData} [cam] 카메라 데이터
- * @property {RTCPeerConnectionState} connectionState WebRTC 연결 상태
- * @property {boolean} isStreaming startWhepStream 진행 여부
- * @property {boolean} isTokenLoading 토큰 발급 요청 진행 여부
+ * @property {RTCPeerConnectionState} connectionState UI 표시 기준 WebRTC 연결 상태
+ * @property {boolean} isStreaming UI 표시 기준 startWhepStream 진행 여부
+ * @property {boolean} isTokenLoading UI 표시 기준 토큰 발급 요청 진행 여부
  * @property {boolean} isTokenError 토큰 발급 실패 여부
  * @property {string | null} streamError 스트림 오류 메시지
  */
@@ -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,9 +31,9 @@ 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 {boolean} isStreaming startWhepStream 진행 여부
- * @property {boolean} isTokenLoading 토큰 발급 요청 진행 여부
+ * @property {RTCPeerConnectionState} connectionState UI 표시 기준 WebRTC 연결 상태
+ * @property {boolean} isStreaming UI 표시 기준 startWhepStream 진행 여부
+ * @property {boolean} isTokenLoading UI 표시 기준 토큰 발급 요청 진행 여부
  * @property {boolean} isTokenError 토큰 발급 실패 여부
  * @property {string | null} streamError 스트림 오류 메시지
  * @returns {string | null} 상태에 따른 메시지 반환 (문제가 없으면 null)
@@ -72,9 +72,9 @@ export function getOverlayMessage({
  * CCTV; 스트리밍 라이브 상태 판단
  * @param {CctvVideoLiveParams} params 상태 파라미터
  * @property {CctvCompanyCameraData} [cam] 카메라 데이터
- * @property {RTCPeerConnectionState} connectionState WebRTC 연결 상태
- * @property {boolean} isStreaming startWhepStream 진행 여부
- * @property {boolean} isTokenLoading 토큰 발급 요청 진행 여부
+ * @property {RTCPeerConnectionState} connectionState UI 표시 기준 WebRTC 연결 상태
+ * @property {boolean} isStreaming UI 표시 기준 startWhepStream 진행 여부
+ * @property {boolean} isTokenLoading UI 표시 기준 토큰 발급 요청 진행 여부
  * @property {boolean} isTokenError 토큰 발급 실패 여부
  * @property {string | null} streamError 스트림 오류 메시지
  * @returns {boolean} 라이브 상태 여부 반환
@@ -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;