@uniai-fe/uds-templates 0.6.26 → 0.6.27

package/package.json

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

package/src/cctv/apis/client.ts

@@ -7,16 +7,42 @@ import type {
   API_Res_CctvRtcToken,
 } from "../types";
 
+/**
+ * CCTV; RTC token fallback max age
+ * @desc
+ * JWT exp를 읽을 수 없는 token은 React Query dataUpdatedAt 기준으로 이 시간까지만 신규 WHEP 연결에 재사용한다.
+ */
 export const CCTV_RTC_TOKEN_FALLBACK_MAX_AGE_MS = 5 * 60 * 1000;
+
+/**
+ * CCTV; RTC token query cache retention
+ * @desc
+ * focus/reconnect 자동 refetch는 막되, 오래된 token이 무기한 신규 연결에 쓰이지 않게 fallback max age와 동일하게 제한한다.
+ */
 export const CCTV_RTC_TOKEN_GC_TIME_MS = CCTV_RTC_TOKEN_FALLBACK_MAX_AGE_MS;
 
+/**
+ * CCTV; client company-list fetcher
+ * @param {object} params 요청 파라미터
+ * @param {string} [params.url] service에서 주입한 company-list API 경로
+ * @returns {Promise<API_Res_CctvCompany>} CCTV company-list 응답
+ */
 export const getClientCctvCompanyList = async ({
   url,
 }: {
   url?: string;
 }): Promise<API_Res_CctvCompany> =>
+  // Provider에서 listUrl을 주입하지 않으면 UDS 기본 Next route를 사용한다.
   await (await fetch(url ?? "/api/cctv/company-list")).json();
 
+/**
+ * CCTV; company-list query hook
+ * @hook
+ * @param {object} params query 파라미터
+ * @param {string} [params.url] service에서 주입한 company-list API 경로
+ * @param {readonly unknown[]} [params.queryKeyDeps] service별 목록 cache 분리용 key dependency
+ * @returns {UseQueryResult<API_Res_CctvCompany>} company-list query 결과
+ */
 export const useQueryCctvCompanyList = ({
   url,
   queryKeyDeps = [],
@@ -25,17 +51,28 @@ export const useQueryCctvCompanyList = ({
   queryKeyDeps?: readonly unknown[];
 }): UseQueryResult<API_Res_CctvCompany> =>
   useQuery({
+    // username/site 등 service-local 조건이 바뀌면 queryKeyDeps로 cache를 분리한다.
     queryKey: ["cctv_company_list", url, ...queryKeyDeps],
     queryFn: () => getClientCctvCompanyList({ url }),
   });
 
+/**
+ * CCTV; RTC token POST fetcher
+ * @param {API_Req_CctvRtcToken & { url?: string }} params token 요청 파라미터
+ * @param {string} params.company_id 업체 id코드
+ * @param {string} params.cam_id 카메라 id코드
+ * @param {string} params.username CCTV token 권한 확인용 계정명
+ * @param {string} [params.url] service에서 주입한 token API 경로
+ * @returns {Promise<API_Res_CctvRtcToken>} RTC token 응답
+ */
 export const postCctvRtcToken = async ({
   company_id,
   cam_id,
   username,
   url,
 }: API_Req_CctvRtcToken & { url?: string }): Promise<API_Res_CctvRtcToken> =>
-  await (
+  await // token route는 service-local proxy가 있으면 그 경로를 우선 사용한다.
+  (
     await fetch(url ?? "/api/cctv/token", {
       method: "POST",
       headers: {
@@ -45,20 +82,37 @@ export const postCctvRtcToken = async ({
     })
   ).json();
 
+/**
+ * CCTV; RTC token query hook
+ * @hook
+ * @param {API_Req_CctvRtcToken & { enabled?: boolean; url?: string }} params token query 파라미터
+ * @param {string} params.company_id 업체 id코드
+ * @param {string} params.cam_id 카메라 id코드
+ * @param {boolean} [params.enabled] scheduler grant 이후 token query를 열기 위한 외부 gate
+ * @param {string} params.username CCTV token 권한 확인용 계정명
+ * @param {string} [params.url] service에서 주입한 token API 경로
+ * @returns {UseQueryResult<API_Res_CctvRtcToken>} RTC token query 결과
+ */
 export const useQueryCctvRtcToken = ({
   company_id,
   cam_id,
+  enabled = true,
   username,
   url,
 }: API_Req_CctvRtcToken & {
+  enabled?: boolean;
   url?: string;
 }): UseQueryResult<API_Res_CctvRtcToken> =>
   useQuery({
+    // token은 username/company/cam/API route 조합별로 분리한다.
     queryKey: ["cctv_rtc_token", username, company_id, cam_id, url],
     queryFn: () => postCctvRtcToken({ company_id, cam_id, username, url }),
-    enabled: Boolean(username && company_id && cam_id),
+    // scheduler grant 전에는 token burst가 생기지 않도록 enabled를 false로 유지한다.
+    enabled: enabled && Boolean(username && company_id && cam_id),
+    // exp decode가 불가한 token은 fallback age를 넘기면 신규 WHEP 연결에 쓰지 않는다.
     staleTime: CCTV_RTC_TOKEN_FALLBACK_MAX_AGE_MS,
     gcTime: CCTV_RTC_TOKEN_GC_TIME_MS,
+    // focus/reconnect/mount가 곧바로 다수 WHEP 재협상으로 이어지지 않도록 자동 refetch를 막는다.
     refetchOnMount: false,
     refetchOnReconnect: false,
     refetchOnWindowFocus: false,

package/src/cctv/components/Provider.tsx

@@ -14,6 +14,10 @@ import {
   createCctvRtcStreamRegistry,
   type CctvRtcStreamRegistry,
 } from "../hooks/streamRegistry";
+import {
+  createCctvRtcStreamScheduler,
+  type CctvRtcStreamScheduler,
+} from "../hooks/streamScheduler";
 
 /**
  * CCTV; API 경로 컨텍스트
@@ -28,6 +32,9 @@ const ApiUrlContext = createContext<CctvApiUrlContext>({
 const RtcStreamRegistryContext = createContext<CctvRtcStreamRegistry | null>(
   null,
 );
+const RtcStreamSchedulerContext = createContext<CctvRtcStreamScheduler | null>(
+  null,
+);
 
 /**
  * CCTV; API 경로 컨텍스트
@@ -40,6 +47,13 @@ export function useCctvApiUrl(): CctvApiUrlContext {
   return useContext(ApiUrlContext);
 }
 
+/**
+ * CCTV; RTC stream registry context hook
+ * @hook
+ * @returns {CctvRtcStreamRegistry} Provider instance 단위 stream registry
+ * @desc
+ * registry는 WHEP PeerConnection/MediaStream을 Provider lifecycle 안에서 유지하고 list/viewer video reattach를 담당한다.
+ */
 export function useCctvRtcStreamRegistry(): CctvRtcStreamRegistry {
   const registry = useContext(RtcStreamRegistryContext);
   if (!registry) {
@@ -50,6 +64,23 @@ export function useCctvRtcStreamRegistry(): CctvRtcStreamRegistry {
   return registry;
 }
 
+/**
+ * CCTV; RTC stream scheduler context hook
+ * @hook
+ * @returns {CctvRtcStreamScheduler} Provider instance 단위 stream scheduler
+ * @desc
+ * scheduler는 item UI 렌더와 token/WHEP 시작 시점을 분리해 초기 요청 burst를 batch 단위로 줄인다.
+ */
+export function useCctvRtcStreamScheduler(): CctvRtcStreamScheduler {
+  const scheduler = useContext(RtcStreamSchedulerContext);
+  if (!scheduler) {
+    throw new Error(
+      "CCTV.Provider 내부에서 useCctvRtcStreamScheduler를 사용해야 합니다.",
+    );
+  }
+  return scheduler;
+}
+
 /**
  * CCTV; Provider props
  * @component
@@ -60,6 +91,7 @@ export function useCctvRtcStreamRegistry(): CctvRtcStreamRegistry {
  * @property {string} [username] CCTV 조회시 권한 확인을 위한 계정명
  * @property {string} [whepUsername] WHEP endpoint username 덮어쓰기 값
  * @property {ContextExtension} [defaultValues] 서비스 확장 context 기본값
+ * @property {CctvRtcStreamOptions} [streamOptions] stream lazy loading 옵션
  * @property {React.ReactNode} children
  */
 export default function CCTVProvider<ContextExtension extends object = object>({
@@ -70,15 +102,39 @@ export default function CCTVProvider<ContextExtension extends object = object>({
   listUrl,
   tokenUrl,
   defaultValues,
+  streamOptions,
   children,
 }: CctvProviderProps<ContextExtension>) {
+  // streamOptions object identity가 매 렌더 바뀌어도 primitive option 값 기준으로만 scheduler를 교체한다.
+  const streamBatchSize = streamOptions?.batchSize;
+  const streamBatchIntervalMs = streamOptions?.batchIntervalMs;
+  const hasStreamOptions =
+    streamBatchSize !== undefined || streamBatchIntervalMs !== undefined;
+
+  // registry는 Provider lifetime 동안 유지해 list/viewer 전환 시 기존 MediaStream을 재사용한다.
   const streamRegistry = useMemo(() => createCctvRtcStreamRegistry(), []);
 
+  // scheduler는 Provider option이 바뀌는 경우에만 새 batch 정책으로 다시 만든다.
+  const streamScheduler = useMemo(
+    () =>
+      createCctvRtcStreamScheduler(
+        hasStreamOptions
+          ? {
+              batchIntervalMs: streamBatchIntervalMs,
+              batchSize: streamBatchSize,
+            }
+          : undefined,
+      ),
+    [hasStreamOptions, streamBatchIntervalMs, streamBatchSize],
+  );
+
   useEffect(() => {
     return () => {
+      // Provider unmount가 CCTV stream lifecycle의 최종 정리 지점이다.
       streamRegistry.closeAll();
+      streamScheduler.clear();
     };
-  }, [streamRegistry]);
+  }, [streamRegistry, streamScheduler]);
 
   const mergedDefaultValues = {
     // 변경 설명: service 확장 context 기본값을 core CCTV form context와 한 RHF scope에서 병합한다.
@@ -93,13 +149,15 @@ export default function CCTVProvider<ContextExtension extends object = object>({
   return (
     <ApiUrlContext.Provider value={{ listUrl, tokenUrl }}>
       <RtcStreamRegistryContext.Provider value={streamRegistry}>
-        <Form.Provider<CctvContext<ContextExtension>>
-          options={{
-            defaultValues: mergedDefaultValues,
-          }}
-        >
-          {children}
-        </Form.Provider>
+        <RtcStreamSchedulerContext.Provider value={streamScheduler}>
+          <Form.Provider<CctvContext<ContextExtension>>
+            options={{
+              defaultValues: mergedDefaultValues,
+            }}
+          >
+            {children}
+          </Form.Provider>
+        </RtcStreamSchedulerContext.Provider>
       </RtcStreamRegistryContext.Provider>
     </ApiUrlContext.Provider>
   );

package/src/cctv/components/cam-list/Item.tsx

@@ -25,8 +25,10 @@ export default function CCTVCamListItem({
   renderOverlay,
   ...cam
 }: CctvCamListItemProps) {
+  // item은 즉시 렌더하지만 token/WHEP 시작은 hook 내부 scheduler grant 이후로 지연된다.
   const { videoRef, ...rtcCtx } = useCctvRtcStream({ cam });
 
+  // live/error/message는 video-state util 하나를 기준으로 계산해 CamList와 Viewer 표시 규칙을 맞춘다.
   const isLive = useMemo(() => getIsLive({ cam, ...rtcCtx }), [cam, rtcCtx]);
   const isError = useMemo(() => getIsError({ cam, ...rtcCtx }), [cam, rtcCtx]);
   const overlayMessage = useMemo(
@@ -44,9 +46,11 @@ export default function CCTVCamListItem({
       )}
     >
       <CCTVVideoTemplate
+        // hook이 반환한 ref에 registry MediaStream이 attach된다.
         ref={videoRef}
         cam={cam}
         className="cctv-cam-list-video-container"
+        // list card에서는 live/share 상태를 header에 노출하고 제목은 footer로 내려 보낸다.
         headerOptions={{
           activeLiveState: true,
           activeTitle: false,
@@ -58,9 +62,11 @@ export default function CCTVCamListItem({
         // 변경 설명: list item custom overlay는 template seam 하나만 따라간다.
         renderOverlay={renderOverlay}
         {...{
+          // Video.Template이 overlay/body/footer를 한 번에 판단할 수 있도록 stream 상태를 함께 넘긴다.
           isError,
           overlayMessage,
           isLive,
+          streamStage: rtcCtx.streamStage,
           canReconnect: rtcCtx.canReconnect,
           reconnectStream: rtcCtx.reconnectStream,
         }}

package/src/cctv/components/pagination/list/Item.tsx

@@ -11,14 +11,29 @@ import {
   getIsError,
 } from "../../../utils/video-state";
 
+/**
+ * CCTV; pagination list item
+ * @component
+ * @param {object} props
+ * @param {string} [props.className] pagination thumbnail item 클래스
+ * @param {string} props.cam_id 카메라 id코드
+ * @param {string} props.cam_name 카메라명
+ * @param {string} props.company_id 업체 id코드
+ * @param {boolean} props.cam_online 카메라 온라인 여부
+ * @param {string} props.cam_rtc WebRTC endpoint base URL
+ * @desc
+ * viewer 하단 thumbnail에서도 동일한 `useCctvRtcStream` 경로를 사용해 list/viewer 전환 시 registry reattach 계약을 유지한다.
+ */
 export default function CCTVPaginationListItem({
   className,
   ...cam
 }: {
   className?: string;
 } & CctvCompanyCameraData) {
+  // thumbnail은 즉시 렌더하고, 실제 token/WHEP 시작은 Provider scheduler가 batch 단위로 grant한다.
   const { videoRef, ...rtcCtx } = useCctvRtcStream({ cam });
 
+  // CamList item과 동일한 util을 사용해 overlay 상태 판정 drift를 막는다.
   const isLive = useMemo(() => getIsLive({ cam, ...rtcCtx }), [cam, rtcCtx]);
   const isError = useMemo(() => getIsError({ cam, ...rtcCtx }), [cam, rtcCtx]);
   const overlayMessage = useMemo(
@@ -26,6 +41,7 @@ export default function CCTVPaginationListItem({
     [cam, rtcCtx],
   );
 
+  // cam.onSelect는 render data에 주입된 선택 handler라 있을 때만 호출한다.
   const handleSelect = useCallback(() => {
     if (typeof cam.onSelect === "function") cam.onSelect();
   }, [cam]);
@@ -47,9 +63,11 @@ export default function CCTVPaginationListItem({
         aria-label={`${cam.cam_name} 선택`}
       >
         <CCTVVideoTemplate
+          // registry가 같은 streamKey의 MediaStream을 thumbnail video에 attach한다.
           ref={videoRef}
           cam={cam}
           className="cctv-pagination-list-video-container"
+          // thumbnail에서는 header live/share 상태만 보이고 footer action은 최소화한다.
           headerOptions={{
             activeLiveState: true,
             activeTitle: false,
@@ -59,9 +77,11 @@ export default function CCTVPaginationListItem({
           }}
           footerOptions={{ cam }}
           {...{
+            // Video.Template overlay가 queued/token-loading/connecting/error 상태를 통합 표시한다.
             isError,
             overlayMessage,
             isLive,
+            streamStage: rtcCtx.streamStage,
             canReconnect: rtcCtx.canReconnect,
             reconnectStream: rtcCtx.reconnectStream,
           }}

package/src/cctv/components/video/Template.tsx

@@ -17,6 +17,7 @@ import type { CctvVideoTemplateProps } from "../../types/props";
  * @property {boolean} [isError]
  * @property {React.ReactNode} [overlayMessage]
  * @property {boolean} [isLive]
+ * @property {CctvRtcStreamStage} [streamStage]
  * @property {CctvCompanyCameraData} [cam]
  * @property {boolean} [canReconnect]
  * @property {CctvRtcReconnectTrigger} [reconnectStream]
@@ -33,6 +34,7 @@ const CCTVVideoTemplate = forwardRef<HTMLVideoElement, CctvVideoTemplateProps>(
       isError,
       isLive,
       overlayMessage,
+      streamStage,
       canReconnect,
       reconnectStream,
       renderOverlay,
@@ -60,6 +62,7 @@ const CCTVVideoTemplate = forwardRef<HTMLVideoElement, CctvVideoTemplateProps>(
             isError,
             isLive,
             overlayMessage,
+            streamStage,
             canReconnect,
             reconnectStream,
           })

package/src/cctv/components/viewer/desktop/Video.tsx

@@ -61,6 +61,7 @@ export default function CCTVViewerDesktopVideo({
         isError,
         overlayMessage,
         isLive,
+        streamStage: rtcCtx.streamStage,
         canReconnect: rtcCtx.canReconnect,
         reconnectStream: rtcCtx.reconnectStream,
       }}

package/src/cctv/hooks/streamScheduler.ts

@@ -0,0 +1,276 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import type {
+  CctvRtcStreamOptions,
+  CctvRtcStreamScheduleStatus,
+} from "../types";
+
+const DEFAULT_STREAM_SCHEDULER_OPTIONS = {
+  batchSize: 4,
+  batchIntervalMs: 1200,
+} satisfies Required<CctvRtcStreamOptions>;
+
+type StreamSchedulerListener = () => void;
+
+/**
+ * CCTV; RTC stream scheduler contract
+ * @property {(identityKey: string) => () => void} request stream 시작 순번 요청 함수
+ * @property {(identityKey: string) => CctvRtcStreamScheduleStatus} getStatus stream 시작 순번 상태 조회 함수
+ * @property {(listener: StreamSchedulerListener) => () => void} subscribe scheduler 변경 구독 함수
+ * @property {() => void} clear scheduler 내부 상태 정리 함수
+ */
+export interface CctvRtcStreamScheduler {
+  /**
+   * stream 시작 순번 요청 함수
+   */
+  request: (identityKey: string) => () => void;
+  /**
+   * stream 시작 순번 상태 조회 함수
+   */
+  getStatus: (identityKey: string) => CctvRtcStreamScheduleStatus;
+  /**
+   * scheduler 변경 구독 함수
+   */
+  subscribe: (listener: StreamSchedulerListener) => () => void;
+  /**
+   * scheduler 내부 상태 정리 함수
+   */
+  clear: () => void;
+}
+
+/**
+ * CCTV; RTC stream scheduler 옵션 정규화
+ * @param {CctvRtcStreamOptions} [options] Provider에서 전달한 stream lazy loading 옵션
+ * @returns {Required<CctvRtcStreamOptions>} scheduler 내부에서 사용할 확정 옵션
+ * @desc
+ * service가 잘못된 수치를 넘겨도 기본값과 최소 clamp만 적용해 scheduler가 멈추지 않게 한다.
+ */
+const getNormalizedSchedulerOptions = (
+  options?: CctvRtcStreamOptions,
+): Required<CctvRtcStreamOptions> => {
+  // optional 값을 먼저 지역 변수로 좁혀 TypeScript가 number 판정을 안정적으로 추론하게 한다.
+  const batchSizeCandidate = options?.batchSize;
+  const batchIntervalCandidate = options?.batchIntervalMs;
+
+  // batchSize는 한 번에 grant할 stream 수라 1보다 작으면 scheduler가 진행되지 않는다.
+  const batchSize =
+    typeof batchSizeCandidate === "number" &&
+    Number.isFinite(batchSizeCandidate)
+      ? Math.max(1, Math.floor(batchSizeCandidate))
+      : DEFAULT_STREAM_SCHEDULER_OPTIONS.batchSize;
+
+  // batchIntervalMs는 batch 사이 대기시간이며 0은 연속 flush 허용값으로 둔다.
+  const batchIntervalMs =
+    typeof batchIntervalCandidate === "number" &&
+    Number.isFinite(batchIntervalCandidate)
+      ? Math.max(0, Math.floor(batchIntervalCandidate))
+      : DEFAULT_STREAM_SCHEDULER_OPTIONS.batchIntervalMs;
+
+  return {
+    batchSize,
+    batchIntervalMs,
+  };
+};
+
+/**
+ * CCTV; RTC stream scheduler 생성
+ * @param {CctvRtcStreamOptions} [options] stream lazy loading 옵션
+ * @returns {CctvRtcStreamScheduler} stream 시작 순번 scheduler
+ * @desc
+ * item UI는 즉시 렌더하되 token/WHEP 시작만 batch 단위로 열어 초기 요청 burst를 줄인다.
+ */
+export function createCctvRtcStreamScheduler(
+  options?: CctvRtcStreamOptions,
+): CctvRtcStreamScheduler {
+  // Provider option은 scheduler 생성 시점에 확정해 queue 처리 중 정책 drift를 막는다.
+  const { batchSize, batchIntervalMs } = getNormalizedSchedulerOptions(options);
+
+  // queue는 아직 token/WHEP 시작 권한을 받지 못한 stream identity 순서를 보관한다.
+  const queue: string[] = [];
+
+  // granted는 token query를 열 수 있는 stream identity 집합이다.
+  const granted = new Set<string>();
+
+  // requestCounts는 같은 stream identity를 여러 component가 동시에 쓰는 경우 premature release를 막는다.
+  const requestCounts = new Map<string, number>();
+
+  // listeners는 hook state와 scheduler 내부 상태를 동기화하는 구독자 집합이다.
+  const listeners = new Set<StreamSchedulerListener>();
+
+  // timer는 다음 batch flush 예약을 단일화해 중복 setTimeout을 방지한다.
+  let timer: ReturnType<typeof setTimeout> | null = null;
+
+  const notify = () => {
+    // queue/grant 상태가 바뀌면 모든 hook subscriber가 status를 다시 읽는다.
+    listeners.forEach(listener => listener());
+  };
+
+  const clearTimer = () => {
+    // 예약된 flush가 없으면 timer cleanup은 no-op으로 둔다.
+    if (!timer) return;
+
+    clearTimeout(timer);
+    timer = null;
+  };
+
+  const flush = () => {
+    // 현재 timer callback이 실행됐으므로 다음 예약이 가능하도록 비운다.
+    timer = null;
+
+    // FIFO 순서대로 이번 batch 크기만큼 grant한다.
+    const nextBatch = queue.splice(0, batchSize);
+    nextBatch.forEach(identityKey => {
+      granted.add(identityKey);
+    });
+
+    // 실제 grant 변화가 있을 때만 subscriber를 깨운다.
+    if (nextBatch.length > 0) {
+      notify();
+    }
+
+    // 아직 대기열이 남아 있으면 다음 batch를 interval 뒤에 예약한다.
+    if (queue.length > 0) {
+      timer = setTimeout(flush, batchIntervalMs);
+    }
+  };
+
+  const scheduleFlush = () => {
+    // 이미 예약된 flush가 있으면 같은 queue에 중복 timer를 만들지 않는다.
+    if (timer) return;
+
+    // 첫 batch는 즉시 열고, 이후 batch만 interval을 적용한다.
+    timer = setTimeout(flush, granted.size === 0 ? 0 : batchIntervalMs);
+  };
+
+  return {
+    request(identityKey) {
+      // 같은 stream identity를 여러 video가 요청하면 reference count만 증가시킨다.
+      const currentCount = requestCounts.get(identityKey) ?? 0;
+      requestCounts.set(identityKey, currentCount + 1);
+
+      // 이미 grant됐거나 queue에 있으면 중복 등록하지 않는다.
+      if (!granted.has(identityKey) && !queue.includes(identityKey)) {
+        queue.push(identityKey);
+        notify();
+        scheduleFlush();
+      }
+
+      return () => {
+        // cleanup은 hook unmount 또는 identity 변경 때 호출되며 reference count를 먼저 낮춘다.
+        const nextCount = (requestCounts.get(identityKey) ?? 1) - 1;
+
+        // 아직 같은 identity를 쓰는 component가 남아 있으면 grant/queue 상태를 유지한다.
+        if (nextCount > 0) {
+          requestCounts.set(identityKey, nextCount);
+          return;
+        }
+
+        // 마지막 subscriber가 사라지면 scheduler 상태에서 identity를 제거한다.
+        requestCounts.delete(identityKey);
+        granted.delete(identityKey);
+
+        // 아직 grant 전 queue에 남아 있던 identity라면 대기열에서도 제거한다.
+        const queuedIndex = queue.indexOf(identityKey);
+        if (queuedIndex > -1) {
+          queue.splice(queuedIndex, 1);
+        }
+
+        // 더 이상 처리할 queue가 없으면 다음 flush 예약도 취소한다.
+        if (queue.length === 0) {
+          clearTimer();
+        }
+
+        // release 결과를 subscriber에게 알려 `queued -> idle` 또는 `granted -> idle` 전환을 반영한다.
+        notify();
+      };
+    },
+    getStatus(identityKey) {
+      // token query를 열 수 있는 상태를 최우선으로 반환한다.
+      if (granted.has(identityKey)) return "granted";
+
+      // queue에 들어갔지만 아직 grant되지 않은 상태는 overlay에서 대기 상태로 표시된다.
+      if (queue.includes(identityKey)) return "queued";
+
+      // 요청 전이거나 release 이후면 idle이다.
+      return "idle";
+    },
+    subscribe(listener) {
+      // hook이 scheduler 상태 변경을 React state로 동기화할 수 있게 listener를 등록한다.
+      listeners.add(listener);
+
+      return () => {
+        // hook cleanup 시 listener 누수를 막는다.
+        listeners.delete(listener);
+      };
+    },
+    clear() {
+      // Provider unmount 시 timer와 모든 mutable scheduler 상태를 비운다.
+      clearTimer();
+      queue.splice(0, queue.length);
+      granted.clear();
+      requestCounts.clear();
+
+      // 마지막 상태 변화를 알린 뒤 listener 집합도 비운다.
+      notify();
+      listeners.clear();
+    },
+  };
+}
+
+/**
+ * CCTV; RTC stream scheduler 상태 구독
+ * @hook
+ * @param {CctvRtcStreamScheduler} scheduler stream 시작 순번 scheduler
+ * @param {string} identityKey stream identity key
+ * @param {boolean} enabled scheduler 요청 활성화 여부
+ * @returns {CctvRtcStreamScheduleStatus} stream 시작 순번 상태
+ */
+export function useCctvRtcStreamScheduleStatus({
+  enabled,
+  identityKey,
+  scheduler,
+}: {
+  /**
+   * scheduler 요청 활성화 여부
+   */
+  enabled: boolean;
+  /**
+   * stream identity key
+   */
+  identityKey: string;
+  /**
+   * stream 시작 순번 scheduler
+   */
+  scheduler: CctvRtcStreamScheduler;
+}): CctvRtcStreamScheduleStatus {
+  const [status, setStatus] = useState<CctvRtcStreamScheduleStatus>("idle");
+
+  useEffect(() => {
+    // 필수 identity가 없거나 offline이면 scheduler에 등록하지 않고 idle로 되돌린다.
+    if (!enabled || !identityKey) {
+      setStatus("idle");
+      return;
+    }
+
+    // scheduler mutable state를 React state로 복사해 render가 status 변화를 감지하게 한다.
+    const syncStatus = () => {
+      setStatus(scheduler.getStatus(identityKey));
+    };
+
+    // subscribe 이후 request해야 request 직후 notify도 놓치지 않는다.
+    const unsubscribe = scheduler.subscribe(syncStatus);
+    const release = scheduler.request(identityKey);
+
+    // request 직후 현재 상태를 즉시 반영해 queued/granted 표시 지연을 줄인다.
+    syncStatus();
+
+    return () => {
+      // cleanup 순서는 scheduler reference release 후 listener 제거로 둬 release notify를 받을 수 있게 한다.
+      release();
+      unsubscribe();
+    };
+  }, [enabled, identityKey, scheduler]);
+
+  return status;
+}