@vibexnpm/talkx 2.3.1

package/src/chat/ChatClient.js

@@ -0,0 +1,2221 @@
+// noinspection JSValidateJSDoc
+
+/**
+ * ChatClient
+ * 채팅 기능 클라이언트
+ */
+
+import EventEmitter from '../utils/EventEmitter.js';
+import Logger from '../utils/Logger.js';
+import { WebSocketPaths, LogLevel, RoomListEventType, ChatRoomType } from '../constants.js';
+
+const MAX_FILES_PER_MESSAGE = 20;
+
+class ChatClient extends EventEmitter {
+    /**
+     * @param {Object} options
+     * @param {Object} options.connectionManager - ConnectionManager 인스턴스
+     * @param {Object} options.apiClient - ApiClient 인스턴스
+     * @param {string} options.userId - 사용자 ID
+     * @param {number} [options.logLevel] - 로그 레벨
+     */
+    constructor(options) {
+        super();
+
+        this.connectionManager = options.connectionManager;
+        this.apiClient = options.apiClient;
+        this.userId = options.userId;
+
+        this.logger = new Logger(options.logLevel || LogLevel.WARN, 'ChatClient');
+
+        // 구독 중인 채팅방
+        this.subscribedRooms = new Map();
+
+        // 채팅방 리스트 구독 상태 (카톡 스타일 리스트 실시간 업데이트)
+        this.roomListSubscribed = false;
+
+        // 현재 보고 있는 채팅방 ID (이 방에서만 자동 읽음 처리)
+        this._activeRoomId = null;
+
+        // 타이핑 표시 debounce 타이머 (roomId → setTimeout ID)
+        // 이 Map 은 outgoing 전용 — 사용자가 startTyping() 호출 시 N초 후 자동 stopTyping() 발신용.
+        this._typingTimers = new Map();
+
+        // 어시스턴트 응답 준비 중 typing=true 수신 후 client-side timeout (roomId → setTimeout ID).
+        // 서버는 typing=false 를 발행하지 않으며 (멘션 N personas / 락 실패 / LLM 실패 / skip 등 종료 추적
+        // 부담 회피), SDK 가 (1) assistant 메시지 도착 시 즉시 해제 (2) 본 timeout 만료 시 자동 해제 책임.
+        // outgoing 타이머 (_typingTimers) 와 의미가 달라 별도 Map 유지.
+        this._assistantTypingTimers = new Map();
+        // 어시 typing 자동 해제 시한 (ms) — LLM 호출 최대 시간 (Sonnet 5-10초) + 부수 작업 + 여유.
+        // 운영 환경 LLM 응답 지연 분포에 따라 조정 가능.
+        this._assistantTypingTimeoutMs = 30000;
+        // 어시 typing 의 generic sender 식별자 — 서버 ChatMessageSentAssistantListener 의
+        // ASSISTANT_TYPING_USER_ID 와 정확히 일치해야 함. UI 가 roomId+userId 로 typing state 추적 시
+        // typing=true / typing=false 가 같은 키로 매칭되도록 일관 유지 필수.
+        this._assistantTypingUserId = '__assistant__';
+        this._assistantTypingUserName = 'AI';
+
+        // 메시지 dedup 보호 — 같은 messageId 의 중복 수신 차단.
+        // 서버측 멱등 race 복구 / 네트워크 재전송 / WebSocket 재연결 직후 등 다양한 중복 시나리오 커버.
+        //
+        // chat WebSocket (MESSAGE_CREATED) 와 roomList (MESSAGE_RECEIVED) 는 같은 messageId 의 별개 이벤트라
+        // 각각 다른 키 공간 사용. 정상 흐름에서 두 이벤트가 거의 동시에 도착하므로 키를 공유하면 둘 중
+        // 하나가 차단되는 부작용 발생.
+        //
+        // 구조: roomId → insertion-order Map<messageId, true> (LRU). size 초과 시 가장 오래된 항목 제거.
+        this._seenChatMessageIdsByRoom = new Map();
+        this._seenRoomListMessageIdsByRoom = new Map();
+        // 방 하나당 최근 N개의 messageId 만 dedup 대상 — 정상 흐름에서 충돌 가능성 없는 적정 크기.
+        this._maxSeenPerRoom = 200;
+    }
+
+    /**
+     * 방별 LRU dedup 체크 — 이미 본 messageId 면 {@code true} 반환 (중복).
+     * 처음 보는 messageId 면 기록 후 {@code false} 반환.
+     *
+     * <p>Map 의 insertion-order 보존 특성을 이용한 가벼운 LRU. 외부 lib 없음.</p>
+     *
+     * @private
+     * @param {Map<string, Map<string, true>>} bucket - 키 공간 (chat / roomList 별도)
+     * @param {string} roomId
+     * @param {string} messageId
+     * @returns {boolean} 이미 본 메시지면 true (호출자가 무시)
+     */
+    _shouldDedupMessage(bucket, roomId, messageId) {
+        if (!roomId || !messageId) return false;
+        let seen = bucket.get(roomId);
+        if (!seen) {
+            seen = new Map();
+            bucket.set(roomId, seen);
+        }
+        if (seen.has(messageId)) {
+            return true;
+        }
+        seen.set(messageId, true);
+        if (seen.size > this._maxSeenPerRoom) {
+            // 가장 오래된 키 제거 (Map insertion-order 의 첫 항목).
+            const oldestKey = seen.keys().next().value;
+            seen.delete(oldestKey);
+        }
+        return false;
+    }
+
+    // ==================== REST API ====================
+
+    /**
+     * 내 채팅방 목록 조회
+     * @param {Object} [params]
+     * @param {number} [params.size=50] - 페이지 크기 (1-100)
+     * @param {string} [params.lastId] - 마지막 채팅방 ID (커서)
+     * @param {number} [params.lastSortValue] - 마지막 정렬값 (epoch millis)
+     * @param {string} [params.type] - 채팅방 타입 필터 ('DIRECT' | 'GROUP'). 생략 시 전체.
+     *   'GROUP' 은 "그룹 탭" 시맨틱 — PRIVATE_GROUP/TEAM 을 포함한 그룹 전체를 반환
+     *   (PRIVATE_GROUP/TEAM 값을 보내도 동일하게 그룹 전체 — 타입별 정확 필터 아님).
+     *   특정 타입만 필요하면 응답의 {@code roomType} 필드로 클라이언트에서 거른다.
+     * @returns {Promise<Object>}
+     */
+    async getRooms(params = {}) {
+        const { size = 50, lastId, lastSortValue, type } = params;
+        return this.apiClient.get('/api/v1/rooms/my', { size, lastId, lastSortValue, type });
+    }
+
+    /**
+     * 채팅방 입장 (상세 조회).
+     *
+     * <p>서버 {@code markAllAsRead} 를 트리거하므로 방 안의 누적 unread 가 전부 읽음 처리된다.
+     * 실시간 읽음 이벤트 보정 수신이 필요하면 {@link #enterRoom} 사용을 권장 — subscribe 를
+     * {@link #getRoom} 보다 먼저 수행해서 "응답 후, 구독 전" 구간의 read 이벤트 유실을 막는다.</p>
+     *
+     * @param {string} roomId - 채팅방 ID
+     * @returns {Promise<Object>}
+     */
+    async getRoom(roomId) {
+        return this.apiClient.get(`/api/v1/rooms/${roomId}`);
+    }
+
+    /**
+     * 채팅방 진입 — <b>권장 진입 경로</b>.
+     *
+     * <p>순서를 고정해서 race-free 진입을 보장:</p>
+     * <ol>
+     *   <li><b>subscribeRoom</b> — WebSocket 구독 먼저. 서버가 발행하는 read/message/typing 이벤트의
+     *       도달을 이 시점부터 보장.</li>
+     *   <li><b>setActiveRoom</b> — 이후 수신되는 신규 메시지 자동 읽음 처리 활성화.</li>
+     *   <li><b>getRoom</b> — 서버 {@code markAllAsRead} + 초기 메시지 50개 fetch. 이 시점에 서버가
+     *       발행하는 read 이벤트는 (1) 의 구독으로 모두 수신됨.</li>
+     * </ol>
+     *
+     * <p>구독이 {@code getRoom} 보다 먼저 완료돼야 "서버에서 발행된 read 이벤트가 아직 구독 안 된
+     * 클라에 유실" 되는 케이스가 제거된다.</p>
+     *
+     * @param {string} roomId - 채팅방 ID
+     * @returns {Promise<Object>} {@link #getRoom} 의 응답 (방 상세 + 초기 메시지)
+     *
+     * @example
+     * // 방 클릭 시
+     * const detail = await client.chat.enterRoom('room-id');
+     * renderRoom(detail);
+     */
+    async enterRoom(roomId) {
+        // "이 호출이 새로 만든 구독인지" 기억 — getRoom 실패 시 rollback 시에 이전 구독은 유지.
+        const wasAlreadySubscribed = this.subscribedRooms.has(roomId);
+
+        // 1) WebSocket 구독을 먼저 — 이후 서버 read 이벤트 유실 방지
+        if (!wasAlreadySubscribed) {
+            await this.subscribeRoom(roomId);
+        }
+        // 2) 자동 읽음 처리 활성 방 지정
+        this.setActiveRoom(roomId);
+
+        try {
+            // 3) 서버 입장 API — markAllAsRead + 초기 메시지 조회
+            return await this.getRoom(roomId);
+        } catch (e) {
+            // getRoom 실패 시 half-open 상태 방지 — 이 호출이 켠 리소스만 되돌림.
+            if (this.getActiveRoom() === roomId) {
+                this.clearActiveRoom();
+            }
+            if (!wasAlreadySubscribed) {
+                this.unsubscribeRoom(roomId);
+            }
+            throw e;
+        }
+    }
+
+    /**
+     * 채팅방 정보 조회 (입장하지 않고 정보만)
+     * @param {string} roomId - 채팅방 ID
+     * @returns {Promise<Object>}
+     */
+    async getRoomInfo(roomId) {
+        return this.apiClient.get(`/api/v1/rooms/${roomId}/info`);
+    }
+
+    /**
+     * 내 방 언어 설정 (다국어). 이 방에서 내가 볼 언어를 지정한다.
+     * @param {string} roomId - 채팅방 ID
+     * @param {string|null} language - BCP-47 코드(예 'ko','en','ja') / 'OFF'(원문 보기) /
+     *   null·''(오버라이드 해제 → 사용자 기본 언어로 복귀)
+     * @returns {Promise<Object>} 갱신된 방 상세
+     */
+    async setMyRoomLanguage(roomId, language) {
+        return this.apiClient.put(`/api/v1/rooms/${roomId}/my-language`, { language });
+    }
+
+    /**
+     * 1:1 채팅방 생성/조회
+     * @param {string} friendId - 상대방 사용자 ID (projectUserId)
+     * @returns {Promise<Object>}
+     */
+    async createOneToOneRoom(friendId) {
+        return this.apiClient.post(`/api/v1/rooms/direct/${friendId}`);
+    }
+
+    /**
+     * 그룹 채팅방 생성.
+     *
+     * <p>방 타입 {@code GROUP} (공개) / {@code PRIVATE_GROUP} (비밀) / {@code TEAM} (팀) 지정 가능.
+     * 비밀방인 경우 {@code password} 필수 (서버가 bcrypt 해시로 저장). 팀방은 비밀번호 금지 —
+     * 초대 전용이라 비밀번호 개념이 없고, 멤버는 입장 시점과 무관하게 방 전체 히스토리를 본다.</p>
+     *
+     * <p>{@code invitedAssistantPersonaIds} 로 AI 어시스턴트 페르소나도 함께 추가 가능.
+     * 페르소나 ID 는 {@link #getAssistants} 로 사전 조회. 서버가 해당 프로젝트에서 사용 가능한
+     * 페르소나인지 검증 (글로벌 또는 자체/오버라이드). 활성 페르소나만 허용.</p>
+     *
+     * @param {Object} data
+     * @param {string} data.roomName - 채팅방 이름 (필수, max 100자)
+     * @param {string} [data.description] - 채팅방 설명 (max 500자)
+     * @param {string[]} [data.invitedUserIds] - 초대할 사용자 ID 배열 (max 50명)
+     * @param {string[]} [data.invitedAssistantPersonaIds] - 추가할 어시스턴트 ID 배열 (max 10개).
+     *   {@link #getAssistants} 로 조회한 어시스턴트의 {@code id} 를 전달.
+     * @param {string} [data.roomType='GROUP'] - 방 타입 ('GROUP' | 'PRIVATE_GROUP' | 'TEAM'). 기본값 'GROUP'.
+     *   'TEAM' = 초대 전용(직접 입장 불가) + 멤버 전체 히스토리 열람 + 비참여자에게 목록 비노출.
+     * @param {string} [data.password] - 비밀번호 (roomType='PRIVATE_GROUP' 일 때 필수, 4~50자.
+     *   'GROUP'/'TEAM' 에는 금지)
+     * @param {number} [data.messageRetentionHours] - 메시지 보관 기간 (시간, 1~8760). 미설정 시 무제한.
+     *   설정 시 메시지를 삭제하지 않고 조회 시 기간 필터링만 적용. 변경 시 즉시 반영.
+     * @param {string} [data.assistantMode='GENERAL'] - 어시스턴트 참여 모드
+     *   ('GENERAL' | 'PEOPLE_ONLY' | 'CALL_ONLY'). 생략 시 서버 기본값 GENERAL.
+     * @param {string} [data.roomAiType] - 방 AI 사용 방식 intent ('NONE' | 'PERSONA_MULTI' | 'PM_BACKSTAGE').
+     *   생략 시 서버가 API 키 권한 + 첨부 페르소나로 파생 (레거시 호환). {@code 'NONE'} 이면
+     *   {@code invitedAssistantPersonaIds}/{@code assistantMode} 동시 지정 불가 (서버 400).
+     *   {@code 'PM_BACKSTAGE'} 는 PM 자동부착 — persona/assistantMode 대신 {@code engagementIntensity} 로 제어.
+     *   권한 없는 값 지정 시 403.
+     *   <b>주의(함정):</b> PERSONA_MULTI 권한이 없는 PM 전용 키는 {@code roomAiType} 을 생략하면 서버 파생이
+     *   {@code 'NONE'}(사람 방)으로 떨어진다 (PM_BACKSTAGE 로 자동 승격되지 않음). {@link #getRoomAiMeta} 의
+     *   {@code availableRoomAiTypes} 로 확인한 타입을 반드시 명시 전송할 것.
+     * @param {string} [data.engagementIntensity] - PM 개입 강도 ('QUIET' | 'NORMAL' | 'ACTIVE').
+     *   {@code 'PM_BACKSTAGE'} 방 전용 — 그 외 타입에 지정 시 서버 거절. 생략 시 서버 기본값 'NORMAL'.
+     * @returns {Promise<Object>}
+     *
+     * @example
+     * // 공개 그룹방
+     * await chat.createGroupRoom({
+     *   roomName: '개발팀 잡담방',
+     *   invitedUserIds: ['user-1', 'user-2']
+     * });
+     *
+     * @example
+     * // 어시스턴트 포함 그룹방
+     * const assistants = await chat.getAssistants();
+     * // UI 에 표시하고 사용자가 선택한 id 들을 그대로 전달
+     * await chat.createGroupRoom({
+     *   roomName: '계약 검토방',
+     *   invitedUserIds: ['user-1', 'user-2'],
+     *   invitedAssistantPersonaIds: [/* 사용자가 선택한 id 배열 *\/],
+     *   assistantMode: 'GENERAL'
+     * });
+     *
+     * @example
+     * // 비밀 그룹방
+     * await chat.createGroupRoom({
+     *   roomName: '비공개 회의실',
+     *   invitedUserIds: ['user-1'],
+     *   roomType: ChatRoomType.PRIVATE_GROUP,
+     *   password: 'secret1234'
+     * });
+     *
+     * @example
+     * // 팀 채팅방 — 초대 전용 + 전체 히스토리 (중간에 들어와도 이전 대화 열람)
+     * await chat.createGroupRoom({
+     *   roomName: '백엔드팀',
+     *   invitedUserIds: ['user-1', 'user-2'],
+     *   roomType: ChatRoomType.TEAM
+     * });
+     */
+    async createGroupRoom(data) {
+        const roomType = data.roomType || ChatRoomType.GROUP;
+
+        // 클라이언트 측 사전 검증 (서버에서도 재검증됨)
+        if (roomType === ChatRoomType.PRIVATE_GROUP) {
+            if (!data.password || data.password.length < 4) {
+                throw new Error('PRIVATE_GROUP requires a password of at least 4 characters');
+            }
+        } else if (roomType === ChatRoomType.GROUP) {
+            if (data.password) {
+                throw new Error('Public GROUP rooms cannot have a password');
+            }
+        } else if (roomType === ChatRoomType.TEAM) {
+            if (data.password) {
+                throw new Error('TEAM rooms cannot have a password (invite-only)');
+            }
+        }
+
+        return this.apiClient.post('/api/v1/rooms/group', {
+            roomName: data.roomName,
+            description: data.description,
+            invitedUserIds: data.invitedUserIds,
+            roomType,
+            password: data.password,
+            messageRetentionHours: data.messageRetentionHours,
+            invitedAssistantPersonaIds: data.invitedAssistantPersonaIds,
+            assistantMode: data.assistantMode,
+            roomAiType: data.roomAiType,
+            engagementIntensity: data.engagementIntensity
+        });
+    }
+
+    /**
+     * 사용 가능한 어시스턴트 리스트 조회.
+     *
+     * <p>받은 리스트를 UI 에 표시하고, 사용자가 선택한 어시스턴트의 {@code id} 를
+     * {@link #createGroupRoom} 의 {@code invitedAssistantPersonaIds} 로 전달.</p>
+     *
+     * @returns {Promise<Array<{id: string, displayName: string, mentionKey: string, role: string}>>}
+     *
+     * @example
+     * const assistants = await chat.getAssistants();
+     * // [{ id, displayName, mentionKey, role }, ...]
+     */
+    async getAssistants() {
+        const response = await this.apiClient.get('/api/v1/assistants');
+        return this._unwrapSuccessResponse(response);
+    }
+
+    /**
+     * 현재 API 키로 생성 가능한 방 AI 타입 조회 (discovery).
+     *
+     * <p>방 생성 UI 에서 {@link #createGroupRoom} 의 {@code roomAiType} 으로 만들 수 있는 타입만 노출하는 데 사용한다.
+     * 키 권한(capability)으로 결정 — {@code 'NONE'}(사람 채팅)은 항상, {@code 'PERSONA_MULTI'}/{@code 'PM_BACKSTAGE'}
+     * 는 권한 보유 시 포함.</p>
+     *
+     * <p><b>중요:</b> 여기서 고른 타입을 {@link #createGroupRoom} 의 {@code roomAiType} 으로 <b>반드시 명시 전송</b>해야 한다.
+     * 생략하면 서버가 키 권한 + persona 로 파생하는데, PERSONA_MULTI 권한이 없는 PM 전용 키는 {@code 'NONE'}(사람 방)으로
+     * 떨어진다 (PM_BACKSTAGE 자동 승격 없음).</p>
+     *
+     * @returns {Promise<{availableRoomAiTypes: string[]}>}
+     *
+     * @example
+     * const meta = await chat.getRoomAiMeta();
+     * // meta.availableRoomAiTypes 예: ['NONE', 'PM_BACKSTAGE']
+     * // → UI 에서 이 타입들만 방 생성 옵션으로 노출, 고른 타입을 createGroupRoom 의 roomAiType 으로 명시 전송
+     */
+    async getRoomAiMeta() {
+        const response = await this.apiClient.get('/api/v1/rooms/ai-meta');
+        return this._unwrapSuccessResponse(response);
+    }
+
+    /**
+     * 어시스턴트 메시지 평점 등록 (1~5점).
+     *
+     * <p>AI 어시스턴트가 생성한 메시지({@code senderType === 'ASSISTANT'})에 대해서만 의미가 있다.
+     * UI 는 어시 메시지이면서 삭제되지 않은 메시지에만 평점 버튼을 노출하는 것을 권장한다
+     * (서버도 사람 메시지 / 삭제 메시지는 거부).</p>
+     *
+     * <p>같은 메시지를 다시 평가하면 갱신된다 (단, 서버에서 해당 평점이 아직 검토 전일 때만).</p>
+     *
+     * @param {string} roomId - 채팅방 ID
+     * @param {string} messageId - 평가할 어시스턴트 메시지의 {@code messageId}
+     * @param {number} rating - 평점 (1~5 정수)
+     * @param {string} [comment] - 자유 코멘트 (max 2000자)
+     * @returns {Promise<void>}
+     *
+     * @example
+     * await chat.rateAssistantMessage(roomId, msg.messageId, 5, '정확한 요약이었어요');
+     */
+    async rateAssistantMessage(roomId, messageId, rating, comment) {
+        // 클라이언트 측 사전 검증 (서버에서도 @Min(1)@Max(5) 재검증됨)
+        if (!Number.isInteger(rating) || rating < 1 || rating > 5) {
+            throw new Error('rating must be an integer between 1 and 5');
+        }
+
+        await this.apiClient.post(
+            `/api/v1/chat-messages/${roomId}/messages/${messageId}/rating`,
+            { rating, comment }
+        );
+    }
+
+    /**
+     * 어시스턴트로 대화 요약 (버튼 진입점, 동기).
+     *
+     * <p>지정한 페르소나가 최근 메시지 범위를 요약해 방에 어시스턴트 메시지로 broadcast 한다.
+     * HTTP 응답은 LLM 처리(수 초) 후 결과를 반환하며, 생성된 메시지는 일반 {@code chatMessage}
+     * 이벤트로도 수신된다.</p>
+     *
+     * @param {string} roomId - 채팅방 ID
+     * @param {Object} options
+     * @param {string} options.personaId - 요약을 수행할 어시스턴트 ID ({@link #getAssistants} 의 {@code id}). 필수.
+     * @param {string} [options.format] - 요약 포맷 ({@link SummarizeFormat}). 미지정 시 서버 기본값 {@code SHORT}.
+     * @param {number} [options.messageCount] - 요약 대상 최근 메시지 수 (1~50). 미지정 시 서버 기본값.
+     * @returns {Promise<{outcome: string, messageId: (string|null), detail: (string|null)}>}
+     *   {@code outcome}: {@code 'EMITTED'} (생성됨, {@code messageId} 존재) |
+     *   {@code 'SKIPPED'} / {@code 'FAILED'} ({@code detail} 에 사유).
+     *
+     * @example
+     * const result = await chat.summarizeWithAssistant(roomId, {
+     *   personaId,
+     *   format: SummarizeFormat.MINUTES,
+     *   messageCount: 30
+     * });
+     * if (result.outcome !== 'EMITTED') console.warn(result.detail);
+     */
+    async summarizeWithAssistant(roomId, options = {}) {
+        const { personaId, format, messageCount } = options;
+        if (!personaId) {
+            throw new Error('summarizeWithAssistant requires options.personaId');
+        }
+
+        const response = await this.apiClient.post(
+            `/api/v1/rooms/${roomId}/assistant/tools/summarize`,
+            { personaId, format, messageCount }
+        );
+        return this._unwrapSuccessResponse(response);
+    }
+
+    /**
+     * 어시스턴트로 특정 메시지 번역 (버튼 진입점, 동기).
+     *
+     * <p>지정한 페르소나가 {@code sourceMessageId} 메시지를 {@code targetLang} 으로 번역해
+     * 방에 어시스턴트 메시지로 broadcast 한다. 생성된 메시지는 일반 {@code chatMessage}
+     * 이벤트로도 수신된다.</p>
+     *
+     * @param {string} roomId - 채팅방 ID
+     * @param {Object} options
+     * @param {string} options.personaId - 번역을 수행할 어시스턴트 ID ({@link #getAssistants} 의 {@code id}). 필수.
+     * @param {string} options.sourceMessageId - 번역 대상 메시지의 {@code messageId}. 필수.
+     * @param {string} [options.targetLang] - 목표 언어 (예: {@code 'en'}, {@code '日本語'}). 미지정 시 서버 정책.
+     * @returns {Promise<{outcome: string, messageId: (string|null), detail: (string|null)}>}
+     *   {@code outcome}: {@code 'EMITTED'} (생성됨, {@code messageId} 존재) |
+     *   {@code 'SKIPPED'} / {@code 'FAILED'} ({@code detail} 에 사유).
+     *
+     * @example
+     * const result = await chat.translateWithAssistant(roomId, {
+     *   personaId,
+     *   sourceMessageId: msg.messageId,
+     *   targetLang: 'en'
+     * });
+     */
+    async translateWithAssistant(roomId, options = {}) {
+        const { personaId, targetLang, sourceMessageId } = options;
+        if (!personaId) {
+            throw new Error('translateWithAssistant requires options.personaId');
+        }
+        if (!sourceMessageId) {
+            throw new Error('translateWithAssistant requires options.sourceMessageId');
+        }
+
+        const response = await this.apiClient.post(
+            `/api/v1/rooms/${roomId}/assistant/tools/translate`,
+            { personaId, targetLang, sourceMessageId }
+        );
+        return this._unwrapSuccessResponse(response);
+    }
+
+    /**
+     * 방 PM 프롬프트 레이어 조회 — PM_BACKSTAGE 방 전용.
+     *
+     * <p>방 레이어는 전역 PM 프롬프트(+회사 레이어)에 <b>합성</b>되는 방 단위 추가 지시문이다 (교체 아님).
+     * 등록된 적이 없으면 404 ({@code PM_PROMPT_LAYER_NOT_FOUND}) — "아직 없음" 상태로 처리할 것.</p>
+     *
+     * <p>권한: 방 참여자 전체 조회 가능. PM_BACKSTAGE 가 아닌 방이면 400
+     * ({@code PM_PROMPT_ROOM_TYPE_UNSUPPORTED}).</p>
+     *
+     * @param {string} roomId - 채팅방 ID
+     * @returns {Promise<Object>} PmPromptLayer — {@code {id, scope:'ROOM', projectId, roomId, content, active, activeVersion, editorType, updatedAt}}
+     *
+     * @example
+     * try {
+     *     const layer = await chat.getRoomPmPrompt(roomId);
+     *     console.log(layer.active, layer.content);
+     * } catch (e) {
+     *     if (e.status === 404) {
+     *         // 레이어 미등록 — 입력 UI 노출
+     *     }
+     * }
+     */
+    async getRoomPmPrompt(roomId) {
+        const response = await this.apiClient.get(`/api/v1/rooms/${roomId}/pm-prompt`);
+        return this._unwrapSuccessResponse(response);
+    }
+
+    /**
+     * 방 PM 프롬프트 레이어 등록/수정 (upsert) — <b>방 주인(OWNER) 전용</b>.
+     *
+     * <p>저장 시 새 버전이 자동 기록된다 ({@link #getRoomPmPromptVersions}). 본문 한도 2,000자.
+     * 비주인 호출은 403 ({@code NOT_ROOM_ADMIN}).</p>
+     *
+     * @param {string} roomId - 채팅방 ID
+     * @param {string} content - 레이어 본문 (1~2,000자). 방의 목적/맥락/금지사항 등 PM 에게 줄 추가 지시문.
+     * @returns {Promise<Object>} 저장된 PmPromptLayer
+     *
+     * @example
+     * await chat.upsertRoomPmPrompt(roomId, '이 방은 모바일앱 리뉴얼 TF. 결정사항은 표로 정리해줘.');
+     */
+    async upsertRoomPmPrompt(roomId, content) {
+        if (typeof content !== 'string' || !content.trim()) {
+            throw new Error('upsertRoomPmPrompt requires non-blank content');
+        }
+        if (content.length > 2000) {
+            throw new Error('upsertRoomPmPrompt content exceeds 2000 characters');
+        }
+
+        const response = await this.apiClient.put(`/api/v1/rooms/${roomId}/pm-prompt`, { content });
+        return this._unwrapSuccessResponse(response);
+    }
+
+    /**
+     * 방 PM 프롬프트 레이어 합성 복귀 (활성화) — 방 주인(OWNER) 전용.
+     *
+     * @param {string} roomId - 채팅방 ID
+     * @returns {Promise<Object>} 변경된 PmPromptLayer ({@code active: true})
+     */
+    async activateRoomPmPrompt(roomId) {
+        const response = await this.apiClient.patch(`/api/v1/rooms/${roomId}/pm-prompt/activate`);
+        return this._unwrapSuccessResponse(response);
+    }
+
+    /**
+     * 방 PM 프롬프트 레이어 합성 제외 (비활성화, soft delete) — 방 주인(OWNER) 전용.
+     *
+     * <p>본문/이력은 보존되고 PM 응답 합성에서만 빠진다. {@link #activateRoomPmPrompt} 로 복귀.</p>
+     *
+     * @param {string} roomId - 채팅방 ID
+     * @returns {Promise<Object>} 변경된 PmPromptLayer ({@code active: false})
+     */
+    async deactivateRoomPmPrompt(roomId) {
+        const response = await this.apiClient.patch(`/api/v1/rooms/${roomId}/pm-prompt/deactivate`);
+        return this._unwrapSuccessResponse(response);
+    }
+
+    /**
+     * 방 PM 프롬프트 레이어 버전 이력 조회 — 방 참여자 전체.
+     *
+     * @param {string} roomId - 채팅방 ID
+     * @returns {Promise<Array<Object>>} 버전 목록 — 각 항목 {@code {version, content, active, editorType, createdAt}} ({@code active}=현재 활성 버전)
+     */
+    async getRoomPmPromptVersions(roomId) {
+        const response = await this.apiClient.get(`/api/v1/rooms/${roomId}/pm-prompt/versions`);
+        return this._unwrapSuccessResponse(response);
+    }
+
+    /**
+     * 방 PM 프롬프트 레이어 버전 활성화 — 방 주인(OWNER) 전용.
+     *
+     * <p>active 포인터 이동 방식 — 지정 버전을 활성으로 전환하고 라이브 본문을 그 버전으로 투영한다.
+     * <b>새 버전을 만들지 않는다</b>(버전 수 불변, 글로벌/회사/방 PM 통일 모델). 존재하지 않는
+     * 버전이면 404 ({@code PM_PROMPT_LAYER_VERSION_NOT_FOUND}).</p>
+     *
+     * @param {string} roomId - 채팅방 ID
+     * @param {number} version - 활성화할 버전 번호 ({@link #getRoomPmPromptVersions} 의 {@code version})
+     * @returns {Promise<Object>} 활성 버전이 반영된 PmPromptLayer
+     */
+    async activateRoomPmPromptVersion(roomId, version) {
+        if (!Number.isInteger(version) || version < 1) {
+            throw new Error('activateRoomPmPromptVersion requires a positive integer version');
+        }
+
+        const response = await this.apiClient.post(
+            `/api/v1/rooms/${roomId}/pm-prompt/versions/${version}/activate`
+        );
+        return this._unwrapSuccessResponse(response);
+    }
+
+    /**
+     * PM 프롬프트 합성 미리보기 — 방 참여자 전체.
+     *
+     * <p>전역(+회사)(+방) 레이어가 합성된 최종 SYSTEM 본문을 반환한다. 컨텍스트 정책 등
+     * 런타임 부착분은 미포함 — 레이어 합성 결과까지만.</p>
+     *
+     * @param {string} roomId - 채팅방 ID
+     * @returns {Promise<{composedPrompt: string}>}
+     *
+     * @example
+     * const { composedPrompt } = await chat.previewRoomPmPrompt(roomId);
+     */
+    async previewRoomPmPrompt(roomId) {
+        const response = await this.apiClient.get(`/api/v1/rooms/${roomId}/pm-prompt/preview`);
+        return this._unwrapSuccessResponse(response);
+    }
+
+    /**
+     * 그룹 채팅방 입장.
+     *
+     * <p>비밀방 ({@code PRIVATE_GROUP}) 은 최초 입장 시 또는 나갔다 재입장 시 비밀번호 필요.
+     * 이미 active 참가자라면 비밀번호 없이 재접근 가능 (서버의 fast path).</p>
+     *
+     * <p>팀방 ({@code TEAM}) 은 초대 전용 — 직접 입장 시도는 {@code TEAM_ROOM_INVITE_ONLY}(403).
+     * {@link #inviteToGroupRoom} 으로 초대받아야 입장된다 (이미 멤버면 fast path 멱등 통과).</p>
+     *
+     * @param {string} roomId - 채팅방 ID
+     * @param {string} [password] - 비밀방 입장 비밀번호 (비밀방 최초/재입장 시 필수)
+     * @returns {Promise<Object>}
+     *
+     * @example
+     * // 공개방 입장
+     * await chat.joinGroupRoom('room-id');
+     *
+     * @example
+     * // 비밀방 입장
+     * await chat.joinGroupRoom('room-id', 'secret1234');
+     */
+    async joinGroupRoom(roomId, password) {
+        const body = password ? { password } : undefined;
+        return this.apiClient.post(`/api/v1/rooms/group/${roomId}/join`, body);
+    }
+
+    /**
+     * 채팅방 나가기 (구독도 자동 해제됨)
+     * @param {string} roomId - 채팅방 ID
+     * @returns {Promise<Object>}
+     */
+    async leaveRoom(roomId) {
+        const result = await this.apiClient.post(`/api/v1/rooms/${roomId}/leave`);
+        this.unsubscribeRoom(roomId);
+        return result;
+    }
+
+    /**
+     * 그룹 채팅방 설정 수정 (방장만).
+     * @param {string} roomId - 채팅방 ID
+     * @param {Object} data - 수정할 필드 (null/undefined 이면 변경 안 함)
+     * @param {string} [data.roomName] - 방 이름
+     * @param {string} [data.description] - 설명
+     * @param {string} [data.roomType] - 공개/비공개 전환 ('GROUP' | 'PRIVATE_GROUP').
+     *   'PRIVATE_GROUP' 전환 시 password 필수, 'GROUP' 전환 시 기존 비번 제거. 생략 시 변경 안 함.
+     * @param {string} [data.password] - 비밀번호 (PRIVATE_GROUP). 공백만으로는 설정 불가, 4~50자.
+     * @param {number} [data.messageRetentionHours] - 보관 기간 (시간)
+     * @param {boolean} [data.anyoneCanInvite] - 누구나 초대 가능 여부
+     * @param {string} [data.assistantMode] - 어시스턴트 참여 모드
+     *   ('GENERAL' | 'PEOPLE_ONLY' | 'CALL_ONLY'). PERSONA_MULTI 방 전용.
+     * @param {string} [data.engagementIntensity] - PM 개입 강도 ('QUIET' | 'NORMAL' | 'ACTIVE').
+     *   PM_BACKSTAGE 방 전용 — PM 참여 레벨 변경. 키 PM_BACKSTAGE 권한 필요(없으면 403).
+     * @returns {Promise<Object>}
+     *
+     * @example
+     * // PERSONA_MULTI 방 — 어시스턴트 모드 변경
+     * await chat.updateGroupRoom('room-id', { assistantMode: 'CALL_ONLY' });
+     *
+     * @example
+     * // PM_BACKSTAGE 방 — PM 개입 강도 변경
+     * await chat.updateGroupRoom('room-id', { engagementIntensity: 'QUIET' });
+     *
+     * @example
+     * // 공개 → 비공개 전환 (비밀번호 필수)
+     * await chat.updateGroupRoom('room-id', { roomType: 'PRIVATE_GROUP', password: 'secret12' });
+     *
+     * @example
+     * // 비공개 → 공개 전환 (기존 비밀번호 제거됨)
+     * await chat.updateGroupRoom('room-id', { roomType: 'GROUP' });
+     */
+    async updateGroupRoom(roomId, data) {
+        return this.apiClient.put(`/api/v1/rooms/group/${roomId}`, data);
+    }
+
+    /**
+     * 그룹 채팅방에 회원 / 어시스턴트 추가 초대.
+     *
+     * <p>두 가지 호출 형식 지원 (backward-compat):</p>
+     * <ul>
+     *   <li>{@code inviteToGroupRoom(roomId, ['user-1', 'user-2'])} — 회원만 초대 (기존)</li>
+     *   <li>{@code inviteToGroupRoom(roomId, { userIds, assistantPersonaIds })} — 회원 + 어시 (신규)</li>
+     * </ul>
+     *
+     * @param {string} roomId - 채팅방 ID
+     * @param {string[]|{userIds?: string[], assistantPersonaIds?: string[]}} userIdsOrData
+     *   배열이면 회원 ID 목록, 객체면 {@code userIds} / {@code assistantPersonaIds}.
+     *   둘 중 하나 이상 필수.
+     * @returns {Promise<Object>}
+     *
+     * @example
+     * // 회원만
+     * await chat.inviteToGroupRoom(roomId, ['user-1', 'user-2']);
+     *
+     * @example
+     * // 회원 + 어시스턴트
+     * await chat.inviteToGroupRoom(roomId, {
+     *   userIds: ['user-3'],
+     *   assistantPersonaIds: [/* 어시스턴트 id 배열 *\/]
+     * });
+     */
+    async inviteToGroupRoom(roomId, userIdsOrData) {
+        const body = Array.isArray(userIdsOrData)
+            ? { userIds: userIdsOrData }
+            : {
+                userIds: userIdsOrData?.userIds,
+                assistantPersonaIds: userIdsOrData?.assistantPersonaIds
+            };
+        return this.apiClient.post(`/api/v1/rooms/group/${roomId}/invite`, body);
+    }
+
+    /**
+     * 그룹 채팅방에서 참가자 단순 추방 — 방 관리자(OWNER/ADMIN) 만 호출 가능.
+     *
+     * <p>대상은 방에서 제거되지만 재입장 / 재초대 가능. 영구 차단이 필요하면
+     * {@link #banMember} 사용.</p>
+     *
+     * <p>서버 응답:</p>
+     * <ul>
+     *   <li>400 {@code CANNOT_KICK_SELF} — 자기 자신 추방 시도</li>
+     *   <li>403 {@code NOT_ROOM_ADMIN} — 방장 아님</li>
+     *   <li>404 {@code USER_NOT_IN_ROOM} — 대상이 현재 참가자 아님</li>
+     * </ul>
+     *
+     * @param {string} roomId
+     * @param {string} userId - 추방할 사용자 ID
+     * @returns {Promise<Object>}
+     */
+    async kickMember(roomId, userId) {
+        return this.apiClient.delete(`/api/v1/rooms/${roomId}/members/${userId}`);
+    }
+
+    /**
+     * 그룹 채팅방에서 참가자 추방 + 영구 차단 — 방 관리자(OWNER/ADMIN) 만 호출 가능.
+     *
+     * <p>{@link #kickMember} 와 동일하게 방에서 제거하되 {@code bannedUserIds} 에 추가되어
+     * {@link #unbanMember} 호출 전까지 재입장 / 재초대가 거부된다. MVP 정책상 현재 또는
+     * 과거 참가자만 차단 가능 (선제적 차단 불가 — 404 {@code USER_NOT_IN_ROOM}).</p>
+     *
+     * @param {string} roomId
+     * @param {string} userId - 차단할 사용자 ID
+     * @returns {Promise<Object>}
+     */
+    async banMember(roomId, userId) {
+        return this.apiClient.post(`/api/v1/rooms/${roomId}/banned-members`, { userId });
+    }
+
+    /**
+     * 영구 차단 해제 — 방 관리자(OWNER/ADMIN) 만 호출 가능.
+     *
+     * <p>{@code bannedUserIds} 에서 제거만 수행. 실제 재입장은 별도 초대 / join 호출 필요.</p>
+     *
+     * @param {string} roomId
+     * @param {string} userId - 해제할 사용자 ID
+     * @returns {Promise<Object>}
+     */
+    async unbanMember(roomId, userId) {
+        return this.apiClient.delete(`/api/v1/rooms/${roomId}/banned-members/${userId}`);
+    }
+
+    /**
+     * 방의 영구 차단 사용자 목록 조회 — 방 관리자(OWNER/ADMIN) 만 호출 가능.
+     *
+     * <p>응답 각 item: {@code { userId, nickname, profileUrl }}.
+     * 일반 참가자가 호출 시 403 {@code NOT_ROOM_ADMIN}.</p>
+     *
+     * @param {string} roomId
+     * @returns {Promise<Array<{userId: string, nickname: string, profileUrl: string}>>}
+     */
+    async getBannedMembers(roomId) {
+        const response = await this.apiClient.get(`/api/v1/rooms/${roomId}/banned-members`);
+        return response && typeof response === 'object' && 'data' in response
+            ? response.data
+            : response;
+    }
+
+    /**
+     * 메시지 고정 (방장만).
+     * @param {string} roomId - 채팅방 ID
+     * @param {string} messageId - 고정할 메시지 ID
+     * @returns {Promise<Object>}
+     */
+    async pinMessage(roomId, messageId) {
+        return this.apiClient.post(`/api/v1/rooms/group/${roomId}/pin/${messageId}`);
+    }
+
+    /**
+     * 메시지 고정 해제 (방장만).
+     * @param {string} roomId - 채팅방 ID
+     * @returns {Promise<Object>}
+     */
+    async unpinMessage(roomId) {
+        return this.apiClient.post(`/api/v1/rooms/group/${roomId}/unpin`);
+    }
+
+    /**
+     * 이모지 리액션 토글.
+     * <p>한 사용자는 메시지당 하나의 이모지만 보유.
+     * 같은 이모지 재전송 시 해제, 다른 이모지 전송 시 교체.</p>
+     * @param {string} roomId - 채팅방 ID
+     * @param {string} messageId - 메시지 ID
+     * @param {string} emoji - 이모지 (예: "👍", "😂")
+     * @returns {Promise<Object>}
+     */
+    async toggleReaction(roomId, messageId, emoji) {
+        return this.apiClient.post(`/api/v1/chat-messages/${roomId}/messages/${messageId}/reaction`, { emoji });
+    }
+
+    /**
+     * 참가 가능한 그룹 채팅방 목록 조회
+     * @param {Object} [params]
+     * @param {number} [params.size=50] - 페이지 크기
+     * @param {string} [params.lastId] - 마지막 채팅방 ID
+     * @param {number} [params.lastSortValue] - 마지막 정렬값
+     * @returns {Promise<Object>}
+     */
+    async getAvailableGroupRooms(params = {}) {
+        const { size = 50, lastId, lastSortValue } = params;
+        return this.apiClient.get('/api/v1/rooms/groups/available', { size, lastId, lastSortValue });
+    }
+
+    /**
+     * 모든 그룹 채팅방 목록 조회
+     * @param {Object} [params]
+     * @param {number} [params.size=50] - 페이지 크기
+     * @param {string} [params.lastId] - 마지막 채팅방 ID
+     * @param {number} [params.lastSortValue] - 마지막 정렬값
+     * @returns {Promise<Object>}
+     */
+    async getAllGroupRooms(params = {}) {
+        const { size = 50, lastId, lastSortValue } = params;
+        return this.apiClient.get('/api/v1/rooms/groups/all', { size, lastId, lastSortValue });
+    }
+
+    /**
+     * 메시지 목록 조회
+     * @param {string} roomId - 채팅방 ID
+     * @param {Object} [params]
+     * @param {number} [params.size=50] - 페이지 크기 (1-100)
+     * @param {string} [params.lastId] - 마지막 메시지 ID (커서)
+     * @param {number} [params.lastSortValue] - 마지막 정렬값 (epoch millis)
+     * @returns {Promise<Object>}
+     */
+    async getMessages(roomId, params = {}) {
+        const { size = 50, lastId, lastSortValue } = params;
+        const response = await this.apiClient.get(
+            `/api/v1/chat-messages/${roomId}/list`, { size, lastId, lastSortValue }
+        );
+        // REST 와 WebSocket 의 타임스탬프 직렬화가 다르다 (REST=ISO 문자열, WS=epoch number).
+        // 선언된 타입(number)으로 통일 — 기존 응답 구조(envelope)는 그대로 둔다.
+        const page = this._unwrapSuccessResponse(response);
+        if (page && Array.isArray(page.content)) {
+            page.content.forEach((m) => this._normalizeMessageTimestamps(m));
+        }
+        return response;
+    }
+
+    /**
+     * 링크 미리보기 조회.
+     *
+     * <p>서버가 OG / Twitter Card / HTML fallback 을 파싱해 미리보기 카드를 반환합니다.
+     * 외부 사이트 차단 등으로 HTML 을 못 가져오면 공개 DNS 로 확인되는 URL 에 한해
+     * 도메인 + favicon 기반 최소 카드를 반환할 수 있습니다.
+     * 이 경우 {@code previewSource} 는 {@code FAVICON_FALLBACK} 입니다.
+     * 미리보기를 만들 수 없는 URL 이면 {@code null} 을 반환합니다.</p>
+     *
+     * <p>민감한 URL 이 query string 으로 남지 않도록 POST body 로 호출합니다.</p>
+     *
+     * @param {string} url - 미리보기를 조회할 URL
+     * @returns {Promise<Object|null>} LinkPreview 또는 null
+     */
+    async fetchLinkPreview(url) {
+        const normalizedUrl = typeof url === 'string' ? url.trim() : '';
+        if (!normalizedUrl) {
+            throw new Error('url is required');
+        }
+
+        const response = await this.apiClient.post('/api/v1/link-preview', {
+            url: normalizedUrl
+        });
+
+        return this._unwrapSuccessResponse(response);
+    }
+
+    /**
+     * 메시지 전송 (REST API).
+     *
+     * <p>멱등 POST — SDK 가 내부에서 UUID 를 자동 생성하며, 호출자는 {@code messageId} 를
+     * 지정할 수 없다. 같은 요청의 네트워크 재시도(SDK 내부 구현 시) 에도 같은 UUID 가 쓰이도록
+     * 설계된다. 서버 Unique 제약 + pre-check 로 중복 저장이 차단되며, 재시도 히트 시
+     * {@code duplicate: true} 로 기존 결과가 그대로 반환된다.</p>
+     *
+     * <p>파일 분리 시 ({@code separateFiles: true}) 하나의 요청이 여러 메시지로 저장된다.
+     * 각 메시지는 고유한 서버 {@code messageId} 를 가지며 응답의 {@code messages} 배열로 전달된다.</p>
+     *
+     * <p>답글: {@code data.replyToMessageId} 에 원본 메시지의 서버 {@code messageId} 를 지정.
+     * 서버가 원본을 조회해서 snapshot 을 생성 후 저장하며, 응답/수신 메시지의 {@code replyTo}
+     * 필드에 원본 요약이 포함됨. 원본이 존재하지 않으면 서버가 400 (REPLY_TARGET_NOT_FOUND) 반환.</p>
+     *
+     * @param {string} roomId - 채팅방 ID
+     * @param {Object} data
+     * @param {string} [data.message] - 메시지 내용 (message 또는 fileInfos 중 하나 필수)
+     * @param {Object[]} [data.fileInfos] - 파일 메타데이터 배열
+     * @param {boolean} [data.separateFiles=true] - 파일 분리 여부
+     * @param {string} [data.replyToMessageId] - 답글 대상 원본 메시지 ID (옵션)
+     * @returns {Promise<{duplicate: boolean, messages: Object[]}>}
+     *   - {@code duplicate}: 멱등 재시도로 기존 결과를 반환한 경우 {@code true}
+     *   - {@code messages}: 저장된 메시지 배열 (파일 분리 시 여러 개). 각 원소의 {@code messageId} 는 서버가 부여한 고유 ID.
+     *
+     * @example
+     * // 일반 메시지
+     * const { messages } = await chat.sendMessage('room-id', { message: '안녕하세요' });
+     * console.log(messages[0].messageId);  // 서버가 생성한 ID — 답글/삭제/리액션에 사용
+     *
+     * @example
+     * // 답글
+     * await chat.sendMessage('room-id', {
+     *   message: '네 동감이에요',
+     *   replyToMessageId: 'original-msg-id'
+     * });
+     *
+     * @example
+     * // 파일 분리 전송 — messages 배열에 텍스트 + 파일별 메시지가 모두 담김
+     * const { messages } = await chat.sendMessage('room-id', {
+     *   message: '사진 보냅니다',
+     *   fileInfos: [f0, f1, f2],
+     *   separateFiles: true
+     * });
+     * // messages.length === 4 (텍스트 1 + 이미지 3)
+     */
+    async sendMessage(roomId, data) {
+        const messageId = this._generateMessageId();
+        return this._sendMessageWithId(roomId, messageId, data);
+    }
+
+    /**
+     * 메시지 전송 — Optimistic UI 버전.
+     *
+     * <p>{@link #sendMessage} 와 동일하게 서버에 메시지를 전송하지만, 호출 즉시
+     * SDK 가 생성한 {@code baseMessageId} 와 응답 {@code messages} 배열과 1-1 매칭되는
+     * 예측 {@code messageIds} 배열을 동기 반환한다. 호출자는 promise 가 resolve 되기 전에
+     * 미리 placeholder 메시지를 UI 에 그려둘 수 있고, resolve 후 같은 ID 로 안전하게 교체할 수 있다.</p>
+     *
+     * <p>{@code messageIds} 는 서버의 messageId derivation 규칙 (텍스트=base, 파일=base#N) 을
+     * SDK 가 mirror 하여 사전 계산한 값이다. 정상 케이스에서는 응답
+     * {@code messages.map(m => m.messageId)} 와 길이/순서가 정확히 일치한다.</p>
+     *
+     * <p><b>분류 규칙 drift 방어</b>: 서버 파일 분류 규칙이 변경되어 예측이 어긋나면
+     * SDK 가 warn 로그를 남기며, 이 경우 응답의 실제 {@code messageId} 로 reconcile 해야 한다.</p>
+     *
+     * @param {string} roomId - 채팅방 ID
+     * @param {Object} data - {@link #sendMessage} 와 동일한 페이로드
+     * @returns {{baseMessageId: string, messageIds: string[], promise: Promise<{duplicate: boolean, messages: Object[]}>}}
+     *
+     * @example
+     * const { messageIds, promise } = chat.sendMessageOptimistic('room-id', {
+     *   message: '안녕하세요'
+     * });
+     * messageIds.forEach(id => appendMessage({ messageId: id, status: 'sending' }));
+     * try {
+     *   const { messages } = await promise;
+     *   messages.forEach(m => replaceMessage(m.messageId, m));
+     * } catch (e) {
+     *   messageIds.forEach(id => markMessageFailed(id, e));
+     * }
+     */
+    sendMessageOptimistic(roomId, data) {
+        const baseMessageId = this._generateMessageId();
+        const messageIds = this._predictMessageIdsFromData(baseMessageId, data);
+
+        const promise = this._sendMessageWithId(roomId, baseMessageId, data)
+            .then((result) => this._attachOptimisticMetadata(messageIds, result));
+
+        return { baseMessageId, messageIds, promise };
+    }
+
+    /**
+     * messageId 를 외부에서 주입받아 실제 send API 를 호출하는 내부 메서드.
+     * <p>{@link #sendMessage} 와 {@link #sendMessageOptimistic} 가 공유하는 단일 코어 — base messageId 를
+     * 양쪽이 같은 값으로 사용해야 optimistic 핸들의 예측 ID 가 서버 저장 ID 와 일치한다.</p>
+     *
+     * @private
+     * @param {string} roomId
+     * @param {string} messageId - SDK 가 생성한 base messageId (UUID)
+     * @param {Object} data
+     * @returns {Promise<{duplicate: boolean, messages: Object[]}>}
+     */
+    async _sendMessageWithId(roomId, messageId, data) {
+        // 메시지 전송 시 타이핑 표시 자동 중단
+        this.stopTyping(roomId);
+
+        // separateFiles 는 SDK 가 명시 전송 — 서버 default 가 변경되어도 SDK 의 prediction
+        // 가정 (`undefined === true`) 과 wire 값이 어긋나지 않도록 fix.
+        const response = await this.apiClient.post(`/api/v1/chat-messages/${roomId}/send`, {
+            messageId,
+            message: data.message,
+            fileInfos: data.fileInfos,
+            separateFiles: data.separateFiles !== false,
+            replyToMessageId: data.replyToMessageId
+        });
+
+        const result = this._unwrapSuccessResponse(response);
+        if (result && Array.isArray(result.messages)) {
+            result.messages.forEach((m) => this._normalizeMessageTimestamps(m));
+        }
+        return result;
+    }
+
+    /**
+     * 텍스트 메시지 전송 (간편 버전).
+     *
+     * @param {string} roomId - 채팅방 ID
+     * @param {string} message - 메시지 내용
+     * @returns {Promise<{duplicate: boolean, messages: Object[]}>}
+     *
+     * @example
+     * const { messages } = await chat.sendTextMessage('room-id', '안녕하세요');
+     * console.log(messages[0].messageId);
+     */
+    async sendTextMessage(roomId, message) {
+        return this.sendMessage(roomId, { message });
+    }
+
+    /**
+     * 텍스트 메시지 전송 — Optimistic UI 버전.
+     *
+     * @param {string} roomId - 채팅방 ID
+     * @param {string} message - 메시지 내용
+     * @returns {{baseMessageId: string, messageIds: string[], promise: Promise<{duplicate: boolean, messages: Object[]}>}}
+     *
+     * @example
+     * const { baseMessageId, promise } = chat.sendTextMessageOptimistic('room-id', '안녕');
+     * appendMessage({ messageId: baseMessageId, content: '안녕', status: 'sending' });
+     * const { messages } = await promise;
+     * replaceMessage(baseMessageId, messages[0]);
+     */
+    sendTextMessageOptimistic(roomId, message) {
+        return this.sendMessageOptimistic(roomId, { message });
+    }
+
+    /**
+     * 채팅 첨부 파일 업로드 (Low-level).
+     *
+     * <p>파일 바이트를 서버로 업로드하고 서버가 생성한 {@code FileMetaData} 를 반환.
+     * 반환값은 {@link #sendMessage} 의 {@code fileInfos} 에 그대로 넣어 전송.</p>
+     *
+     * <p>업로드와 메시지 전송을 분리 호출해야 하는 케이스 (업로드 후 프리뷰 표시 →
+     * 사용자가 전송 버튼 클릭 시 메시지 전송 등) 에 사용. 한 번에 처리하려면
+     * {@link #sendFileMessage} 가 편리.</p>
+     *
+     * @param {string} roomId - 업로드 대상 채팅방 ID (권한 검증 + S3 namespace)
+     * @param {File|Blob} file - 업로드할 파일
+     * @param {Object} [options]
+     * @param {Function} [options.onProgress] - {@code ({loaded, total, percent}) => void} — 진행률 콜백
+     * @param {AbortSignal} [options.signal] - 업로드 취소용 AbortSignal
+     * @returns {Promise<Object>} FileMetaData (fileId/fileUrl/fileName/fileType/fileSize/imageInfo/videoInfo/audioInfo/documentInfo)
+     *
+     * @example
+     * const meta = await chat.uploadFile('room-id', fileInput.files[0], {
+     *   onProgress: ({ percent }) => console.log(`${percent}%`)
+     * });
+     * await chat.sendMessage('room-id', {
+     *   fileInfos: [meta],
+     *   message: '첨부합니다'
+     * });
+     */
+    async uploadFile(roomId, file, options = {}) {
+        if (!roomId) {
+            throw new Error('roomId is required');
+        }
+        if (!file) {
+            throw new Error('file is required');
+        }
+
+        const response = await this.apiClient.upload(
+            `/api/v1/files/${roomId}/upload`,
+            file,
+            {
+                onProgress: options.onProgress,
+                signal: options.signal
+            }
+        );
+
+        // 서버 SuccessResponse 래퍼 안의 data 가 FileMetaData
+        return this._unwrapSuccessResponse(response);
+    }
+
+    /**
+     * 파일 업로드 + 메시지 전송 통합 (High-level).
+     *
+     * <p>내부적으로:</p>
+     * <ol>
+     *     <li>각 파일을 {@link #uploadFile} 로 업로드 (배열이면 병렬)</li>
+     *     <li>수신된 {@code FileMetaData} 들을 모아 {@link #sendMessage} 로 전송</li>
+     * </ol>
+     *
+     * <p>업로드 중 하나라도 실패하면 전체 rejected — 이미 업로드된 S3 객체는
+     * 고아로 남으며 라이프사이클 정책으로 정리됨 (설계 결정).</p>
+     *
+     * @param {string} roomId - 채팅방 ID
+     * @param {File|Blob|Array<File|Blob>} files - 단일 파일 또는 파일 배열
+     * @param {Object} [options]
+     * @param {string} [options.message] - 함께 보낼 텍스트 본문
+     * @param {boolean} [options.separateFiles] - 파일별 개별 메시지 분리 여부 (서버 설정)
+     * @param {string} [options.replyToMessageId] - 답글 대상 원본 메시지의 서버 {@code messageId}
+     * @param {Function} [options.onUploadProgress] - {@code ({loaded,total,percent,fileIndex}) => void} — 파일별 진행률
+     * @param {AbortSignal} [options.signal] - 취소 시그널 — 업로드 중에만 유효
+     * @returns {Promise<{duplicate: boolean, messages: Object[]}>}
+     *
+     * @example
+     * // 단일 파일
+     * await chat.sendFileMessage('room-id', file, {
+     *   message: '첨부',
+     *   onUploadProgress: ({ percent }) => console.log(`${percent}%`)
+     * });
+     *
+     * @example
+     * // 다중 파일 (병렬 업로드)
+     * await chat.sendFileMessage('room-id', [file1, file2, file3], {
+     *   message: '여러 파일',
+     *   onUploadProgress: ({ fileIndex, percent }) =>
+     *     console.log(`파일 ${fileIndex}: ${percent}%`)
+     * });
+     */
+    async sendFileMessage(roomId, files, options = {}) {
+        const fileArray = this._normalizeFileArray(files);
+        const metas = await this._uploadFiles(roomId, fileArray, options);
+        const fileInfos = this._applyFileMetadata(metas, options.metadata);
+
+        return this.sendMessage(roomId, {
+            message: options.message,
+            fileInfos,
+            separateFiles: options.separateFiles,
+            replyToMessageId: options.replyToMessageId
+        });
+    }
+
+    /**
+     * 파일 업로드 + 메시지 전송 — Optimistic UI 버전.
+     *
+     * <p>호출 즉시 {@code baseMessageId} 와 응답 {@code messages} 와 1-1 매칭되는 예측
+     * {@code messageIds} 를 동기 반환한다. 호출자는 업로드 시작 전에 placeholder 메시지를
+     * UI 에 그릴 수 있다.</p>
+     *
+     * <p><b>입력 검증은 동기 throw</b>: 빈 배열 / max 초과 등 {@link #_normalizeFileArray} 의
+     * 검증 실패는 promise 가 만들어지기 전에 즉시 throw 되므로, 잘못된 입력에 대해 placeholder 가
+     * 먼저 그려지는 일은 없다.</p>
+     *
+     * <p><b>업로드 실패 처리</b>: 업로드 단계에서 실패하면 promise 가 reject 된다. 호출자는 UI 의
+     * placeholder 들을 모두 실패 상태로 표시하고, S3 에 부분 업로드된 객체는 라이프사이클 정책으로 정리된다.</p>
+     *
+     * @param {string} roomId
+     * @param {File|Blob|Array<File|Blob>} files
+     * @param {Object} [options] - {@link #sendFileMessage} 와 동일
+     * @returns {{baseMessageId: string, messageIds: string[], promise: Promise<{duplicate: boolean, messages: Object[]}>}}
+     *
+     * @example
+     * const { messageIds, promise } = chat.sendFileMessageOptimistic('room-id', files, {
+     *   message: '사진 보냅니다'
+     * });
+     * messageIds.forEach((id, i) => appendMessage({
+     *   messageId: id,
+     *   localFile: files[i] || null,
+     *   status: 'uploading'
+     * }));
+     * try {
+     *   const { messages } = await promise;
+     *   messages.forEach(m => replaceMessage(m.messageId, m));
+     * } catch (e) {
+     *   messageIds.forEach(id => markMessageFailed(id, e));
+     * }
+     */
+    sendFileMessageOptimistic(roomId, files, options = {}) {
+        // validation 은 동기 — placeholder 가 그려지기 전에 throw 되어야 함
+        const fileArray = this._normalizeFileArray(files);
+
+        const baseMessageId = this._generateMessageId();
+        const messageIds = this._predictMessageIds(
+            baseMessageId,
+            this._predictGroupCount(fileArray, options.separateFiles !== false),
+            this._hasTextMessage(options.message)
+        );
+
+        const promise = (async () => {
+            const metas = await this._uploadFiles(roomId, fileArray, options);
+            const fileInfos = this._applyFileMetadata(metas, options.metadata);
+            const result = await this._sendMessageWithId(roomId, baseMessageId, {
+                message: options.message,
+                fileInfos,
+                separateFiles: options.separateFiles,
+                replyToMessageId: options.replyToMessageId
+            });
+            return this._attachOptimisticMetadata(messageIds, result);
+        })();
+
+        return { baseMessageId, messageIds, promise };
+    }
+
+    /**
+     * 파일 입력 정규화 — 단일 파일 / 배열 양쪽 허용 + 개수 검증.
+     * <p>{@link #sendFileMessage} 와 {@link #sendFileMessageOptimistic} 가 공유.</p>
+     *
+     * @private
+     * @param {File|Blob|Array<File|Blob>} files
+     * @returns {Array<File|Blob>}
+     * @throws {Error} 빈 배열 또는 MAX_FILES_PER_MESSAGE 초과
+     */
+    _normalizeFileArray(files) {
+        const fileArray = Array.isArray(files) ? files : [files];
+        if (fileArray.length === 0) {
+            throw new Error('At least one file is required');
+        }
+        if (fileArray.length > MAX_FILES_PER_MESSAGE) {
+            throw new Error(`A maximum of ${MAX_FILES_PER_MESSAGE} files can be sent in one message`);
+        }
+        return fileArray;
+    }
+
+    /**
+     * 파일 배열 병렬 업로드 — 각 파일의 진행률은 fileIndex 로 구분.
+     * <p>{@link #sendFileMessage} 와 {@link #sendFileMessageOptimistic} 가 공유.</p>
+     *
+     * @private
+     * @param {string} roomId
+     * @param {Array<File|Blob>} fileArray
+     * @param {Object} options - signal, onUploadProgress 사용
+     * @returns {Promise<Object[]>} FileMetaData 배열
+     */
+    async _uploadFiles(roomId, fileArray, options = {}) {
+        return Promise.all(
+            fileArray.map((file, index) =>
+                this.uploadFile(roomId, file, {
+                    signal: options.signal,
+                    onProgress: options.onUploadProgress
+                        ? (p) => options.onUploadProgress({ ...p, fileIndex: index })
+                        : undefined
+                })
+            )
+        );
+    }
+
+    /**
+     * 업로드된 FileMetaData 배열에 고객사 pass-through metadata 를 병합.
+     *
+     * <p>{@link #sendFileMessage} / {@link #sendFileMessageOptimistic} 가 공유.
+     * 호출자가 {@code options.metadata} 를 안 주면 metas 가 그대로 반환되어 기존 동작과 100% 호환.</p>
+     *
+     * @private
+     * @param {Object[]} metas - uploadFile 결과의 FileMetaData 배열
+     * @param {Object|Array<Object|null|undefined>|null|undefined} metadata - 단일 객체(broadcast) 또는 index 별 배열
+     * @returns {Object[]} metadata 가 병합된 새 배열 (기존 meta 객체는 수정하지 않음)
+     */
+    _applyFileMetadata(metas, metadata) {
+        if (metadata === undefined || metadata === null) {
+            return metas;
+        }
+
+        return metas.map((meta, index) => {
+            const itemMetadata = Array.isArray(metadata)
+                ? metadata[index]
+                : metadata;
+
+            if (itemMetadata === undefined || itemMetadata === null) {
+                return meta;
+            }
+
+            return {
+                ...meta,
+                metadata: itemMetadata
+            };
+        });
+    }
+
+    /**
+     * 답글 전송 (간편 버전) — 텍스트 답글 전용.
+     *
+     * @param {string} roomId - 채팅방 ID
+     * @param {string} message - 답글 내용
+     * @param {string} replyToMessageId - 원본 메시지의 서버 {@code messageId}
+     * @returns {Promise<{duplicate: boolean, messages: Object[]}>}
+     *
+     * @example
+     * // "안녕하세요" 메시지에 답장
+     * await chat.sendReply('room-id', '네 반가워요', 'original-msg-id');
+     */
+    async sendReply(roomId, message, replyToMessageId) {
+        return this.sendMessage(roomId, { message, replyToMessageId });
+    }
+
+    /**
+     * 답글 전송 — Optimistic UI 버전.
+     *
+     * @param {string} roomId - 채팅방 ID
+     * @param {string} message - 답글 내용
+     * @param {string} replyToMessageId - 원본 메시지의 서버 {@code messageId}
+     * @returns {{baseMessageId: string, messageIds: string[], promise: Promise<{duplicate: boolean, messages: Object[]}>}}
+     */
+    sendReplyOptimistic(roomId, message, replyToMessageId) {
+        return this.sendMessageOptimistic(roomId, { message, replyToMessageId });
+    }
+
+    /**
+     * 메시지 삭제.
+     *
+     * @param {string} roomId - 채팅방 ID
+     * @param {string} messageId - 메시지 ID
+     * @param {string} [deleteType='ALL'] - 삭제 유형.
+     *   {@code 'ALL'} — 모두에게 삭제 (양쪽 "삭제된 메시지입니다" 표시).
+     *   {@code 'SELF'} — 나만 삭제 (내 화면에서만 숨김, 상대방은 원본 유지).
+     * @returns {Promise<Object>}
+     *
+     * @example
+     * // 모두에게 삭제
+     * await chat.deleteMessage('room-id', 'msg-id');
+     *
+     * @example
+     * // 나만 삭제
+     * await chat.deleteMessage('room-id', 'msg-id', 'SELF');
+     */
+    async deleteMessage(roomId, messageId, deleteType = 'ALL') {
+        return this.apiClient.post(`/api/v1/chat-messages/${roomId}/messages/${messageId}/delete`, {
+            deleteType
+        });
+    }
+
+    /**
+     * 메시지 수정.
+     *
+     * <p>본인 메시지만 수정 가능. 수정 후 '수정됨' 라벨이 표시됩니다.</p>
+     *
+     * @param {string} roomId - 채팅방 ID
+     * @param {string} messageId - 메시지 ID
+     * @param {string} message - 수정할 내용 (max 5000자)
+     * @returns {Promise<Object>}
+     *
+     * @example
+     * await chat.editMessage('room-id', 'msg-id', '수정된 내용입니다');
+     */
+    async editMessage(roomId, messageId, message) {
+        return this.apiClient.put(`/api/v1/chat-messages/${roomId}/messages/${messageId}`, {
+            message
+        });
+    }
+
+    /**
+     * 서버의 {@code SendMessageService.hasTextMessage} mirror — null/공백 문자열을 모두 "텍스트 없음" 으로 취급.
+     * <p>서버 기준 ({@code message != null && !message.isBlank()}) 과 동일해야 messageIds prediction 이 일치한다.</p>
+     *
+     * @private
+     * @param {string|null|undefined} message
+     * @returns {boolean}
+     */
+    _hasTextMessage(message) {
+        return typeof message === 'string' && message.trim().length > 0;
+    }
+
+    /**
+     * MIME 타입 → 서버 {@code ChatMessageType} 분류 (서버 {@code FileGroupingService.classifyFileType} mirror).
+     * <p>서버 도메인 규칙과 동일해야 group count 예측이 일치한다. 서버 변경 시 본 메서드도 동기화 필요.</p>
+     *
+     * @private
+     * @param {string} mimeType
+     * @returns {string} 'IMAGE' | 'VIDEO' | 'AUDIO' | 'DOCUMENT' | 'FILE'
+     */
+    _classifyFileType(mimeType) {
+        const mime = (mimeType || '').toLowerCase();
+        if (mime.startsWith('image/')) return 'IMAGE';
+        if (mime.startsWith('video/')) return 'VIDEO';
+        if (mime.startsWith('audio/')) return 'AUDIO';
+        if (mime.includes('pdf') || mime.includes('document')) return 'DOCUMENT';
+        return 'FILE';
+    }
+
+    /**
+     * 파일 그룹 수 예측 (서버 {@code FileGroupingService.groupFiles} mirror).
+     * <p>{@code separateFiles=true} 면 파일 개수, {@code false} 면 타입별 distinct 개수.
+     * File 객체 ({@code .type}) / FileMetaData 객체 ({@code .fileType}) 양쪽 입력 모두 처리.</p>
+     *
+     * @private
+     * @param {Array<File|Blob|Object>} fileArray
+     * @param {boolean} separateFiles
+     * @returns {number}
+     */
+    _predictGroupCount(fileArray, separateFiles) {
+        if (!fileArray || fileArray.length === 0) return 0;
+        if (separateFiles) return fileArray.length;
+
+        // 입력 순서 보존하면서 distinct 타입 카운트 (서버 LinkedHashMap 동작과 동일)
+        const typesSeen = new Set();
+        for (const file of fileArray) {
+            const mime = file && (file.type || file.fileType) || '';
+            typesSeen.add(this._classifyFileType(mime));
+        }
+        return typesSeen.size;
+    }
+
+    /**
+     * 서버 저장 messageId 배열 예측 (서버 {@code SendMessageService} mirror).
+     * <p>규칙 ({@code SendMessageService.java:102-106, 197}):
+     * {@code expectedMessageCount = (hasMessage?1:0) + groupCount}, 1 이면 base, 2 이상이면
+     * 텍스트=base / 파일=base#0..#(N-1).</p>
+     *
+     * @private
+     * @param {string} baseMessageId
+     * @param {number} groupCount
+     * @param {boolean} hasMessage
+     * @returns {string[]} 응답 messages 와 같은 순서
+     */
+    _predictMessageIds(baseMessageId, groupCount, hasMessage) {
+        const expectedCount = (hasMessage ? 1 : 0) + groupCount;
+        if (expectedCount === 0) return [];
+        if (expectedCount === 1) return [baseMessageId];
+
+        const ids = [];
+        if (hasMessage) ids.push(baseMessageId);
+        for (let i = 0; i < groupCount; i++) {
+            ids.push(`${baseMessageId}#${i}`);
+        }
+        return ids;
+    }
+
+    /**
+     * {@code SendMessageData} 페이로드로부터 messageIds 예측.
+     * <p>{@link #sendMessageOptimistic} 가 사용 — {@code data.fileInfos} 가 있으면 그걸로
+     * group count 예측, 없으면 텍스트 단건으로 처리.</p>
+     *
+     * @private
+     */
+    _predictMessageIdsFromData(baseMessageId, data) {
+        const fileInfos = (data && data.fileInfos) || [];
+        const separate = !data || data.separateFiles !== false;
+        const groupCount = this._predictGroupCount(fileInfos, separate);
+        const hasMessage = this._hasTextMessage(data && data.message);
+        return this._predictMessageIds(baseMessageId, groupCount, hasMessage);
+    }
+
+    /**
+     * 예측 messageIds 와 서버 응답을 비교하여 result 에 optimistic metadata 첨부.
+     * <p>서버 분류 규칙 drift 를 런타임에 감지하기 위한 방어 로직. mismatch 발생 시
+     * warn 로그 + 응답에 {@code optimistic.predictionMatched: false} 를 실어 호출자가
+     * 프로그래밍적으로 fallback reconcile 을 결정할 수 있게 한다.</p>
+     *
+     * <p>길이 mismatch 와 같은 길이의 값/순서 mismatch 모두 동일하게 {@code predictionMatched: false}
+     * 로 표시된다. 호출자는 README "Drift 방어" 섹션의 fallback 패턴을 사용하면 된다.</p>
+     *
+     * @private
+     * @param {string[]} predictedMessageIds
+     * @param {{duplicate: boolean, messages: Array<{messageId: string}>}} result
+     * @returns {{duplicate: boolean, messages: Array, optimistic: {predictedMessageIds: string[], actualMessageIds: string[], predictionMatched: boolean}}}
+     */
+    _attachOptimisticMetadata(predictedMessageIds, result) {
+        const actualMessageIds = (result && Array.isArray(result.messages))
+            ? result.messages.map(m => (m && m.messageId) || null)
+            : [];
+
+        const predictionMatched =
+            actualMessageIds.length === predictedMessageIds.length &&
+            predictedMessageIds.every((id, i) => id === actualMessageIds[i]);
+
+        if (!predictionMatched) {
+            this.logger.warn('Optimistic messageId prediction mismatch — server may have changed grouping rules. Use result.optimistic.actualMessageIds to reconcile.', {
+                predicted: predictedMessageIds,
+                actual: actualMessageIds
+            });
+        }
+
+        return {
+            ...result,
+            optimistic: {
+                predictedMessageIds,
+                actualMessageIds,
+                predictionMatched
+            }
+        };
+    }
+
+    /**
+     * 메시지 ID 생성 (UUID v4 형식)
+     * @private
+     * @returns {string}
+     */
+    _generateMessageId() {
+        // crypto.randomUUID() 우선 사용 (높은 엔트로피), 미지원 환경 fallback
+        if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
+            return crypto.randomUUID();
+        }
+        return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
+            const r = Math.random() * 16 | 0;
+            const v = c === 'x' ? r : (r & 0x3 | 0x8);
+            return v.toString(16);
+        });
+    }
+
+    /**
+     * 서버 SuccessResponse 래퍼가 있으면 data 만 꺼내고, 아니면 원본 응답을 그대로 반환합니다.
+     * data 가 null 이어도 그대로 null 을 반환해야 하므로 nullish coalescing 을 쓰지 않습니다.
+     *
+     * @private
+     * @param {*} response
+     * @returns {*}
+     */
+    _unwrapSuccessResponse(response) {
+        return response
+            && typeof response === 'object'
+            && Object.prototype.hasOwnProperty.call(response, 'data')
+            ? response.data
+            : response;
+    }
+
+    /**
+     * REST 메시지 응답의 타임스탬프를 epoch millis(number)로 정규화합니다 (in-place).
+     *
+     * <p>서버의 두 전달 경로가 서로 다르게 직렬화한다 — WebSocket 이벤트는 epoch number,
+     * REST(목록/전송 응답)는 ISO 문자열(타임존 없는 LocalDateTime). 선언된 타입
+     * ({@code ChatMessage.sentAt: number})으로 통일해 소비자 분기를 제거한다.</p>
+     *
+     * <p>⚠️ 한계: 서버 ISO 문자열에 타임존이 없어 브라우저 로컬 타임존으로 해석된다 —
+     * 서버(KST)와 사용자 타임존이 다르면 오프셋만큼 어긋날 수 있다. 근본 해소는
+     * 백엔드 직렬화 통일(후속 결정) 영역.</p>
+     *
+     * @private
+     * @param {Object} message - REST 응답의 메시지 객체 (수정됨)
+     * @returns {Object} 같은 객체
+     */
+    _normalizeMessageTimestamps(message) {
+        if (!message || typeof message !== 'object') {
+            return message;
+        }
+        message.sentAt = this._toEpochMillis(message.sentAt);
+        message.editedAt = this._toEpochMillis(message.editedAt);
+        if (message.replyTo && typeof message.replyTo === 'object') {
+            message.replyTo.sentAt = this._toEpochMillis(message.replyTo.sentAt);
+        }
+        return message;
+    }
+
+    /**
+     * ISO 문자열이면 epoch millis 로 변환, number/null/undefined 는 그대로 통과.
+     * 파싱 불가 문자열은 원본 유지 (조용한 데이터 손실 방지).
+     *
+     * @private
+     * @param {*} value
+     * @returns {*}
+     */
+    _toEpochMillis(value) {
+        if (typeof value !== 'string') {
+            return value;
+        }
+        const parsed = Date.parse(value);
+        return Number.isNaN(parsed) ? value : parsed;
+    }
+
+    // ==================== WebSocket 구독 ====================
+
+    /**
+     * 채팅방 구독.
+     *
+     * <p>구독 시 메시지, 읽음, 타이핑, 멤버 변경 이벤트를 자동으로 수신.
+     * 멤버 변경은 roomList 구독 이벤트를 내부 변환하여
+     * {@code memberJoined} / {@code memberLeft} 로 emit.</p>
+     *
+     * <p>자동 읽음 처리는 {@link #setActiveRoom} 으로 현재 보고 있는 방을 설정해야 동작합니다.
+     * 구독만으로는 읽음 처리되지 않으며, 다른 방을 보고 있으면 안읽음 카운트가 유지됩니다.</p>
+     *
+     * @param {string} roomId - 채팅방 ID
+     * @returns {Promise<void>}
+     *
+     * @fires memberJoined - { roomId, members: [{ userId, nickname, profileUrl }], participantCount, timestamp }
+     * @fires memberLeft   - { roomId, members: [{ userId, nickname, profileUrl }], participantCount, timestamp }
+     */
+    async subscribeRoom(roomId) {
+        if (this.subscribedRooms.has(roomId)) {
+            this.logger.warn(`Already subscribed to room: ${roomId}`);
+            return;
+        }
+
+        // 메시지 구독
+        const chatDestination = WebSocketPaths.getChatDestination(roomId);
+        await this.connectionManager.subscribe(chatDestination, (message) => {
+            this._handleChatMessage(roomId, message);
+        });
+
+        // 읽음 이벤트 구독
+        const readDestination = WebSocketPaths.getChatReadDestination(roomId);
+        await this.connectionManager.subscribe(readDestination, (message) => {
+            this._handleReadEvent(roomId, message);
+        });
+
+        // 타이핑 이벤트 구독
+        const typingDestination = WebSocketPaths.getChatTypingDestination(roomId);
+        await this.connectionManager.subscribe(typingDestination, (event) => {
+            this._handleTypingEvent(roomId, event);
+        });
+
+        // 멤버 변경 이벤트 — roomList 이벤트를 방 수준으로 변환하여 자동 emit
+        // 서버가 members 배열(입장/퇴장 사용자들) + participantCount(정확한 인원수) 포함
+        const memberJoinedHandler = (event) => {
+            if (event.roomId === roomId) {
+                this.emit('memberJoined', {
+                    roomId,
+                    members: event.members || [],
+                    participantCount: event.activeParticipantCount,
+                    timestamp: event.timestamp
+                });
+            }
+        };
+        const memberLeftHandler = (event) => {
+            if (event.roomId === roomId) {
+                this.emit('memberLeft', {
+                    roomId,
+                    members: event.members || [],
+                    participantCount: event.activeParticipantCount,
+                    timestamp: event.timestamp
+                });
+            }
+        };
+        this.on('roomListJoined', memberJoinedHandler);
+        this.on('roomListLeft', memberLeftHandler);
+
+        this.subscribedRooms.set(roomId, {
+            chatDestination,
+            readDestination,
+            typingDestination,
+            memberJoinedHandler,
+            memberLeftHandler,
+            subscribedAt: new Date()
+        });
+
+        this.logger.info(`Subscribed to room: ${roomId}`);
+        this.emit('roomSubscribed', { roomId });
+    }
+
+    /**
+     * 채팅방 구독 해제
+     * @param {string} roomId - 채팅방 ID
+     */
+    unsubscribeRoom(roomId) {
+        const subscription = this.subscribedRooms.get(roomId);
+        if (!subscription) {
+            this.logger.warn(`Not subscribed to room: ${roomId}`);
+            return;
+        }
+
+        this.connectionManager.unsubscribe(subscription.chatDestination);
+        this.connectionManager.unsubscribe(subscription.readDestination);
+        if (subscription.typingDestination) {
+            this.connectionManager.unsubscribe(subscription.typingDestination);
+        }
+
+        // 멤버 변경 리스너 해제
+        if (subscription.memberJoinedHandler) {
+            this.off('roomListJoined', subscription.memberJoinedHandler);
+        }
+        if (subscription.memberLeftHandler) {
+            this.off('roomListLeft', subscription.memberLeftHandler);
+        }
+
+        // 타이핑 타이머 정리 (outgoing + incoming assistant 둘 다)
+        this._clearTypingTimer(roomId);
+        this._clearAssistantTypingTimer(roomId);
+
+        // 현재 보고 있는 방이면 activeRoom 해제
+        if (this._activeRoomId === roomId) {
+            this._activeRoomId = null;
+        }
+
+        this.subscribedRooms.delete(roomId);
+
+        // 방별 dedup bucket 정리 — 장시간 세션에서 많은 방을 오갈 때 메모리 누수 차단.
+        // 각 bucket 은 방당 최대 _maxSeenPerRoom(200) entries 라 개별은 작지만 방 수가 늘면 누적.
+        this._seenChatMessageIdsByRoom.delete(roomId);
+        this._seenRoomListMessageIdsByRoom.delete(roomId);
+
+        this.logger.info(`Unsubscribed from room: ${roomId}`);
+        this.emit('roomUnsubscribed', { roomId });
+    }
+
+    /**
+     * 모든 채팅방 구독 해제
+     */
+    unsubscribeAllRooms() {
+        this.subscribedRooms.forEach((_, roomId) => {
+            this.unsubscribeRoom(roomId);
+        });
+    }
+
+    /**
+     * 현재 보고 있는 채팅방 설정.
+     * 이 방에서 수신되는 다른 사용자의 메시지는 자동으로 읽음 처리됩니다.
+     * 다른 방이나 리스트 화면으로 이동 시 {@link #clearActiveRoom} 호출.
+     *
+     * @param {string} roomId - 현재 보고 있는 채팅방 ID
+     */
+    setActiveRoom(roomId) {
+        this._activeRoomId = roomId;
+        this.logger.debug(`Active room set: ${roomId}`);
+    }
+
+    /**
+     * 현재 보고 있는 채팅방 해제 (리스트 화면 등으로 이동 시).
+     * 자동 읽음 처리가 중단됩니다.
+     */
+    clearActiveRoom() {
+        this.logger.debug(`Active room cleared (was: ${this._activeRoomId})`);
+        this._activeRoomId = null;
+    }
+
+    /**
+     * 현재 보고 있는 채팅방 ID 반환.
+     * @returns {string|null}
+     */
+    getActiveRoom() {
+        return this._activeRoomId;
+    }
+
+    /**
+     * 채팅방 리스트 실시간 업데이트 구독 (카톡 스타일).
+     *
+     * 리스트 화면에서 호출. 구독 후 다음 이벤트를 받을 수 있음:
+     *  - roomListUpdate — 모든 이벤트 (통합, eventType 으로 분기)
+     *  - roomListMessage — 새 메시지 수신 (MESSAGE_RECEIVED)
+     *  - roomListMessageDeleted — 현재 lastMessage 삭제 (MESSAGE_DELETED)
+     *  - roomListMessageUpdated — 현재 lastMessage 편집 (MESSAGE_UPDATED)
+     *  - roomListCreated — 새 방 생성 (ROOM_CREATED)
+     *  - roomListJoined — 방 입장 (ROOM_JOINED)
+     *  - roomListLeft — 방 퇴장 (ROOM_LEFT)
+     *  - roomListSelfLeft — 본인이 나간 경우 (리스트에서 제거 신호)
+     *
+     * @returns {Promise<void>}
+     *
+     * @example
+     * await client.chat.subscribeRoomList();
+     *
+     * client.on('roomListMessage', (event) => {
+     *   // 해당 방을 리스트 최상단으로 이동
+     *   // event.actorId !== currentUserId 일 때만 unread +1
+     *   moveRoomToTop(event.roomId);
+     *   updateLastMessage(event.roomId, event.lastMessage, event.lastMessageAt);
+     *   if (event.actorId !== currentUserId) {
+     *     incrementUnread(event.roomId, event.unreadCountDelta);
+     *   }
+     * });
+     *
+     * client.on('roomListSelfLeft', (event) => {
+     *   // 본인이 나간 방 → 리스트에서 제거
+     *   removeRoomFromList(event.roomId);
+     * });
+     */
+    async subscribeRoomList() {
+        if (this.roomListSubscribed) {
+            this.logger.warn('Already subscribed to room list');
+            return;
+        }
+
+        const destination = WebSocketPaths.ROOM_LIST_USER_DESTINATION;
+        await this.connectionManager.subscribe(destination, (event) => {
+            // noinspection JSCheckFunctionSignatures
+            this._handleRoomListEvent(event);
+        });
+
+        this.roomListSubscribed = true;
+        this.logger.info('Subscribed to room list');
+        this.emit('roomListSubscribed', {});
+    }
+
+    /**
+     * 채팅방 리스트 구독 해제.
+     */
+    unsubscribeRoomList() {
+        if (!this.roomListSubscribed) {
+            this.logger.warn('Not subscribed to room list');
+            return;
+        }
+
+        this.connectionManager.unsubscribe(WebSocketPaths.ROOM_LIST_USER_DESTINATION);
+        this.roomListSubscribed = false;
+
+        this.logger.info('Unsubscribed from room list');
+        this.emit('roomListUnsubscribed', {});
+    }
+
+    /**
+     * 채팅방 리스트 구독 여부.
+     * @returns {boolean}
+     */
+    isRoomListSubscribed() {
+        return this.roomListSubscribed;
+    }
+
+    /**
+     * 메시지 읽음 처리
+     * @param {string} roomId - 채팅방 ID
+     * @param {string} messageId - 메시지 ID
+     */
+    markAsRead(roomId, messageId) {
+        if (!this.connectionManager.isConnected()) {
+            this.logger.warn('Cannot mark as read: not connected');
+            return false;
+        }
+
+        return this.connectionManager.send(WebSocketPaths.CHAT_READ, {
+            roomId,
+            messageId
+        });
+    }
+
+    // ==================== 이벤트 핸들러 ====================
+
+    /**
+     * 채팅 메시지 수신 처리.
+     *
+     * <p>서버는 동일 채널(/topic/chat/{roomId})로 신규/수정/삭제/리액션/OG 첨부
+     * 이벤트를 모두 발행하고, 페이로드의 {@code eventType} 으로 구분한다.
+     * 클라는 eventType 에 따라 별도 이벤트로 re-emit.</p>
+     *
+     * <ul>
+     *   <li>{@code MESSAGE_CREATED} → {@code message} + {@code newMessage} (상대 메시지면) + 자동 읽음</li>
+     *   <li>{@code MESSAGE_UPDATED} → {@code message} + {@code messageUpdated}</li>
+     *   <li>{@code MESSAGE_DELETED} → {@code message} + {@code messageDeleted}</li>
+     *   <li>{@code REACTION_CHANGED} → {@code message} + {@code reactionChanged}</li>
+     *   <li>{@code LINK_PREVIEW_ATTACHED} → {@code message} + {@code linkPreviewAttached}</li>
+     *   <li>{@code MESSAGE_TRANSLATED} → {@code message} + {@code messageTranslated} (translations 머지)</li>
+     * </ul>
+     *
+     * <p>{@code message} 이벤트는 모든 케이스에서 발행되어 하위 호환을 유지한다 —
+     * 기존 구독 코드는 messageId 로 merge 하면 계속 작동.</p>
+     *
+     * @private
+     * @param {string} roomId - 채팅방 ID
+     * @param {Object} message - 수신된 메시지 (eventType 필드 포함)
+     */
+    _handleChatMessage(roomId, message) {
+        this.logger.debug(`Message received in room ${roomId} (${message.eventType}):`, message);
+
+        // MESSAGE_CREATED 만 dedup 대상 — 다른 eventType (UPDATED/DELETED/REACTION/LINK_PREVIEW) 는
+        // 같은 messageId 의 의도된 재발행이라 dedup 하면 안 됨.
+        if (message.eventType === 'MESSAGE_CREATED'
+                && this._shouldDedupMessage(this._seenChatMessageIdsByRoom, roomId, message.messageId)) {
+            this.logger.debug(`Duplicate MESSAGE_CREATED suppressed: room=${roomId}, messageId=${message.messageId}`);
+            return;
+        }
+
+        // 편집(MESSAGE_UPDATED) 시 서버가 번역을 무효화한다. payload 에 번역 필드가 없으면 generic emit 前에
+        // 명시적 null 처리 — generic 'message' / 상위 'chatMessage' 소비자도 stale 번역을 즉시 지우도록 (다국어 §9).
+        if (message.eventType === 'MESSAGE_UPDATED') {
+            if (message.translations === undefined) message.translations = null;
+            if (message.sourceLang === undefined) message.sourceLang = null;
+            if (message.translationsOf === undefined) message.translationsOf = null;
+        }
+
+        // 모든 이벤트는 통합 이벤트로 pass-through (하위 호환)
+        this.emit('message', { roomId, message });
+
+        switch (message.eventType) {
+            case 'MESSAGE_CREATED':
+                // 어시 메시지 도착 = "AI 응답 준비중" 종료 신호. typing timer 즉시 해제 + typing=false emit.
+                // 서버는 typing=false 를 발행하지 않고 client-side 가 책임 (assistant typing 설계).
+                // userId / userName 은 서버 typing=true 발행과 정확히 일치하는 generic marker 사용 —
+                // UI 가 roomId+userId 로 typing state 추적 시 true/false 가 같은 키로 매칭되어야 안 꺼지는
+                // 케이스 방지. message.userId (페르소나 ID) 를 그대로 쓰면 키 불일치로 영구 표시 위험.
+                if (message.senderType === 'ASSISTANT') {
+                    this._clearAssistantTypingTimer(roomId);
+                    this.emit('typing', {
+                        roomId,
+                        userId: this._assistantTypingUserId,
+                        userName: this._assistantTypingUserName,
+                        typing: false,
+                        senderType: 'ASSISTANT'
+                    });
+                }
+
+                // 상대방 메시지일 때만 newMessage + 자동 읽음 처리
+                if (message.userId !== this.userId) {
+                    this.emit('newMessage', { roomId, message });
+
+                    // 현재 보고 있는 방에서만 자동 읽음 처리
+                    if (this._activeRoomId === roomId && message.messageId) {
+                        this.markAsRead(roomId, message.messageId);
+                    }
+                }
+                break;
+
+            case 'MESSAGE_UPDATED':
+                // 번역 stale 클리어(번역 필드 null 보정)는 generic emit 前에 이미 수행됨 (_handleChatMessage 상단).
+                this.emit('messageUpdated', { roomId, message });
+                break;
+
+            case 'MESSAGE_DELETED':
+                this.emit('messageDeleted', { roomId, message });
+                break;
+
+            case 'REACTION_CHANGED':
+                this.emit('reactionChanged', { roomId, message });
+                break;
+
+            case 'LINK_PREVIEW_ATTACHED':
+                this.emit('linkPreviewAttached', { roomId, message });
+                break;
+
+            case 'MESSAGE_TRANSLATED':
+                // 서버가 비동기 번역 완료 후 패치 — message.translations/sourceLang 채워져 옴.
+                // 소비자는 messageId 로 기존 메시지에 머지 (linkPreviewAttached 와 동일 패턴).
+                this.emit('messageTranslated', { roomId, message });
+                break;
+
+            default:
+                // 미지의 eventType — 구버전 서버(eventType 없음)와 호환 유지.
+                // 안전장치로 기존 동작(신규 메시지 알림) 수행.
+                this.logger.warn(`Unknown eventType "${message.eventType}" — falling back to legacy behavior`);
+                if (message.userId !== this.userId) {
+                    this.emit('newMessage', { roomId, message });
+                    if (this._activeRoomId === roomId && message.messageId) {
+                        this.markAsRead(roomId, message.messageId);
+                    }
+                }
+        }
+    }
+
+    /**
+     * 채팅방 리스트 업데이트 이벤트 수신 처리.
+     * @private
+     * @param {Object} event - 서버 RoomListEvent
+     * @param {string} event.eventType - RoomListEventType
+     * @param {string} event.roomId
+     * @param {string} event.actorId - 이벤트 발생 사용자
+     * @param {number} [event.unreadCountDelta]
+     * @param {string} [event.lastMessage]
+     * @param {string} [event.lastMessageType]
+     * @param {string} [event.lastMessageAt]
+     * @param {string} event.timestamp
+     */
+    _handleRoomListEvent(event) {
+        this.logger.debug('Room list event:', event);
+
+        // MESSAGE_RECEIVED 의 messageId 기반 dedup — chat WebSocket 측과 별도 키 공간.
+        // 서버가 messageId 를 안 내려준 구버전 페이로드면 dedup 통과 (backward compatible).
+        if (event.eventType === RoomListEventType.MESSAGE_RECEIVED
+                && event.messageId
+                && this._shouldDedupMessage(this._seenRoomListMessageIdsByRoom, event.roomId, event.messageId)) {
+            this.logger.debug(`Duplicate roomList MESSAGE_RECEIVED suppressed: room=${event.roomId}, messageId=${event.messageId}`);
+            return;
+        }
+
+        // 1. 통합 이벤트 (모든 타입)
+        this.emit('roomListUpdate', event);
+
+        // 2. 타입별 이벤트
+        switch (event.eventType) {
+            case RoomListEventType.MESSAGE_RECEIVED:
+                this.emit('roomListMessage', event);
+                break;
+            case RoomListEventType.MESSAGE_DELETED:
+                this.emit('roomListMessageDeleted', event);
+                break;
+            case RoomListEventType.MESSAGE_UPDATED:
+                this.emit('roomListMessageUpdated', event);
+                break;
+            case RoomListEventType.ROOM_CREATED:
+                this.emit('roomListCreated', event);
+                break;
+            case RoomListEventType.ROOM_JOINED:
+                this.emit('roomListJoined', event);
+                break;
+            case RoomListEventType.ROOM_LEFT:
+                this.emit('roomListLeft', event);
+                // 본인이 나간 경우 편의 이벤트 (리스트에서 제거해야 함)
+                if (event.actorId === this.userId) {
+                    this.emit('roomListSelfLeft', event);
+                }
+                break;
+            case RoomListEventType.ROOM_KICKED:
+                this.emit('roomListKicked', event);
+                // 본인이 추방당한 경우 편의 이벤트 — UI 에서 "추방되었습니다" 표시 + 리스트 제거
+                if (this._isSelfInMembers(event)) {
+                    this.emit('roomListSelfKicked', event);
+                }
+                break;
+            case RoomListEventType.ROOM_BANNED:
+                this.emit('roomListBanned', event);
+                // 본인이 영구 차단당한 경우 편의 이벤트 — "영구 차단되었습니다" 표시 + 리스트 제거
+                if (this._isSelfInMembers(event)) {
+                    this.emit('roomListSelfBanned', event);
+                }
+                break;
+            case RoomListEventType.ROOM_UPDATED:
+                this.emit('roomListRoomUpdated', event);
+                break;
+            case RoomListEventType.MESSAGE_RETENTION_CLEANUP:
+                // noinspection JSUnresolvedReference
+                this.emit('retentionCleanup', {
+                    roomId: event.roomId,
+                    cutoffTime: event.cutoffTime
+                });
+                break;
+            default:
+                this.logger.warn('Unknown room list event type:', event.eventType);
+        }
+    }
+
+    /**
+     * 읽음 이벤트 수신 처리
+     * @private
+     * @param {string} roomId - 채팅방 ID
+     * @param {Object} event - 읽음 이벤트 (단일 또는 배치)
+     */
+    _handleReadEvent(roomId, event) {
+        this.logger.debug(`Read event in room ${roomId}:`, event);
+
+        const resolvedRoomId = event.roomId || roomId;
+
+        // 배치 이벤트인 경우 (방 입장 시 일괄 읽음 처리)
+        if (event.events && Array.isArray(event.events)) {
+            event.events.forEach(e => {
+                this.emit('messageRead', {
+                    roomId: resolvedRoomId,
+                    messageId: e.messageId,
+                    userId: event.userId,
+                    remainingUnreadCount: e.remainingUnreadCount
+                });
+            });
+        }
+        // 단일 이벤트인 경우 (실시간 개별 읽음 처리)
+        else {
+            this.emit('messageRead', {
+                roomId: resolvedRoomId,
+                messageId: event.messageId,
+                userId: event.userId,
+                remainingUnreadCount: event.remainingUnreadCount
+            });
+        }
+    }
+
+    // ==================== 타이핑 표시 ====================
+
+    /**
+     * 타이핑 시작 알림.
+     *
+     * <p>호출할 때마다 내부 타이머가 리셋됩니다 (debounce).
+     * 3초간 추가 호출이 없으면 자동으로 {@link #stopTyping} 이 호출됩니다.
+     * 메시지 전송 ({@link #sendMessage}) 시에도 자동 중단됩니다.</p>
+     *
+     * @param {string} roomId - 채팅방 ID
+     *
+     * @example
+     * // input 이벤트에 연결
+     * inputField.addEventListener('input', () => {
+     *     client.chat.startTyping('room-id');
+     * });
+     */
+    startTyping(roomId) {
+        if (!this.connectionManager.isConnected()) return;
+
+        const existingTimer = this._typingTimers.get(roomId);
+
+        // throttle: 이미 typing 상태면 stop 타이머만 리셋 (STOMP 재전송 안 함)
+        if (existingTimer) {
+            clearTimeout(existingTimer);
+        } else {
+            // 최초 또는 stop 이후 첫 호출에만 STOMP 전송
+            this.connectionManager.send(WebSocketPaths.CHAT_TYPING, {
+                roomId,
+                typing: true
+            });
+        }
+
+        // 3초 후 자동 stopTyping
+        const timer = setTimeout(() => {
+            this.stopTyping(roomId);
+        }, 3000);
+
+        this._typingTimers.set(roomId, timer);
+    }
+
+    /**
+     * 타이핑 중단 알림.
+     *
+     * <p>직접 호출하거나, {@link #startTyping} 의 3초 타이머 만료 시,
+     * 또는 메시지 전송 시 자동 호출됩니다.</p>
+     *
+     * @param {string} roomId - 채팅방 ID
+     */
+    stopTyping(roomId) {
+        this._clearTypingTimer(roomId);
+
+        if (!this.connectionManager.isConnected()) return;
+
+        this.connectionManager.send(WebSocketPaths.CHAT_TYPING, {
+            roomId,
+            typing: false
+        });
+    }
+
+    /**
+     * 이벤트 members 배열에 본인이 포함돼 있는지 확인.
+     * <p>ROOM_KICKED / ROOM_BANNED 이벤트에서 "내가 추방당했는가" 판별용. actorId (추방한 방장) 가 아니라
+     * members 배열(추방된 사용자) 을 보는 이유는, 같은 이벤트를 방장 본인도 수신하기 때문.</p>
+     * @private
+     */
+    _isSelfInMembers(event) {
+        return Array.isArray(event.members)
+            && event.members.some(m => m && m.userId === this.userId);
+    }
+
+    /**
+     * 타이핑 이벤트 수신 처리.
+     * <p>본인 이벤트는 필터링하여 emit 하지 않음.</p>
+     * @private
+     */
+    _handleTypingEvent(roomId, event) {
+        // 본인 이벤트 필터 — USER 타이핑만 적용 (어시는 본인 userId 매칭 불가, generic marker 사용)
+        if (event.senderType !== 'ASSISTANT' && event.userId === this.userId) return;
+
+        // 어시 typing=true 수신 시 client-side timeout 시작 — 서버 측 typing=false 발행이 없으므로
+        // (1) 어시 메시지 도착 (_handleChatMessage) 또는 (2) 본 timeout 만료 중 먼저 도달 시 typing=false emit.
+        if (event.senderType === 'ASSISTANT' && event.typing === true) {
+            this._startAssistantTypingTimer(roomId);
+        }
+
+        this.emit('typing', {
+            roomId,
+            userId: event.userId,
+            userName: event.userName,
+            typing: event.typing,
+            senderType: event.senderType || 'USER'   // 구버전 서버 호환 — senderType 없으면 USER
+        });
+    }
+
+    /**
+     * 어시스턴트 typing 자동 해제 타이머 시작/재시작.
+     * 같은 방에 이미 timer 있으면 reset (새로운 어시 응답 라운드).
+     * @private
+     */
+    _startAssistantTypingTimer(roomId) {
+        this._clearAssistantTypingTimer(roomId);
+        const timer = setTimeout(() => {
+            this._assistantTypingTimers.delete(roomId);
+            // timeout 만료 = LLM 지연 또는 서버 실패 — UI 가 영구 "답변 준비중" 에 갇히지 않도록 해제 emit.
+            // userId / userName 은 generic marker 일관 (typing=true 발행과 매칭 — P1 fix).
+            this.emit('typing', {
+                roomId,
+                userId: this._assistantTypingUserId,
+                userName: this._assistantTypingUserName,
+                typing: false,
+                senderType: 'ASSISTANT'
+            });
+            this.logger.debug(`Assistant typing auto-cleared (timeout): room=${roomId}`);
+        }, this._assistantTypingTimeoutMs);
+        this._assistantTypingTimers.set(roomId, timer);
+    }
+
+    /**
+     * 어시스턴트 typing 자동 해제 타이머 취소.
+     * 어시 메시지 도착 시 즉시 호출 (timeout 도달 전 해제).
+     * @private
+     */
+    _clearAssistantTypingTimer(roomId) {
+        const timer = this._assistantTypingTimers.get(roomId);
+        if (timer) {
+            clearTimeout(timer);
+            this._assistantTypingTimers.delete(roomId);
+        }
+    }
+
+    /**
+     * 타이핑 타이머 정리.
+     * @private
+     */
+    _clearTypingTimer(roomId) {
+        const timer = this._typingTimers.get(roomId);
+        if (timer) {
+            clearTimeout(timer);
+            this._typingTimers.delete(roomId);
+        }
+    }
+
+    // ==================== 유틸리티 ====================
+
+    /**
+     * 구독 중인 채팅방 목록
+     * @returns {string[]}
+     */
+    getSubscribedRooms() {
+        return Array.from(this.subscribedRooms.keys());
+    }
+
+    /**
+     * 채팅방 구독 여부 확인
+     * @param {string} roomId
+     * @returns {boolean}
+     */
+    isSubscribed(roomId) {
+        return this.subscribedRooms.has(roomId);
+    }
+
+    /**
+     * 로그 레벨 설정
+     * @param {number} level
+     */
+    setLogLevel(level) {
+        this.logger.setLevel(level);
+    }
+
+    /**
+     * 리소스 정리.
+     *
+     * <p>{@link #unsubscribeRoom} 에서 방별 타이머를 정리하지만, 구독 목록에 없는
+     * roomId 의 debounce 타이머가 남아 있을 수 있어 Map 전체를 명시적으로 비운다.</p>
+     */
+    destroy() {
+        this.unsubscribeAllRooms();
+        if (this.roomListSubscribed) {
+            this.unsubscribeRoomList();
+        }
+
+        this._typingTimers.forEach((timer) => clearTimeout(timer));
+        this._typingTimers.clear();
+
+        // 어시 typing 수신 타이머도 전체 cleanup — unsubscribeRoom 이 방별로 정리하지만 구독 목록에
+        // 없는 roomId 의 타이머가 남아 있을 수 있어 명시 정리 (메모리 누수 차단).
+        this._assistantTypingTimers.forEach((timer) => clearTimeout(timer));
+        this._assistantTypingTimers.clear();
+
+        // dedup bucket 전체 clear — unsubscribeRoom 이 방별로 정리하지만 구독 외 경로로 누적된 bucket
+        // (예: 구독 안 한 방의 push/listener) 이 있을 수 있어 안전하게 명시 정리.
+        this._seenChatMessageIdsByRoom.clear();
+        this._seenRoomListMessageIdsByRoom.clear();
+
+        this.removeAllListeners();
+        this.logger.info('ChatClient destroyed');
+    }
+}
+
+export default ChatClient;