@uniai-fe/uds-templates 0.10.2 → 0.10.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniai-fe/uds-templates",
-  "version": "0.10.2",
+  "version": "0.10.4",
   "description": "UNIAI Design System; UI Templates Package",
   "type": "module",
   "private": false,
@@ -56,27 +56,27 @@
   },
   "devDependencies": {
     "@svgr/webpack": "^8.1.0",
-    "@tanstack/react-query": "^5.101.1",
-    "@types/node": "^24.12.3",
+    "@tanstack/react-query": "^5.101.2",
+    "@types/node": "^24.13.2",
     "@types/react": "^19.2.17",
     "@types/react-dom": "^19.2.3",
-    "eslint": "^9.39.2",
-    "jotai": "^2.20.1",
+    "eslint": "^9.39.4",
+    "jotai": "^2.20.2",
     "next": "16.2.10",
-    "prettier": "^3.8.4",
-    "react-hook-form": "^7.80.0",
+    "prettier": "^3.8.5",
+    "react-hook-form": "^7.81.0",
     "sass": "^1.101.0",
     "typescript": "6.0.3",
     "@uniai-fe/next-devkit": "0.4.0",
     "@uniai-fe/eslint-config": "0.4.1",
-    "@uniai-fe/util-api": "0.2.1",
     "@uniai-fe/tsconfig": "0.2.0",
     "@uniai-fe/react-hooks": "0.3.0",
+    "@uniai-fe/util-api": "0.2.1",
+    "@uniai-fe/uds-primitives": "0.10.0",
     "@uniai-fe/util-functions": "0.4.3",
     "@uniai-fe/util-jotai": "0.3.0",
+    "@uniai-fe/util-rtc": "0.2.1",
     "@uniai-fe/uds-foundation": "0.5.0",
-    "@uniai-fe/uds-primitives": "0.10.0",
-    "@uniai-fe/util-rtc": "0.2.0",
     "@uniai-fe/util-next": "0.5.0"
   },
   "scripts": {

package/src/cctv/hooks/streamRegistry.ts

@@ -2,30 +2,119 @@
 
 import { startWhepStream, type WhepStreamHandle } from "@uniai-fe/util-rtc";
 
+/**
+ * CCTV Stream Registry Types; 외부 구독 snapshot
+ * @property {RTCPeerConnectionState} connectionState PeerConnection 연결 상태
+ * @property {boolean} isStreaming WHEP 시작 promise 진행 여부
+ * @property {MediaStream | null} stream 현재 수신 중인 MediaStream
+ * @property {string | null} streamError 마지막 WHEP 시작 오류 메시지
+ * @desc 외부 subscriber에 노출하는 immutable RTC stream 상태 계약
+ */
 interface CctvRtcStreamSnapshot {
+  /**
+   * PeerConnection 연결 상태
+   */
   connectionState: RTCPeerConnectionState;
+  /**
+   * WHEP 시작 promise 진행 여부
+   */
   isStreaming: boolean;
+  /**
+   * 현재 수신 중인 MediaStream
+   */
   stream: MediaStream | null;
+  /**
+   * 마지막 WHEP 시작 오류 메시지
+   */
   streamError: string | null;
 }
 
+/**
+ * CCTV Stream Registry Types; Provider scope stream entry
+ * @property {Set<HTMLVideoElement>} attachedVideos 같은 stream을 표시하는 video 집합
+ * @property {AbortController | null} controller 진행 중이거나 연결된 WHEP cleanup controller
+ * @property {WhepStreamHandle | null} handle 연결 완료 뒤 PeerConnection cleanup handle
+ * @property {string} identityKey camera와 endpoint 기준 stream family key
+ * @property {Set<(snapshot: CctvRtcStreamSnapshot) => void>} listeners snapshot 구독자 집합
+ * @property {MediaStream | null} pendingStream handle 반환 전 수신한 replacement stream
+ * @property {Map<HTMLVideoElement, MediaProvider | null>} previousVideoSources replacement 실패 시 복원할 video source
+ * @property {string} streamKey token generation까지 포함한 stream key
+ * @desc Provider scope에서 단일 stream lifecycle과 replacement rollback resource를 소유하는 내부 entry 계약
+ */
 interface CctvRtcStreamEntry extends CctvRtcStreamSnapshot {
+  /**
+   * 같은 stream을 표시하는 video element 집합
+   */
   attachedVideos: Set<HTMLVideoElement>;
+  /**
+   * 진행 중이거나 연결된 WHEP를 중단하는 controller
+   */
   controller: AbortController | null;
+  /**
+   * 연결 완료 뒤 PeerConnection을 닫는 handle
+   */
   handle: WhepStreamHandle | null;
+  /**
+   * camera와 endpoint 기준 stream family key
+   */
   identityKey: string;
+  /**
+   * entry snapshot 구독자 집합
+   */
   listeners: Set<(snapshot: CctvRtcStreamSnapshot) => void>;
+  /**
+   * handle 반환 전 수신한 replacement MediaStream
+   */
+  pendingStream: MediaStream | null;
+  /**
+   * replacement 실패 시 복원할 video별 기존 source
+   */
+  previousVideoSources: Map<HTMLVideoElement, MediaProvider | null>;
+  /**
+   * token generation까지 포함한 stream key
+   */
   streamKey: string;
 }
 
+/**
+ * CCTV Stream Registry Types; RTC stream 시작 파라미터
+ * @property {string} endpoint token-specific WHEP 요청 endpoint
+ * @property {string} identityKey camera와 endpoint 기준 stream family key
+ * @property {string} streamKey token generation까지 포함한 stream key
+ * @property {string} token WHEP Bearer token
+ * @property {HTMLVideoElement} video 최초 stream attach 대상 video
+ * @desc registry가 token generation별 WHEP lifecycle을 시작하는 입력 계약
+ */
 interface CctvRtcStreamStartParams {
+  /**
+   * token-specific WHEP 요청 endpoint
+   */
   endpoint: string;
+  /**
+   * camera와 endpoint 기준 stream family key
+   */
   identityKey: string;
+  /**
+   * token generation까지 포함한 stream key
+   */
   streamKey: string;
+  /**
+   * WHEP Bearer token
+   */
   token: string;
+  /**
+   * 최초 stream attach 대상 video element
+   */
   video: HTMLVideoElement;
 }
 
+/**
+ * CCTV Stream Registry Util; 외부 구독용 immutable snapshot 생성
+ * @util
+ * @param {CctvRtcStreamEntry} [entry] snapshot을 만들 registry entry
+ * @desc Map에 entry가 없을 때는 새 연결 전 기본 상태를 반환한다.
+ * @return {CctvRtcStreamSnapshot} 현재 entry 상태 또는 기본 idle 상태
+ */
 const getEntrySnapshot = (
   entry?: CctvRtcStreamEntry,
 ): CctvRtcStreamSnapshot => ({
@@ -35,12 +124,26 @@ const getEntrySnapshot = (
   streamError: entry?.streamError ?? null,
 });
 
+/**
+ * CCTV Stream Registry Util; video element에 RTC stream 연결
+ * @util
+ * @param {HTMLVideoElement} video stream attach 대상 video
+ * @param {MediaStream | null} stream 표시할 MediaStream 또는 초기화용 null
+ * @desc inline autoplay 속성과 srcObject를 함께 적용한다.
+ */
 const attachVideo = (video: HTMLVideoElement, stream: MediaStream | null) => {
   video.playsInline = true;
   video.autoplay = true;
   video.srcObject = stream;
 };
 
+/**
+ * CCTV Stream Registry Util; 지정 stream의 video 연결 해제
+ * @util
+ * @param {HTMLVideoElement} video cleanup 대상 video
+ * @param {MediaStream | null} stream 제거 대상 MediaStream
+ * @desc replacement stream이 이미 붙은 video를 이전 entry cleanup이 비우지 않게 한다.
+ */
 const clearVideoIfAttachedStream = (
   video: HTMLVideoElement,
   stream: MediaStream | null,
@@ -50,12 +153,25 @@ const clearVideoIfAttachedStream = (
   }
 };
 
+/**
+ * CCTV Stream Registry Util; entry snapshot 구독자 통지
+ * @util
+ * @param {CctvRtcStreamEntry} entry 변경된 registry entry
+ * @desc 현재 entry의 immutable snapshot을 생성해 등록된 listener에 전달한다.
+ */
 const notifyEntry = (entry: CctvRtcStreamEntry) => {
   const snapshot = getEntrySnapshot(entry);
   entry.listeners.forEach(listener => listener(snapshot));
 };
 
+/**
+ * CCTV Stream Registry Util; 단일 registry entry resource 정리
+ * @util
+ * @param {CctvRtcStreamEntry} entry 종료할 registry entry
+ * @desc AbortController와 WHEP handle cleanup은 각 구현의 idempotent 계약을 재사용한다.
+ */
 const closeEntry = (entry: CctvRtcStreamEntry) => {
+  // pending WHEP와 연결 완료 handle을 모두 닫되 다음 close가 중복 실행되지 않게 참조를 비운다.
   entry.controller?.abort();
   entry.controller = null;
   entry.handle?.close();
@@ -64,59 +180,135 @@ const closeEntry = (entry: CctvRtcStreamEntry) => {
   entry.isStreaming = false;
 
   entry.attachedVideos.forEach(video => {
-    clearVideoIfAttachedStream(video, entry.stream);
+    // committed 전 replacement도 현재 entry가 video에 붙인 resource로 보고 선택적으로 제거한다.
+    clearVideoIfAttachedStream(video, entry.pendingStream ?? entry.stream);
   });
+  entry.pendingStream = null;
+  entry.previousVideoSources.clear();
 
+  // 마지막 closed snapshot을 전달한 뒤 entry가 외부 객체를 붙잡지 않도록 집합을 비운다.
   notifyEntry(entry);
   entry.attachedVideos.clear();
   entry.listeners.clear();
 };
 
+/**
+ * CCTV Stream Registry Types; Provider scope registry 계약
+ * @property {(streamKey: string, video: HTMLVideoElement) => () => void} attach video attach와 detach cleanup 등록
+ * @property {() => void} closeAll Provider scope의 모든 stream 종료
+ * @property {(identityKey: string, exceptStreamKey?: string) => void} closeByIdentity 같은 camera family의 stream 종료
+ * @property {(streamKey: string) => CctvRtcStreamSnapshot} getSnapshot stream snapshot 조회
+ * @property {(params: CctvRtcStreamStartParams) => void} start streamKey 단위 WHEP 시작
+ * @property {(streamKey: string, listener: (snapshot: CctvRtcStreamSnapshot) => void) => () => void} subscribe stream snapshot 구독
+ * @desc Provider scope에서 WHEP stream 시작, 연결, 구독과 cleanup을 관리하는 공개 registry 계약
+ */
 export interface CctvRtcStreamRegistry {
+  /**
+   * video attach와 detach cleanup 등록
+   */
   attach: (streamKey: string, video: HTMLVideoElement) => () => void;
+  /**
+   * Provider scope의 모든 stream 종료
+   */
   closeAll: () => void;
+  /**
+   * 같은 camera family의 stream을 optional 예외 key 외에는 모두 종료
+   */
   closeByIdentity: (identityKey: string, exceptStreamKey?: string) => void;
+  /**
+   * streamKey의 현재 외부 구독 snapshot 조회
+   */
   getSnapshot: (streamKey: string) => CctvRtcStreamSnapshot;
+  /**
+   * streamKey 단위 WHEP 시작
+   */
   start: (params: CctvRtcStreamStartParams) => void;
+  /**
+   * streamKey snapshot 구독과 unsubscribe cleanup 등록
+   */
   subscribe: (
     streamKey: string,
     listener: (snapshot: CctvRtcStreamSnapshot) => void,
   ) => () => void;
 }
 
+/**
+ * CCTV Stream Registry Util; Provider scope stream registry 생성
+ * @util
+ * @desc 같은 streamKey의 중복 WHEP start를 막고 camera identity별 replacement cleanup을 관리한다.
+ * @return {CctvRtcStreamRegistry} 독립된 Provider scope stream registry
+ * @example
+ * const registry = createCctvRtcStreamRegistry();
+ * registry.start({ endpoint, identityKey, streamKey, token, video });
+ */
 export function createCctvRtcStreamRegistry(): CctvRtcStreamRegistry {
+  // Map은 token generation이 포함된 streamKey마다 현재 lifecycle owner를 하나만 유지한다.
   const entries = new Map<string, CctvRtcStreamEntry>();
 
+  // entry resource를 정리한 뒤 streamKey의 Map owner를 제거한다.
   const deleteEntry = (entry: CctvRtcStreamEntry) => {
     closeEntry(entry);
     entries.delete(entry.streamKey);
   };
 
   return {
+    /**
+     * CCTV Stream Registry Util; streamKey entry에 video 연결
+     * @util
+     * @param {string} streamKey attach할 stream key
+     * @param {HTMLVideoElement} video attach 대상 video
+     * @desc 현재 stream을 video에 연결하고 attach 집합에 등록한다.
+     * @return {() => void} 현재 video attach만 해제하는 cleanup
+     */
     attach(streamKey, video) {
       const entry = entries.get(streamKey);
       if (!entry) {
+        // 아직 시작되지 않은 key는 stale srcObject 없이 빈 video 상태로 정규화한다.
         attachVideo(video, null);
+        // 소유할 registry entry가 없으므로 Map mutation 없이 현재 video만 비우는 cleanup을 반환한다.
         return () => {
           if (video.srcObject) video.srcObject = null;
         };
       }
 
+      // 기존 MediaStream이 있으면 즉시 reattach하고 pending entry면 현재 화면을 보존한다.
       entry.attachedVideos.add(video);
-      if (entry.stream || !video.srcObject) {
-        attachVideo(video, entry.stream);
+      if (!entry.previousVideoSources.has(video)) {
+        // pending replacement 실패 시 이 attach 직전 source로 돌아갈 수 있게 최초 값만 보관한다.
+        entry.previousVideoSources.set(video, video.srcObject);
+      }
+      // handle 성공 전 track도 새 subscriber video에는 보이되 committed snapshot으로 승격하지 않는다.
+      const attachedStream = entry.stream ?? entry.pendingStream;
+      if (attachedStream || !video.srcObject) {
+        attachVideo(video, attachedStream);
       }
 
       return () => {
+        // detach된 video는 이후 실패 복원과 entry cleanup의 소유 대상에서 제외한다.
         entry.attachedVideos.delete(video);
-        clearVideoIfAttachedStream(video, entry.stream);
+        entry.previousVideoSources.delete(video);
+        clearVideoIfAttachedStream(video, entry.pendingStream ?? entry.stream);
       };
     },
+    /**
+     * CCTV Stream Registry Util; Provider scope의 모든 stream 정리
+     * @util
+     * @desc 모든 entry resource를 닫고 registry Map을 비운다.
+     */
     closeAll() {
+      // Provider unmount에서 모든 entry를 한 번 닫은 뒤 registry owner Map을 비운다.
       entries.forEach(entry => closeEntry(entry));
       entries.clear();
     },
+    /**
+     * CCTV Stream Registry Util; 같은 identity의 이전 stream 정리
+     * @util
+     * @param {string} identityKey cleanup할 camera stream family key
+     * @param {string} [exceptStreamKey] 유지할 replacement stream key
+     * @desc optional 예외 key를 제외한 같은 camera family entry를 닫는다.
+     */
     closeByIdentity(identityKey, exceptStreamKey) {
+      // replacement track이 붙은 뒤 같은 camera family의 이전 generation만 선택적으로 닫는다.
       entries.forEach(entry => {
         if (
           entry.identityKey === identityKey &&
@@ -126,15 +318,35 @@ export function createCctvRtcStreamRegistry(): CctvRtcStreamRegistry {
         }
       });
     },
+    /**
+     * CCTV Stream Registry Util; streamKey snapshot 조회
+     * @util
+     * @param {string} streamKey 조회할 stream key
+     * @desc 내부 mutable entry를 노출하지 않고 외부 구독용 snapshot만 반환한다.
+     * @return {CctvRtcStreamSnapshot} 현재 entry 상태 또는 기본 idle 상태
+     */
     getSnapshot(streamKey) {
+      // 외부 consumer가 내부 mutable entry를 직접 소유하지 않도록 snapshot만 반환한다.
       return getEntrySnapshot(entries.get(streamKey));
     },
+    /**
+     * CCTV Stream Registry Util; streamKey 단위 WHEP 연결 시작
+     * @util
+     * @property {string} params.endpoint token-specific WHEP 요청 endpoint
+     * @property {string} params.identityKey camera와 endpoint 기준 stream family key
+     * @property {string} params.streamKey token generation까지 포함한 stream key
+     * @property {string} params.token WHEP Bearer token
+     * @property {HTMLVideoElement} params.video 최초 stream attach 대상 video element
+     * @desc 같은 streamKey의 중복 start를 막고 현재 entry의 lifecycle만 갱신한다.
+     */
     start({ endpoint, identityKey, streamKey, token, video }) {
       const existingEntry = entries.get(streamKey);
       if (existingEntry) {
+        // 같은 token generation의 concurrent attach는 기존 WHEP start 하나를 공유한다.
         return;
       }
 
+      // WHEP promise보다 entry를 먼저 등록해 같은 tick의 중복 start를 차단한다.
       const controller = new AbortController();
       const entry: CctvRtcStreamEntry = {
         attachedVideos: new Set([video]),
@@ -144,13 +356,21 @@ export function createCctvRtcStreamRegistry(): CctvRtcStreamRegistry {
         identityKey,
         isStreaming: true,
         listeners: new Set(),
+        pendingStream: null,
+        // 최초 video가 이미 표시하던 connected stream을 replacement 실패 rollback 값으로 보존한다.
+        previousVideoSources: new Map([[video, video.srcObject]]),
         stream: null,
         streamError: null,
         streamKey,
       };
 
       entries.set(streamKey, entry);
+      // Map owner 일치와 AbortSignal 상태로 현재 entry의 lifecycle 소유권을 확인한다.
+      const isCurrentEntry = () =>
+        entries.get(streamKey) === entry && !controller.signal.aborted;
+
       if (!video.srcObject) {
+        // cold start는 빈 video를 초기화하고 replacement는 기존 화면을 그대로 유지한다.
         attachVideo(video, null);
       } else {
         video.playsInline = true;
@@ -163,41 +383,90 @@ export function createCctvRtcStreamRegistry(): CctvRtcStreamRegistry {
         video,
         signal: controller.signal,
         onConnectionStateChange: state => {
+          if (!isCurrentEntry()) {
+            // Provider cleanup 또는 같은 key owner 교체 뒤 늦은 state event는 반영하지 않는다.
+            return;
+          }
+
           entry.connectionState = state;
           notifyEntry(entry);
         },
         onTrack: event => {
-          entry.stream = event.streams[0] ?? null;
+          if (!isCurrentEntry()) {
+            // 닫힌 entry의 late track이 video와 snapshot을 되살리지 않게 막는다.
+            return;
+          }
+
+          // track만으로 성공을 확정하지 않고 handle 반환 전까지 pending resource로 유지한다.
+          entry.pendingStream = event.streams[0] ?? null;
           entry.attachedVideos.forEach(attachedVideo =>
-            attachVideo(attachedVideo, entry.stream),
+            attachVideo(attachedVideo, entry.pendingStream),
           );
-          notifyEntry(entry);
         },
       })
         .then(handle => {
+          // pending 중 close된 start가 늦게 resolve되면 새 handle을 즉시 회수한다.
+          if (!isCurrentEntry()) {
+            handle.close();
+            // 회수한 stale handle을 현재 entry의 성공 상태로 다시 기록하지 않는다.
+            return;
+          }
+
           entry.handle = handle;
           entry.isStreaming = false;
+          // remote SDP까지 완료된 handle만 committed snapshot으로 승격해 이전 generation을 닫게 한다.
+          entry.stream = entry.pendingStream;
+          entry.pendingStream = null;
           notifyEntry(entry);
+          entry.previousVideoSources.clear();
         })
         .catch(error => {
+          if (entries.get(streamKey) !== entry) {
+            // abort/delete된 이전 owner의 rejection은 현재 entry 상태를 덮어쓰지 않는다.
+            return;
+          }
+
+          // 실패 원인이 어느 negotiation 단계이든 util-rtc 내부 PeerConnection cleanup을 요청한다.
+          entry.controller?.abort();
           entry.controller = null;
           entry.handle = null;
           entry.isStreaming = false;
+          const failedStream = entry.pendingStream ?? entry.stream;
+          entry.attachedVideos.forEach(attachedVideo => {
+            // 외부에서 다른 source로 교체한 video는 건드리지 않고 이 entry의 실패 stream만 rollback한다.
+            if (failedStream && attachedVideo.srcObject === failedStream) {
+              attachedVideo.srcObject =
+                entry.previousVideoSources.get(attachedVideo) ?? null;
+            }
+          });
+          entry.pendingStream = null;
           entry.stream = null;
+          entry.previousVideoSources.clear();
           entry.streamError =
             error instanceof Error
               ? error.message
               : "스트림 연결에 실패했습니다.";
-          entry.attachedVideos.forEach(attachedVideo =>
-            clearVideoIfAttachedStream(attachedVideo, entry.stream),
-          );
+          // subscriber에는 terminal error를 전달하되 실패 entry는 다음 명시적 start를 막지 않는다.
           notifyEntry(entry);
+          entries.delete(streamKey);
         });
     },
+    /**
+     * CCTV Stream Registry Util; streamKey snapshot listener 등록
+     * @util
+     * @param {string} streamKey 구독할 stream key
+     * @param {(snapshot: CctvRtcStreamSnapshot) => void} listener snapshot listener
+     * @desc 등록 직후 현재 snapshot을 전달하고 이후 상태 변경을 구독한다.
+     * @return {() => void} 현재 listener만 제거하는 unsubscribe
+     */
     subscribe(streamKey, listener) {
       const entry = entries.get(streamKey);
-      if (!entry) return () => undefined;
+      if (!entry) {
+        // 구독할 lifecycle owner가 없으므로 listener를 저장하지 않고 no-op cleanup을 반환한다.
+        return () => undefined;
+      }
 
+      // 구독 직후 현재 snapshot을 전달해 registry reattach의 첫 render 지연을 줄인다.
       entry.listeners.add(listener);
       listener(getEntrySnapshot(entry));