@uniai-fe/uds-templates 0.6.12 → 0.6.14

package/package.json

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

package/src/cctv/hooks/streamRegistry.ts

@@ -2,6 +2,7 @@
 
 import { startWhepStream, type WhepStreamHandle } from "@uniai-fe/util-rtc";
 import {
+  getCctvDebugJwtMetadata,
   getCctvDebugKeyLabel,
   getCctvDebugUrlLabel,
   logCctvDebugEvent,
@@ -31,6 +32,8 @@ interface CctvRtcStreamStartParams {
   video: HTMLVideoElement;
 }
 
+const WHEP_ERROR_BODY_PREVIEW_LIMIT = 1000;
+
 const getEntrySnapshot = (
   entry?: CctvRtcStreamEntry,
 ): CctvRtcStreamSnapshot => ({
@@ -46,11 +49,70 @@ 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));
 };
 
+const getWhepResponseBodyPreview = async (
+  response: Response,
+): Promise<string | null> => {
+  try {
+    const text = await response.clone().text();
+    return text.slice(0, WHEP_ERROR_BODY_PREVIEW_LIMIT);
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * WHEP 실패 body를 startWhepStream 외부에서 관찰하기 위한 fetch wrapper.
+ * @desc
+ * 성공 응답은 그대로 통과시키고, 실패 응답에서만 clone body를 읽어 debug log에 남긴다.
+ */
+const createCctvDebugWhepFetcher =
+  ({
+    endpoint,
+    identityKey,
+    streamKey,
+    token,
+  }: {
+    endpoint: string;
+    identityKey: string;
+    streamKey: string;
+    token: string;
+  }): typeof fetch =>
+  async (input, init) => {
+    const response = await fetch(input, init);
+    if (response.ok) return response;
+
+    logCctvDebugEvent({
+      event: "whep:response-error",
+      level: "error",
+      payload: {
+        endpoint: getCctvDebugUrlLabel(endpoint),
+        identityKey: getCctvDebugKeyLabel(identityKey),
+        responseBody: await getWhepResponseBodyPreview(response),
+        status: response.status,
+        statusText: response.statusText,
+        streamKey: getCctvDebugKeyLabel(streamKey),
+        token: getCctvDebugJwtMetadata(token),
+      },
+      source: "streamRegistry",
+    });
+
+    return response;
+  };
+
 const closeEntry = (entry: CctvRtcStreamEntry) => {
   logCctvDebugEvent({
     event: "entry:close",
@@ -72,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);
@@ -113,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() {
@@ -180,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: {
@@ -188,12 +253,19 @@ export function createCctvRtcStreamRegistry(): CctvRtcStreamRegistry {
           endpoint: getCctvDebugUrlLabel(endpoint),
           identityKey: getCctvDebugKeyLabel(identityKey),
           streamKey: getCctvDebugKeyLabel(streamKey),
+          token: getCctvDebugJwtMetadata(token),
         },
         source: "streamRegistry",
       });
 
       startWhepStream({
         endpoint,
+        fetcher: createCctvDebugWhepFetcher({
+          endpoint,
+          identityKey,
+          streamKey,
+          token,
+        }),
         token,
         video,
         signal: controller.signal,
@@ -268,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/debug.ts

@@ -32,6 +32,15 @@ export interface CctvDebugSummary {
   total: number;
 }
 
+export interface CctvDebugJwtMetadata {
+  expiresAt: string | null;
+  expiresInSec: number | null;
+  headerAlg: string | null;
+  headerKid: string | null;
+  tokenLabel: string | null;
+  tokenPartCount: number;
+}
+
 export interface CctvDebugBuffer {
   clear: () => void;
   dump: () => CctvDebugEvent[];
@@ -108,6 +117,13 @@ const getDebugStorageOverride = (keys: readonly string[]): boolean | null => {
   return null;
 };
 
+const getDebugConsoleOverride = (): boolean | null => {
+  const queryOverride = getDebugQueryOverride(DEBUG_CONSOLE_QUERY_KEYS);
+  if (queryOverride !== null) return queryOverride;
+
+  return getDebugStorageOverride(DEBUG_CONSOLE_STORAGE_KEYS);
+};
+
 const isLocalhostDebugDefaultEnabled = (): boolean => {
   const { hostname } = window.location;
   return (
@@ -221,6 +237,57 @@ const summarizeCctvDebugEvents = (
   };
 };
 
+const decodeBase64UrlJson = (value: string): Record<string, unknown> | null => {
+  try {
+    const base64 = value.replace(/-/g, "+").replace(/_/g, "/");
+    const padded = base64.padEnd(Math.ceil(base64.length / 4) * 4, "=");
+    const parsed = JSON.parse(atob(padded));
+
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+      ? (parsed as Record<string, unknown>)
+      : null;
+  } catch {
+    return null;
+  }
+};
+
+const getJwtStringClaim = (
+  claims: Record<string, unknown> | null,
+  key: string,
+): string | null => {
+  const value = claims?.[key];
+  return typeof value === "string" ? value : null;
+};
+
+const getJwtExpiresAt = (
+  claims: Record<string, unknown> | null,
+): { expiresAt: string | null; expiresInSec: number | null } => {
+  const exp = claims?.exp;
+  if (typeof exp !== "number" || !Number.isFinite(exp)) {
+    return { expiresAt: null, expiresInSec: null };
+  }
+
+  const expiresAtMs = exp * 1000;
+  return {
+    expiresAt: new Date(expiresAtMs).toISOString(),
+    expiresInSec: Math.floor((expiresAtMs - Date.now()) / 1000),
+  };
+};
+
+const stringifyCctvDebugEvent = (entry: CctvDebugEvent): string => {
+  try {
+    return JSON.stringify(entry);
+  } catch {
+    return JSON.stringify({
+      at: entry.at,
+      event: entry.event,
+      level: entry.level,
+      seq: entry.seq,
+      source: entry.source,
+    });
+  }
+};
+
 /**
  * identity/stream key를 원문 대신 추적 가능한 hash label로 바꾼다.
  */
@@ -253,11 +320,37 @@ export const getCctvDebugUrlLabel = (
   }
 };
 
+/**
+ * JWT 원문 대신 헤더/만료시각과 hash label만 기록한다.
+ * @desc
+ * token signature mismatch를 추적하기 위한 메타 정보이며, Bearer token 원문과 payload claim은
+ * debug log에 남기지 않는다.
+ */
+export const getCctvDebugJwtMetadata = (
+  token: string | null | undefined,
+): CctvDebugJwtMetadata | null => {
+  if (!token) return null;
+
+  const [headerPart, payloadPart] = token.split(".");
+  const header = headerPart ? decodeBase64UrlJson(headerPart) : null;
+  const payload = payloadPart ? decodeBase64UrlJson(payloadPart) : null;
+  const { expiresAt, expiresInSec } = getJwtExpiresAt(payload);
+
+  return {
+    expiresAt,
+    expiresInSec,
+    headerAlg: getJwtStringClaim(header, "alg"),
+    headerKid: getJwtStringClaim(header, "kid"),
+    tokenLabel: getCctvDebugKeyLabel(token),
+    tokenPartCount: token.split(".").length,
+  };
+};
+
 /**
  * CCTV debug logging 활성화 여부를 확인한다.
  * @desc
- * production default는 off다. `?udsCctvDebug=1` 또는
- * `localStorage.setItem("uds:cctv:debug", "1")`로 runtime에서 켤 수 있다.
+ * production default는 off, localhost default는 ring buffer on이다.
+ * console 출력은 별도 console flag를 켠 경우에만 활성화한다.
  */
 export const isCctvDebugEnabled = (): boolean => {
   if (!isBrowser()) return false;
@@ -265,6 +358,9 @@ export const isCctvDebugEnabled = (): boolean => {
   const queryOverride = getDebugQueryOverride(DEBUG_QUERY_KEYS);
   if (queryOverride !== null) return queryOverride;
 
+  const consoleOverride = getDebugConsoleOverride();
+  if (consoleOverride === true) return true;
+
   const storageOverride = getDebugStorageOverride(DEBUG_STORAGE_KEYS);
   if (storageOverride !== null) return storageOverride;
 
@@ -274,19 +370,7 @@ export const isCctvDebugEnabled = (): boolean => {
 const isCctvDebugConsoleEnabled = (): boolean => {
   if (!isBrowser()) return false;
 
-  const consoleQueryOverride = getDebugQueryOverride(DEBUG_CONSOLE_QUERY_KEYS);
-  if (consoleQueryOverride !== null) return consoleQueryOverride;
-
-  const consoleStorageOverride = getDebugStorageOverride(
-    DEBUG_CONSOLE_STORAGE_KEYS,
-  );
-  if (consoleStorageOverride !== null) return consoleStorageOverride;
-
-  return (
-    getDebugQueryOverride(DEBUG_QUERY_KEYS) === true ||
-    getDebugStorageOverride(DEBUG_STORAGE_KEYS) === true ||
-    isLocalhostDebugDefaultEnabled()
-  );
+  return getDebugConsoleOverride() === true;
 };
 
 /**
@@ -373,5 +457,5 @@ export const logCctvDebugEvent = ({
           ? console.info
           : console.debug;
 
-  logger.call(console, "[UDS:CCTV]", entry);
+  logger.call(console, `[UDS:CCTV] ${stringifyCctvDebugEvent(entry)}`);
 };

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} 라이브 상태 여부 반환