connectbase-client 5.13.0 → 6.0.0

package/dist/index.d.mts

@@ -7403,9 +7403,31 @@ declare class RealtimeAPI {
      */
     getState(): ConnectionState;
     /**
-     * 연결 여부 확인
+     * pub/sub 사용 가능 여부.
+     *
+     * WebSocket 으로 연결됐을 때만 true 다. SSE fallback 모드에서는 `subscribe` /
+     * `sendMessage` / `setPresence` / typing 이 전부 예외를 던지므로, 여기서 true 를
+     * 반환하면 앱이 "연결됨"으로 오판하고 아무것도 오가지 않는 채 조용히 멈춘다
+     * (platform-issue 01a01e6a-3cb1).
+     *
+     * AI 스트리밍만 필요하다면 {@link isStreamReady} 를, 다운그레이드 여부를 알고 싶다면
+     * {@link isDegraded} 를 쓴다.
      */
     isConnected(): boolean;
+    /**
+     * SSE fallback 으로 다운그레이드된 상태인지 여부.
+     *
+     * true 면 연결은 살아 있지만 단방향이라 `realtime.stream()` 만 동작한다. 사용자에게
+     * "제한된 네트워크라 일부 기능을 쓸 수 없다" 고 안내할 지점이다.
+     */
+    isDegraded(): boolean;
+    /**
+     * AI 스트리밍(`realtime.stream()`) 사용 가능 여부.
+     *
+     * WS 든 SSE fallback 이든 연결만 서 있으면 true 다. 종전 `isConnected()` 와 같은
+     * 판정이므로, 스트리밍 게이팅에 `isConnected()` 를 쓰던 코드는 이쪽으로 옮긴다.
+     */
+    isStreamReady(): boolean;
     /**
      * 상태 변경 핸들러 등록
      */
@@ -10047,6 +10069,14 @@ interface ICEServer {
 /** ICE 서버 목록 응답 */
 interface ICEServersResponse {
     ice_servers: ICEServer[];
+    /**
+     * ephemeral TURN 자격증명의 만료 시각(Unix epoch 초).
+     *
+     * 서버가 `TURN_SHARED_SECRET` 으로 시간제한 자격증명을 발급한 경우에만 0 이 아니다.
+     * STUN 전용 구성에서는 0 — 만료가 없다는 뜻이다. 통화가 길어질 수 있으면 이 시각
+     * 전에 `getICEServers()` 를 다시 불러 새 자격증명을 받는다.
+     */
+    expires_at?: number;
 }
 /**
  * 채널별 통계 (룸 ID 의 `channel:room` 컨벤션 기준 집계).
@@ -10122,6 +10152,16 @@ declare class WebRTCAPI {
     private reconnectAttempts;
     private maxReconnectAttempts;
     private reconnectTimeout;
+    /**
+     * 시그널링 소켓의 세대(generation) 토큰.
+     *
+     * 소켓을 열 때마다 1 증가하며, 각 핸들러는 자기가 열릴 때의 세대를 클로저에 담아둔다.
+     * 세대가 밀린 핸들러는 "옛 소켓의 지연 이벤트" 이므로 인스턴스 상태를 건드리지 않는다.
+     * 참조(`this.ws`)만 끊는 것으로는 부족하다 — 핸들러 클로저가 인스턴스를 캡처하고 있어
+     * close 이벤트가 뒤늦게 도착하면 새 연결을 'disconnected' 로 덮어쓰고 새로 만든 피어
+     * 연결까지 정리해버린다.
+     */
+    private wsGeneration;
     private currentRoomId;
     private currentPeerId;
     private currentUserId;
@@ -10158,6 +10198,14 @@ declare class WebRTCAPI {
      */
     connect(options: WebRTCConnectOptions): Promise<void>;
     private connectWebSocket;
+    /**
+     * 소켓에 붙은 핸들러를 전부 떼어낸다.
+     *
+     * `this.ws = null` 로 참조만 끊으면 클로저가 살아남아 close 이벤트가 계속 들어온다.
+     * 세대 토큰이 그 이벤트를 무시해주긴 하지만, 핸들러 자체를 떼면 인스턴스 참조가 끊겨
+     * 소켓이 GC 될 때까지 인스턴스를 붙잡고 있지 않는다.
+     */
+    private static detachSocket;
     private buildWebSocketUrl;
     private handleSignalingMessage;
     private createPeerConnection;
@@ -10172,6 +10220,44 @@ declare class WebRTCAPI {
      * WebRTC 연결 해제
      */
     disconnect(): void;
+    /**
+     * 현재 세션의 룸을 교체한다.
+     *
+     * `disconnect()` 후 곧바로 `connect()` 하는 패턴을 안전하게 감싼 것이다. 옛 소켓의
+     * close 이벤트가 새 연결의 'connecting' 구간에 떨어져도 세대 토큰이 걸러낸다.
+     * 생략한 옵션은 현재 세션 값을 그대로 이어받는다.
+     *
+     * @example
+     * ```typescript
+     * await cb.webrtc.switchRoom('channel:room-b')
+     * ```
+     */
+    switchRoom(roomId: string, options?: Omit<WebRTCConnectOptions, "roomId">): Promise<void>;
+    /**
+     * 소켓, 룸, 이벤트 리스너, 피어 연결을 **독립적으로** 갖는 새 WebRTC 세션을 만든다.
+     *
+     * `cb.webrtc` 는 인스턴스 하나에 소켓 하나/룸 하나라, 한 앱에 WebRTC 기능이 둘 이상이면
+     * (예: 공간 음성채팅 + 1:1 통화) 서로 연결을 뺏고 이벤트가 교차한다. 기능마다 세션을
+     * 하나씩 만들면 각자의 소켓과 핸들러를 갖는다.
+     *
+     * 인증 정보(HttpClient)와 서버 주소, appId 는 부모와 공유한다.
+     *
+     * @example
+     * ```typescript
+     * const voice = cb.webrtc.createSession()
+     * const call = cb.webrtc.createSession()
+     *
+     * voice.onRemoteStream((peerId, stream) => attachToSpatialAudio(peerId, stream))
+     * call.onRemoteStream((peerId, stream) => showCallScreen(stream))
+     *
+     * await voice.connect({ roomId: 'voice:lobby', localStream: mic })
+     * await call.connect({ roomId: 'call:alice-bob', localStream: mic })
+     *
+     * // 각 세션은 독립적으로 끊는다
+     * call.disconnect()
+     * ```
+     */
+    createSession(): WebRTCAPI;
     /**
      * 현재 연결 상태 조회
      */

package/dist/index.d.ts

@@ -7403,9 +7403,31 @@ declare class RealtimeAPI {
      */
     getState(): ConnectionState;
     /**
-     * 연결 여부 확인
+     * pub/sub 사용 가능 여부.
+     *
+     * WebSocket 으로 연결됐을 때만 true 다. SSE fallback 모드에서는 `subscribe` /
+     * `sendMessage` / `setPresence` / typing 이 전부 예외를 던지므로, 여기서 true 를
+     * 반환하면 앱이 "연결됨"으로 오판하고 아무것도 오가지 않는 채 조용히 멈춘다
+     * (platform-issue 01a01e6a-3cb1).
+     *
+     * AI 스트리밍만 필요하다면 {@link isStreamReady} 를, 다운그레이드 여부를 알고 싶다면
+     * {@link isDegraded} 를 쓴다.
      */
     isConnected(): boolean;
+    /**
+     * SSE fallback 으로 다운그레이드된 상태인지 여부.
+     *
+     * true 면 연결은 살아 있지만 단방향이라 `realtime.stream()` 만 동작한다. 사용자에게
+     * "제한된 네트워크라 일부 기능을 쓸 수 없다" 고 안내할 지점이다.
+     */
+    isDegraded(): boolean;
+    /**
+     * AI 스트리밍(`realtime.stream()`) 사용 가능 여부.
+     *
+     * WS 든 SSE fallback 이든 연결만 서 있으면 true 다. 종전 `isConnected()` 와 같은
+     * 판정이므로, 스트리밍 게이팅에 `isConnected()` 를 쓰던 코드는 이쪽으로 옮긴다.
+     */
+    isStreamReady(): boolean;
     /**
      * 상태 변경 핸들러 등록
      */
@@ -10047,6 +10069,14 @@ interface ICEServer {
 /** ICE 서버 목록 응답 */
 interface ICEServersResponse {
     ice_servers: ICEServer[];
+    /**
+     * ephemeral TURN 자격증명의 만료 시각(Unix epoch 초).
+     *
+     * 서버가 `TURN_SHARED_SECRET` 으로 시간제한 자격증명을 발급한 경우에만 0 이 아니다.
+     * STUN 전용 구성에서는 0 — 만료가 없다는 뜻이다. 통화가 길어질 수 있으면 이 시각
+     * 전에 `getICEServers()` 를 다시 불러 새 자격증명을 받는다.
+     */
+    expires_at?: number;
 }
 /**
  * 채널별 통계 (룸 ID 의 `channel:room` 컨벤션 기준 집계).
@@ -10122,6 +10152,16 @@ declare class WebRTCAPI {
     private reconnectAttempts;
     private maxReconnectAttempts;
     private reconnectTimeout;
+    /**
+     * 시그널링 소켓의 세대(generation) 토큰.
+     *
+     * 소켓을 열 때마다 1 증가하며, 각 핸들러는 자기가 열릴 때의 세대를 클로저에 담아둔다.
+     * 세대가 밀린 핸들러는 "옛 소켓의 지연 이벤트" 이므로 인스턴스 상태를 건드리지 않는다.
+     * 참조(`this.ws`)만 끊는 것으로는 부족하다 — 핸들러 클로저가 인스턴스를 캡처하고 있어
+     * close 이벤트가 뒤늦게 도착하면 새 연결을 'disconnected' 로 덮어쓰고 새로 만든 피어
+     * 연결까지 정리해버린다.
+     */
+    private wsGeneration;
     private currentRoomId;
     private currentPeerId;
     private currentUserId;
@@ -10158,6 +10198,14 @@ declare class WebRTCAPI {
      */
     connect(options: WebRTCConnectOptions): Promise<void>;
     private connectWebSocket;
+    /**
+     * 소켓에 붙은 핸들러를 전부 떼어낸다.
+     *
+     * `this.ws = null` 로 참조만 끊으면 클로저가 살아남아 close 이벤트가 계속 들어온다.
+     * 세대 토큰이 그 이벤트를 무시해주긴 하지만, 핸들러 자체를 떼면 인스턴스 참조가 끊겨
+     * 소켓이 GC 될 때까지 인스턴스를 붙잡고 있지 않는다.
+     */
+    private static detachSocket;
     private buildWebSocketUrl;
     private handleSignalingMessage;
     private createPeerConnection;
@@ -10172,6 +10220,44 @@ declare class WebRTCAPI {
      * WebRTC 연결 해제
      */
     disconnect(): void;
+    /**
+     * 현재 세션의 룸을 교체한다.
+     *
+     * `disconnect()` 후 곧바로 `connect()` 하는 패턴을 안전하게 감싼 것이다. 옛 소켓의
+     * close 이벤트가 새 연결의 'connecting' 구간에 떨어져도 세대 토큰이 걸러낸다.
+     * 생략한 옵션은 현재 세션 값을 그대로 이어받는다.
+     *
+     * @example
+     * ```typescript
+     * await cb.webrtc.switchRoom('channel:room-b')
+     * ```
+     */
+    switchRoom(roomId: string, options?: Omit<WebRTCConnectOptions, "roomId">): Promise<void>;
+    /**
+     * 소켓, 룸, 이벤트 리스너, 피어 연결을 **독립적으로** 갖는 새 WebRTC 세션을 만든다.
+     *
+     * `cb.webrtc` 는 인스턴스 하나에 소켓 하나/룸 하나라, 한 앱에 WebRTC 기능이 둘 이상이면
+     * (예: 공간 음성채팅 + 1:1 통화) 서로 연결을 뺏고 이벤트가 교차한다. 기능마다 세션을
+     * 하나씩 만들면 각자의 소켓과 핸들러를 갖는다.
+     *
+     * 인증 정보(HttpClient)와 서버 주소, appId 는 부모와 공유한다.
+     *
+     * @example
+     * ```typescript
+     * const voice = cb.webrtc.createSession()
+     * const call = cb.webrtc.createSession()
+     *
+     * voice.onRemoteStream((peerId, stream) => attachToSpatialAudio(peerId, stream))
+     * call.onRemoteStream((peerId, stream) => showCallScreen(stream))
+     *
+     * await voice.connect({ roomId: 'voice:lobby', localStream: mic })
+     * await call.connect({ roomId: 'call:alice-bob', localStream: mic })
+     *
+     * // 각 세션은 독립적으로 끊는다
+     * call.disconnect()
+     * ```
+     */
+    createSession(): WebRTCAPI;
     /**
      * 현재 연결 상태 조회
      */

package/dist/index.js

@@ -7936,9 +7936,35 @@ var RealtimeAPI = class {
     return this.state;
   }
   /**
-   * 연결 여부 확인
+   * pub/sub 사용 가능 여부.
+   *
+   * WebSocket 으로 연결됐을 때만 true 다. SSE fallback 모드에서는 `subscribe` /
+   * `sendMessage` / `setPresence` / typing 이 전부 예외를 던지므로, 여기서 true 를
+   * 반환하면 앱이 "연결됨"으로 오판하고 아무것도 오가지 않는 채 조용히 멈춘다
+   * (platform-issue 01a01e6a-3cb1).
+   *
+   * AI 스트리밍만 필요하다면 {@link isStreamReady} 를, 다운그레이드 여부를 알고 싶다면
+   * {@link isDegraded} 를 쓴다.
    */
   isConnected() {
+    return this.state === "connected" && this.activeTransport === "ws";
+  }
+  /**
+   * SSE fallback 으로 다운그레이드된 상태인지 여부.
+   *
+   * true 면 연결은 살아 있지만 단방향이라 `realtime.stream()` 만 동작한다. 사용자에게
+   * "제한된 네트워크라 일부 기능을 쓸 수 없다" 고 안내할 지점이다.
+   */
+  isDegraded() {
+    return this.sseFallbackActive;
+  }
+  /**
+   * AI 스트리밍(`realtime.stream()`) 사용 가능 여부.
+   *
+   * WS 든 SSE fallback 이든 연결만 서 있으면 true 다. 종전 `isConnected()` 와 같은
+   * 판정이므로, 스트리밍 게이팅에 `isConnected()` 를 쓰던 코드는 이쪽으로 옮긴다.
+   */
+  isStreamReady() {
     return this.state === "connected";
   }
   /**
@@ -11069,7 +11095,7 @@ var VideoAPI = class {
 };
 
 // src/api/webrtc.ts
-var WebRTCAPI = class {
+var WebRTCAPI = class _WebRTCAPI {
   constructor(http, webrtcUrl, appId) {
     this.ws = null;
     this.state = "disconnected";
@@ -11081,6 +11107,16 @@ var WebRTCAPI = class {
     this.reconnectAttempts = 0;
     this.maxReconnectAttempts = 5;
     this.reconnectTimeout = null;
+    /**
+     * 시그널링 소켓의 세대(generation) 토큰.
+     *
+     * 소켓을 열 때마다 1 증가하며, 각 핸들러는 자기가 열릴 때의 세대를 클로저에 담아둔다.
+     * 세대가 밀린 핸들러는 "옛 소켓의 지연 이벤트" 이므로 인스턴스 상태를 건드리지 않는다.
+     * 참조(`this.ws`)만 끊는 것으로는 부족하다 — 핸들러 클로저가 인스턴스를 캡처하고 있어
+     * close 이벤트가 뒤늦게 도착하면 새 연결을 'disconnected' 로 덮어쓰고 새로 만든 피어
+     * 연결까지 정리해버린다.
+     */
+    this.wsGeneration = 0;
     // 현재 연결 정보
     this.currentRoomId = null;
     this.currentPeerId = null;
@@ -11153,15 +11189,23 @@ var WebRTCAPI = class {
   connectWebSocket() {
     return new Promise((resolve, reject) => {
       const wsUrl = this.buildWebSocketUrl();
-      this.ws = new WebSocket(wsUrl);
+      const generation = ++this.wsGeneration;
+      const ws = new WebSocket(wsUrl);
+      this.ws = ws;
+      const isStale = () => this.wsGeneration !== generation;
       const timeout = setTimeout(() => {
+        if (isStale()) return;
         if (this.state === "connecting") {
-          this.ws?.close();
+          ws.close();
           reject(new Error("\uC5F0\uACB0 \uC2DC\uAC04 \uCD08\uACFC"));
         }
       }, 1e4);
-      this.ws.onopen = () => {
+      ws.onopen = () => {
         clearTimeout(timeout);
+        if (isStale()) {
+          ws.close(1e3, "superseded");
+          return;
+        }
         this.reconnectAttempts = 0;
         this.sendSignaling({
           type: "join",
@@ -11172,7 +11216,8 @@ var WebRTCAPI = class {
           }
         });
       };
-      this.ws.onmessage = async (event) => {
+      ws.onmessage = async (event) => {
+        if (isStale()) return;
         try {
           const msg = JSON.parse(event.data);
           await this.handleSignalingMessage(msg, resolve, reject);
@@ -11180,13 +11225,15 @@ var WebRTCAPI = class {
           console.error("Failed to parse signaling message:", error);
         }
       };
-      this.ws.onerror = (event) => {
+      ws.onerror = (event) => {
         clearTimeout(timeout);
+        if (isStale()) return;
         console.error("WebSocket error:", event);
         this.emitError(new Error("WebSocket \uC5F0\uACB0 \uC624\uB958"));
       };
-      this.ws.onclose = (event) => {
+      ws.onclose = (event) => {
         clearTimeout(timeout);
+        if (isStale()) return;
         if (this.state === "connecting") {
           reject(new Error("\uC5F0\uACB0\uC774 \uC885\uB8CC\uB418\uC5C8\uC2B5\uB2C8\uB2E4"));
         }
@@ -11194,6 +11241,19 @@ var WebRTCAPI = class {
       };
     });
   }
+  /**
+   * 소켓에 붙은 핸들러를 전부 떼어낸다.
+   *
+   * `this.ws = null` 로 참조만 끊으면 클로저가 살아남아 close 이벤트가 계속 들어온다.
+   * 세대 토큰이 그 이벤트를 무시해주긴 하지만, 핸들러 자체를 떼면 인스턴스 참조가 끊겨
+   * 소켓이 GC 될 때까지 인스턴스를 붙잡고 있지 않는다.
+   */
+  static detachSocket(ws) {
+    ws.onopen = null;
+    ws.onmessage = null;
+    ws.onerror = null;
+    ws.onclose = null;
+  }
   buildWebSocketUrl() {
     const wsBase = this.webrtcUrl.replace("https://", "wss://").replace("http://", "ws://");
     const publicKey = this.http.getPublicKey();
@@ -11404,19 +11464,76 @@ var WebRTCAPI = class {
       clearTimeout(this.reconnectTimeout);
       this.reconnectTimeout = null;
     }
-    if (this.ws && this.ws.readyState === WebSocket.OPEN) {
-      this.sendSignaling({ type: "leave" });
-      this.ws.close(1e3, "User disconnected");
+    this.reconnectAttempts = 0;
+    this.wsGeneration++;
+    const ws = this.ws;
+    this.ws = null;
+    if (ws) {
+      _WebRTCAPI.detachSocket(ws);
+      if (ws.readyState === WebSocket.OPEN) {
+        try {
+          ws.send(JSON.stringify({ type: "leave" }));
+        } catch {
+        }
+        ws.close(1e3, "User disconnected");
+      } else if (ws.readyState === WebSocket.CONNECTING) {
+        ws.close();
+      }
     }
     this.peerConnections.forEach((pc) => pc.close());
     this.peerConnections.clear();
     this.remoteStreams.clear();
-    this.ws = null;
     this.currentRoomId = null;
     this.currentPeerId = null;
     this.localStream = null;
     this.setState("disconnected");
   }
+  /**
+   * 현재 세션의 룸을 교체한다.
+   *
+   * `disconnect()` 후 곧바로 `connect()` 하는 패턴을 안전하게 감싼 것이다. 옛 소켓의
+   * close 이벤트가 새 연결의 'connecting' 구간에 떨어져도 세대 토큰이 걸러낸다.
+   * 생략한 옵션은 현재 세션 값을 그대로 이어받는다.
+   *
+   * @example
+   * ```typescript
+   * await cb.webrtc.switchRoom('channel:room-b')
+   * ```
+   */
+  async switchRoom(roomId, options = {}) {
+    const localStream = options.localStream ?? this.localStream ?? void 0;
+    const userId = options.userId ?? this.currentUserId ?? void 0;
+    const isBroadcaster = options.isBroadcaster ?? this.isBroadcaster;
+    this.disconnect();
+    await this.connect({ roomId, userId, isBroadcaster, localStream });
+  }
+  /**
+   * 소켓, 룸, 이벤트 리스너, 피어 연결을 **독립적으로** 갖는 새 WebRTC 세션을 만든다.
+   *
+   * `cb.webrtc` 는 인스턴스 하나에 소켓 하나/룸 하나라, 한 앱에 WebRTC 기능이 둘 이상이면
+   * (예: 공간 음성채팅 + 1:1 통화) 서로 연결을 뺏고 이벤트가 교차한다. 기능마다 세션을
+   * 하나씩 만들면 각자의 소켓과 핸들러를 갖는다.
+   *
+   * 인증 정보(HttpClient)와 서버 주소, appId 는 부모와 공유한다.
+   *
+   * @example
+   * ```typescript
+   * const voice = cb.webrtc.createSession()
+   * const call = cb.webrtc.createSession()
+   *
+   * voice.onRemoteStream((peerId, stream) => attachToSpatialAudio(peerId, stream))
+   * call.onRemoteStream((peerId, stream) => showCallScreen(stream))
+   *
+   * await voice.connect({ roomId: 'voice:lobby', localStream: mic })
+   * await call.connect({ roomId: 'call:alice-bob', localStream: mic })
+   *
+   * // 각 세션은 독립적으로 끊는다
+   * call.disconnect()
+   * ```
+   */
+  createSession() {
+    return new _WebRTCAPI(this.http, this.webrtcUrl, this.appId);
+  }
   /**
    * 현재 연결 상태 조회
    */

package/dist/index.mjs

@@ -7887,9 +7887,35 @@ var RealtimeAPI = class {
     return this.state;
   }
   /**
-   * 연결 여부 확인
+   * pub/sub 사용 가능 여부.
+   *
+   * WebSocket 으로 연결됐을 때만 true 다. SSE fallback 모드에서는 `subscribe` /
+   * `sendMessage` / `setPresence` / typing 이 전부 예외를 던지므로, 여기서 true 를
+   * 반환하면 앱이 "연결됨"으로 오판하고 아무것도 오가지 않는 채 조용히 멈춘다
+   * (platform-issue 01a01e6a-3cb1).
+   *
+   * AI 스트리밍만 필요하다면 {@link isStreamReady} 를, 다운그레이드 여부를 알고 싶다면
+   * {@link isDegraded} 를 쓴다.
    */
   isConnected() {
+    return this.state === "connected" && this.activeTransport === "ws";
+  }
+  /**
+   * SSE fallback 으로 다운그레이드된 상태인지 여부.
+   *
+   * true 면 연결은 살아 있지만 단방향이라 `realtime.stream()` 만 동작한다. 사용자에게
+   * "제한된 네트워크라 일부 기능을 쓸 수 없다" 고 안내할 지점이다.
+   */
+  isDegraded() {
+    return this.sseFallbackActive;
+  }
+  /**
+   * AI 스트리밍(`realtime.stream()`) 사용 가능 여부.
+   *
+   * WS 든 SSE fallback 이든 연결만 서 있으면 true 다. 종전 `isConnected()` 와 같은
+   * 판정이므로, 스트리밍 게이팅에 `isConnected()` 를 쓰던 코드는 이쪽으로 옮긴다.
+   */
+  isStreamReady() {
     return this.state === "connected";
   }
   /**
@@ -11020,7 +11046,7 @@ var VideoAPI = class {
 };
 
 // src/api/webrtc.ts
-var WebRTCAPI = class {
+var WebRTCAPI = class _WebRTCAPI {
   constructor(http, webrtcUrl, appId) {
     this.ws = null;
     this.state = "disconnected";
@@ -11032,6 +11058,16 @@ var WebRTCAPI = class {
     this.reconnectAttempts = 0;
     this.maxReconnectAttempts = 5;
     this.reconnectTimeout = null;
+    /**
+     * 시그널링 소켓의 세대(generation) 토큰.
+     *
+     * 소켓을 열 때마다 1 증가하며, 각 핸들러는 자기가 열릴 때의 세대를 클로저에 담아둔다.
+     * 세대가 밀린 핸들러는 "옛 소켓의 지연 이벤트" 이므로 인스턴스 상태를 건드리지 않는다.
+     * 참조(`this.ws`)만 끊는 것으로는 부족하다 — 핸들러 클로저가 인스턴스를 캡처하고 있어
+     * close 이벤트가 뒤늦게 도착하면 새 연결을 'disconnected' 로 덮어쓰고 새로 만든 피어
+     * 연결까지 정리해버린다.
+     */
+    this.wsGeneration = 0;
     // 현재 연결 정보
     this.currentRoomId = null;
     this.currentPeerId = null;
@@ -11104,15 +11140,23 @@ var WebRTCAPI = class {
   connectWebSocket() {
     return new Promise((resolve, reject) => {
       const wsUrl = this.buildWebSocketUrl();
-      this.ws = new WebSocket(wsUrl);
+      const generation = ++this.wsGeneration;
+      const ws = new WebSocket(wsUrl);
+      this.ws = ws;
+      const isStale = () => this.wsGeneration !== generation;
       const timeout = setTimeout(() => {
+        if (isStale()) return;
         if (this.state === "connecting") {
-          this.ws?.close();
+          ws.close();
           reject(new Error("\uC5F0\uACB0 \uC2DC\uAC04 \uCD08\uACFC"));
         }
       }, 1e4);
-      this.ws.onopen = () => {
+      ws.onopen = () => {
         clearTimeout(timeout);
+        if (isStale()) {
+          ws.close(1e3, "superseded");
+          return;
+        }
         this.reconnectAttempts = 0;
         this.sendSignaling({
           type: "join",
@@ -11123,7 +11167,8 @@ var WebRTCAPI = class {
           }
         });
       };
-      this.ws.onmessage = async (event) => {
+      ws.onmessage = async (event) => {
+        if (isStale()) return;
         try {
           const msg = JSON.parse(event.data);
           await this.handleSignalingMessage(msg, resolve, reject);
@@ -11131,13 +11176,15 @@ var WebRTCAPI = class {
           console.error("Failed to parse signaling message:", error);
         }
       };
-      this.ws.onerror = (event) => {
+      ws.onerror = (event) => {
         clearTimeout(timeout);
+        if (isStale()) return;
         console.error("WebSocket error:", event);
         this.emitError(new Error("WebSocket \uC5F0\uACB0 \uC624\uB958"));
       };
-      this.ws.onclose = (event) => {
+      ws.onclose = (event) => {
         clearTimeout(timeout);
+        if (isStale()) return;
         if (this.state === "connecting") {
           reject(new Error("\uC5F0\uACB0\uC774 \uC885\uB8CC\uB418\uC5C8\uC2B5\uB2C8\uB2E4"));
         }
@@ -11145,6 +11192,19 @@ var WebRTCAPI = class {
       };
     });
   }
+  /**
+   * 소켓에 붙은 핸들러를 전부 떼어낸다.
+   *
+   * `this.ws = null` 로 참조만 끊으면 클로저가 살아남아 close 이벤트가 계속 들어온다.
+   * 세대 토큰이 그 이벤트를 무시해주긴 하지만, 핸들러 자체를 떼면 인스턴스 참조가 끊겨
+   * 소켓이 GC 될 때까지 인스턴스를 붙잡고 있지 않는다.
+   */
+  static detachSocket(ws) {
+    ws.onopen = null;
+    ws.onmessage = null;
+    ws.onerror = null;
+    ws.onclose = null;
+  }
   buildWebSocketUrl() {
     const wsBase = this.webrtcUrl.replace("https://", "wss://").replace("http://", "ws://");
     const publicKey = this.http.getPublicKey();
@@ -11355,19 +11415,76 @@ var WebRTCAPI = class {
       clearTimeout(this.reconnectTimeout);
       this.reconnectTimeout = null;
     }
-    if (this.ws && this.ws.readyState === WebSocket.OPEN) {
-      this.sendSignaling({ type: "leave" });
-      this.ws.close(1e3, "User disconnected");
+    this.reconnectAttempts = 0;
+    this.wsGeneration++;
+    const ws = this.ws;
+    this.ws = null;
+    if (ws) {
+      _WebRTCAPI.detachSocket(ws);
+      if (ws.readyState === WebSocket.OPEN) {
+        try {
+          ws.send(JSON.stringify({ type: "leave" }));
+        } catch {
+        }
+        ws.close(1e3, "User disconnected");
+      } else if (ws.readyState === WebSocket.CONNECTING) {
+        ws.close();
+      }
     }
     this.peerConnections.forEach((pc) => pc.close());
     this.peerConnections.clear();
     this.remoteStreams.clear();
-    this.ws = null;
     this.currentRoomId = null;
     this.currentPeerId = null;
     this.localStream = null;
     this.setState("disconnected");
   }
+  /**
+   * 현재 세션의 룸을 교체한다.
+   *
+   * `disconnect()` 후 곧바로 `connect()` 하는 패턴을 안전하게 감싼 것이다. 옛 소켓의
+   * close 이벤트가 새 연결의 'connecting' 구간에 떨어져도 세대 토큰이 걸러낸다.
+   * 생략한 옵션은 현재 세션 값을 그대로 이어받는다.
+   *
+   * @example
+   * ```typescript
+   * await cb.webrtc.switchRoom('channel:room-b')
+   * ```
+   */
+  async switchRoom(roomId, options = {}) {
+    const localStream = options.localStream ?? this.localStream ?? void 0;
+    const userId = options.userId ?? this.currentUserId ?? void 0;
+    const isBroadcaster = options.isBroadcaster ?? this.isBroadcaster;
+    this.disconnect();
+    await this.connect({ roomId, userId, isBroadcaster, localStream });
+  }
+  /**
+   * 소켓, 룸, 이벤트 리스너, 피어 연결을 **독립적으로** 갖는 새 WebRTC 세션을 만든다.
+   *
+   * `cb.webrtc` 는 인스턴스 하나에 소켓 하나/룸 하나라, 한 앱에 WebRTC 기능이 둘 이상이면
+   * (예: 공간 음성채팅 + 1:1 통화) 서로 연결을 뺏고 이벤트가 교차한다. 기능마다 세션을
+   * 하나씩 만들면 각자의 소켓과 핸들러를 갖는다.
+   *
+   * 인증 정보(HttpClient)와 서버 주소, appId 는 부모와 공유한다.
+   *
+   * @example
+   * ```typescript
+   * const voice = cb.webrtc.createSession()
+   * const call = cb.webrtc.createSession()
+   *
+   * voice.onRemoteStream((peerId, stream) => attachToSpatialAudio(peerId, stream))
+   * call.onRemoteStream((peerId, stream) => showCallScreen(stream))
+   *
+   * await voice.connect({ roomId: 'voice:lobby', localStream: mic })
+   * await call.connect({ roomId: 'call:alice-bob', localStream: mic })
+   *
+   * // 각 세션은 독립적으로 끊는다
+   * call.disconnect()
+   * ```
+   */
+  createSession() {
+    return new _WebRTCAPI(this.http, this.webrtcUrl, this.appId);
+  }
   /**
    * 현재 연결 상태 조회
    */