@uniai-fe/uds-templates 0.6.13 → 0.6.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniai-fe/uds-templates",
-  "version": "0.6.13",
+  "version": "0.6.14",
   "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

@@ -140,8 +140,8 @@ const canUseTokenForNewConnection = ({
  *   videoRef, // WebRTC MediaStream을 연결할 video 요소 ref
  *   connectionState, // RTCPeerConnectionState 상태값
  *   streamError, // 스트림 시도 중 발생한 오류 메시지
- *   isStreaming, // 현재 스트림 연결 절차가 진행 중인지 여부
- *   isTokenLoading, // 토큰 발급 요청이 진행 중인지 여부
+ *   isStreaming, // UI 표시 기준 스트림 연결 절차 진행 여부
+ *   isTokenLoading, // UI 표시 기준 토큰 발급 요청 진행 여부
  *   isTokenError, // 토큰 발급 요청이 실패했는지 여부
  *   canReconnect, // UDS 내부 grace/stagger 이후 재연결 호출이 가능한지 여부
  *   refetchToken, // 토큰 발급을 재시도하는 함수
@@ -328,16 +328,30 @@ export function useCctvRtcStream({
     streamIdentityKey,
   ]);
 
-  const shouldPreserveConnectedDisplay =
+  const isPostConnectedReplacementLoading =
     hasConnected &&
-    !isPostConnectedReconnectReady &&
-    DISPLAY_CONNECTED_DURING_RECOVERY_STATES.has(connectionState);
+    Boolean(streamIdentityKey) &&
+    !isTokenError &&
+    !streamError &&
+    (isTokenLoading || isStreaming);
+
+  const shouldPreserveConnectedDisplay =
+    isPostConnectedReplacementLoading ||
+    (hasConnected &&
+      !isPostConnectedReconnectReady &&
+      DISPLAY_CONNECTED_DURING_RECOVERY_STATES.has(connectionState));
 
   // 반환 state는 CamList/Viewer/overlay의 live/error/message 계산에 직접 쓰인다.
-  // post-connected disconnected는 자동 재연결 대신 기존 화면을 유지해 UI reset 파동을 막는다.
+  // post-connected recovery/replacement 중에는 기존 화면을 유지해 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 +482,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 +553,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 +566,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 +641,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 +712,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 +737,10 @@ export function useCctvRtcStream({
         connectionState,
         displayConnectionState,
         hasConnected,
+        isPostConnectedReplacementLoading,
         isPostConnectedReconnectReady,
+        displayIsStreaming,
+        displayIsTokenLoading,
         isStreaming,
         isTokenError,
         isTokenLoading,
@@ -721,7 +755,10 @@ export function useCctvRtcStream({
     connectionState,
     debugBasePayload,
     displayConnectionState,
+    displayIsStreaming,
+    displayIsTokenLoading,
     hasConnected,
+    isPostConnectedReplacementLoading,
     isPostConnectedReconnectReady,
     isStreaming,
     isTokenError,
@@ -770,8 +807,8 @@ export function useCctvRtcStream({
     videoRef,
     connectionState: displayConnectionState,
     streamError,
-    isStreaming,
-    isTokenLoading,
+    isStreaming: displayIsStreaming,
+    isTokenLoading: displayIsTokenLoading,
     isTokenError,
     canReconnect,
     refetchToken,

package/src/cctv/types/hook.ts

@@ -60,8 +60,8 @@ export interface UseCctvRtcStreamError {
 /**
  * CCTV; useCctvRtcStream 연결 상태
  * @property {RTCPeerConnectionState} connectionState WebRTC 연결 상태
- * @property {boolean} isStreaming startWhepStream 진행 여부
- * @property {boolean} isTokenLoading 토큰 발급 요청 진행 여부
+ * @property {boolean} isStreaming UI 표시 기준 startWhepStream 진행 여부
+ * @property {boolean} isTokenLoading UI 표시 기준 토큰 발급 요청 진행 여부
  * @property {boolean} isTokenError 토큰 발급 실패 여부
  * @property {string | null} streamError 스트림 오류 메시지
  */
@@ -71,11 +71,17 @@ export interface UseCctvRtcStreamState extends UseCctvRtcStreamError {
    */
   connectionState: RTCPeerConnectionState;
   /**
-   * startWhepStream 진행 여부
+   * UI 표시 기준 startWhepStream 진행 여부
+   * @desc
+   * 최초 연결 전에는 실제 진행 상태를 나타낸다. 이미 한 번 연결된 stream을 교체하는 동안에는
+   * 기존 화면과 live count를 유지하기 위해 false로 smoothing될 수 있다.
    */
   isStreaming: boolean;
   /**
-   * 토큰 발급 요청 진행 여부
+   * UI 표시 기준 토큰 발급 요청 진행 여부
+   * @desc
+   * 최초 연결 전에는 실제 요청 상태를 나타낸다. 이미 한 번 연결된 stream의 재연결 token
+   * 재발급 중에는 기존 화면과 live count를 유지하기 위해 false로 smoothing될 수 있다.
    */
   isTokenLoading: boolean;
 }
@@ -85,8 +91,8 @@ export interface UseCctvRtcStreamState extends UseCctvRtcStreamError {
  * @property {React.RefObject<HTMLVideoElement>} videoRef <video /> ref
  * @property {RTCPeerConnectionState} connectionState 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 토큰 재발급 함수

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

@@ -7,8 +7,8 @@ import type { UseCctvRtcStreamError, UseCctvRtcStreamState } from "./hook";
  * @property {boolean} [hasCamProp] 직접 cam prop을 받은 경우 true
  * @property {boolean} [isFetching] 서버에서 cam 리스트를 가져오는 중인지 여부
  * @property {RTCPeerConnectionState} connectionState WebRTC 연결 상태
- * @property {boolean} isStreaming startWhepStream 진행 여부
- * @property {boolean} isTokenLoading 토큰 발급 요청 진행 여부
+ * @property {boolean} isStreaming UI 표시 기준 startWhepStream 진행 여부
+ * @property {boolean} isTokenLoading UI 표시 기준 토큰 발급 요청 진행 여부
  * @property {boolean} isTokenError 토큰 발급 실패 여부
  * @property {string | null} streamError 스트림 오류 메시지
  * @property {boolean} [canReconnect] UDS 내부 허용 사유와 grace/stagger를 통과해 재연결 호출이 가능한지 여부
@@ -36,8 +36,8 @@ export interface CctvVideoOverlayMessageParams extends UseCctvRtcStreamState {
  * CCTV; getIsLive() params
  * @property {CctvCompanyCameraData} [cam] 카메라 데이터
  * @property {RTCPeerConnectionState} connectionState WebRTC 연결 상태
- * @property {boolean} isStreaming startWhepStream 진행 여부
- * @property {boolean} isTokenLoading 토큰 발급 요청 진행 여부
+ * @property {boolean} isStreaming UI 표시 기준 startWhepStream 진행 여부
+ * @property {boolean} isTokenLoading UI 표시 기준 토큰 발급 요청 진행 여부
  * @property {boolean} isTokenError 토큰 발급 실패 여부
  * @property {string | null} streamError 스트림 오류 메시지
  */

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

@@ -32,8 +32,8 @@ const RTC_SESSION_ENDED_RECONNECT_STATES = new Set<RTCPeerConnectionState>([
  * @property {boolean} [hasCamProp] 직접 cam prop을 받은 경우 true
  * @property {boolean} [isFetching] 서버에서 cam 리스트를 가져오는 중인지 여부
  * @property {RTCPeerConnectionState} connectionState WebRTC 연결 상태
- * @property {boolean} isStreaming startWhepStream 진행 여부
- * @property {boolean} isTokenLoading 토큰 발급 요청 진행 여부
+ * @property {boolean} isStreaming UI 표시 기준 startWhepStream 진행 여부
+ * @property {boolean} isTokenLoading UI 표시 기준 토큰 발급 요청 진행 여부
  * @property {boolean} isTokenError 토큰 발급 실패 여부
  * @property {string | null} streamError 스트림 오류 메시지
  * @returns {string | null} 상태에 따른 메시지 반환 (문제가 없으면 null)
@@ -73,8 +73,8 @@ export function getOverlayMessage({
  * @param {CctvVideoLiveParams} params 상태 파라미터
  * @property {CctvCompanyCameraData} [cam] 카메라 데이터
  * @property {RTCPeerConnectionState} connectionState WebRTC 연결 상태
- * @property {boolean} isStreaming startWhepStream 진행 여부
- * @property {boolean} isTokenLoading 토큰 발급 요청 진행 여부
+ * @property {boolean} isStreaming UI 표시 기준 startWhepStream 진행 여부
+ * @property {boolean} isTokenLoading UI 표시 기준 토큰 발급 요청 진행 여부
  * @property {boolean} isTokenError 토큰 발급 실패 여부
  * @property {string | null} streamError 스트림 오류 메시지
  * @returns {boolean} 라이브 상태 여부 반환