@uniai-fe/uds-templates 0.6.9 → 0.6.11

package/package.json

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

package/src/cctv/hooks/useRtcStream.ts

@@ -32,16 +32,10 @@ const POST_CONNECTED_RECONNECT_GRACE_MS = 5000;
 const POST_CONNECTED_RECONNECT_STAGGER_MS = 5000;
 const TOKEN_EXPIRY_SAFETY_MS = 30 * 1000;
 
-type CctvRtcReconnectReason =
-  | "tokenError"
-  | "streamError"
-  | "failed"
-  | "disconnected";
+type CctvRtcReconnectReason = "tokenError" | "streamError" | "failed";
 
-const DISPLAY_CONNECTED_DURING_GRACE_STATES = new Set<RTCPeerConnectionState>([
-  "disconnected",
-  "failed",
-]);
+const DISPLAY_CONNECTED_DURING_RECOVERY_STATES =
+  new Set<RTCPeerConnectionState>(["disconnected", "failed"]);
 
 /**
  * 같은 회사/카메라 묶음이 동시에 재연결하지 않도록 identity 기반 지연값을 만든다.
@@ -70,6 +64,8 @@ const getPostConnectedReconnectDelayMs = (delayKey: string): number =>
  * @desc
  * `closed`는 `streamRegistry.closeByIdentity()`처럼 UDS가 의도적으로 닫을 때도 발생하므로
  * 자동 재연결 사유에 포함하지 않는다.
+ * `disconnected`는 ICE transient 상태에서도 발생하고 기존 MediaStream track이 살아 있을 수 있으므로,
+ * media-health 확인 없이 자동 재연결을 유발하지 않는다.
  */
 const getPostConnectedReconnectReason = ({
   connectionState,
@@ -83,7 +79,6 @@ const getPostConnectedReconnectReason = ({
   if (isTokenError) return "tokenError";
   if (streamError) return "streamError";
   if (connectionState === "failed") return "failed";
-  if (connectionState === "disconnected") return "disconnected";
   return null;
 };
 
@@ -336,12 +331,44 @@ export function useCctvRtcStream({
   const shouldPreserveConnectedDisplay =
     hasConnected &&
     !isPostConnectedReconnectReady &&
-    DISPLAY_CONNECTED_DURING_GRACE_STATES.has(connectionState);
+    DISPLAY_CONNECTED_DURING_RECOVERY_STATES.has(connectionState);
 
+  // 반환 state는 CamList/Viewer/overlay의 live/error/message 계산에 직접 쓰인다.
+  // post-connected disconnected는 자동 재연결 대신 기존 화면을 유지해 UI reset 파동을 막는다.
   const displayConnectionState = shouldPreserveConnectedDisplay
     ? "connected"
     : connectionState;
 
+  const skippedDisconnectedDebugKeyRef = useRef<string | null>(null);
+
+  useEffect(() => {
+    if (
+      connectionState !== "disconnected" ||
+      !hasConnected ||
+      !streamIdentityKey
+    ) {
+      if (connectionState !== "disconnected") {
+        skippedDisconnectedDebugKeyRef.current = null;
+      }
+      return;
+    }
+
+    const skipKey = `${streamIdentityKey}|${activeStreamKeyRef.current ?? ""}`;
+    if (skippedDisconnectedDebugKeyRef.current === skipKey) return;
+
+    skippedDisconnectedDebugKeyRef.current = skipKey;
+    logCctvDebugEvent({
+      event: "reconnect-gate:skip-disconnected",
+      payload: {
+        ...debugBasePayload,
+        connectionState,
+        reason: "disconnected-observed-only",
+        streamKey: getCctvDebugKeyLabel(activeStreamKeyRef.current),
+      },
+      source: "useRtcStream",
+    });
+  }, [connectionState, debugBasePayload, hasConnected, streamIdentityKey]);
+
   const hasReusableRegistryStream = useMemo(() => {
     if (!streamKeyCandidate) return false;
 

package/src/cctv/types/hook.ts

@@ -88,7 +88,7 @@ export interface UseCctvRtcStreamState extends UseCctvRtcStreamError {
  * @property {boolean} isStreaming startWhepStream 진행 여부
  * @property {boolean} isTokenLoading 토큰 발급 요청 진행 여부
  * @property {boolean} isTokenError 토큰 발급 실패 여부
- * @property {boolean} canReconnect UDS 내부 grace/stagger를 통과해 재연결 호출이 가능한지 여부
+ * @property {boolean} canReconnect UDS 내부 허용 사유와 grace/stagger를 통과해 재연결 호출이 가능한지 여부
  * @property {() => Promise<void>} refetchToken 토큰 재발급 함수
  * @property {() => Promise<QueryObserverResult<API_Res_CctvRtcToken>>} reconnectStream 재연결 trigger 함수
  */
@@ -98,10 +98,12 @@ export interface UseCctvRtcStreamReturn extends UseCctvRtcStreamState {
    */
   videoRef: React.RefObject<HTMLVideoElement | null>;
   /**
-   * UDS 내부 grace/stagger를 통과해 재연결 호출이 가능한지 여부
+   * UDS 내부 허용 사유와 grace/stagger를 통과해 재연결 호출이 가능한지 여부
    * @desc
    * 스트림 장애 감지 즉시 true가 되는 플래그가 아니라,
    * 서비스 overlay가 reconnectStream()을 호출해도 되는 시점에 true가 된다.
+   * post-connected `disconnected`는 자동 재연결 사유가 아니며,
+   * token/stream 오류 또는 `failed`처럼 명확한 복구 사유만 true 전환 후보가 된다.
    */
   canReconnect: boolean;
   /**

package/src/cctv/types/props.ts

@@ -9,7 +9,7 @@ import type { CctvRtcReconnectTrigger } from "./hook";
  * @property {boolean | undefined} [isError] 영상 에러 상태 여부
  * @property {boolean | undefined} [isLive] 영상 live 상태 여부
  * @property {React.ReactNode} [overlayMessage] 기본 안내/에러 메시지 콘텐츠
- * @property {boolean | undefined} [canReconnect] UDS 내부 grace/stagger를 통과해 재연결 호출이 가능한지 여부
+ * @property {boolean | undefined} [canReconnect] UDS 내부 허용 사유와 grace/stagger를 통과해 재연결 호출이 가능한지 여부
  * @property {CctvRtcReconnectTrigger | undefined} [reconnectStream] 재연결 trigger 함수
  */
 export interface CctvVideoRenderOverlayContext {
@@ -38,10 +38,11 @@ export interface CctvVideoRenderOverlayContext {
    */
   overlayMessage?: React.ReactNode;
   /**
-   * UDS 내부 grace/stagger를 통과해 재연결 호출이 가능한지 여부
+   * UDS 내부 허용 사유와 grace/stagger를 통과해 재연결 호출이 가능한지 여부
    * @desc
    * custom overlay에서 자동 재연결을 구현할 때 이 값이 true인 경우에만
    * reconnectStream()을 호출해야 한다.
+   * post-connected `disconnected`는 이 값만으로 자동 재연결하지 않는다.
    */
   canReconnect?: boolean;
   /**
@@ -129,7 +130,7 @@ export interface CctvVideoOverlayFooterProps {
  * @property {boolean} [isError] 에러 상태 여부
  * @property {boolean} [isLive] 영상이 정상적으로 재생 중인지 여부
  * @property {React.ReactNode} [overlayMessage] 에러/안내 메시지 콘텐츠
- * @property {boolean} [canReconnect] UDS 내부 grace/stagger를 통과해 재연결 호출이 가능한지 여부
+ * @property {boolean} [canReconnect] UDS 내부 허용 사유와 grace/stagger를 통과해 재연결 호출이 가능한지 여부
  * @property {CctvRtcReconnectTrigger} [reconnectStream] 재연결 trigger 함수
  */
 export interface CctvVideoStateProps {
@@ -146,7 +147,7 @@ export interface CctvVideoStateProps {
    */
   overlayMessage?: React.ReactNode;
   /**
-   * UDS 내부 grace/stagger를 통과해 재연결 호출이 가능한지 여부
+   * UDS 내부 허용 사유와 grace/stagger를 통과해 재연결 호출이 가능한지 여부
    */
   canReconnect?: boolean;
   /**

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

@@ -11,7 +11,7 @@ import type { UseCctvRtcStreamError, UseCctvRtcStreamState } from "./hook";
  * @property {boolean} isTokenLoading 토큰 발급 요청 진행 여부
  * @property {boolean} isTokenError 토큰 발급 실패 여부
  * @property {string | null} streamError 스트림 오류 메시지
- * @property {boolean} [canReconnect] UDS 내부 grace/stagger를 통과해 재연결 호출이 가능한지 여부
+ * @property {boolean} [canReconnect] UDS 내부 허용 사유와 grace/stagger를 통과해 재연결 호출이 가능한지 여부
  */
 export interface CctvVideoOverlayMessageParams extends UseCctvRtcStreamState {
   /**
@@ -27,7 +27,7 @@ export interface CctvVideoOverlayMessageParams extends UseCctvRtcStreamState {
    */
   isFetching?: boolean;
   /**
-   * UDS 내부 grace/stagger를 통과해 재연결 호출이 가능한지 여부
+   * UDS 내부 허용 사유와 grace/stagger를 통과해 재연결 호출이 가능한지 여부
    */
   canReconnect?: boolean;
 }
@@ -53,7 +53,7 @@ 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 {
   /**
@@ -61,7 +61,7 @@ export interface CctvVideoErrorParams extends UseCctvRtcStreamError {
    */
   cam?: CctvCompanyCameraData;
   /**
-   * UDS 내부 grace/stagger를 통과해 재연결 호출이 가능한지 여부
+   * UDS 내부 허용 사유와 grace/stagger를 통과해 재연결 호출이 가능한지 여부
    */
   canReconnect?: boolean;
 }

package/src/cctv/utils/debug.ts

@@ -11,13 +11,36 @@ export interface CctvDebugEvent {
   source: string;
 }
 
+export interface CctvDebugReconnectStartSummary {
+  at: string;
+  caller: string | null;
+  camId: string | null;
+  connectionState: string | null;
+  isPostConnectedReconnectReady: boolean | null;
+  reconnectReason: string | null;
+}
+
+export interface CctvDebugSummary {
+  connectionStateCounts: Record<string, number>;
+  eventCounts: Record<string, number>;
+  first: string | null;
+  generatedAt: string;
+  last: string | null;
+  reconnectCallers: Record<string, number>;
+  reconnectReasons: Record<string, number>;
+  reconnectStarts: CctvDebugReconnectStartSummary[];
+  total: number;
+}
+
 export interface CctvDebugBuffer {
   clear: () => void;
   dump: () => CctvDebugEvent[];
   enabled: true;
   events: CctvDebugEvent[];
+  filter: (keywords?: readonly string[]) => CctvDebugEvent[];
   limit: number;
   sequence: number;
+  summary: () => CctvDebugSummary;
 }
 
 declare global {
@@ -28,15 +51,175 @@ declare global {
 
 const DEBUG_QUERY_KEYS = ["udsCctvDebug", "cctvDebug"] as const;
 const DEBUG_STORAGE_KEYS = ["uds:cctv:debug", "UDS_CCTV_DEBUG"] as const;
+const DEBUG_CONSOLE_QUERY_KEYS = [
+  "udsCctvDebugConsole",
+  "cctvDebugConsole",
+] as const;
+const DEBUG_CONSOLE_STORAGE_KEYS = [
+  "uds:cctv:debug:console",
+  "UDS_CCTV_DEBUG_CONSOLE",
+] as const;
 const DEBUG_ENABLED_VALUES = new Set(["1", "true", "yes", "on", "debug"]);
+const DEBUG_DISABLED_VALUES = new Set(["0", "false", "no", "off"]);
 const DEBUG_BUFFER_LIMIT = 1000;
+const DEBUG_DEFAULT_FILTER_KEYWORDS = [
+  "reconnect",
+  "close",
+  "rejected",
+  "connection-state:change",
+  "track:received",
+] as const;
 
 const isBrowser = (): boolean =>
   typeof window !== "undefined" && typeof document !== "undefined";
 
-const isDebugValueEnabled = (value: string | null): boolean =>
-  value === "" ||
-  (typeof value === "string" && DEBUG_ENABLED_VALUES.has(value));
+const getDebugValueOverride = (value: string | null): boolean | null => {
+  if (value === "") return true;
+  if (typeof value !== "string") return null;
+
+  const normalizedValue = value.toLowerCase();
+  if (DEBUG_ENABLED_VALUES.has(normalizedValue)) return true;
+  if (DEBUG_DISABLED_VALUES.has(normalizedValue)) return false;
+  return null;
+};
+
+const getDebugQueryOverride = (keys: readonly string[]): boolean | null => {
+  const query = new URLSearchParams(window.location.search);
+  for (const key of keys) {
+    if (!query.has(key)) continue;
+
+    const override = getDebugValueOverride(query.get(key));
+    if (override !== null) return override;
+  }
+
+  return null;
+};
+
+const getDebugStorageOverride = (keys: readonly string[]): boolean | null => {
+  for (const key of keys) {
+    try {
+      const override = getDebugValueOverride(window.localStorage.getItem(key));
+      if (override !== null) return override;
+    } catch {
+      return false;
+    }
+  }
+
+  return null;
+};
+
+const isLocalhostDebugDefaultEnabled = (): boolean => {
+  const { hostname } = window.location;
+  return (
+    hostname === "localhost" ||
+    hostname === "127.0.0.1" ||
+    hostname === "[::1]" ||
+    hostname === "::1" ||
+    hostname.endsWith(".localhost")
+  );
+};
+
+const getPayloadString = (
+  payload: Record<string, unknown> | undefined,
+  key: string,
+): string | null => {
+  const value = payload?.[key];
+  return typeof value === "string" ? value : null;
+};
+
+const getPayloadBoolean = (
+  payload: Record<string, unknown> | undefined,
+  key: string,
+): boolean | null => {
+  const value = payload?.[key];
+  return typeof value === "boolean" ? value : null;
+};
+
+const getReconnectCaller = (
+  payload: Record<string, unknown> | undefined,
+): string | null => {
+  const callerStack = payload?.callerStack;
+  const stackLines = Array.isArray(callerStack)
+    ? callerStack.filter((line): line is string => typeof line === "string")
+    : typeof callerStack === "string"
+      ? callerStack.split("\n")
+      : [];
+
+  return (
+    stackLines
+      .find(
+        line =>
+          line.includes("CCTVManagerVideoOverlay") ||
+          line.includes("reconnectOnFocus"),
+      )
+      ?.trim() ?? null
+  );
+};
+
+const countBy = <T extends string>(
+  target: Record<T, number>,
+  key: T | null,
+): void => {
+  if (!key) return;
+  target[key] = (target[key] ?? 0) + 1;
+};
+
+const filterCctvDebugEvents = (
+  events: readonly CctvDebugEvent[],
+  keywords: readonly string[] = DEBUG_DEFAULT_FILTER_KEYWORDS,
+): CctvDebugEvent[] =>
+  events.filter(entry =>
+    keywords.some(keyword => entry.event.includes(keyword)),
+  );
+
+const summarizeCctvDebugEvents = (
+  events: readonly CctvDebugEvent[],
+): CctvDebugSummary => {
+  const eventCounts: Record<string, number> = {};
+  const connectionStateCounts: Record<string, number> = {};
+  const reconnectReasons: Record<string, number> = {};
+  const reconnectCallers: Record<string, number> = {};
+  const reconnectStarts: CctvDebugReconnectStartSummary[] = [];
+
+  for (const entry of events) {
+    countBy(eventCounts, entry.event);
+
+    if (entry.event === "connection-state:change") {
+      countBy(connectionStateCounts, getPayloadString(entry.payload, "state"));
+    }
+
+    if (entry.event !== "reconnect-stream:start") continue;
+
+    const reconnectReason = getPayloadString(entry.payload, "reconnectReason");
+    const caller = getReconnectCaller(entry.payload);
+
+    countBy(reconnectReasons, reconnectReason ?? "none");
+    countBy(reconnectCallers, caller ?? "unknown");
+    reconnectStarts.push({
+      at: entry.at,
+      caller,
+      camId: getPayloadString(entry.payload, "camId"),
+      connectionState: getPayloadString(entry.payload, "connectionState"),
+      isPostConnectedReconnectReady: getPayloadBoolean(
+        entry.payload,
+        "isPostConnectedReconnectReady",
+      ),
+      reconnectReason,
+    });
+  }
+
+  return {
+    connectionStateCounts,
+    eventCounts,
+    first: events[0]?.at ?? null,
+    generatedAt: new Date().toISOString(),
+    last: events[events.length - 1]?.at ?? null,
+    reconnectCallers,
+    reconnectReasons,
+    reconnectStarts,
+    total: events.length,
+  };
+};
 
 /**
  * identity/stream key를 원문 대신 추적 가능한 hash label로 바꾼다.
@@ -79,20 +262,30 @@ export const getCctvDebugUrlLabel = (
 export const isCctvDebugEnabled = (): boolean => {
   if (!isBrowser()) return false;
 
-  const query = new URLSearchParams(window.location.search);
-  for (const key of DEBUG_QUERY_KEYS) {
-    if (query.has(key) && isDebugValueEnabled(query.get(key))) return true;
-  }
+  const queryOverride = getDebugQueryOverride(DEBUG_QUERY_KEYS);
+  if (queryOverride !== null) return queryOverride;
 
-  for (const key of DEBUG_STORAGE_KEYS) {
-    try {
-      if (isDebugValueEnabled(window.localStorage.getItem(key))) return true;
-    } catch {
-      return false;
-    }
-  }
+  const storageOverride = getDebugStorageOverride(DEBUG_STORAGE_KEYS);
+  if (storageOverride !== null) return storageOverride;
 
-  return false;
+  return isLocalhostDebugDefaultEnabled();
+};
+
+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
+  );
 };
 
 /**
@@ -126,6 +319,8 @@ const getCctvDebugBuffer = (): CctvDebugBuffer | null => {
       buffer.sequence = 0;
     },
     dump: () => [...buffer.events],
+    filter: keywords => filterCctvDebugEvents(buffer.events, keywords),
+    summary: () => summarizeCctvDebugEvents(buffer.events),
   };
 
   window.__UDS_CCTV_DEBUG__ = buffer;
@@ -166,6 +361,8 @@ export const logCctvDebugEvent = ({
     buffer.events.splice(0, buffer.events.length - buffer.limit);
   }
 
+  if (!isCctvDebugConsoleEnabled()) return;
+
   const logger =
     level === "error"
       ? console.error

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

@@ -62,10 +62,7 @@ export function getOverlayMessage({
   if (canReconnect && RTC_SESSION_ENDED_RECONNECT_STATES.has(connectionState)) {
     return CCTV_MESSAGE.sessionEnded;
   }
-  // grace/stagger가 끝난 disconnected는 더 이상 준비 상태가 아니라 재연결 대상 장애다.
-  if (canReconnect && connectionState === "disconnected") {
-    return CCTV_MESSAGE.offline;
-  }
+  // raw disconnected는 useCctvRtcStream에서 post-connected connected로 smoothing한다.
   if (isTokenLoading || isStreaming) return CCTV_MESSAGE.preparing;
   if (RTC_PREPARING_STATES.has(connectionState)) return CCTV_MESSAGE.preparing;
   return null;