@vibexnpm/talkx 8.12.0 → 9.1.0

package/src/webrtc/WebRTCClient.js

@@ -1,22 +1,37 @@
 /**
  * WebRTCClient
- * WebRTC 통화 기능 클라이언트
+ * 화상통화 클라이언트 — 통화 제어는 서버 REST, 미디어는 LiveKit(SFU), 서버 → 클라이언트 알림은 STOMP(화상통화 SFU 설계 v0.7
+ * §5.3·§8). 클라이언트는 통화 신호를 보내지 않는다(I7).
+ *
+ * <p>한 번에 한 통화만 미디어에 붙는다(방을 만드는 중부터 그 통화로 잡는다). 울리는 통화는 여러 개일 수 있다(통화 중 초대 — 앱이
+ * BUSY 로 거절할 수 있다).</p>
+ *
+ * 내보내는 이벤트(TalkFlowClient 에도 같은 이름으로 나간다):
+ * <ul>
+ *   <li>{@code incomingCall} — {@code {callRoomId, kind, callerId, callerName, callerProfileUrl, title}}</li>
+ *   <li>{@code ringStopped} — {@code {callRoomId, reason}}: accepted·rejected·answered_elsewhere·timeout·stale 또는 서버 사유</li>
+ *   <li>{@code callStateChanged} — {@code {callRoomId, state, reason?}} ({@link CallState}). 받지 않고 끝난 울림도 ended 로 끝난다.</li>
+ *   <li>{@code callEnded} — {@code {callRoomId, reason}} (state ended 와 같은 때)</li>
+ *   <li>{@code callRejected} — {@code {callRoomId, userId, reason}} (방장: 초대 대상의 거절·무응답)</li>
+ *   <li>{@code participantJoined} / {@code participantLeft} — {@code {callRoomId, userId}}</li>
+ *   <li>{@code trackSubscribed} / {@code trackUnsubscribed} — {@code {callRoomId, userId, source, track}}</li>
+ *   <li>{@code localTrackPublished} / {@code localTrackUnpublished} — {@code {callRoomId, source, track}}</li>
+ *   <li>{@code participantMediaChanged} — {@code {callRoomId, userId, camera, microphone, screen}} (내 것이면 userId 는 null)</li>
+ *   <li>{@code callRecoveryFailed} — {@code {callRoomId, reason}} (미디어 연결이 끊긴 채 돌아오지 못했다 — 이 기기에서 끝난다)</li>
+ *   <li>{@code callError} — {@code {callRoomId, code, message, error}}</li>
+ * </ul>
  */
 
 import EventEmitter from '../utils/EventEmitter.js';
 import Logger from '../utils/Logger.js';
-import MediaStreamManager from './MediaStreamManager.js';
-import PeerConnectionManager from './PeerConnectionManager.js';
-import { WebSocketPaths, SignalTypes, ErrorTypes, DefaultConfig, LogLevel } from '../constants.js';
+import CallLedger from './CallLedger.js';
+import LiveKitMediaSession from './LiveKitMediaSession.js';
+import { WebSocketPaths, CallEventTypes, CallKind, CallState, ErrorTypes, DefaultConfig, LogLevel } from '../constants.js';
 
-/** 1:1 통화 제어 신호. 받는 쪽은 roomId 가 없어야 1:1 신호로 받는다(_acceptsSignal). */
-const DIRECT_CONTROL_SIGNALS = new Set([
-    SignalTypes.CALL_REQUEST, SignalTypes.CALL_ACCEPT, SignalTypes.CALL_REJECT,
-    SignalTypes.CALL_CANCEL, SignalTypes.CALL_BUSY
-]);
-
-/** 받은 초대·내가 연 방은 응답 전까지만 의미가 있다. 오래된 것부터 잊는다. */
-const MAX_REMEMBERED_CALL_ROOMS = 32;
+const ROOMS = '/api/v1/webrtc/rooms';
+/** 서버가 이미 16번 시도한 뒤의 409 — 같은 요청을 이만큼 더 보낸다(§5.3). */
+const CONFLICT_ATTEMPTS = 3;
+const CONFLICT_CODE = 'CALL_CONCURRENT_UPDATE';
 
 class WebRTCClient extends EventEmitter {
     /**
@@ -24,8 +39,9 @@ class WebRTCClient extends EventEmitter {
      * @param {Object} options.connectionManager - ConnectionManager 인스턴스
      * @param {Object} options.apiClient - ApiClient 인스턴스
      * @param {string} options.userId - 사용자 ID
-     * @param {Object[]} [options.iceServers] - ICE 서버 설정
+     * @param {number} [options.ringTimeoutMs] - 받는 쪽 울림을 스스로 끄는 시각
      * @param {number} [options.logLevel] - 로그 레벨
+     * @param {() => LiveKitMediaSession} [options.createMediaSession] - 미디어 세션 생성(시험은 가짜를 넣는다)
      */
     constructor(options) {
         super();
@@ -33,1268 +49,1093 @@ class WebRTCClient extends EventEmitter {
         this.connectionManager = options.connectionManager;
         this.apiClient = options.apiClient;
         this.userId = options.userId;
-        this.logLevel = options.logLevel || LogLevel.WARN;
-
+        this.logLevel = options.logLevel ?? LogLevel.WARN;
         this.logger = new Logger(this.logLevel, 'WebRTCClient');
-
-        // 미디어 및 피어 연결 매니저
-        this.mediaManager = new MediaStreamManager({ logLevel: this.logLevel });
-        this.peerManager = new PeerConnectionManager({
-            iceServers: options.iceServers || DefaultConfig.iceServers,
-            logLevel: this.logLevel
-        });
-
-        // 현재 통화 상태
-        this.currentRoom = null;
-        this.isGroupCall = false;
-        this.participants = new Map();
-        this._callActive = false;
-        this._callGeneration = 0;
-        this._deferredGroupPeers = new Map();
-        this._joinedGroupRoom = null;
-        this._groupJoin = null;
-        this._directCallPeer = null;
-        this._incomingCallPeer = null;
-        // 서버(REST)가 roomId 를 붙여 보내는 그룹 초대 취소·거절을 받을 방. callRoomId -> host / 나
-        this._receivedInvitations = new Map();
-        this._hostedCallRooms = new Map();
-        // 서버는 생성 응답 전에 초대를 보낸다(CreateCallRoomService). 응답보다 먼저 온 거절은 응답을 받을 때까지 보관한다.
-        this._pendingRoomCreations = 0;
-        this._earlyRoomRejects = [];
-        this._groupRecoveryTimer = null;
-        this._groupRecoveryAttempts = 0;
-        this._onReconnected = () => {
-            this._recoverGroupParticipation().catch(error => this.logger.error('Call recovery failed:', error));
+        this.ringTimeoutMs = options.ringTimeoutMs ?? DefaultConfig.callRingTimeoutMs;
+        this._createMediaSession = options.createMediaSession ?? (() => new LiveKitMediaSession({ logLevel: this.logLevel }));
+
+        this._ledger = new CallLedger();
+        /** @type {Map<string, {callRoomId: string, kind: string, callerId: string|null, title: string|null, timer: *}>} */
+        this._ringing = new Map();
+        /** 미디어에 붙은(붙는 중·방을 만드는 중인) 통화 하나. */
+        this._call = null;
+        this._incomingCallsEnabled = false;
+        /** 알림 구독을 켜고 끈 횟수 — 대기 줄에 섰던 구독이 붙었을 때 그 사이 끄라고 했는지 본다. */
+        this._incomingGeneration = 0;
+        /** destroy 뒤 — 새 통화도, 늦게 끝나는 요청(만드는 중·입장 중이던 통화의 정리·재시도)도 보내지 않는다. */
+        this._closed = false;
+        /**
+         * 지금 로그인 신원의 번호 — 신원이 끝날 때마다(_resetIdentity) 올린다. 서버 요청은 그 요청을 시작한 신원이 지금 신원일 때만
+         * 나간다(재시도마다 다시 본다) — 로그아웃·사용자 전환 뒤에 옛 신원의 요청이 새 자격으로 나가지 않게.
+         */
+        this._identity = 0;
+        /**
+         * 방마다 진행 중인 나가기·취소·거절·정리 요청(끝나면 지운다). 그 방의 새 입장은 이 요청들의 응답 뒤에 보낸다 — 서버 참가는 사용자마다
+         * 하나라, 늦게 처리된 나가기가 새 참가를 닫는다(보낸 순서와 서버 처리 순서는 다를 수 있다). 요청마다 시간 상한(apiTimeout)이 있다.
+         * @type {Map<string, Promise<void>>}
+         */
+        this._exits = new Map();
+
+        // STOMP 가 끊겼거나 탭이 쉬는 사이 울림이 멈췄을 수 있다 — 돌아오면 울리던 통화를 서버에 다시 묻는다(§5.3 울림 상한).
+        // ConnectionManager 계약: resumed(연결이 살아 있었음)와 reconnected(다시 붙음)는 서로 배타적이라 둘 다 들어야 한다.
+        this._onConnectionRestored = () => {
+            this._recheckRinging().catch(error => this.logger.warn('Ring re-check failed:', error));
         };
-        this.connectionManager.on?.('reconnected', this._onReconnected);
-
-        // ICE 서버 초기화 상태
-        this._iceServersFetched = false;
-
-        // 1:1 통화 대기 상태 (CALL_REQUEST 전송 후 CALL_ACCEPT 대기)
-        this._waitingForCallAccept = false;
-        this._pendingCallTarget = null;
-
-        // ICE candidate 큐 (peer connection 생성 전에 도착한 candidate 저장)
-        this._pendingIceCandidates = new Map();
-
-        // 이벤트 연결
-        this._setupEventHandlers();
+        this.connectionManager.on?.('reconnected', this._onConnectionRestored);
+        this.connectionManager.on?.('resumed', this._onConnectionRestored);
     }
 
+    // ==================== 수신 대기 ====================
+
     /**
-     * ICE 서버 설정 초기화 (TURN credentials 가져오기)
-     * 통화 시작 전 호출하면 더 빠른 연결 가능
+     * 통화 알림 수신 — 개인 큐({@code /user/queue/webrtc})를 구독한다. connect() 가 부른다.
      * @returns {Promise<void>}
      */
-    async initializeIceServers() {
-        if (this._iceServersFetched) {
+    async enableIncomingCalls() {
+        if (this._incomingCallsEnabled) {
             return;
         }
-
+        // 구독을 기다리기 전에 켠 것으로 표시한다 — 그 사이 다시 불러도 구독을 두 번 걸지 않게. STOMP 가 끊겨 구독이 대기 줄에 선 사이 끄라고
+        // 했으면(disable·destroy) 붙은 뒤 이 구독을 푼다 — ConnectionManager.unsubscribe 는 붙은 구독만 풀고 대기 줄에는 닿지 않는다.
+        this._incomingCallsEnabled = true;
+        const generation = ++this._incomingGeneration;
+        const destination = WebSocketPaths.getWebRTCUserDestination();
+        let subscription;
         try {
-            const data = await this.getTurnCredentials();
-            if (data && data.iceServers) {
-                this.peerManager.setIceServers(data.iceServers);
-                this._iceServersFetched = true;
-                this.logger.info('ICE servers fetched successfully');
-            }
+            subscription = await this.connectionManager.subscribe(destination, (message) => this._handleEvent(message));
         } catch (error) {
-            this.logger.warn('Failed to fetch TURN credentials, using fallback ICE servers:', error.message);
-            this._setFallbackIceServers();
+            if (generation === this._incomingGeneration) {
+                this._incomingCallsEnabled = false;
+            }
+            throw error;
+        }
+        if (generation !== this._incomingGeneration) {
+            // 기다리는 사이 껐다(다시 켰을 수도 있다) — 이 구독만 푼다. 대기 줄에 같은 목적지 구독이 여럿 섰다가 함께 붙으면 맵에는 마지막
+            // 것만 있어 목적지로 풀면 남의 구독을 풀고 이 구독은 남는다.
+            this.connectionManager.unsubscribe(destination, subscription);
         }
     }
 
-    /**
-     * 기본 ICE 서버 설정 (Fallback)
-     * @private
-     */
-    _setFallbackIceServers() {
-        this.peerManager.setIceServers([
-            { urls: 'stun:stun.l.google.com:19302' },
-            { urls: 'stun:stun1.l.google.com:19302' }
-        ]);
+    /** 통화 알림 수신을 끈다. */
+    disableIncomingCalls() {
+        if (!this._incomingCallsEnabled) {
+            return;
+        }
+        this._incomingGeneration += 1;
+        this.connectionManager.unsubscribe(WebSocketPaths.getWebRTCUserDestination());
+        this._incomingCallsEnabled = false;
     }
 
-    /**
-     * 이벤트 핸들러 설정
-     * @private
-     */
-    _setupEventHandlers() {
-        // 미디어 이벤트
-        this.mediaManager.on('streamStarted', (data) => this.emit('localStreamStarted', data));
-        this.mediaManager.on('streamStopped', (data) => this.emit('localStreamStopped', data));
-        this.mediaManager.on('videoToggled', () => this._sendMediaState());
-        this.mediaManager.on('audioToggled', () => this._sendMediaState());
-        this.mediaManager.on('screenShareStarted', (data) => this.emit('screenShareStarted', data));
-        this.mediaManager.on('screenShareEnded', (data) => this.emit('screenShareEnded', data));
-        this.mediaManager.on('error', (error) => this.emit('error', error));
-
-        // 피어 연결 이벤트
-        this.peerManager.on('remoteTrack', (data) => this.emit('remoteTrack', data));
-        this.peerManager.on('peerConnected', (data) => this.emit('peerConnected', data));
-        this.peerManager.on('peerDisconnected', (data) => this.emit('peerDisconnected', data));
-        this.peerManager.on('peerClosed', (data) => this.emit('peerClosed', data));
-        this.peerManager.on('error', (error) => this.emit('error', error));
-
-        // ICE Candidate 전송
-        this.peerManager.on('iceCandidate', ({ peerId, candidate }) => {
-            this._sendSignal({
-                type: SignalTypes.ICE_CANDIDATE,
-                receiverId: peerId,
-                data: { candidate }
-            });
-        });
-
-        // Negotiation (Offer 전송)
-        this.peerManager.on('negotiationNeeded', ({ peerId, description }) => {
-            this._sendSignal({
-                type: SignalTypes.CALL_OFFER,
-                receiverId: peerId,
-                data: { sdp: description }
-            });
-        });
-
-        // Answer 전송
-        this.peerManager.on('answerCreated', ({ peerId, answer }) => {
-            this._sendSignal({
-                type: SignalTypes.CALL_ANSWER,
-                receiverId: peerId,
-                data: { sdp: answer }
-            });
-        });
+    /** @returns {boolean} */
+    isIncomingCallsEnabled() {
+        return this._incomingCallsEnabled;
     }
 
-    // ==================== REST API ====================
+    // ==================== 통화 시작·응답 ====================
 
     /**
-     * TURN 서버 인증 정보 가져오기
-     * @returns {Promise<Object>}
+     * 1:1 통화를 건다 — 방을 만들고 입장해 미디어에 붙은 채 상대를 기다린다.
+     * @param {string} targetUserId
+     * @param {{video?: boolean, audio?: boolean}} [media]
+     * @returns {Promise<string>} callRoomId
      */
-    async getTurnCredentials() {
-        const response = await this.apiClient.get('/api/v1/webrtc/turn-credentials');
-        return response.data;
+    async callUser(targetUserId, media = {}) {
+        const call = this._beginCall({ kind: CallKind.DIRECT, media, host: true });
+        return this._startHosted(call, { kind: CallKind.DIRECT, invitedUsers: [targetUserId] });
     }
 
     /**
-     * 통화방 생성
-     * @public
-     * @param {Object} data
-     * @param {string[]} [data.invitedUsers] - 초대할 사용자 ID
-     * @param {string} [data.title] - 통화방 제목
-     * @param {number} [data.maxParticipants] - 최대 참가자 수 (생략 시 서버 기본값)
-     * @returns {Promise<Object>}
+     * 그룹 통화를 연다 — 방을 만들고 입장해 미디어에 붙는다.
+     * @param {{invitedUsers: string[], title?: string, maxParticipants?: number, video?: boolean, audio?: boolean}} options
+     * @returns {Promise<string>} callRoomId
      */
-    // noinspection JSUnusedGlobalSymbols
-    async createCallRoom(data) {
-        this._pendingRoomCreations++;
-        try {
-            const response = await this.apiClient.post('/api/v1/webrtc/rooms', data);
-            const callRoomId = response?.data?.callRoomId;
-            if (callRoomId) this._rememberCallRoom(this._hostedCallRooms, callRoomId, this.userId);
-            return response;
-        } finally {
-            this._pendingRoomCreations--;
-            // 보관한 거절을 같은 경로로 다시 판정한다. 연 방의 것은 전달되고, 진행 중인 생성이 남았으면 다시 보관되며, 아니면 버려진다.
-            for (const message of this._earlyRoomRejects.splice(0)) {
-                this._handleSignal(message).catch(error => this.logger.error('Early rejection handling failed:', error));
-            }
-        }
+    async createGroupCall({ invitedUsers, title, maxParticipants, video, audio } = {}) {
+        const call = this._beginCall({ kind: CallKind.GROUP, media: { video, audio }, host: true });
+        return this._startHosted(call, { kind: CallKind.GROUP, invitedUsers, title, maxParticipants });
     }
 
     /**
-     * 통화방 정보 조회
-     * @public
-     * @param {string} roomId - 통화방 ID
-     * @returns {Promise<Object>}
+     * 울리는 통화를 받는다. 이 기기의 울림을 끄고 입장한다 — 다른 기기는 서버 «응답함» 으로 울림을 끈다.
+     * @param {string} callRoomId
+     * @param {{video?: boolean, audio?: boolean}} [media]
+     * @returns {Promise<string>}
      */
-    // noinspection JSUnusedGlobalSymbols
-    async getCallRoom(roomId) {
-        return this.apiClient.get(`/api/v1/webrtc/rooms/${roomId}`);
+    async acceptCall(callRoomId, media = {}) {
+        requireCallRoomId(callRoomId);
+        const ring = this._ringing.get(callRoomId);
+        const call = this._beginCall({ kind: ring?.kind ?? null, media, host: false, callRoomId });
+        call.fromRing = Boolean(ring);
+        // 울림 → 통화를 한 번에 바꾼다 — 아래 양보 사이에 나가기·신원 끝남이 끼어도 울림이 남거나 끝남이 두 번 나가지 않게.
+        this._stopRinging(callRoomId, 'accepted', true);
+        // 끝남 알림 안에서 불렸으면(앱이 callEnded 에서 같은 통화에 바로 다시 들어감) 그 알림 쌍이 다 나간 뒤 시작한다 — 새 통화의 상태
+        // 알림이 옛 통화의 끝남보다 먼저 가지 않게. 끝남 알림은 동기로 나가므로 한 번 양보하면 된다.
+        await Promise.resolve();
+        if (this._call !== call) {
+            // 그 사이 끝났다(나가기·신원 끝남) — 결과는 callEnded 로 이미 알렸다.
+            return callRoomId;
+        }
+        return this._enter(call);
     }
 
     /**
-     * 통화방 참여
-     * @public
-     * @param {string} roomId - 통화방 ID
-     * @returns {Promise<Object>}
+     * 그룹 통화에 들어가거나 다시 들어간다(초대 수락·재참가·이 기기에서 끊긴 뒤 복귀).
+     * @param {string} callRoomId
+     * @param {{video?: boolean, audio?: boolean}} [media]
+     * @returns {Promise<string>}
      */
-    // noinspection JSUnusedGlobalSymbols
-    async joinCallRoomApi(roomId) {
-        // REST 응답보다 PEER_JOINED에 대한 offer가 먼저 도착할 수 있다.
-        // 로컬에서 요청한 방만 허용하고, 실패·종료 뒤에는 이 권한을 남기지 않는다.
-        const join = { roomId, generation: this._callGeneration };
-        this._groupJoin = join;
-        try {
-            const response = await this.apiClient.post(`/api/v1/webrtc/rooms/${roomId}/join`);
-            if (this._groupJoin === join && this._callGeneration === join.generation) this._joinedGroupRoom = roomId;
-            return response;
-        } catch (error) {
-            if (this._groupJoin === join && this.currentRoom !== roomId) this._clearDeferredGroup(roomId);
-            throw error;
-        } finally {
-            if (this._groupJoin === join) this._groupJoin = null;
-        }
+    async joinCall(callRoomId, media = {}) {
+        return this.acceptCall(callRoomId, media);
     }
 
     /**
-     * 통화방 나가기
-     * @public
-     * @param {string} roomId - 통화방 ID
-     * @returns {Promise<Object>}
+     * 울리는 통화를 거절한다.
+     * @param {string} callRoomId
+     * @param {{reason?: 'DECLINED'|'BUSY'}} [options]
      */
-    // noinspection JSUnusedGlobalSymbols
-    async leaveCallRoomApi(roomId) {
-        const response = await this.apiClient.post(`/api/v1/webrtc/rooms/${roomId}/leave`);
-        if (this._joinedGroupRoom === roomId) this._joinedGroupRoom = null;
-        if (this._groupJoin?.roomId === roomId) this._groupJoin = null;
-        if (this.currentRoom !== roomId) this._clearDeferredGroup(roomId);
-        return response;
+    async rejectCall(callRoomId, { reason = 'DECLINED' } = {}) {
+        requireCallRoomId(callRoomId);
+        this._stopRinging(callRoomId, 'rejected');
+        await this._trackExit(callRoomId,
+            this._send(this._identity, () => this.apiClient.post(`${ROOMS}/${callRoomId}/reject`, undefined, { reason })));
     }
 
-    // ==================== 통화 수신 대기 ====================
+    // ==================== 통화 끝내기 ====================
 
     /**
-     * 통화 수신 대기 활성화
-     * connect() 후 자동 호출되지만, 수동으로도 호출 가능
-     * 개인 WebRTC 채널(/user/queue/webrtc)을 구독하여 초대 알림 수신
-     * @public
-     * @returns {Promise<void>}
+     * 건 통화를 취소한다(방장, 상대가 입장하기 전). 방을 만드는 중이면 만든 뒤 바로 취소한다.
+     * @param {string} [callRoomId] - 생략하면 지금 통화
      */
-    async enableIncomingCalls() {
-        if (this._incomingCallsEnabled) {
-            this.logger.debug('Incoming calls already enabled');
+    async cancelCall(callRoomId) {
+        const call = this._call;
+        if (call && (callRoomId === undefined || callRoomId === call.callRoomId)) {
+            if (!call.callRoomId) {
+                return this._endWhileCreating(call, 'cancelled', (id) => this.apiClient.post(`${ROOMS}/${id}/cancel`));
+            }
+            // 방장이 아니면 서버가 403 으로 거절한다 — 통화는 그대로다. 응답 전에 나가고 같은 통화에 다시 들어가면 새 입장은 이 취소 뒤에 간다.
+            await this._trackExit(call.callRoomId, this._send(call.identity, () => this.apiClient.post(`${ROOMS}/${call.callRoomId}/cancel`)));
+            await this._finish(call, 'cancelled', { callOver: true });
             return;
         }
-
-        await this._subscribeToDirectSignaling();
-        this._incomingCallsEnabled = true;
-        this.logger.info('Incoming calls enabled - now listening for call invitations');
+        if (!callRoomId) {
+            throw callError(ErrorTypes.NO_ACTIVE_CALL, 'No call to cancel');
+        }
+        await this._trackExit(callRoomId, this._send(this._identity, () => this.apiClient.post(`${ROOMS}/${callRoomId}/cancel`)));
     }
 
     /**
-     * 통화 수신 대기 비활성화
-     * @public
+     * 지금 통화에서 나간다 — 이 기기의 미디어를 먼저 끊기 시작하고 같은 틱에 서버에 나가기를 보낸다. 서버 요청이 실패하면 던지지만
+     * 이 기기의 통화는 이미 끝났다(서버는 끊김 유예 뒤 닫는다). 방을 만드는 중이면 만든 뒤 끝내고 취소를 보낸다.
      */
-    disableIncomingCalls() {
-        if (!this._incomingCallsEnabled) {
-            return;
+    async leaveCall() {
+        const call = this._requireCall();
+        if (!call.callRoomId) {
+            return this._endWhileCreating(call, 'left', null);
+        }
+        // 나가기는 끝남 알림보다 먼저(누른 그 틱에) 보내 방별 추적에 올린다 — 알림 안에서 같은 통화에 다시 들어가도 새 입장은 이 나가기
+        // 뒤에 나간다. 끊기(수백 ms)를 기다리지 않으니 그 사이 로그아웃·사용자 전환이 끼어도 누른 순간의 신원으로 나간다.
+        const exit = this._exitRequest(call);
+        const left = exit ? this._trackExit(call.callRoomId, this._send(call.identity, exit)) : null;
+        const finished = this._finish(call, 'left');
+        const failure = (await Promise.allSettled(left ? [finished, left] : [finished])).find(result => result.status === 'rejected');
+        if (failure) {
+            throw failure.reason;
         }
-
-        const directDestination = WebSocketPaths.getWebRTCUserDestination();
-        this.connectionManager.unsubscribe(directDestination);
-        this._incomingCallsEnabled = false;
-        this.logger.info('Incoming calls disabled');
     }
 
     /**
-     * 통화 수신 대기 상태 확인
-     * @public
-     * @returns {boolean}
+     * 나가기에 보낼 서버 요청. 방장이거나 입장을 보냈으면 나가기. 받는 쪽이 입장을 보내기 전에 나가면 서버 참가가 없어 나가기는 아무것도
+     * 하지 않는다 — 울리던 초대를 받은 것이면 거절(DECLINED)로 서버 초대를 정리하고(안 하면 다른 기기가 울림 상한까지 울리고 방장이
+     * 기다린다), 울림 없이 다시 들어가던 중이면 보낼 것이 없다.
+     * @returns {(() => Promise<*>)|null}
      */
-    isIncomingCallsEnabled() {
-        return this._incomingCallsEnabled || false;
+    _exitRequest(call) {
+        if (call.host || call.joinAttempted) {
+            return () => this.apiClient.post(`${ROOMS}/${call.callRoomId}/leave`);
+        }
+        if (call.fromRing) {
+            return () => this.apiClient.post(`${ROOMS}/${call.callRoomId}/reject`, undefined, { reason: 'DECLINED' });
+        }
+        return null;
     }
 
-    // ==================== 통화 기능 ====================
-
-    /**
-     * 통화 시작 (미디어 및 구독)
-     * @param {Object} options
-     * @param {string} options.roomId - 통화방 ID
-     * @param {boolean} [options.isGroup=false] - 그룹 통화 여부
-     * @param {Object} [options.mediaConstraints] - 미디어 제약조건
-     * @returns {Promise<MediaStream>}
-     */
-    async startCall(options) {
-        const { roomId, isGroup = false, mediaConstraints = { video: true, audio: true } } = options;
-        if (this._pendingStart) throw new Error('A call is already starting');
-        // 조기 offer의 peer 존재만으로 막지 않는다. 이미 소유한 통화만 보호한다.
-        if (this.currentRoom !== null || this._callActive || this._waitingForCallAccept) {
-            throw new Error('A call is already active');
-        }
-        this._callGeneration++;
-        this._cancelGroupRecoveryRetry();
-        this._groupRecoveryAttempts = 0;
-        this._groupRecovery = null;
-        const start = { cancelled: false };
-        this._pendingStart = start;
-        const checkCancelled = () => { if (start.cancelled) throw new Error('Call start cancelled'); };
-
-        try {
-            this.currentRoom = roomId;
-            this.isGroupCall = isGroup;
-            for (const deferredRoom of new Set(this._deferredGroupPeers.values())) {
-                if (!isGroup || deferredRoom !== roomId) this._clearDeferredGroup(deferredRoom);
-            }
-            // 그룹 참가 임대를 먼저 연결한다. 권한 팝업/TURN 조회가 90초를 넘어도 갱신된다.
-            await this._subscribeToSignaling(roomId, isGroup);
-            checkCancelled();
-            await this.initializeIceServers();
-            checkCancelled();
-            const localStream = await this.mediaManager.getUserMedia(mediaConstraints);
-            checkCancelled();
-            // 먼저 수신한 offer의 peer에도 트랙을 추가하고 재협상한다.
-            // 권한 대기 중 시그널을 버리면 상대의 기존 peer가 offer를 다시 보내지 않을 수 있다.
-            this.peerManager.setLocalStream(localStream);
-            for (const peerId of this._deferredGroupPeers.keys()) {
-                await this._resumeGroupNegotiation(peerId);
-                checkCancelled();
-            }
-            this._callActive = true;
-
-            // 입장 시그널 전송
-            this._sendSignal({
-                type: SignalTypes.JOIN_ROOM,
-                roomId
-            });
-
-            this.logger.info(`Call started in room: ${roomId}`);
-            this.emit('callStarted', { roomId, isGroup, localStream });
-
-            return localStream;
-
-        } catch (error) {
-            if (isGroup) this.connectionManager.unsubscribe(WebSocketPaths.getWebRTCDestination(roomId));
-            this._unsubscribeFromSignaling();
-            this.mediaManager.stopAll();
-            this.peerManager.closeAllPeerConnections();
-            this.peerManager.setLocalStream(null);
-            this.participants.clear();
-            this._pendingIceCandidates.clear();
-            this._deferredGroupPeers.clear();
-            this._callActive = false;
-            this.currentRoom = null;
-            this.isGroupCall = false;
-            this._joinedGroupRoom = null;
-            this._groupJoin = null;
-            this.logger.error('Failed to start call:', error);
-            this.emit('error', {
-                type: ErrorTypes.PEER_CONNECTION_FAILED,
-                message: error.message,
-                error
-            });
-            throw error;
-        } finally {
-            this._pendingStart = null;
+    /** 모두의 통화를 끝낸다(방장). 방을 만드는 중이면 만든 뒤 끝낸다. */
+    async endCallForAll() {
+        const call = this._requireCall();
+        if (!call.callRoomId) {
+            return this._endWhileCreating(call, 'ended_by_host', (id) => this.apiClient.delete(`${ROOMS}/${id}`));
         }
+        await this._trackExit(call.callRoomId, this._send(call.identity, () => this.apiClient.delete(`${ROOMS}/${call.callRoomId}`)));
+        await this._finish(call, 'ended_by_host', { callOver: true });
     }
 
-    /**
-     * 1:1 통화 요청
-     * @param {string} targetUserId - 상대방 사용자 ID
-     * @param {Object} [mediaConstraints] - 미디어 제약조건
-     */
-    async callUser(targetUserId, mediaConstraints = { video: true, audio: true }) {
-        try {
-            // TURN 서버 설정 초기화
-            await this.initializeIceServers();
-
-            // 로컬 미디어 획득
-            const localStream = await this.mediaManager.getUserMedia(mediaConstraints);
-            this.peerManager.setLocalStream(localStream);
-
-            // 1:1 통화 구독
-            await this._subscribeToDirectSignaling();
-
-            // CALL_ACCEPT 대기 상태 설정
-            // PeerConnection은 CALL_ACCEPT를 받은 후에 생성하여 자동 negotiation 방지
-            this._callActive = true;
-            this._waitingForCallAccept = true;
-            this._pendingCallTarget = targetUserId;
-            this._incomingCallPeer = null;
+    // ==================== 미디어 ====================
 
-            // 통화 요청 시그널
-            this._sendSignal({
-                type: SignalTypes.CALL_REQUEST,
-                receiverId: targetUserId
-            });
-
-            this.currentRoom = null;
-            this.isGroupCall = false;
-
-            this.emit('callRequested', { targetUserId, localStream });
+    /** @param {boolean} enabled */
+    async setCameraEnabled(enabled) {
+        await this._changeDevice('camera', 'video', enabled, session => session.setCameraEnabled(enabled));
+    }
 
-        } catch (error) {
-            this.logger.error('Failed to call user:', error);
-            this._waitingForCallAccept = false;
-            this._pendingCallTarget = null;
-            throw error;
-        }
+    /** @param {boolean} enabled */
+    async setMicrophoneEnabled(enabled) {
+        await this._changeDevice('microphone', 'audio', enabled, session => session.setMicrophoneEnabled(enabled));
     }
 
     /**
-     * 통화 수락
-     * @param {string} callerId - 발신자 ID
-     * @param {Object} [mediaConstraints] - 미디어 제약조건
+     * 카메라·마이크를 켜고 끈다 — 통화가 있으면 언제든(방을 만드는 중·입장 중·다시 입장 중 포함). 의도를 «먼저» 기억한다 — 미디어 연결이
+     * 아직 없으면 의도만 적고 끝나며, 다음 연결이 이 의도로 붙는다(접속 중인 연결은 세션이 마지막 의도로 맞춘다). 연결에서 못 바꿨고 아직
+     * 그 연결이면 그 연결이 실제로 쓰는 상태로 되돌린다 — 앞선 호출도 실패했으면 그 의도(한 번도 적용되지 않은 값)가 아니라(그 사이 다시
+     * 붙었으면 새 연결이 이 의도로 붙었다).
      */
-    async acceptCall(callerId, mediaConstraints = { video: true, audio: true }) {
+    async _changeDevice(source, key, enabled, action) {
+        const call = this._requireCall();
+        call.media[key] = enabled;
+        // 내 호출 차례 — 실패해 되돌릴 때 그 뒤의 호출(같은 값을 다시 누른 것 포함)을 덮지 않게.
+        const turn = ++call.mediaTurn[key];
+        const session = call.session;
+        if (!session) {
+            return;
+        }
         try {
-            // TURN 서버 설정 초기화
-            await this.initializeIceServers();
-
-            // 로컬 미디어 획득 (수신자도 미디어 필요)
-            const localStream = await this.mediaManager.getUserMedia(mediaConstraints);
-            this.peerManager.setLocalStream(localStream);
-
-            // 피어 연결 생성 (Polite - 수신자)
-            // skipAutoNegotiation: true - 수신자는 offer를 받아서 answer를 보내므로 자동 negotiation 불필요
-            this.peerManager.createPeerConnection(callerId, true, { skipAutoNegotiation: true });
-            this._directCallPeer = callerId;
-            this._incomingCallPeer = null;
-
-            // 수락 시그널
-            this._sendSignal({
-                type: SignalTypes.CALL_ACCEPT,
-                receiverId: callerId
-            });
-
-            this._callActive = true;
-            this.emit('callAccepted', { callerId });
-
+            await this._mediaCall(source, () => action(session));
         } catch (error) {
-            this.logger.error('Failed to accept call:', error);
+            if (call.session === session && call.mediaTurn[key] === turn) {
+                call.media[key] = session.appliedMedia(source);
+            }
             throw error;
         }
     }
 
-    /**
-     * 통화 거절
-     * @param {string} callerId - 발신자 ID
-     */
-    rejectCall(callerId) {
-        if (this._incomingCallPeer === callerId) this._incomingCallPeer = null;
-        this._sendSignal({
-            type: SignalTypes.CALL_REJECT,
-            receiverId: callerId
-        });
+    async startScreenShare() {
+        await this._mediaCall('screen', session => session.setScreenShareEnabled(true));
+    }
 
-        this.emit('callRejected', { callerId });
+    async stopScreenShare() {
+        await this._mediaCall('screen', session => session.setScreenShareEnabled(false));
     }
 
     /**
-     * 통화 취소 (발신자가 수신자 응답 전 취소)
+     * 장치 목록 — 통화 전에도 부를 수 있다.
+     * @param {MediaDeviceKind} [kind]
+     * @returns {Promise<MediaDeviceInfo[]>}
      */
-    cancelCall() {
-        if (this._waitingForCallAccept && this._pendingCallTarget) {
-            this._sendSignal({
-                type: SignalTypes.CALL_CANCEL,
-                receiverId: this._pendingCallTarget
-            });
-
-            this.emit('callCancelled', { targetUserId: this._pendingCallTarget });
-
-            // 대기 상태 초기화
-            this._waitingForCallAccept = false;
-            this._pendingCallTarget = null;
-
-            // 미디어 정리
-            this._callActive = false;
-            this.mediaManager.stopAll();
+    async getDevices(kind) {
+        const session = this._call?.session ?? this._createMediaSession();
+        try {
+            return await session.getDevices(kind);
+        } catch (error) {
+            throw callError(ErrorTypes.ENUMERATE_DEVICES_FAILED, 'Failed to enumerate devices', error);
         }
     }
 
     /**
-     * 통화 종료
+     * 장치를 바꾼다 — 통화가 있으면 언제든. 고른 장치를 «먼저» 기억한다 — 미디어 연결이 아직 없으면 기억만 하고 끝나며, 다시 입장(제거됨·
+     * 첫 접속 실패)해도 새 연결이 그 장치로 붙는다(livekit 은 고른 장치를 그 Room 에만 적는다). 그 연결에서 못 바꿨고 아직 그 연결이면
+     * 그 연결이 지금 쓰는 장치로 기억을 되돌린다(모르면 기본 장치) — 한 번도 적용되지 않은 앞선 선택을 기억하지 않게. 스피커를 일부만
+     * 바꾸고 쓰던 출력으로 되돌리지도 못하면 그 오류(`DEVICE_SWITCH_FAILED`)에 outputMismatch 가 붙는다 — 일부 상대 소리가 고른 출력에
+     * 남았고 기억은 쓰던 출력이다(다시 고르면 모두 그 출력으로 맞춘다).
+     * @param {MediaDeviceKind} kind - audioinput·videoinput·audiooutput
+     * @param {string} deviceId
      */
-    endCall() {
-        this._endCall(true);
-    }
-
-    _endCall(notifyPeers) {
-        this._callGeneration++;
-        this._cancelGroupRecoveryRetry();
-        this._groupRecoveryAttempts = 0;
-        this._groupRecovery = null;
-        this._callActive = false;
-        this._deferredGroupPeers.clear();
-        this._joinedGroupRoom = null;
-        this._groupJoin = null;
-        this._incomingCallPeer = null;
-        if (this._pendingStart) this._pendingStart.cancelled = true;
-        // 대기 중인 통화가 있으면 취소 처리
-        if (notifyPeers && this._waitingForCallAccept && this._pendingCallTarget) {
-            this._sendSignal({
-                type: SignalTypes.CALL_CANCEL,
-                receiverId: this._pendingCallTarget
-            });
-        }
-
-        // 대기 상태 초기화
-        this._waitingForCallAccept = false;
-        this._pendingCallTarget = null;
-
-        if (this.currentRoom) {
-            // 퇴장 시그널 전송
-            if (notifyPeers) this._sendSignal({
-                type: SignalTypes.LEAVE_ROOM,
-                roomId: this.currentRoom
-            });
-
-            // 구독 해제
-            this._unsubscribeFromSignaling();
-        }
-
-        // 모든 피어에게 종료 시그널
-        if (notifyPeers) this.peerManager.getPeerIds().forEach(peerId => {
-            this._sendSignal({
-                type: SignalTypes.CALL_END,
-                receiverId: peerId
-            });
-        });
-        // 1:1 상대에게 가는 CALL_END 에 그룹 roomId 가 붙지 않도록 보낸 뒤에 지운다(_groupRoomFor).
-        this._directCallPeer = null;
-
-        // 정리
-        this.peerManager.closeAllPeerConnections();
-        this.peerManager.setLocalStream(null);
-        this.mediaManager.stopAll();
-        this.participants.clear();
-        this._pendingIceCandidates.clear();
-
-        const roomId = this.currentRoom;
-        this.currentRoom = null;
-        this.isGroupCall = false;
-
-        this.emit('callEnded', { roomId });
-        this.logger.info('Call ended');
+    async switchDevice(kind, deviceId) {
+        const call = this._requireCall();
+        call.devices[kind] = deviceId;
+        const turn = call.deviceTurn[kind] = (call.deviceTurn[kind] ?? 0) + 1;
+        const session = call.session;
+        if (!session) {
+            return true;
+        }
+        let switched = false;
+        try {
+            switched = await session.switchDevice(kind, deviceId);
+            return switched;
+        } catch (error) {
+            if (error?.code === ErrorTypes.INVALID_STATE) {
+                throw error;
+            }
+            const failure = callError(ErrorTypes.DEVICE_SWITCH_FAILED, 'Failed to switch device', error);
+            // 스피커를 일부만 바꾸고 되돌리지 못했다 — 일부 상대 소리가 고른 출력에 남았다(기억은 쓰던 출력). 다시 고르면 모두 맞춘다.
+            if (error?.outputMismatch) {
+                failure.outputMismatch = true;
+            }
+            throw failure;
+        } finally {
+            if (!switched && call.session === session && call.deviceTurn[kind] === turn) {
+                const inUse = session.deviceInUse(kind);
+                if (inUse === undefined) {
+                    delete call.devices[kind];
+                } else {
+                    call.devices[kind] = inUse;
+                }
+            }
+        }
     }
 
-    // ==================== 미디어 제어 ====================
+    // ==================== 조회 ====================
 
-    /**
-     * 비디오 토글
-     * @returns {boolean}
-     */
-    toggleVideo() {
-        return this.mediaManager.toggleVideo();
+    /** @param {string} callRoomId */
+    async getCallRoom(callRoomId) {
+        requireCallRoomId(callRoomId);
+        return unwrap(await this._send(this._identity, () => this.apiClient.get(`${ROOMS}/${callRoomId}`)));
     }
 
     /**
-     * 오디오 토글
-     * @returns {boolean}
+     * 내 참가 상태 — {@code {callRoomId, participating, ring}}. ring 은 초대 대상의 울림 상태(RINGING 이면 아직 울리는 중).
+     * @param {string} callRoomId
      */
-    toggleAudio() {
-        return this.mediaManager.toggleAudio();
+    async getParticipation(callRoomId) {
+        requireCallRoomId(callRoomId);
+        return unwrap(await this._send(this._identity, () => this.apiClient.get(`${ROOMS}/${callRoomId}/participation`)));
     }
 
-    /**
-     * 화면 공유 시작
-     * @returns {Promise<MediaStream>}
-     */
-    async startScreenShare() {
-        const screenStream = await this.mediaManager.getDisplayMedia();
-
-        // 피어들에게 화면 공유 트랙 전송
-        const videoTrack = screenStream.getVideoTracks()[0];
-        const localVideoTrack = this.mediaManager.getTrack('video');
+    /** @returns {boolean} */
+    isInCall() {
+        return this._call !== null;
+    }
 
-        if (localVideoTrack && videoTrack) {
-            await this.peerManager.replaceTrack(localVideoTrack, videoTrack);
+    /** 지금 통화 — 없으면 null. 방을 만드는 중이면 callRoomId 가 null 이다. */
+    getCurrentCall() {
+        const call = this._call;
+        if (!call) {
+            return null;
         }
-
-        // 화면 공유 종료 시 원복 — 복원 시점의 현재 카메라 트랙 사용 (공유 중 switchDevice 대응)
-        videoTrack.onended = async () => {
-            const currentVideoTrack = this.mediaManager.getTrack('video');
-            if (currentVideoTrack) {
-                await this.peerManager.replaceTrack(videoTrack, currentVideoTrack);
-            }
-            this.emit('screenShareEnded', {});
+        return {
+            callRoomId: call.callRoomId,
+            kind: call.kind,
+            state: call.state,
+            participants: call.session?.participants() ?? [],
+            localMedia: call.session?.getLocalMediaState() ?? { camera: false, microphone: false, screen: false }
         };
+    }
 
-        return screenStream;
+    /** 울리는 통화들. */
+    getRingingCalls() {
+        return [...this._ringing.values()].map(({ callRoomId, kind, callerId, title }) => ({ callRoomId, kind, callerId, title }));
     }
 
-    /**
-     * 화면 공유 중지
-     */
-    stopScreenShare() {
-        const screenStream = this.mediaManager.getScreenStream();
-        if (screenStream) {
-            screenStream.getTracks().forEach(track => track.stop());
-        }
+    /** @param {number} level */
+    setLogLevel(level) {
+        this.logger.setLevel(level);
     }
 
     /**
-     * 로컬 스트림 가져오기
-     * @public
-     * @returns {MediaStream|null}
+     * 통화를 건 로그인 신원이 끝났다(로그아웃·사용자·회사 전환·세션 지워짐) — TalkFlowClient 가 부른다. 이 기기에서만 정리하고, 그
+     * 신원으로 시작한 요청은 더 보내지 않는다(진행 중인 재시도·만들기·입장 응답 뒤의 정리 포함). 로그인 세션은 클라이언트에 알리기 전에
+     * 토큰을 바꾸므로(AuthSession._accept) 그 뒤에 보내는 요청은 새 신원으로 간다. 서버는 미디어가 끊긴 뒤 끊김 유예가 지나면 참가를
+     * 닫는다. 같은 인스턴스는 다음 신원으로 계속 쓴다(토큰 직접 방식의 로그아웃 뒤 setToken).
      */
-    // noinspection JSUnusedGlobalSymbols
-    getLocalStream() {
-        return this.mediaManager.getLocalStream();
+    async _resetIdentity() {
+        this._identity += 1;
+        // 새 사용자가 반영될 때까지(setToken 이 userId 를 넣을 때까지, 로그인 세션은 이 인스턴스를 버릴 때까지) 통화 요청을 받지 않는다 —
+        // 그 사이 자격은 이미 새 신원일 수 있어(AuthSession._accept) 옛 사용자로 보이는 요청이 새 신원으로 나간다.
+        this.userId = null;
+        for (const callRoomId of [...this._ringing.keys()]) {
+            this._stopRinging(callRoomId, 'ended');
+        }
+        // 장부(묘비·울림 정지 표식)도 그 신원의 것이다 — 다음 신원이 같은 통화에 초대돼도 막지 않게 비운다.
+        this._ledger = new CallLedger();
+        const call = this._call;
+        if (!call) {
+            return;
+        }
+        if (!call.callRoomId) {
+            // 방을 만드는 중 — 알릴 방 id 가 아직 없다. 만들기를 기다리지 않는다(신원 전환을 막지 않게). 만든 뒤 _startHosted 가
+            // 아무것도 보내지 않고 callUser 를 NO_ACTIVE_CALL 로 끝낸다.
+            this._call = null;
+            return;
+        }
+        await this._finish(call, 'left');
     }
 
     /**
-     * 디바이스 목록 가져오기
-     * @returns {Promise<Object>}
+     * 자원 정리 — 서버에 아무것도 보내지 않고, 뒤에 부르는 통화 시작도 막는다. 로그아웃·사용자 전환은 TalkFlowClient 가 그 전에
+     * 나가기를 보내거나(자격이 아직 지금 신원일 때) 이 기기에서만 끝낸다(_resetIdentity).
      */
-    async getDevices() {
-        return this.mediaManager.getDevices();
+    destroy() {
+        this._closed = true;
+        this.connectionManager.off?.('reconnected', this._onConnectionRestored);
+        this.connectionManager.off?.('resumed', this._onConnectionRestored);
+        for (const ring of this._ringing.values()) {
+            clearTimeout(ring.timer);
+        }
+        this._ringing.clear();
+        const call = this._call;
+        this._call = null;
+        if (call) {
+            call.endReason = 'destroyed';
+            if (call.callRoomId) {
+                this.connectionManager.unsubscribe(WebSocketPaths.getWebRTCDestination(call.callRoomId));
+            }
+            call.session?.disconnect().catch(error => this.logger.warn('Media disconnect failed:', error));
+        }
+        this.disableIncomingCalls();
+        this.removeAllListeners();
     }
 
-    /**
-     * 디바이스 전환
-     * @param {string} deviceId
-     * @param {string} kind - 'video' or 'audio'
-     */
-    async switchDevice(deviceId, kind) {
-        // switchDevice가 localStream을 교체하므로, 교체 전 기존 트랙을 먼저 저장
-        const oldTrack = this.mediaManager.getTrack(kind);
-        const newTrack = await this.mediaManager.switchDevice(deviceId, kind);
+    // ==================== 내부: 통화 진행 ====================
 
-        // 피어들에게 트랙 교체
-        if (oldTrack) {
-            await this.peerManager.replaceTrack(oldTrack, newTrack);
+    _beginCall({ kind, media, host, callRoomId = null }) {
+        if (this._closed) {
+            throw callError(ErrorTypes.INVALID_STATE, 'WebRTC client is destroyed');
         }
-
-        return newTrack;
+        if (!this.userId) {
+            throw callError(ErrorTypes.INVALID_STATE, 'No signed-in user for calls (the signed-in user is changing)');
+        }
+        if (this._call) {
+            throw callError(ErrorTypes.CALL_ALREADY_ACTIVE, `Another call is active: ${this._call.callRoomId ?? '(creating)'}`);
+        }
+        const call = {
+            callRoomId,
+            kind,
+            host,
+            identity: this._identity,
+            state: null,
+            session: null,
+            media: { video: media?.video !== false, audio: media?.audio !== false },
+            /** 고른 장치(종류별 deviceId) — 다시 입장해도 새 연결이 이 장치로 붙는다. */
+            devices: {},
+            /** 카메라·마이크 바꾸기·장치 바꾸기의 호출 차례 — 실패한 호출은 마지막 호출일 때만 되돌린다. */
+            mediaTurn: { video: 0, audio: 0 },
+            deviceTurn: {},
+            created: null,
+            cancelRequested: false,
+            ending: null,
+            fromRing: false,
+            joinAttempted: false,
+            removedRejoinUsed: false,
+            endReason: null,
+            callOver: false
+        };
+        this._call = call;
+        return call;
     }
 
-    /**
-     * 비디오 상태 직접 설정
-     * @public
-     * @param {boolean} enabled
-     */
-    // noinspection JSUnusedGlobalSymbols
-    setVideoEnabled(enabled) {
-        this.mediaManager.setVideoEnabled(enabled);
-        this._sendMediaState();
+    /** 방장 — 방을 만들고 입장한다. 만드는 동안 «취소»·«나가기» 가 오면 만든 뒤 그 메서드가 끝낸다. */
+    async _startHosted(call, body) {
+        let markCreated;
+        call.created = new Promise((resolve) => { markCreated = resolve; });
+        let room;
+        try {
+            room = await this._createRoom(call, body);
+        } catch (error) {
+            markCreated();
+            if (this._call === call) {
+                this._call = null;
+            }
+            throw error;
+        }
+        call.callRoomId = room.callRoomId;
+        markCreated();
+        if (this._call !== call) {
+            // 만드는 동안 이 기기에서만 끝났다(destroy·로그인 신원 끝남) — 서버에 아무것도 보내지 않는다. 알릴 방 id 가 없던 통화라 결과는
+            // 여기로만 알린다. 나가기·취소·모두 끝내기는 만들기를 기다려 아래 cancelRequested 로 온다.
+            throw callError(ErrorTypes.NO_ACTIVE_CALL, 'The call ended on this device before the room was created');
+        }
+        if (call.cancelRequested) {
+            // 만드는 동안 나가기·취소·모두 끝내기를 눌렀다 — 그 메서드가 이어서 끝낸다.
+            return call.callRoomId;
+        }
+        return this._enter(call);
     }
 
-    /**
-     * 오디오 상태 직접 설정
-     * @public
-     * @param {boolean} enabled
-     */
-    // noinspection JSUnusedGlobalSymbols
-    setAudioEnabled(enabled) {
-        this.mediaManager.setAudioEnabled(enabled);
-        this._sendMediaState();
+    async _enter(call) {
+        const callRoomId = call.callRoomId;
+        this._setState(call, CallState.CONNECTING);
+        this._subscribeCallTopic(call);
+        try {
+            // 서버가 이미 끝냈다고 알린 통화(방 생성 응답보다 먼저 온 1:1 거절 등)에는 입장하지 않는다.
+            const endedBefore = this._ledger.endedReason(callRoomId);
+            if (endedBefore) {
+                await this._finish(call, endedBefore, { callOver: true });
+                return callRoomId;
+            }
+            const grant = await this._join(call);
+            if (this._call !== call) {
+                this._afterLateJoin(call);
+                return callRoomId;
+            }
+            call.kind = grant.kind ?? call.kind;
+            await this._connectMedia(call, grant.media, true);
+            return callRoomId;
+        } catch (error) {
+            if (this._call !== call) {
+                // 그 사이 끝났다(거절·취소·종료·나가기) — 결과는 callEnded 로 이미 알렸다.
+                return callRoomId;
+            }
+            await this._finish(call, 'failed', { error, abandon: 'start' });
+            throw error;
+        }
     }
 
     /**
-     * 디바이스 변경 감지 시작
-     * @public
+     * 통화방 토픽(종료 알림)을 구독한다 — 기다리지 않는다. STOMP 가 끊겨 있으면 구독은 다시 붙을 때까지 큐에 서는데, 미디어에는
+     * STOMP 가 필요 없고 놓친 종료는 미디어 방 삭제(room_deleted)로도 온다. 큐에 선 동안 통화가 끝나면 _finish 의 구독 해제가 큐에
+     * 닿지 않는다(ConnectionManager.unsubscribe 는 붙은 구독만 푼다) — 붙은 뒤에 그 통화가 지금 통화가 아니면 이 구독만 푼다. 끊긴 사이
+     * 같은 방 구독이 큐에 여럿 섰다가 함께 붙으면 맵에는 마지막 것만 있어, 목적지로 풀면 남의 구독을 풀고 이 구독은 남는다.
      */
-    // noinspection JSUnusedGlobalSymbols
-    startDeviceChangeDetection() {
-        this.mediaManager.startDeviceChangeDetection();
-        this.mediaManager.on('deviceChange', (devices) => {
-            this.emit('deviceChange', devices);
-        });
+    _subscribeCallTopic(call) {
+        const topic = WebSocketPaths.getWebRTCDestination(call.callRoomId);
+        Promise.resolve(this.connectionManager.subscribe(topic, (message) => this._handleEvent(message)))
+            .then((subscription) => {
+                if (this._call !== call) {
+                    this.connectionManager.unsubscribe(topic, subscription);
+                }
+            })
+            .catch(error => this.logger.warn('Call topic subscription failed:', error));
     }
 
     /**
-     * 디바이스 변경 감지 중지
-     * @public
+     * 이 기기가 통화를 끝낸 뒤에 입장 응답이 왔다 — 서버에는 참가가 열렸다. 서버가 끝낸 통화가 아니면 나가기를 다시 보낸다(안 보내면
+     * 서버에 붙지 않는 참가가 접속 유예 동안 정원을 차지한다). 그 통화의 신원이 끝났으면 보내지 않는다. 그 사이 같은 통화에 다시
+     * 들어갔으면 보내지 않는다 — 서버 참가는 사용자마다 하나라 이 나가기가 새 참가를 닫는다.
      */
-    // noinspection JSUnusedGlobalSymbols
-    stopDeviceChangeDetection() {
-        this.mediaManager.stopDeviceChangeDetection();
+    _afterLateJoin(call) {
+        if (call.callOver || this._closed || call.identity !== this._identity || this._call?.callRoomId === call.callRoomId) {
+            return;
+        }
+        this._trackExit(call.callRoomId, this.apiClient.post(`${ROOMS}/${call.callRoomId}/leave`))
+            .catch(error => this.logger.warn('Leave after a late join failed:', error));
     }
 
-    /**
-     * 비디오 해상도/프레임레이트 변경
-     * @public
-     * @param {Object} constraints - { width, height, frameRate }
-     * @returns {Promise<void>}
-     */
-    // noinspection JSUnusedGlobalSymbols
-    async applyVideoConstraints(constraints) {
-        return this.mediaManager.applyVideoConstraints(constraints);
+    async _connectMedia(call, media, allowRejoin) {
+        const session = this._createMediaSession();
+        call.session = session;
+        this._wireSession(call, session);
+        try {
+            await session.connect(media.url, media.token, { video: call.media.video, audio: call.media.audio, devices: { ...call.devices } });
+        } catch (error) {
+            if (call.session === session) {
+                call.session = null;
+            }
+            if (this._call !== call) {
+                return;
+            }
+            // 접속 중에 같은 사람이 다른 기기로 들어왔거나(replaced) 미디어 방이 지워졌다 — 다시 입장하지 않고 그 사유로 끝낸다(나가기
+            // 없음). 다시 입장하면 방금 들어온 다른 기기를 밀어낸다.
+            const reason = error?.disconnectReason;
+            if (reason === 'replaced' || reason === 'room_deleted' || reason === 'room_closed') {
+                await this._finish(call, reason);
+                return;
+            }
+            if (!allowRejoin) {
+                throw callError(ErrorTypes.MEDIA_CONNECTION_FAILED, 'Failed to connect to the media server', error);
+            }
+            // 첫 접속 실패(방이 지워졌거나 토큰 마감 등) — 입장을 한 번 다시 부르면 서버가 방과 토큰을 다시 만든다(§5.3).
+            this.logger.warn('Media connect failed, joining again once:', error);
+            const grant = await this._join(call);
+            if (this._call === call) {
+                await this._connectMedia(call, grant.media, false);
+            } else {
+                this._afterLateJoin(call);
+            }
+            return;
+        }
+        if (this._call !== call || call.session !== session) {
+            await session.disconnect();
+            return;
+        }
+        // 접속이 끝날 때 LiveKit 이 재접속 중이면 아직 붙은 것이 아니다 — 다시 붙으면 세션의 reconnected 가 connected 로 바꾼다.
+        if (session.isReconnecting()) {
+            if (call.state !== CallState.RECONNECTING) {
+                this._setState(call, CallState.RECONNECTING);
+            }
+            return;
+        }
+        // 접속이 끝난 직후 끼어든 재접속 시작·끝 알림이 이미 connected 로 바꿨으면 다시 내지 않는다 — 상태 알림은 바뀔 때만.
+        if (call.state !== CallState.CONNECTED) {
+            this._setState(call, CallState.CONNECTED);
+        }
     }
 
-    /**
-     * 현재 비디오 설정 가져오기
-     * @public
-     * @returns {MediaTrackSettings|null}
-     */
-    // noinspection JSUnusedGlobalSymbols
-    getVideoSettings() {
-        return this.mediaManager.getVideoSettings();
+    _wireSession(call, session) {
+        const live = () => this._call === call && call.session === session;
+        const forward = (event) => session.on(event, (payload) => {
+            if (live()) this.emit(event, { callRoomId: call.callRoomId, ...payload });
+        });
+        ['participantJoined', 'participantLeft', 'trackSubscribed', 'trackUnsubscribed', 'localTrackPublished',
+            'localTrackUnpublished', 'participantMediaChanged'].forEach(forward);
+        session.on('mediaError', ({ source, error }) => {
+            if (!live()) return;
+            // 통화에 붙을 때 켜던 장치가 실패했다(사용자가 그 뒤에 바꾸지 않았다) — 꺼진 것으로 기억한다. 다시 입장해도 누르지 않은 장치를
+            // 다시 켜지 않는다(다시 누르면 다시 시도).
+            const key = source === 'camera' ? 'video' : source === 'microphone' ? 'audio' : null;
+            if (key) {
+                call.media[key] = false;
+                call.mediaTurn[key] += 1;
+            }
+            const code = source === 'screen' ? ErrorTypes.SCREEN_SHARE_DENIED : ErrorTypes.MEDIA_ACCESS_DENIED;
+            this.emit('callError', { callRoomId: call.callRoomId, code, message: `Failed to enable ${source}`, error });
+        });
+        // LiveKit 이 스스로 옮긴 장치(빠진 장치를 다른 장치로 다시 열기·출력 전환)를 기억한다 — 다시 입장해도 없는 장치로 붙지 않게
+        // (undefined 면 기본 장치). 그 종류의 장치 바꾸기가 진행 중이면 세션이 알리지 않는다.
+        session.on('deviceInUseChanged', ({ kind, deviceId }) => {
+            if (!live()) return;
+            if (deviceId === undefined) {
+                delete call.devices[kind];
+            } else {
+                call.devices[kind] = deviceId;
+            }
+        });
+        // 상태 알림은 바뀔 때만 — reconnected 는 재접속 중일 때만 connected 로 바꾼다(접속 직후 한 칸에 끼어도 두 번 내지 않게).
+        session.on('reconnecting', () => {
+            if (live() && call.state !== CallState.RECONNECTING) this._setState(call, CallState.RECONNECTING);
+        });
+        session.on('reconnected', () => {
+            if (live() && call.state === CallState.RECONNECTING) this._setState(call, CallState.CONNECTED);
+        });
+        session.on('disconnected', ({ reason }) => {
+            if (!live()) return;
+            this._onMediaDisconnected(call, reason).catch(error => this.logger.error('Media disconnect handling failed:', error));
+        });
     }
 
-    /**
-     * 현재 오디오 설정 가져오기
-     * @public
-     * @returns {MediaTrackSettings|null}
-     */
-    // noinspection JSUnusedGlobalSymbols
-    getAudioSettings() {
-        return this.mediaManager.getAudioSettings();
+    async _onMediaDisconnected(call, reason) {
+        call.session = null;
+        switch (reason) {
+            case 'client':
+                // SDK 가 끊은 것만 client 로 온다 — 그때는 이미 live 가 아니라 여기 오지 않는다. 혹시 오면 끝난 것으로 본다.
+                return this._finish(call, 'left');
+            case 'replaced':
+                // 같은 사람이 다른 기기로 들어왔다 — 이 기기만 끝낸다. 나가기를 보내면 새 기기의 참가가 닫힌다.
+                return this._finish(call, 'replaced');
+            case 'room_deleted':
+            case 'room_closed':
+                return this._finish(call, reason);
+            case 'removed':
+                return this._rejoinAfterRemoval(call);
+            default:
+                this.emit('callRecoveryFailed', { callRoomId: call.callRoomId, reason });
+                return this._finish(call, 'connection_lost');
+        }
     }
 
-    // ==================== 시그널링 ====================
-
     /**
-     * 시그널링 구독
-     * @private
+     * 서버가 연결을 뺐다 — 참가가 열려 있는데 «확인 → 제거» 창에 걸렸을 수 있다(설계 L6). 입장을 한 번 다시 부른다: 성공하면 새
+     * 토큰으로 다시 붙고(사용자가 끈 장치는 끈 채), 거부되면(참가가 닫혔거나 통화가 끝났다) 끝낸다 — 나가기는 보내지 않는다(닫을 참가가
+     * 없거나, 같은 사람의 다른 기기 참가다). 다시 연 참가에 미디어로 못 붙었으면 그 참가는 이 기기가 연 것이라 나가기로 닫는다 — 안
+     * 닫으면 접속 유예(admitGrace) 동안 1:1 상대가 기다리고 그룹 정원을 차지한다.
      */
-    async _subscribeToSignaling(roomId, isGroup) {
-        if (isGroup) {
-            // 그룹 통화: /topic/webrtc/{roomId}
-            const destination = WebSocketPaths.getWebRTCDestination(roomId);
-            await this.connectionManager.subscribe(destination, (message) => {
-                this._handleSignal(message);
-            });
+    async _rejoinAfterRemoval(call) {
+        if (call.removedRejoinUsed) {
+            return this._finish(call, 'removed');
+        }
+        call.removedRejoinUsed = true;
+        this._setState(call, CallState.RECONNECTING, 'removed');
+        let grant;
+        try {
+            grant = await this._join(call);
+        } catch (error) {
+            if (this._call === call) {
+                await this._finish(call, 'removed', { error });
+            }
+            return;
+        }
+        if (this._call !== call) {
+            this._afterLateJoin(call);
+            return;
+        }
+        try {
+            await this._connectMedia(call, grant.media, false);
+        } catch (error) {
+            if (this._call === call) {
+                await this._finish(call, 'removed', { error, abandon: 'leave' });
+            }
         }
-
-        // 1:1 또는 그룹 모두에서 개인 큐 구독
-        await this._subscribeToDirectSignaling();
     }
 
     /**
-     * 1:1 시그널링 구독
-     * @private
+     * 이 기기의 통화를 끝낸다.
+     * @param {Object} call
+     * @param {string} reason
+     * @param {{error?: Error, callOver?: boolean, abandon?: 'start'|'leave'}} [options]
+     *        callOver — 서버에서 통화가 끝났다(묘비를 남겨 늦은 초대가 다시 울리지 않게). 이 기기만 나간 것이면 남기지 않는다 — 다시
+     *        들어갈 수 있다. abandon — 이 기기의 실패를 서버에 알린다({@link #_abandon}).
      */
-    async _subscribeToDirectSignaling() {
-        const destination = WebSocketPaths.getWebRTCUserDestination();
-        await this.connectionManager.subscribe(destination, (message) => {
-            this._handleSignal(message);
-        });
+    async _finish(call, reason, { error, callOver = false, abandon = null } = {}) {
+        if (this._call !== call) {
+            return;
+        }
+        this._call = null;
+        call.endReason = reason;
+        call.callOver = callOver;
+        if (callOver && call.callRoomId) {
+            this._ledger.markEnded(call.callRoomId, reason);
+        }
+        if (call.callRoomId) {
+            this.connectionManager.unsubscribe(WebSocketPaths.getWebRTCDestination(call.callRoomId));
+        }
+        // 미디어 끊기를 시작하되 끝남은 끊기(수백 ms)를 기다리지 않고 지금 알린다 — 그 사이 같은 통화에 다시 들어가도 이 알림이 새 통화의
+        // 알림보다 먼저 간다(늦게 가면 앱이 새 통화 화면을 지운다). 끊는 동안 옛 세션의 이벤트는 _wireSession 이 거른다.
+        const session = call.session;
+        call.session = null;
+        // 실패 정리(취소·나가기)는 끝남 알림보다 먼저 시작해 방별 추적에 올린다 — 알림 안에서 같은 통화에 다시 들어가도 새 입장은 이 정리
+        // 뒤에 나간다.
+        if (abandon) {
+            this._trackExit(call.callRoomId, this._abandon(call, abandon)).catch(cleanupError => this.logger.warn('Call cleanup failed:', cleanupError));
+        }
+        const disconnecting = session
+            ? session.disconnect().catch(disconnectError => this.logger.warn('Media disconnect failed:', disconnectError))
+            : null;
+        this._setState(call, CallState.ENDED, reason);
+        this.emit('callEnded', { callRoomId: call.callRoomId, reason });
+        if (error) {
+            this.emit('callError', { callRoomId: call.callRoomId, code: error.code ?? ErrorTypes.UNKNOWN_ERROR, message: error.message, error });
+        }
+        await disconnecting;
     }
 
     /**
-     * 시그널링 구독 해제
-     * @private
+     * 이 기기의 실패를 서버에 알린다 — 안 알리면 상대 폰이 울림 상한까지 울리거나(거는 쪽 실패), 상대가 접속 유예 동안 기다린다(받는
+     * 쪽 실패). 통화를 시작하다 실패했으면('start') 방장은 취소(아무도 안 들어왔을 때만 된다 — 409 면 나가기), 통화 중에 실패했으면
+     * ('leave') 나가기만 — 그룹 통화는 다른 사람에게 이어지고 1:1 은 서버가 끝낸다. 받는 쪽은 입장을 시도했으면 나가기. 실패해도 서버가
+     * 유예 뒤에 닫는다.
+     * @param {Object} call
+     * @param {'start'|'leave'} mode
      */
-    _unsubscribeFromSignaling() {
-        if (this.currentRoom && this.isGroupCall) {
-            const destination = WebSocketPaths.getWebRTCDestination(this.currentRoom);
-            this.connectionManager.unsubscribe(destination);
+    async _abandon(call, mode) {
+        if (!call.callRoomId) {
+            return;
         }
-
-        // 수신 대기가 활성화된 경우 direct 채널 구독 유지 (그룹 통화 종료 후에도 수신 가능)
-        if (!this._incomingCallsEnabled) {
-            const directDestination = WebSocketPaths.getWebRTCUserDestination();
-            this.connectionManager.unsubscribe(directDestination);
+        if (call.host && mode === 'start') {
+            try {
+                await this._send(call.identity, () => this.apiClient.post(`${ROOMS}/${call.callRoomId}/cancel`));
+                return;
+            } catch (error) {
+                if (statusOf(error) !== 409) {
+                    throw error;
+                }
+            }
+        }
+        if (call.host || call.joinAttempted) {
+            await this._send(call.identity, () => this.apiClient.post(`${ROOMS}/${call.callRoomId}/leave`));
         }
     }
 
-    /**
-     * 시그널 전송
-     * @private
-     */
-    _sendSignal(signal) {
-        const payload = {
-            type: signal.type,
-            roomId: signal.roomId || this._groupRoomFor(signal),
-            receiverId: signal.receiverId,
-            data: signal.data
-        };
-
-        this.connectionManager.send(WebSocketPaths.WEBRTC_SIGNAL, payload);
-        this.logger.debug('Signal sent:', payload);
+    _setState(call, state, reason) {
+        call.state = state;
+        this.emit('callStateChanged', reason ? { callRoomId: call.callRoomId, state, reason } : { callRoomId: call.callRoomId, state });
     }
 
-    /**
-     * 그룹 roomId 는 그룹 상대·그룹 방 신호에만 붙인다.
-     * 1:1 신호에 붙으면 상대가 방 신호로 보고 버린다(그룹 통화 중 자동 BUSY 유실).
-     * @private
-     */
-    _groupRoomFor({ type, receiverId }) {
-        if (DIRECT_CONTROL_SIGNALS.has(type)) return undefined;
-        if (receiverId && receiverId === this._directCallPeer) return undefined;
-        return this.currentRoom || this._deferredGroupPeers.get(receiverId);
+    _whenCreated(call) {
+        if (call.callRoomId || !call.created) {
+            return Promise.resolve();
+        }
+        call.cancelRequested = true;
+        return call.created;
     }
 
     /**
-     * 미디어 상태 전송
-     * @private
+     * 방을 만드는 중의 끝내기(나가기·취소·모두 끝내기) — 처음 누른 것이 정하고 뒤에 누른 것은 그것을 기다린다. 방이 만들어지면 그
+     * 요청을 보내고(나가기면 이 기기에서 끝낸 뒤 취소), 성공하면 서버가 끝낸 통화로 끝낸다. 서버 요청이 실패해도 이 기기에서는 끝내고
+     * 정리(취소 → 409 면 나가기)를 보낸다 — 입장·미디어 없이 남아 다음 통화를 막지 않게. 응답을 기다리는 사이 다른 경로(나가기 등)로
+     * 이미 끝났으면 정리는 그 경로가 했다 — 다시 보내지 않는다(그 사이 같은 통화에 다시 들어갔으면 새 참가를 닫는다).
+     * @param {Object} call
+     * @param {string} reason
+     * @param {((callRoomId: string) => Promise<*>)|null} request - 나가기면 null
      */
-    _sendMediaState() {
-        if (!this.currentRoom && this.peerManager.getPeerIds().length === 0) {
-            return;
+    _endWhileCreating(call, reason, request) {
+        if (!call.ending) {
+            call.ending = (async () => {
+                await this._whenCreated(call);
+                if (this._call !== call || !call.callRoomId) {
+                    // 만들기가 실패했거나(callUser 가 그 오류로 끝난다) 그 사이 이 기기에서만 끝났다.
+                    return;
+                }
+                const cleanup = async () => {
+                    // 정리를 끝남 알림보다 먼저 시작해 방별 추적에 올린다(_finish 와 같은 이유).
+                    const abandoning = this._trackExit(call.callRoomId, this._abandon(call, 'start'));
+                    await this._finish(call, reason);
+                    await abandoning.catch(error => this.logger.warn('Call cleanup failed:', error));
+                };
+                if (!request) {
+                    await cleanup();
+                    return;
+                }
+                try {
+                    // 방별 추적에 올린다 — 응답 전에 나가고 같은 통화에 다시 들어가면 새 입장은 이 요청 뒤에 간다.
+                    await this._trackExit(call.callRoomId, this._send(call.identity, () => request(call.callRoomId)));
+                } catch (error) {
+                    if (this._call === call) {
+                        await cleanup();
+                    }
+                    throw error;
+                }
+                await this._finish(call, reason, { callOver: true });
+            })();
         }
-
-        const mediaState = {
-            videoEnabled: this.mediaManager.isVideoEnabled(),
-            audioEnabled: this.mediaManager.isAudioEnabled()
-        };
-
-        this._sendSignal({
-            type: SignalTypes.VIDEO_STATE_CHANGED,
-            data: mediaState
-        });
-
-        this.emit('mediaStateChanged', mediaState);
+        return call.ending;
     }
 
-    /**
-     * 시그널 처리
-     * @private
-     */
-    async _handleSignal(message) {
-        const { type, senderId, data } = message;
+    // ==================== 내부: 서버 이벤트 ====================
 
-        // 자신의 시그널 무시
-        if (senderId === this.userId) {
+    _handleEvent(message) {
+        const type = message?.type;
+        const data = message?.data ?? {};
+        const callRoomId = data.callRoomId ?? message?.roomId;
+        // 로그인 신원이 바뀌는 중(userId 없음) — 옛 연결로 온 알림은 버린다.
+        if (!type || !callRoomId || !this.userId) {
+            return;
+        }
+        const version = Number(data.version);
+        // 서버가 끝낸 통화(묘비)는 상태를 되살리지 않는다 — 초대는 버리고 끝내기는 다시 하지 않는다. 아직 알리지 않은 «일어난 일»(거절)은
+        // 알린다 — 같은 version 의 1:1 CALL_END 가 CALL_REJECT 보다 먼저 와도.
+        const ended = this._ledger.endedReason(callRoomId) !== null;
+        // 초대만 «지금 상태» 다 — 통화가 그 뒤로 나아갔으면(낡은 version) 울리지 않는다. 다른 이벤트는 «일어난 일» 이라 늦어도 받는다.
+        if (type === CallEventTypes.INVITATION && (ended || this._ledger.isStale(callRoomId, version))) {
+            return;
+        }
+        if (!this._ledger.record(callRoomId, version, type)) {
+            this.logger.debug('Duplicate call event ignored:', type, callRoomId, data.version);
             return;
         }
-
-        if (this._holdsEarlyRoomReject(message)) return;
-        if (!this._acceptsSignal(message)) return;
-
-        this.logger.debug(`Signal received: ${type} from ${senderId}`);
-
         switch (type) {
-            case SignalTypes.JOIN_ROOM:
-            case SignalTypes.PEER_JOINED:
-                await this._handleUserJoined(senderId, message.roomId);
-                break;
-
-            case SignalTypes.LEAVE_ROOM:
-            case SignalTypes.PEER_LEFT:
-                this._handleUserLeft(senderId);
-                break;
-
-            case SignalTypes.CALL_OFFER:
-                await this._handleOffer(senderId, data.sdp, message.roomId);
-                break;
-
-            case SignalTypes.CALL_ANSWER:
-                await this._handleAnswer(senderId, data.sdp);
-                break;
-
-            case SignalTypes.ICE_CANDIDATE:
-                await this._handleIceCandidate(senderId, data.candidate);
-                break;
-
-            case SignalTypes.VIDEO_STATE_CHANGED:
-            case SignalTypes.AUDIO_STATE_CHANGED:
-                this._handleMediaState(senderId, data);
-                break;
-
-            case SignalTypes.CALL_REQUEST:
-                // 통화 중이거나 통화 요청 대기 중이면 BUSY 응답
-                if (this.isInCall() || this._waitingForCallAccept) {
-                    this._sendSignal({
-                        type: SignalTypes.CALL_BUSY,
-                        receiverId: senderId
-                    });
-                    this.emit('incomingCallWhileBusy', { callerId: senderId });
-                } else {
-                    this._incomingCallPeer = senderId;
-                    this.emit('incomingCall', { callerId: senderId });
-                }
-                break;
-
-            case SignalTypes.CALL_BUSY:
-                // 상대방이 통화 중
-                this._waitingForCallAccept = false;
-                this._pendingCallTarget = null;
-                this._callActive = false;
-                this.mediaManager.stopAll();
-                this.emit('callBusy', { userId: senderId });
-                break;
-
-            case SignalTypes.CALL_INVITATION: {
-                // 그룹 통화 초대 (createCallRoom으로 초대받은 경우)
-                const callRoomId = data?.callRoomId || message.roomId;
-                // 취소 수락 기준은 서버가 채운 roomId·senderId(host)다. data 는 보낸 쪽이 정한 값이라 기억 키로 쓰지 않는다.
-                if (message.roomId) this._rememberCallRoom(this._receivedInvitations, message.roomId, senderId);
-                this.emit('callInvitation', {
-                    callRoomId,
-                    title: data?.title,
-                    hostUserId: data?.hostUserId || senderId,
-                    maxParticipants: data?.maxParticipants,
-                    createdAt: data?.createdAt
-                });
-                break;
-            }
-
-            case SignalTypes.CALL_ACCEPT:
-                await this._handleCallAccepted(senderId);
-                break;
-
-            case SignalTypes.CALL_REJECT:
-                if (message.roomId) {
-                    // 그룹 초대 거절(서버 REST 발신). host 의 통화·미디어는 그대로 둔다.
-                    this.emit('callRejected', { userId: senderId, roomId: message.roomId });
-                    break;
-                }
-                // 대기 상태 초기화
-                this._waitingForCallAccept = false;
-                this._pendingCallTarget = null;
-                this._callActive = false;
-                // 발신자 미디어 정리 (거절당했으므로 통화 불가)
-                this.mediaManager.stopAll();
-                this.emit('callRejected', { userId: senderId });
-                break;
-
-            case SignalTypes.CALL_CANCEL:
-                if (message.roomId) {
-                    // 그룹 초대 취소(서버 REST 발신). 1:1 대기 상태는 건드리지 않는다.
-                    this._receivedInvitations.delete(message.roomId);
-                    this.emit('callCancelled', { userId: senderId, roomId: message.roomId });
-                    break;
-                }
-                this._incomingCallPeer = null;
-                // 대기 상태 초기화
-                this._waitingForCallAccept = false;
-                this._pendingCallTarget = null;
-                this.emit('callCancelled', { userId: senderId });
-                break;
-
-            case SignalTypes.CALL_END:
-                if (data?.callEndScope === 'ROOM') {
-                    this._endCall(false); // _acceptsSignal에서 현재/참가 요청한 그룹 방 일치를 확인했다.
-                } else {
-                    this._handleCallEnded(senderId);
-                }
-                break;
-
+            case CallEventTypes.INVITATION:
+                return this._onInvitation(callRoomId, message, data);
+            case CallEventTypes.ANSWERED:
+                // 그 사용자가 다른 기기에서 받았거나(그룹이면 거절도) 응답했다 — 이 기기 울림을 끈다.
+                if (!data.userId || data.userId === this.userId) this._stopRinging(callRoomId, 'answered_elsewhere');
+                return;
+            case CallEventTypes.REJECT:
+                this.emit('callRejected', { callRoomId, userId: data.rejectedBy ?? null, reason: data.reason ?? null });
+                if (data.kind === CallKind.DIRECT && !ended) this._endCall(callRoomId, data.reason ?? 'declined');
+                return;
+            case CallEventTypes.CANCEL:
+                if (ended) return;
+                // 1:1 취소는 통화가 끝난 것이다 — 받는 중(입장 진행 중)이어도 끝낸다. 그룹 취소는 그 사람의 울림만.
+                if (data.kind === CallKind.DIRECT) this._endCall(callRoomId, data.reason ?? 'cancelled');
+                else this._stopRinging(callRoomId, data.reason ?? 'cancelled');
+                return;
+            case CallEventTypes.END:
+                if (!ended) this._endCall(callRoomId, data.reason ?? 'ended');
+                return;
             default:
-                this.logger.warn(`Unknown signal type: ${type}`);
+                this.logger.debug('Unknown call event ignored:', type);
         }
     }
 
-    /** 미디어를 공유할 상대/방은 로컬 참가·발신·수락으로만 결정한다. */
-    _acceptsSignal({ type, senderId, roomId }) {
-        if (!senderId) return false;
-        if (type === SignalTypes.CALL_INVITATION) return true;
-        if (type === SignalTypes.CALL_REQUEST) return !roomId;
-        // 그룹 초대 거절·취소는 서버가 roomId 를 붙여 보낸다. 내가 연 방·받은 초대의 host 것만 받는다.
-        if (roomId && type === SignalTypes.CALL_REJECT) return this._hostedCallRooms.has(roomId);
-        if (roomId && type === SignalTypes.CALL_CANCEL) return this._receivedInvitations.get(roomId) === senderId;
-        if ([SignalTypes.CALL_ACCEPT, SignalTypes.CALL_BUSY, SignalTypes.CALL_REJECT].includes(type)) {
-            return !roomId && this._waitingForCallAccept && senderId === this._pendingCallTarget;
-        }
-        if (type === SignalTypes.CALL_CANCEL) return !roomId && senderId === this._incomingCallPeer;
-        // 수락한 1:1 상대의 신호는 roomId 없이 온다. 그룹 통화 중에 수락했어도 받는다.
-        if (!roomId && senderId === this._directCallPeer) return true;
-        const groupRoom = this.isGroupCall ? this.currentRoom
-            : (!this._callActive && !this._waitingForCallAccept ? this._groupJoin?.roomId || this._joinedGroupRoom : null);
-        if (groupRoom) return roomId === groupRoom;
-        return !roomId && senderId === this._pendingCallTarget;
-    }
-
-    /** 방 생성 응답 전에 온 그룹 거절은 응답의 방 ID 로 판정할 수 있을 때까지 보관한다. */
-    _holdsEarlyRoomReject(message) {
-        const { type, roomId } = message;
-        if (type !== SignalTypes.CALL_REJECT || !roomId || this._pendingRoomCreations === 0
-                || this._hostedCallRooms.has(roomId)) return false;
-        this._earlyRoomRejects.push(message);
-        if (this._earlyRoomRejects.length > MAX_REMEMBERED_CALL_ROOMS) this._earlyRoomRejects.shift();
-        return true;
-    }
-
-    _rememberCallRoom(rooms, roomId, userId) {
-        rooms.delete(roomId);
-        rooms.set(roomId, userId);
-        if (rooms.size > MAX_REMEMBERED_CALL_ROOMS) rooms.delete(rooms.keys().next().value);
-    }
-
-    _clearDeferredGroup(roomId) {
-        for (const [peerId, peerRoom] of this._deferredGroupPeers) {
-            if (peerRoom !== roomId) continue;
-            this.peerManager.closePeerConnection(peerId);
-            this.participants.delete(peerId);
-            this._pendingIceCandidates.delete(peerId);
-            this._deferredGroupPeers.delete(peerId);
+    _onInvitation(callRoomId, message, data) {
+        if (this._ledger.isRingStopped(callRoomId) || this._ringing.has(callRoomId) || this._call?.callRoomId === callRoomId) {
+            return;
+        }
+        const ring = {
+            callRoomId,
+            kind: data.kind ?? null,
+            callerId: data.hostUserId ?? message.senderId ?? null,
+            title: data.title ?? null,
+            timer: setTimeout(() => this._stopRinging(callRoomId, 'timeout'), this.ringTimeoutMs)
+        };
+        ring.timer.unref?.();
+        this._ringing.set(callRoomId, ring);
+        this.emit('incomingCall', {
+            callRoomId,
+            kind: ring.kind,
+            callerId: ring.callerId,
+            callerName: message.nickName ?? null,
+            callerProfileUrl: message.profileUrl ?? null,
+            title: ring.title
+        });
+        // incomingCall 안에서 바로 거절·받기를 했으면(통화 중 BUSY 거절·자동 응답) 울림은 이미 끝났다 — ringing 을 내지 않는다(내면 끝난
+        // 통화의 마지막 상태가 ringing 이 된다).
+        if (this._ringing.get(callRoomId) === ring) {
+            this.emit('callStateChanged', { callRoomId, state: CallState.RINGING });
         }
     }
 
-    /**
-     * 사용자 입장 처리
-     * @private
-     */
-    async _handleUserJoined(userId, roomId) {
-        this.participants.set(userId, { joinedAt: new Date() });
-
-        // userId 비교로 Polite/Impolite 결정 (작은 쪽이 Polite)
-        // Perfect Negotiation에서 충돌 시 한 쪽만 양보하도록 보장
-        const polite = this.userId < userId;
-        const defer = !!roomId && !this.peerManager.localStream;
-        this.peerManager.createPeerConnection(userId, polite, { skipAutoNegotiation: defer });
-        if (defer) this._deferredGroupPeers.set(userId, roomId);
-
-        this.emit('userJoined', { userId });
-        this.logger.info(`User joined: ${userId} (I am ${polite ? 'polite' : 'impolite'})`);
-    }
-
-    /**
-     * 사용자 퇴장 처리
-     * @private
-     */
-    _handleUserLeft(userId) {
-        this.participants.delete(userId);
-        this.peerManager.closePeerConnection(userId);
-
-        this.emit('userLeft', { userId });
-        this.logger.info(`User left: ${userId}`);
+    /** 서버가 통화를 끝냈다 — 묘비를 남기고, 울리던 것이면 울림을 끄고, 이 기기가 그 통화에 있으면(입장 진행 중 포함) 끝낸다. */
+    _endCall(callRoomId, reason) {
+        this._ledger.markEnded(callRoomId, reason);
+        this._stopRinging(callRoomId, reason);
+        if (this._call?.callRoomId === callRoomId) {
+            this._finish(this._call, reason, { callOver: true }).catch(error => this.logger.error('Call finish failed:', error));
+        }
     }
 
     /**
-     * Offer 처리
-     * @private
+     * 울림을 끈다. 받아서 끈 게 아니면 이 기기에서 그 통화가 끝난 것이다 — callStateChanged(ended)·callEnded 도 낸다(울림 시작에
+     * ringing 을 냈으니 짝을 맞춘다).
      */
-    async _handleOffer(senderId, sdp, roomId = this.isGroupCall ? this.currentRoom : null) {
-        // 피어 연결이 없으면 생성
-        if (!this.peerManager.getPeerConnection(senderId)) {
-            // userId 비교로 Polite/Impolite 결정
-            const polite = this.userId < senderId;
-            // skipAutoNegotiation: true - offer를 먼저 처리한 후 answer 전송
-            // 트랙 추가 시 자동 negotiation이 발생하면 offer 충돌 발생
-            this.peerManager.createPeerConnection(senderId, polite, { skipAutoNegotiation: true });
-            // REST join의 PEER_JOINED는 startCall보다 먼저 올 수 있다.
-            // 메시지의 roomId로 그룹을 식별하되, 1:1 수동 협상에는 적용하지 않는다.
-            if (roomId && !this.peerManager.localStream) this._deferredGroupPeers.set(senderId, roomId);
-        }
-
-        await this.peerManager.handleRemoteDescription(senderId, sdp);
-        await this._resumeGroupNegotiation(senderId);
-
-        // remoteDescription 설정 후 대기 중인 ICE candidates 처리
-        await this._processPendingIceCandidates(senderId);
-    }
-
-    async _resumeGroupNegotiation(peerId) {
-        if (!this.isGroupCall || this._deferredGroupPeers.get(peerId) !== this.currentRoom
-            || !this.peerManager.localStream) return;
-        if (await this.peerManager.resumeAutoNegotiation(peerId)) this._deferredGroupPeers.delete(peerId);
+    _stopRinging(callRoomId, reason, accepted = false) {
+        this._ledger.stopRinging(callRoomId);
+        const ring = this._ringing.get(callRoomId);
+        if (!ring) {
+            return;
+        }
+        clearTimeout(ring.timer);
+        this._ringing.delete(callRoomId);
+        this.emit('ringStopped', { callRoomId, reason });
+        if (!accepted) {
+            this.emit('callStateChanged', { callRoomId, state: CallState.ENDED, reason });
+            this.emit('callEnded', { callRoomId, reason });
+        }
     }
 
-    /** 재구독은 참가 이력을 복구하지 않는다. 동일 사용자의 다른 기기 참가도 이 조회에 반영된다. */
-    async _recoverGroupParticipation() {
-        if (!this.isGroupCall || !this.currentRoom || this._groupRecovery) return;
-        this._cancelGroupRecoveryRetry();
-        const roomId = this.currentRoom;
-        const generation = this._callGeneration;
-        const stillCurrent = () => this.currentRoom === roomId && this._callGeneration === generation;
-        const recovery = (async () => {
+    async _recheckRinging() {
+        const identity = this._identity;
+        for (const callRoomId of [...this._ringing.keys()]) {
             try {
-                const response = await this.apiClient.get(`/api/v1/webrtc/rooms/${roomId}/participation`);
-                if (!stillCurrent()) return;
-                if (!response.data.participating) {
-                    await this.joinCallRoomApi(roomId);
-                    if (!stillCurrent()) return;
-                    this._sendSignal({ type: SignalTypes.JOIN_ROOM, roomId });
+                const participation = await this.getParticipation(callRoomId);
+                if (identity !== this._identity) {
+                    return;
+                }
+                if (participation?.ring !== 'RINGING') {
+                    this._stopRinging(callRoomId, 'stale');
                 }
-                this._groupRecoveryAttempts = 0;
             } catch (error) {
-                if (!stillCurrent()) return;
-                if ([403, 404, 409].includes(error?.status ?? error?.response?.status)) {
-                    // 확정 실패만 로컬 종료한다. 다른 기기 참가를 지우는 LEAVE는 보내지 않는다.
-                    this._endCall(false);
-                    this.emit('callRecoveryFailed', { roomId, error });
+                if (identity !== this._identity) {
+                    return;
+                }
+                if (statusOf(error) === 404) {
+                    this._stopRinging(callRoomId, 'ended');
                 } else {
-                    // 일시 오류 동안 미디어·peer·구독을 유지하고 1s→2s→…→30s 간격으로 재시도한다.
-                    const delay = Math.min(30000, 1000 * 2 ** Math.min(this._groupRecoveryAttempts++, 5));
-                    this._groupRecoveryTimer = setTimeout(() => {
-                        this._groupRecoveryTimer = null;
-                        if (stillCurrent()) this._onReconnected();
-                    }, delay);
-                    this._groupRecoveryTimer.unref?.();
-                    this.logger.warn('Call participation recovery will retry:', error);
+                    this.logger.warn('Ring re-check failed, keeping the ring until timeout:', error);
                 }
             }
-        })();
-        this._groupRecovery = recovery;
-        try { await recovery; }
-        finally { if (this._groupRecovery === recovery) this._groupRecovery = null; }
-    }
-
-    _cancelGroupRecoveryRetry() {
-        clearTimeout(this._groupRecoveryTimer);
-        this._groupRecoveryTimer = null;
-    }
-
-    /**
-     * Answer 처리
-     * @private
-     */
-    async _handleAnswer(senderId, sdp) {
-        await this.peerManager.handleRemoteDescription(senderId, sdp);
-        // remoteDescription 설정 후 대기 중인 ICE candidates 처리
-        await this._processPendingIceCandidates(senderId);
+        }
     }
 
-    /**
-     * ICE Candidate 처리
-     * @private
-     */
-    async _handleIceCandidate(senderId, candidate) {
-        // peer connection이 아직 없으면 큐에 저장
-        if (!this.peerManager.getPeerConnection(senderId)) {
-            this._queueIceCandidate(senderId, candidate);
-            return;
-        }
+    // ==================== 내부: REST ====================
 
-        // addIceCandidate가 false 반환하면 (remoteDescription 미설정) 큐에 저장
-        const added = await this.peerManager.addIceCandidate(senderId, new RTCIceCandidate(candidate));
-        if (!added) {
-            this._queueIceCandidate(senderId, candidate);
+    async _createRoom(call, body) {
+        // 만들기는 멱등이 아니다(보낼 때마다 새 방) — 다시 보내지 않는다. 서버도 만들기에는 CALL_CONCURRENT_UPDATE 를 내지 않는다(insert).
+        this._requireIdentity(call.identity);
+        const room = unwrap(await this.apiClient.post(ROOMS, body));
+        if (!room?.callRoomId) {
+            throw callError(ErrorTypes.API_ERROR, 'Call room creation returned no callRoomId');
         }
-    }
-
-    /**
-     * ICE candidate를 큐에 저장
-     * @private
-     */
-    _queueIceCandidate(peerId, candidate) {
-        if (!this._pendingIceCandidates.has(peerId)) {
-            this._pendingIceCandidates.set(peerId, []);
+        this._ledger.observe(room.callRoomId, Number(room.version));
+        return room;
+    }
+
+    async _join(call) {
+        // 같은 방의 나가기·취소·거절·모두 끝내기·정리 요청이 하나도 남지 않을 때까지 기다린다(this._exits) — 기다리는 사이 새로 오른
+        // 요청(지금 통화의 모두 끝내기 등)도 기다린다.
+        for (let pending = this._exits.get(call.callRoomId); pending;) {
+            await pending;
+            if (this._call !== call) {
+                // 기다리는 사이 끝났다 — 입장을 보내지 않는다(보내면 나간 참가를 되살린다).
+                throw callError(ErrorTypes.NO_ACTIVE_CALL, 'The call ended before joining');
+            }
+            const next = this._exits.get(call.callRoomId);
+            pending = next === pending ? null : next;
         }
-        this._pendingIceCandidates.get(peerId).push(candidate);
-        this.logger.debug(`ICE candidate queued for ${peerId}`);
-    }
-
-    /**
-     * 대기 중인 ICE candidate 처리
-     * @private
-     */
-    async _processPendingIceCandidates(peerId) {
-        const candidates = this._pendingIceCandidates.get(peerId);
-        if (!candidates || candidates.length === 0) {
-            return;
+        if (this._call !== call) {
+            throw callError(ErrorTypes.NO_ACTIVE_CALL, 'The call ended before joining');
         }
-
-        this.logger.debug(`Processing ${candidates.length} pending ICE candidates for ${peerId}`);
-
-        for (const candidate of candidates) {
-            await this.peerManager.addIceCandidate(peerId, new RTCIceCandidate(candidate));
+        call.joinAttempted = true;
+        // 그 사이 이 기기가 통화를 끝냈으면 409 재시도를 멈춘다 — 다시 보내면 나간 참가를 되살린다.
+        const grant = unwrap(await this._send(call.identity, () => this.apiClient.post(`${ROOMS}/${call.callRoomId}/join`),
+            () => this._call === call));
+        if (!grant?.media?.url || !grant?.media?.token) {
+            throw callError(ErrorTypes.API_ERROR, 'Join returned no media grant');
         }
-
-        this._pendingIceCandidates.delete(peerId);
+        this._ledger.observe(call.callRoomId, Number(grant.version));
+        return grant;
     }
 
     /**
-     * 미디어 상태 처리
-     * @private
+     * 서버 요청 — 그 요청을 시작한 신원이 지금 신원일 때만 보낸다(다시 보낼 때마다 다시 본다). 409 CALL_CONCURRENT_UPDATE(서버가 이미
+     * 16번 시도한 뒤)는 같은 요청을 다시 보낸다(§5.3).
+     * @param {number} identity - 요청을 시작한 신원(통화면 call.identity)
+     * @param {() => Promise<*>} request
+     * @param {() => boolean} [stillWanted] - 다시 보내기 전에 확인 — false 면 마지막 오류를 던진다
      */
-    _handleMediaState(userId, state) {
-        this.emit('participantMediaState', {
-            userId,
-            videoEnabled: state.videoEnabled,
-            audioEnabled: state.audioEnabled
-        });
+    async _send(identity, request, stillWanted = () => true) {
+        for (let attempt = 1; ; attempt++) {
+            this._requireIdentity(identity);
+            try {
+                return await request();
+            } catch (error) {
+                if (attempt >= CONFLICT_ATTEMPTS || statusOf(error) !== 409 || error?.response?.code !== CONFLICT_CODE) {
+                    throw error;
+                }
+                await new Promise(resolve => setTimeout(resolve, 50 + Math.floor(Math.random() * 150)));
+                if (!stillWanted()) {
+                    throw error;
+                }
+            }
+        }
     }
 
     /**
-     * 통화 수락 처리 (발신자 측에서 CALL_ACCEPT 수신 시)
-     * @private
+     * 그 방의 나가기·취소·거절·정리 요청을 추적에 올린다 — 끝나면(성공·실패) 지운다. 받은 요청을 그대로 돌려준다(오류도 그대로).
+     * @param {string|null} callRoomId
+     * @param {Promise<*>} request
      */
-    async _handleCallAccepted(userId) {
-        this._directCallPeer = userId;
-        // 대기 상태 초기화
-        this._waitingForCallAccept = false;
-        this._pendingCallTarget = null;
-
-        // 이제 PeerConnection 생성 (Impolite - 발신자)
-        // skipAutoNegotiation: true - 트랙 추가 시 자동 negotiation 건너뛰고 수동으로 offer 전송
-        this.peerManager.createPeerConnection(userId, false, { skipAutoNegotiation: true });
-
-        // Offer 생성 및 전송
-        const offer = await this.peerManager.createOffer(userId);
-        this._sendSignal({
-            type: SignalTypes.CALL_OFFER,
-            receiverId: userId,
-            data: { sdp: offer }
+    _trackExit(callRoomId, request) {
+        if (!callRoomId) {
+            return request;
+        }
+        const settled = request.then(() => {}, () => {});
+        const previous = this._exits.get(callRoomId);
+        const all = previous ? Promise.all([previous, settled]).then(() => {}) : settled;
+        this._exits.set(callRoomId, all);
+        all.then(() => {
+            if (this._exits.get(callRoomId) === all) {
+                this._exits.delete(callRoomId);
+            }
         });
-
-        this.emit('callAccepted', { userId });
+        return request;
     }
 
-    /**
-     * 통화 종료 처리
-     * @private
-     */
-    _handleCallEnded(userId) {
-        this.peerManager.closePeerConnection(userId);
-        this.participants.delete(userId);
-        // 끝난 1:1 상대는 더 이상 선택한 상대가 아니다. 그룹 통화가 남아도 그의 roomId 없는 신호를 받지 않는다.
-        if (userId === this._directCallPeer) this._directCallPeer = null;
-
-        this.emit('participantLeft', { userId });
-
-        // 모든 참여자가 나갔으면 통화 종료
-        if (this.peerManager.getPeerIds().length === 0) {
-            this.endCall();
+    _requireIdentity(identity) {
+        if (this._closed || identity !== this._identity || !this.userId) {
+            throw callError(ErrorTypes.INVALID_STATE,
+                'Call request dropped: the signed-in identity changed or is changing, or the client is destroyed');
         }
     }
 
-    // ==================== 유틸리티 ====================
+    // ==================== 내부: 확인 ====================
 
-    /**
-     * 현재 통화 중인지 확인
-     * @returns {boolean}
-     */
-    isInCall() {
-        return this.currentRoom !== null || this.peerManager.getPeerIds().length > 0;
-    }
-
-    /**
-     * 현재 통화방 ID
-     * @returns {string|null}
-     */
-    getCurrentRoom() {
-        return this.currentRoom;
+    _requireCall() {
+        if (!this._call) {
+            throw callError(ErrorTypes.NO_ACTIVE_CALL, 'No active call');
+        }
+        return this._call;
     }
 
-    /**
-     * 참여자 목록
-     * @returns {string[]}
-     */
-    getParticipants() {
-        return Array.from(this.participants.keys());
+    _requireSession() {
+        const session = this._requireCall().session;
+        if (!session) {
+            throw callError(ErrorTypes.INVALID_STATE, 'Media is not connected');
+        }
+        return session;
     }
 
-    /**
-     * 연결 상태 요약
-     * @public
-     * @returns {Object}
-     */
-    // noinspection JSUnusedGlobalSymbols
-    getConnectionSummary() {
-        return this.peerManager.getConnectionSummary();
+    async _mediaCall(source, action) {
+        const session = this._requireSession();
+        try {
+            return await action(session);
+        } catch (error) {
+            // 미디어가 아직 붙지 않았다(화면 공유는 접속이 끝난 뒤에만) — 권한 거부로 보이지 않게 그대로 던진다.
+            if (error?.code === ErrorTypes.INVALID_STATE) {
+                throw error;
+            }
+            const code = source === 'screen' ? ErrorTypes.SCREEN_SHARE_DENIED : ErrorTypes.MEDIA_ACCESS_DENIED;
+            throw callError(code, `Failed to change ${source}`, error);
+        }
     }
+}
 
-    /**
-     * 특정 피어의 연결 통계 가져오기 (디버깅/모니터링용)
-     * @public
-     * @param {string} peerId - 피어 ID
-     * @returns {Promise<RTCStatsReport|null>}
-     */
-    // noinspection JSUnusedGlobalSymbols
-    async getStats(peerId) {
-        return this.peerManager.getStats(peerId);
+function requireCallRoomId(callRoomId) {
+    if (!callRoomId) {
+        throw new Error('callRoomId is required');
     }
+}
 
-    /**
-     * 미디어 상태
-     * @returns {Object}
-     */
-    getMediaState() {
-        return {
-            videoEnabled: this.mediaManager.isVideoEnabled(),
-            audioEnabled: this.mediaManager.isAudioEnabled(),
-            streamInfo: this.mediaManager.getStreamInfo()
-        };
-    }
+function unwrap(response) {
+    return response && typeof response === 'object' && 'data' in response ? response.data : response;
+}
 
-    /**
-     * 로그 레벨 설정
-     * @param {number} level
-     */
-    setLogLevel(level) {
-        this.logger.setLevel(level);
-        this.mediaManager.setLogLevel(level);
-        this.peerManager.setLogLevel(level);
-    }
+function statusOf(error) {
+    return error?.status ?? error?.response?.status;
+}
 
-    /**
-     * 리소스 정리
-     */
-    destroy() {
-        this.connectionManager.off?.('reconnected', this._onReconnected);
-        this.endCall();
-        this.mediaManager.destroy();
-        this.peerManager.destroy();
-        this.removeAllListeners();
-        this.logger.info('WebRTCClient destroyed');
+function callError(code, message, cause) {
+    const error = new Error(message);
+    error.code = code;
+    if (cause) {
+        error.cause = cause;
     }
+    return error;
 }
 
 export default WebRTCClient;