@vibexnpm/talkx 3.0.5 → 3.0.7

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@vibexnpm/talkx",
-    "version": "3.0.5",
+    "version": "3.0.7",
     "type": "module",
     "description": "TalkFlow SDK - Chat & WebRTC unified client",
     "main": "dist/talkflow-sdk.umd.js",
@@ -46,6 +46,8 @@
         "@rollup/plugin-node-resolve": "^16.0.3",
         "@rollup/plugin-replace": "^6.0.3",
         "@rollup/plugin-terser": "^0.4.4",
+        "babel-jest": "^29.7.0",
+        "jest": "^29.7.0",
         "rollup": "^4.12.0"
     }
 }

package/src/TalkFlowClient.js

@@ -72,7 +72,20 @@ class TalkFlowClient extends EventEmitter {
             jwtToken: options.jwtToken || null,
             useSockJS: options.useSockJS !== false,
             reconnectDelay: options.reconnectDelay || DefaultConfig.reconnectDelay,
+            maxReconnectDelay: options.maxReconnectDelay || DefaultConfig.maxReconnectDelay,
             maxReconnectAttempts: options.maxReconnectAttempts || DefaultConfig.maxReconnectAttempts,
+            heartbeatIncoming: options.heartbeatIncoming || DefaultConfig.heartbeatIncoming,
+            heartbeatOutgoing: options.heartbeatOutgoing || DefaultConfig.heartbeatOutgoing,
+            // 탭 복귀 / 네트워크 복구 시 자동 재연결. false 로 꺼야 하므로 !== false 로 보존 —
+            // options 에 담지 않으면 undefined 가 전달되어 ConnectionManager 기본값 true 로 되살아난다.
+            resumeOnVisibility: options.resumeOnVisibility !== false,
+            // 갭 복구 (재연결/복귀 후 끊긴 구간 메시지 재조회). false 로 꺼야 하므로 !== false 로 보존.
+            syncOnReconnect: options.syncOnReconnect !== false,
+            rewindMillis: options.rewindMillis !== undefined
+                ? options.rewindMillis
+                : DefaultConfig.rewindMillis,
+            maxSyncPages: options.maxSyncPages || DefaultConfig.maxSyncPages,
+            syncPageSize: options.syncPageSize || DefaultConfig.syncPageSize,
             iceServers: options.iceServers || DefaultConfig.iceServers,
             // connect() 시 채팅방 리스트 자동 구독 여부 (카톡 스타일).
             // 기본 true — 앱 어디서든 리스트 이벤트를 놓치지 않음 (배지/알림 등).
@@ -299,7 +312,14 @@ class TalkFlowClient extends EventEmitter {
     }
 
     /**
-     * 브라우저 locale 감지 — {@code navigator.language} 를 BCP-47 소문자로 정규화. 비브라우저/미가용 시 null.
+     * 브라우저 locale 감지 — {@code navigator.language} 를 BCP-47 소문자로 정규화하고 지역 변형을 primary 로
+     * 축약한다({@code ko-KR → 'ko'}, {@code en-US → 'en'}). 단 {@code zh} 계열은 간체/번체 구분을 위해
+     * 변형을 보존한다({@code zh-TW → 'zh-tw'}). 비브라우저/미가용 시 null.
+     *
+     * <p>축약 이유(값공간 통일): 서버 저장·번역·요약 키는 짧은 코드({@code 'ko'}/{@code 'en'}) 기준이다. 시드가
+     * 지역 변형을 그대로 보내면 명시 요청({@code lang: 'en'})과 키가 분열되어 같은 언어 이중 생성·조회 miss 가
+     * 발생한다. 서버 {@code LanguageCode} 도 동일 규칙으로 축약하므로 어느 쪽으로 들어와도 같은 값이 된다.</p>
+     *
      * <p>{@link #registerUser} 자동 시드에 사용되며, 고객사 BFF 의 {@code /users/auth} 시드에도 쓸 수 있다.</p>
      * @returns {string|null}
      */
@@ -307,7 +327,33 @@ class TalkFlowClient extends EventEmitter {
         if (typeof navigator === 'undefined' || !navigator.language) {
             return null;
         }
-        return navigator.language.trim().toLowerCase() || null;
+        return TalkFlowClient.normalizeLanguageCode(navigator.language);
+    }
+
+    /**
+     * 언어 코드 canonical 정규화 — 소문자 + 지역 변형 축약(zh 계열 보존). 서버 {@code LanguageCode} 규칙의 미러.
+     * <p>{@code 'OFF'}(원문 sentinel)는 대문자 그대로 유지한다. 빈 값은 null.</p>
+     * @param {string|null|undefined} code - BCP-47 코드(예 'ko-KR') / 'OFF' / null
+     * @returns {string|null}
+     */
+    static normalizeLanguageCode(code) {
+        if (!code || typeof code !== 'string') {
+            return null;
+        }
+        const trimmed = code.trim();
+        if (!trimmed) {
+            return null;
+        }
+        if (trimmed.toUpperCase() === 'OFF') {
+            return 'OFF';
+        }
+        const lower = trimmed.toLowerCase();
+        const dash = lower.indexOf('-');
+        if (dash < 0) {
+            return lower;
+        }
+        const primary = lower.slice(0, dash);
+        return primary === 'zh' ? lower : primary;
     }
 
     /**
@@ -319,8 +365,10 @@ class TalkFlowClient extends EventEmitter {
      * @returns {string|null}
      */
     static displayText(message, myLang) {
-        if (message && message.translations && myLang && message.translations[myLang]) {
-            return message.translations[myLang];
+        // myLang 도 canonical 로 정규화 — 앱이 'ko-KR' 처럼 지역 변형을 넘겨도 서버 저장 키('ko')와 일치시킨다.
+        const lang = TalkFlowClient.normalizeLanguageCode(myLang);
+        if (message && message.translations && lang && message.translations[lang]) {
+            return message.translations[lang];
         }
         return message ? message.content : null;
     }

package/src/chat/ChatClient.js

@@ -7,7 +7,7 @@
 
 import EventEmitter from '../utils/EventEmitter.js';
 import Logger from '../utils/Logger.js';
-import { WebSocketPaths, LogLevel, RoomListEventType, ChatRoomType } from '../constants.js';
+import { WebSocketPaths, LogLevel, RoomListEventType, ChatRoomType, DefaultConfig } from '../constants.js';
 
 const MAX_FILES_PER_MESSAGE = 20;
 
@@ -80,8 +80,56 @@ class ChatClient extends EventEmitter {
         // 구조: roomId → insertion-order Map<messageId, true> (LRU). size 초과 시 가장 오래된 항목 제거.
         this._seenChatMessageIdsByRoom = new Map();
         this._seenRoomListMessageIdsByRoom = new Map();
-        // 방 하나당 최근 N개의 messageId 만 dedup 대상 — 정상 흐름에서 충돌 가능성 없는 적정 크기.
-        this._maxSeenPerRoom = 200;
+
+        // ── 갭 복구 (RECONNECT_SYNC_DESIGN §6.2 / §6.3) ──
+        this.syncOnReconnect = options.syncOnReconnect !== false;
+        this.rewindMillis = options.rewindMillis !== undefined
+            ? options.rewindMillis
+            : DefaultConfig.rewindMillis;
+        this.maxSyncPages = options.maxSyncPages || DefaultConfig.maxSyncPages;
+        this.syncPageSize = options.syncPageSize || DefaultConfig.syncPageSize;
+
+        // 방별 서버 커서 워터마크 — Mongo _id 단독(anchor). sentAt 은 비교에 쓰지 않는다:
+        // 같은 메시지라도 WS(서버 systemDefault epoch)와 REST(offset 없는 ISO → 브라우저 로컬 해석)의
+        // sentAt 이 서로 다른 값이라, 두 출처를 섞어 비교하면 단조 규칙이 잘못된 방향으로 작동한다.
+        this._anchor = new Map();
+        // anchor 세대 — sync 진행 중 라이브 메시지가 앞서 갔는지 판정한다(generation guard).
+        this._anchorGen = new Map();
+        // 방별 sync 중복 실행 방지 (빠른 visible/hidden 토글).
+        this._syncInFlight = new Set();
+        // replay 중에는 개별 메시지로 anchor 를 전진시키지 않는다 — 완료 후 lastId 로 1회 커밋.
+        this._replaying = false;
+
+        // 방 하나당 dedup 대상 messageId 수. sync 상한보다 커야 되감기 구간의 중복이 새어나가지 않는다.
+        // 상수로 두면 maxSyncPages 튜닝 시 조용히 어긋나므로 config 에서 파생시킨다 (설계 §7).
+        this._maxSeenPerRoom = Math.max(200, this.maxSyncPages * this.syncPageSize + 100);
+
+        this._installSyncTriggers();
+    }
+
+    /**
+     * 갭 복구 트리거 배선 — {@code reconnected} / {@code resumed} 양쪽 (설계 §6.1 이벤트 계약).
+     *
+     * <p>두 이벤트는 상호 배타적이다: 복귀가 재연결을 유발하면 {@code reconnected} 만, 연결이 살아 있으면
+     * {@code resumed} 만 발행된다. 그래서 둘 다 들어도 한 번의 복귀에 sync 가 두 번 돌지 않는다.
+     * 반대로 하나만 들으면 절반의 시나리오를 놓친다.</p>
+     *
+     * @private
+     */
+    _installSyncTriggers() {
+        if (!this.connectionManager || typeof this.connectionManager.on !== 'function') return;
+
+        this._onReconnectedForSync = ({ attempts } = {}) => {
+            this.syncAfterReconnect(`reconnected:${attempts ?? 0}`)
+                .catch((error) => this.logger.warn('Gap sync after reconnect failed:', error));
+        };
+        this._onResumedForSync = ({ reason } = {}) => {
+            this.syncAfterReconnect(`resumed:${reason ?? 'unknown'}`)
+                .catch((error) => this.logger.warn('Gap sync after resume failed:', error));
+        };
+
+        this.connectionManager.on('reconnected', this._onReconnectedForSync);
+        this.connectionManager.on('resumed', this._onResumedForSync);
     }
 
     /**
@@ -145,7 +193,17 @@ class ChatClient extends EventEmitter {
      * @returns {Promise<Object>}
      */
     async getRoom(roomId) {
-        return this.apiClient.get(`/api/v1/rooms/${roomId}`);
+        const genAtStart = this._anchorGen.get(roomId) || 0;
+        const response = await this.apiClient.get(`/api/v1/rooms/${roomId}`);
+
+        // 입장 응답의 초기 메시지(최신순)로 갭 복구 anchor 를 심는다 — 이 방에서 라이브 메시지를
+        // 한 건도 받기 전에 백그라운드로 가는 경로를 덮기 위함(§6.2).
+        // (타임스탬프 정규화는 기존 동작을 그대로 둔다 — 여기서 바꾸면 기존 소비자 계약이 흔들린다.)
+        const detail = this._unwrapSuccessResponse(response);
+        if (detail && Array.isArray(detail.messages)) {
+            this._seedAnchorFromLatest(roomId, detail.messages, genAtStart);
+        }
+        return response;
     }
 
     /**
@@ -925,18 +983,304 @@ class ChatClient extends EventEmitter {
      */
     async getMessages(roomId, params = {}) {
         const { size = 50, lastId, lastSortValue } = params;
+        // 커서가 없으면 "최신 페이지" — 이때만 anchor 를 심는다 (과거 페이지네이션은 워터마크를 뒤로 민다).
+        // null 과 undefined 를 함께 잡는다(느슨한 비교) — 호출자가 명시적으로 null 을 넘겨도 서버에는
+        // 최신 페이지로 나가므로, 엄격 비교로 두면 그 경로만 조용히 seed 를 건너뛴다.
+        const isLatestPage = lastId == null && lastSortValue == null;
+        const genAtStart = this._anchorGen.get(roomId) || 0;
+
         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));
+            if (isLatestPage) {
+                this._seedAnchorFromLatest(roomId, page.content, genAtStart);
+            }
+        }
+        return response;
+    }
+
+    /**
+     * 초기 REST 로드로 anchor 를 심는다 (RECONNECT_SYNC_DESIGN §6.2).
+     *
+     * <p><b>없으면 가장 흔한 복귀 경로가 통째로 skip 된다</b> — 방에 들어와 초기 50건을 REST 로 본 뒤
+     * 라이브 메시지를 한 건도 받기 전에 백그라운드로 가면 anchor 가 없어 갭 복구가 돌지 않는다.
+     * 그게 바로 이 기능이 없애려는 증상이다.</p>
+     *
+     * <p><b>최신 페이지에서만</b> 호출해야 한다. 과거 방향 페이지네이션(무한 스크롤) 결과로 심으면
+     * 워터마크가 뒤로 밀린다. 목록은 최신순(DESC)이라 {@code content[0]} 이 가장 최신이다.</p>
+     *
+     * <p>진행 중 라이브 메시지가 도착했으면(세대 변화) 그쪽이 더 최신이므로 덮어쓰지 않는다 —
+     * {@code id} 는 문자열 비교로 시간 순서를 보장하지 못해 "더 최신인지" 를 직접 판별할 수 없기 때문에
+     * sync 커밋과 동일한 generation guard 로 처리한다.</p>
+     *
+     * @private
+     */
+    _seedAnchorFromLatest(roomId, descendingMessages, genAtStart) {
+        if (!Array.isArray(descendingMessages) || descendingMessages.length === 0) return false;
+        const newest = descendingMessages[0];
+        if (!newest || !newest.id) return false;
+        return this._commitAnchorFromSync(roomId, newest.id, genAtStart);
+    }
+
+    /**
+     * 갭 복구용 forward 조회 — 앵커 <b>이후</b> 메시지를 오름차순으로 가져온다.
+     *
+     * <p>커서는 메시지 {@code id}(Mongo {@code _id}) 하나뿐이다. 시간값은 보내지 않는다 —
+     * 서버가 앵커를 조회해 {@code sentAt} 을 직접 읽으므로 timezone/정밀도 불일치가 생길 수 없다.</p>
+     *
+     * <p>읽음 부작용이 없다({@code /list} 와 동일). 백그라운드 방의 unread 를 건드리지 않는다.</p>
+     *
+     * @param {string} roomId
+     * @param {Object} [params]
+     * @param {string} [params.afterId] - 앵커 메시지의 Mongo _id. 없으면 방의 가장 오래된 것부터.
+     * @param {number} [params.rewindMillis] - 시계 스큐 방어 되감기. <b>첫 페이지에만</b> 보낸다.
+     * @param {number} [params.size]
+     * @returns {Promise<Object>}
+     */
+    async syncMessages(roomId, params = {}) {
+        const { afterId, rewindMillis, size = this.syncPageSize } = params;
+        const response = await this.apiClient.get(
+            `/api/v1/chat-messages/${roomId}/sync`, { afterId, rewindMillis, size }
+        );
+        const page = this._unwrapSuccessResponse(response);
         if (page && Array.isArray(page.content)) {
             page.content.forEach((m) => this._normalizeMessageTimestamps(m));
         }
         return response;
     }
 
+    /**
+     * 라이브 수신으로 anchor 전진 (+세대 증가).
+     *
+     * <p>{@code MESSAGE_CREATED} 에서만 호출한다. UPDATED/DELETED/REACTION 은 과거 메시지의 재발행이라
+     * anchor 를 건드리면 워터마크가 뒤로 밀린다.</p>
+     *
+     * @private
+     */
+    _advanceAnchorFromLive(roomId, messageId) {
+        if (!roomId || !messageId) return;
+        this._anchor.set(roomId, messageId);
+        this._anchorGen.set(roomId, (this._anchorGen.get(roomId) || 0) + 1);
+    }
+
+    /**
+     * sync 완료 커밋 — 시작 시점 세대가 유지된 경우에만 anchor 를 덮어쓴다.
+     *
+     * <p>sync 진행 중 라이브 메시지가 들어와 anchor 가 더 앞서 갔을 수 있는데, 그걸 sync 결과로 덮으면
+     * <b>워터마크가 후퇴</b>해 다음 sync 가 같은 구간을 다시 긁는다.</p>
+     *
+     * @private
+     * @returns {boolean} 커밋 여부
+     */
+    _commitAnchorFromSync(roomId, lastId, genAtStart) {
+        if (!lastId) return false;
+        if ((this._anchorGen.get(roomId) || 0) !== genAtStart) {
+            this.logger.debug(`Anchor commit skipped (live advanced): room=${roomId}`);
+            return false;
+        }
+        this._anchor.set(roomId, lastId);
+        return true;
+    }
+
+    /**
+     * 복구한 메시지를 라이브와 <b>동일한 경로</b>로 재생한다.
+     *
+     * <p>반드시 {@link #_handleChatMessage} 하나로만 흘려야 한다 — dedup({@code _shouldDedupMessage})은
+     * check 와 record 가 한 몸이라, 호출자가 미리 dedup 을 돌린 뒤 넘기면 {@code _handleChatMessage} 가
+     * 같은 messageId 를 중복으로 판정해 <b>복구 메시지를 전부 삼킨다</b>.</p>
+     *
+     * <p>REST 응답에는 {@code eventType} 이 없으므로 {@code MESSAGE_CREATED} 를 합성한다. 삭제
+     * placeholder 도 CREATED 로 흘린다 — dedup 대상이 CREATED 뿐이라, DELETED 로 보내면 재동기화 때마다
+     * 중복 emit 된다. 삭제 표시는 payload 의 {@code deletedStatus} 가 담당한다.</p>
+     *
+     * @private
+     */
+    _replayMessages(roomId, messages) {
+        if (!Array.isArray(messages) || messages.length === 0) return 0;
+
+        let emitted = 0;
+        this._replaying = true;
+        try {
+            messages.forEach((message) => {
+                // 되감기 구간에는 이미 받은 메시지가 정상적으로 섞여 들어온다. dedup 에 걸려 화면에
+                // 나가지 않은 건 복구 건수에서 빼야 syncCompleted 지표가 "실제로 새로 들어온 수" 가 된다.
+                const handled = this._handleChatMessage(roomId, {
+                    ...message,
+                    eventType: message.eventType || 'MESSAGE_CREATED'
+                });
+                if (handled) emitted += 1;
+            });
+        } finally {
+            this._replaying = false;
+        }
+        return emitted;
+    }
+
+    /**
+     * 갭이 상한을 넘었을 때의 폴백 — 최신 페이지만 다시 싣는다.
+     *
+     * <p>{@code getRoom}/{@code enterRoom} 은 서버 {@code markAllAsRead} 를 트리거하므로 절대 쓰지 않는다.
+     * 백그라운드 방의 누적 unread 가 통째로 지워진다. 읽음 부작용이 없는 {@code /list} 만 사용한다.</p>
+     *
+     * @private
+     */
+    async _reloadLatestPage(roomId, genAtStart) {
+        const response = await this.getMessages(roomId, { size: this.syncPageSize });
+        const page = this._unwrapSuccessResponse(response) || {};
+        const content = Array.isArray(page.content) ? page.content : [];
+
+        // /list 는 최신순(DESC) — 도착 순서대로 replay 하려면 뒤집는다.
+        const ascending = content.slice().reverse();
+        // 폴백 페이지에도 이미 본 메시지가 섞이므로, 지표는 조회 건수가 아니라 실제 emit 수여야 한다.
+        const emitted = this._replayMessages(roomId, ascending);
+
+        const newest = ascending.length ? ascending[ascending.length - 1].id : null;
+        this._commitAnchorFromSync(roomId, newest, genAtStart);
+        return emitted;
+    }
+
+    /** @private */
+    _isCursorExpired(error) {
+        return error?.status === 410 || error?.response?.code === 'SYNC_CURSOR_EXPIRED';
+    }
+
+    /**
+     * 방 하나의 갭 복구 (RECONNECT_SYNC_DESIGN §6.3).
+     *
+     * <p><b>fetch 와 replay 를 분리</b>한다. 페이지마다 즉시 emit 하면 상한 초과를 알게 된 시점에 이미
+     * 일부를 내보낸 뒤라 "부분 replay 없음" 이 성립하지 않는다.</p>
+     *
+     * @private
+     * @returns {Promise<Object|null>} 복구 결과. 대상이 아니면 null.
+     */
+    async _syncRoom(roomId) {
+        const anchor = this._anchor.get(roomId);
+        // 이 세션에서 아직 받은 메시지가 없는 방 — enterRoom 의 초기 로드가 담당한다.
+        if (!anchor) return null;
+        if (this._syncInFlight.has(roomId)) return null;
+
+        this._syncInFlight.add(roomId);
+        const genAtStart = this._anchorGen.get(roomId) || 0;
+        const startedAt = Date.now();
+
+        try {
+            // ── Phase 1: fetch only (emit 없음) ──
+            const buffer = [];
+            let cursor = anchor;
+            // 되감기는 워터마크 기준 첫 페이지에서 1회만 의미가 있다. 매 페이지 되감으면 같은 구간을 반복 조회한다.
+            let rewindMillis = this.rewindMillis;
+            let hasMore = true;
+            let pages = 0;
+
+            while (hasMore && pages < this.maxSyncPages) {
+                const response = await this.syncMessages(roomId, { afterId: cursor, rewindMillis });
+                const page = this._unwrapSuccessResponse(response) || {};
+                const content = Array.isArray(page.content) ? page.content : [];
+
+                buffer.push(...content);
+                rewindMillis = 0;
+                hasMore = !!page.hasNext;
+                if (page.lastId) cursor = page.lastId;
+                pages += 1;
+            }
+
+            // ── Phase 2: 판정 후 replay ──
+            if (hasMore) {
+                // 상한 초과 — 버퍼를 통째로 버리고 최신 페이지로 전환한다(부분 replay 금지).
+                this.logger.info(`Gap too large, falling back to latest page: room=${roomId}`);
+                this.emit('gapTruncated', { roomId, fetched: buffer.length });
+                const reloaded = await this._reloadLatestPage(roomId, genAtStart);
+                return {
+                    roomId, recovered: reloaded, truncated: true, durationMs: Date.now() - startedAt
+                };
+            }
+
+            const recovered = this._replayMessages(roomId, buffer);
+            this._commitAnchorFromSync(roomId, cursor, genAtStart);
+            return { roomId, recovered, truncated: false, durationMs: Date.now() - startedAt };
+
+        } catch (error) {
+            if (this._isCursorExpired(error)) {
+                // retention 정리 등으로 앵커가 사라짐 — 최신 페이지로 복구한다.
+                this.logger.warn(`Sync cursor expired, reloading latest: room=${roomId}`);
+                this.emit('gapTruncated', { roomId, fetched: 0, reason: 'cursorExpired' });
+                const reloaded = await this._reloadLatestPage(roomId, genAtStart);
+                return {
+                    roomId, recovered: reloaded, truncated: true, durationMs: Date.now() - startedAt
+                };
+            }
+            throw error;
+        } finally {
+            this._syncInFlight.delete(roomId);
+        }
+    }
+
+    /**
+     * 구독 중인 모든 방의 갭 복구 + 방 목록 갱신.
+     *
+     * <p>재연결 성공({@code reconnected}) 과 복귀 감지({@code resumed}) 양쪽에서 호출된다. 두 이벤트는
+     * 상호 배타적이라 중복 실행되지 않는다.</p>
+     *
+     * @param {string} [reason]
+     * @returns {Promise<void>}
+     */
+    async syncAfterReconnect(reason = 'manual') {
+        if (!this.syncOnReconnect) return;
+
+        const roomIds = Array.from(this.subscribedRooms.keys()).filter((id) => this._anchor.has(id));
+        if (roomIds.length === 0) {
+            await this._refreshRoomList(reason);
+            return;
+        }
+
+        this.emit('syncStarted', { roomIds, reason });
+        const startedAt = Date.now();
+        const rooms = [];
+
+        for (const roomId of roomIds) {
+            try {
+                const result = await this._syncRoom(roomId);
+                if (result) rooms.push(result);
+            } catch (error) {
+                // 한 방의 실패가 나머지 방 복구를 막지 않게 한다.
+                this.logger.warn(`Gap sync failed: room=${roomId}`, error);
+            }
+        }
+
+        await this._refreshRoomList(reason);
+
+        this.emit('syncCompleted', {
+            rooms,
+            totalRecovered: rooms.reduce((sum, r) => sum + (r.recovered || 0), 0),
+            durationMs: Date.now() - startedAt,
+            reason
+        });
+    }
+
+    /**
+     * 재연결 시 방 목록/unread 1회 갱신.
+     *
+     * <p>기존 {@code roomListUpdate} 로 흘리지 않는다 — 그건 단건 delta 계약이라 전체 스냅샷을 실으면
+     * 기존 구독자가 형태가 다른 payload 를 delta 로 오해한다. 별도 {@code roomListSynced} 로 분리.</p>
+     *
+     * @private
+     */
+    async _refreshRoomList(reason) {
+        if (!this.roomListSubscribed) return;
+        try {
+            const response = await this.getRooms({ size: 50 });
+            const page = this._unwrapSuccessResponse(response) || {};
+            this.emit('roomListSynced', { rooms: page.content || [], reason });
+        } catch (error) {
+            this.logger.warn('Room list refresh failed (non-fatal):', error);
+        }
+    }
+
     /**
      * 링크 미리보기 조회.
      *
@@ -1941,7 +2285,13 @@ class ChatClient extends EventEmitter {
         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;
+            return false;
+        }
+
+        // 갭 복구 워터마크 전진 — 라이브 수신분만. replay 중에는 개별 전진을 막고
+        // sync 완료 시 응답 lastId 로 1회 커밋한다(중간 실패 시 어중간한 위치에 남는 것 방지).
+        if (message.eventType === 'MESSAGE_CREATED' && !this._replaying) {
+            this._advanceAnchorFromLive(roomId, message.id);
         }
 
         // 편집(MESSAGE_UPDATED) 시 서버가 번역을 무효화한다. payload 에 번역 필드가 없으면 generic emit 前에
@@ -2021,6 +2371,8 @@ class ChatClient extends EventEmitter {
                     }
                 }
         }
+
+        return true;
     }
 
     /**
@@ -2496,6 +2848,20 @@ class ChatClient extends EventEmitter {
         this._seenChatMessageIdsByRoom.clear();
         this._seenRoomListMessageIdsByRoom.clear();
 
+        // 갭 복구 트리거 해제 — connectionManager 는 ChatClient 보다 오래 살 수 있어(사용자 전환 등)
+        // 리스너를 남기면 죽은 ChatClient 가 계속 깨어난다.
+        if (this.connectionManager && typeof this.connectionManager.off === 'function') {
+            if (this._onReconnectedForSync) {
+                this.connectionManager.off('reconnected', this._onReconnectedForSync);
+            }
+            if (this._onResumedForSync) {
+                this.connectionManager.off('resumed', this._onResumedForSync);
+            }
+        }
+        this._anchor.clear();
+        this._anchorGen.clear();
+        this._syncInFlight.clear();
+
         this.removeAllListeners();
         this.logger.info('ChatClient destroyed');
     }

package/src/constants.js

@@ -376,10 +376,23 @@ export const DefaultConfig = {
 
     // Connection
     reconnectDelay: 5000,
+    // 지수 백오프 상한 — 서버 재시작 시 전 클라이언트가 고정 간격으로 몰리는 것을 완화.
+    maxReconnectDelay: 30000,
     maxReconnectAttempts: 10,
     heartbeatIncoming: 10000,
     heartbeatOutgoing: 10000,
 
+    // 포그라운드 복귀 / 네트워크 복구 시 자동 재연결 (RECONNECT_SYNC_DESIGN §6.1). false = 킬 스위치.
+    resumeOnVisibility: true,
+
+    // 갭 복구 (RECONNECT_SYNC_DESIGN §6.3). false = 킬 스위치.
+    syncOnReconnect: true,
+    // 멀티 인스턴스 시계 스큐 방어 되감기 폭 — 첫 페이지에만, 서버가 clamp 후 1회 차감.
+    rewindMillis: 3000,
+    // 갭 페이지 상한. 초과 시 버퍼 폐기 + gapTruncated + 최신 페이지 재로드.
+    maxSyncPages: 5,
+    syncPageSize: 100,
+
     // API
     apiTimeout: 30000,