@vibexnpm/talkx 3.0.6 → 3.0.8

package/src/core/ConnectionManager.js

@@ -6,7 +6,7 @@
 import EventEmitter from '../utils/EventEmitter.js';
 import Logger from '../utils/Logger.js';
 import { ConnectionState, ErrorTypes, WebSocketPaths, DefaultConfig, LogLevel } from '../constants.js';
-import { Client as StompClient } from '@stomp/stompjs';
+import { Client as StompClient, ReconnectionTimeMode, StompSocketState } from '@stomp/stompjs';
 import SockJS from 'sockjs-client';
 
 // STOMP Client 가져오기 (CDN 사용 시 전역 객체 우선)
@@ -51,9 +51,11 @@ class ConnectionManager extends EventEmitter {
         this.useSockJS = options.useSockJS !== false;
 
         this.reconnectDelay = options.reconnectDelay || DefaultConfig.reconnectDelay;
+        this.maxReconnectDelay = options.maxReconnectDelay || DefaultConfig.maxReconnectDelay;
         this.maxReconnectAttempts = options.maxReconnectAttempts || DefaultConfig.maxReconnectAttempts;
         this.heartbeatIncoming = options.heartbeatIncoming || DefaultConfig.heartbeatIncoming;
         this.heartbeatOutgoing = options.heartbeatOutgoing || DefaultConfig.heartbeatOutgoing;
+        this.resumeOnVisibility = options.resumeOnVisibility !== false;
 
         this.logger = new Logger(options.logLevel || LogLevel.WARN, 'ConnectionManager');
 
@@ -64,6 +66,191 @@ class ConnectionManager extends EventEmitter {
         this.subscriptions = new Map();
         this.pendingSubscriptions = [];
         this.userId = null;
+
+        // 사용자가 명시적으로 끊은 상태인지 — 포그라운드 복귀가 이걸 되살리면 안 된다.
+        this._intentionalDisconnect = false;
+        // forceReconnect 의 teardown 중 발생하는 close 이벤트를 재연결 시도로 오해하지 않도록.
+        this._tearingDown = false;
+        // connect() 가 최소 1회 호출됐는지 — 복귀 자동 재연결의 전제 조건.
+        this._connectRequested = false;
+        // forceReconnect 단일 실행 보장 (복귀 이벤트 3종이 거의 동시에 들어온다).
+        this._forceReconnectPromise = null;
+        this._lifecycleHandlers = null;
+
+        this._installLifecycleListeners();
+    }
+
+    /**
+     * 포그라운드 복귀 / 네트워크 복구 감지 (RECONNECT_SYNC_DESIGN §6.1).
+     *
+     * <p>이게 없으면 백그라운드에서 재시도 횟수를 소진해 ERROR 로 죽은 연결이 복귀해도 되살아나지 않아
+     * <b>새로고침만이 유일한 복구 수단</b>이 된다. 모바일은 OS 가 타이머까지 얼려서 재시도 루프 자체가
+     * 돌지 못하므로 복귀 시점의 능동적 깨우기가 필수다.</p>
+     *
+     * <p>SSR/Node 환경에서는 no-op.</p>
+     *
+     * @private
+     */
+    _installLifecycleListeners() {
+        if (typeof window === 'undefined' || typeof window.addEventListener !== 'function') {
+            return;
+        }
+
+        const onVisibilityChange = () => {
+            if (typeof document !== 'undefined' && document.visibilityState === 'visible') {
+                this._onResume('visibilitychange');
+            }
+        };
+        // bfcache 복원 — visibilitychange 가 안 오는 경로가 있어 별도로 받는다.
+        const onPageShow = () => this._onResume('pageshow');
+        const onOnline = () => this._onResume('online');
+
+        if (typeof document !== 'undefined' && typeof document.addEventListener === 'function') {
+            document.addEventListener('visibilitychange', onVisibilityChange);
+        }
+        window.addEventListener('pageshow', onPageShow);
+        window.addEventListener('online', onOnline);
+
+        this._lifecycleHandlers = { onVisibilityChange, onPageShow, onOnline };
+    }
+
+    /** @private */
+    _removeLifecycleListeners() {
+        if (!this._lifecycleHandlers) return;
+
+        const { onVisibilityChange, onPageShow, onOnline } = this._lifecycleHandlers;
+        if (typeof document !== 'undefined' && typeof document.removeEventListener === 'function') {
+            document.removeEventListener('visibilitychange', onVisibilityChange);
+        }
+        if (typeof window !== 'undefined' && typeof window.removeEventListener === 'function') {
+            window.removeEventListener('pageshow', onPageShow);
+            window.removeEventListener('online', onOnline);
+        }
+        this._lifecycleHandlers = null;
+    }
+
+    /**
+     * 복귀 시점 판정.
+     *
+     * <p><b>이벤트 계약</b> — {@code resumed} 와 {@code reconnected} 는 <b>상호 배타적</b>이며 둘을 합쳐야
+     * "재동기화가 필요한 시점" 전체를 덮는다:</p>
+     * <ul>
+     *   <li>{@code resumed} — 복귀했는데 연결이 <b>살아 있어 재연결이 필요 없었다</b>. 그래도 백그라운드
+     *       동안 프레임을 놓쳤을 수 있으므로 갭 복구는 돌아야 한다.</li>
+     *   <li>{@code reconnected} — 재연결에 <b>성공</b>했다. 복귀가 유발한 경우든(좀비 소켓/ERROR 복구)
+     *       탭이 열린 채 일시 끊겼다 붙은 경우든 이 이벤트로 수렴한다.</li>
+     * </ul>
+     *
+     * <p>재연결이 일어나는 경로에서는 {@code resumed} 를 발행하지 않는다 — 하나의 복귀에 두 이벤트가
+     * 겹쳐 나가면 소비자가 갭 복구를 두 번 돌린다. 소비자는 <b>둘 다</b> 구독해야 한다.</p>
+     *
+     * @private
+     */
+    _onResume(reason) {
+        if (!this.resumeOnVisibility || this._intentionalDisconnect) {
+            return;
+        }
+
+        // connect() 를 아직 한 번도 호출하지 않았으면 복귀가 연결을 만들어내면 안 된다.
+        // 이 경로는 TalkFlowClient.connect() 를 우회하므로 roomList 자동 구독 / WebRTC enable 등
+        // 상위 초기화가 통째로 빠진 "반쪽 연결" 이 된다. 최초 연결은 반드시 사용자 호출로 시작한다.
+        // (1회 연결된 뒤의 재연결은 _restoreSubscriptions 가 STOMP 구독을 되살리므로 안전하다.)
+        if (!this._connectRequested) {
+            this.logger.debug(`Resume (${reason}) ignored — connect() has not been called yet`);
+            return;
+        }
+
+        // 연결 시도 중이거나 강제 재연결이 진행 중이면 그대로 둔다 — 중복 activate 방지.
+        if (this.state === ConnectionState.CONNECTING || this._forceReconnectPromise) {
+            return;
+        }
+
+        if (this.state === ConnectionState.CONNECTED) {
+            if (this._isSocketAlive()) {
+                this.logger.debug(`Resume (${reason}): connection alive`);
+                this.emit('resumed', { reason });
+                return;
+            }
+            // 좀비 소켓 — STOMP 가 아직 close 를 인지하지 못한 상태.
+            this.logger.warn(`Resume (${reason}): zombie socket detected, forcing reconnect`);
+            this.forceReconnect(`zombie-socket:${reason}`);
+            return;
+        }
+
+        // DISCONNECTED(비의도) / RECONNECTING / ERROR — 재시도 횟수를 리셋하고 즉시 되살린다.
+        this.logger.info(`Resume (${reason}): reviving connection from state=${this.state}`);
+        this.forceReconnect(reason);
+    }
+
+    /**
+     * 소켓이 실제로 열려 있는지.
+     *
+     * <p>{@code state === CONNECTED} 만으로는 부족하다 — OS 가 백그라운드에서 소켓을 끊어도
+     * STOMP 가 close 를 인지하기 전까지 상태는 CONNECTED 로 남는다. 반대로 readyState 가 OPEN 인데
+     * 실제로는 죽은 경우는 STOMP 자체의 incoming heartbeat 감시가 닫아주고, 그 사이 유실분은
+     * 갭 복구가 메운다.</p>
+     *
+     * @private
+     */
+    _isSocketAlive() {
+        const socket = this.stompClient && this.stompClient.webSocket;
+        if (!socket) return false;
+        return socket.readyState === StompSocketState.OPEN;
+    }
+
+    /**
+     * 강제 재연결 — 기존 클라이언트를 완전히 정리한 뒤 새로 활성화.
+     *
+     * <p>ERROR 상태({@link #_handleReconnect} 가 {@code deactivate} 로 STOMP 루프를 끈 상태)에서도
+     * 되살아나야 하므로 {@code activate} 재호출이 필요하다.</p>
+     *
+     * @param {string} reason
+     * @returns {Promise<void>}
+     */
+    async forceReconnect(reason) {
+        if (this._intentionalDisconnect || this.state === ConnectionState.CONNECTING) {
+            return;
+        }
+
+        // 단일 실행 — 복귀 시 visibilitychange / pageshow / online 이 거의 동시에 들어오는데,
+        // deactivate() 를 await 하는 동안 state 는 아직 CONNECTED 라 재진입 가드가 없으면
+        // 두 번째 resume 이 그대로 통과해 클라이언트를 이중으로 만든다.
+        if (this._forceReconnectPromise) {
+            this.logger.debug(`Force reconnect already in progress, joining: ${reason}`);
+            return this._forceReconnectPromise;
+        }
+
+        this._forceReconnectPromise = this._doForceReconnect(reason)
+            .finally(() => { this._forceReconnectPromise = null; });
+
+        return this._forceReconnectPromise;
+    }
+
+    /** @private */
+    async _doForceReconnect(reason) {
+        this.logger.info(`Force reconnect: ${reason}`);
+
+        if (this.stompClient) {
+            this._tearingDown = true;
+            try {
+                await this.stompClient.deactivate();
+            } catch (error) {
+                this.logger.warn('Error deactivating stomp client on force reconnect:', error);
+            } finally {
+                this._tearingDown = false;
+            }
+            this.stompClient = null;
+        }
+
+        // connect() 가 CONNECTED/CONNECTING 이면 조기 반환하므로 상태를 먼저 내려둔다.
+        this._setState(ConnectionState.DISCONNECTED);
+        this.reconnectAttempts = 0;
+
+        try {
+            await this.connect();
+        } catch (error) {
+            this.logger.warn(`Force reconnect failed (${reason}):`, error);
+        }
     }
 
     /**
@@ -112,6 +299,10 @@ class ConnectionManager extends EventEmitter {
             heartbeatIncoming: this.heartbeatIncoming,
             heartbeatOutgoing: this.heartbeatOutgoing,
             reconnectDelay: this.reconnectDelay,
+            // 지수 백오프 — 고정 간격이면 서버 재시작 시 전 클라이언트가 같은 주기로 몰린다.
+            // STOMP 7 내장 기능이라 직접 타이머를 굴리지 않는다.
+            reconnectTimeMode: ReconnectionTimeMode.EXPONENTIAL,
+            maxReconnectDelay: this.maxReconnectDelay,
             debug: (str) => {
                 if (this.logger.level <= LogLevel.DEBUG) {
                     this.logger.debug('STOMP:', str);
@@ -155,6 +346,8 @@ class ConnectionManager extends EventEmitter {
 
         this._setState(ConnectionState.CONNECTING);
         this.reconnectAttempts = 0;
+        this._intentionalDisconnect = false;
+        this._connectRequested = true;
 
         return new Promise((resolve, reject) => {
             this._connectResolve = resolve;
@@ -176,8 +369,13 @@ class ConnectionManager extends EventEmitter {
      * @private
      */
     _onConnect(frame) {
+        // 재연결 여부 판정은 카운터 리셋 전에 — 갭 복구(S4)가 이 신호로 동기화를 건다.
+        const attempts = this.reconnectAttempts;
+        const isReconnect = attempts > 0 || this._hasConnectedBefore === true;
+
         this._setState(ConnectionState.CONNECTED);
         this.reconnectAttempts = 0;
+        this._hasConnectedBefore = true;
         this.logger.info('Connected to server', frame);
 
         // 기존 구독 재등록 (재연결 시)
@@ -188,6 +386,11 @@ class ConnectionManager extends EventEmitter {
 
         this.emit('connected', { frame });
 
+        // 재연결 '성공' 신호 — 기존에는 성공 이벤트가 없어 connected 재발행으로만 유추해야 했다.
+        if (isReconnect) {
+            this.emit('reconnected', { attempts });
+        }
+
         if (this._connectResolve) {
             this._connectResolve();
             this._connectResolve = null;
@@ -238,6 +441,13 @@ class ConnectionManager extends EventEmitter {
     _onWebSocketClose(event) {
         this.logger.warn('WebSocket closed:', event);
 
+        // forceReconnect 의 의도적 teardown 이면 재연결 시도로 집계하지 않는다 —
+        // 카운터가 오염되면 복귀 직후 다시 max 를 소진해버린다.
+        if (this._tearingDown) {
+            this.logger.debug('WebSocket closed during intentional teardown — not counting as reconnect');
+            return;
+        }
+
         if (this.state !== ConnectionState.DISCONNECTED) {
             this._handleReconnect();
         }
@@ -445,6 +655,8 @@ class ConnectionManager extends EventEmitter {
      * clear 만 하면 호출자 {@code await} 가 영원히 hang 된다.</p>
      */
     async disconnect() {
+        // 명시적 해제 — 포그라운드 복귀가 이걸 되살리면 안 된다.
+        this._intentionalDisconnect = true;
         this._drainPendingSubscriptions('Disconnected before subscription completed');
 
         if (this.stompClient) {
@@ -508,6 +720,7 @@ class ConnectionManager extends EventEmitter {
      * ConnectionManager 를 직접 소유한 사용자가 destroy 만 호출하는 경로도 안전해야 함.</p>
      */
     async destroy() {
+        this._removeLifecycleListeners();
         await this.disconnect();
         this.removeAllListeners();
         this.logger.info('ConnectionManager destroyed');

package/src/talkflow/eventForwarding.js

@@ -2,10 +2,18 @@ const CONNECTION_EVENT_MAP = [
     ['connected', 'connected'],
     ['disconnected', 'disconnected'],
     ['reconnecting', 'reconnecting'],
+    // 재연결 '성공' + 포그라운드 복귀 감지 (RECONNECT_SYNC_DESIGN §6.1/§6.4)
+    ['reconnected', 'reconnected'],
+    ['resumed', 'resumed'],
     ['error', 'connectionError']
 ];
 
 const CHAT_EVENT_MAP = [
+    // 갭 복구 (RECONNECT_SYNC_DESIGN §6.4) — 기본 메시지 수신 코드는 변경 불필요, 선택 구독용.
+    ['syncStarted', 'syncStarted'],
+    ['syncCompleted', 'syncCompleted'],
+    ['gapTruncated', 'gapTruncated'],
+    ['roomListSynced', 'roomListSynced'],
     ['message', 'chatMessage'],
     ['newMessage', 'newChatMessage'],
     ['messageUpdated', 'messageUpdated'],

package/src/talkflow/session.js

@@ -20,7 +20,11 @@ export function initializeSubClients(client) {
         projectId: client.options.projectId,
         useSockJS: client.options.useSockJS,
         reconnectDelay: client.options.reconnectDelay,
+        maxReconnectDelay: client.options.maxReconnectDelay,
         maxReconnectAttempts: client.options.maxReconnectAttempts,
+        heartbeatIncoming: client.options.heartbeatIncoming,
+        heartbeatOutgoing: client.options.heartbeatOutgoing,
+        resumeOnVisibility: client.options.resumeOnVisibility,
         logLevel: client.options.logLevel
     });
 
@@ -28,6 +32,10 @@ export function initializeSubClients(client) {
         connectionManager: client.connectionManager,
         apiClient: client.apiClient,
         userId: client._userId,
+        syncOnReconnect: client.options.syncOnReconnect,
+        rewindMillis: client.options.rewindMillis,
+        maxSyncPages: client.options.maxSyncPages,
+        syncPageSize: client.options.syncPageSize,
         logLevel: client.options.logLevel
     });
 
@@ -330,6 +338,10 @@ export function applySessionMethods(TalkFlowClient) {
 
         if (needReinitialize && this.connectionManager) {
             await this.disconnect();
+            // destroy() 로 버려야 lifecycle listener(visibilitychange/pageshow/online)가 해제된다.
+            // disconnect() 만 하고 참조를 끊으면 죽은 매니저가 window 에 매달린 채 남아,
+            // 사용자 전환이 잦은 앱에서 복귀 이벤트마다 유령 매니저가 함께 깨어난다.
+            await this.connectionManager.destroy();
             if (this.pushManager) {
                 this.pushManager.reset();
                 this._pushEnablePromise = null;

package/types/index.d.ts

@@ -332,16 +332,16 @@ export interface RoomSummaryRollup {
     format: string;
     /** 이 rollup 의 언어(소문자 BCP-47 / {@code 'OFF'}=원문). {@link RoomSummaryView.language} 와 동일. */
     language: string;
-    /** rollup 이 커버하는 가장 오래된 지점. */
-    coverStartAt: string | null;
-    /** 마지막으로 요약된 지점. */
-    watermarkAt: string | null;
+    /** rollup 이 커버하는 가장 오래된 지점(epoch millis). */
+    coverStartAt: number | null;
+    /** 마지막으로 요약된 지점(epoch millis). */
+    watermarkAt: number | null;
     /** 전체 segment 수(페이지 총량 힌트). */
     segmentCount: number;
     /** 이 키(포맷×언어)가 최신 대화를 아직 반영 안 함(reducedSegmentCount < segmentCount) — refreshSummary 로 최신화 가능. */
     stale: boolean;
-    /** 마지막 갱신 시각. */
-    updatedAt: string;
+    /** 마지막 갱신 시각(epoch millis). */
+    updatedAt: number;
 }
 
 /** Rolling 누적 요약 구간 부분요약 — {@link RoomSummaryView.segments} 항목. 항상 {@code contentFormat==='neutral'}. */
@@ -352,9 +352,9 @@ export interface RoomSummarySegment {
     content: string;
     /** 항상 {@code 'neutral'}(format 미적용). */
     contentFormat: string;
-    fromSentAt: string | null;
+    fromSentAt: number | null;
     fromMessageId: string | null;
-    toSentAt: string | null;
+    toSentAt: number | null;
     toMessageId: string | null;
     /** 이 구간이 담은 메시지 수. */
     messageCount: number;
@@ -407,8 +407,8 @@ export interface SummaryUpdateEvent {
      * 그 외 null. 각 사용자는 자기 언어가 이 목록에 있으면 {@code getSummary({ format, lang })} 로 읽는다(§S1).
      */
     languages: string[] | null;
-    /** 갱신 시각. {@code READY} 만 포함, 그 외 null. */
-    updatedAt: string | null;
+    /** 갱신 시각(epoch millis). {@code READY} 만 포함, 그 외 null. */
+    updatedAt: number | null;
 }
 
 /**
@@ -723,7 +723,8 @@ export interface ParticipantResponse {
      * 과도기 동안 {@code ADMIN} 생성자가 보일 수 있으나 권한은 동일.</p>
      */
     role: 'OWNER' | 'ADMIN' | 'MEMBER' | 'ASSISTANT';
-    joinedAt: string;
+    /** 참가 시각(epoch millis). */
+    joinedAt: number;
 }
 
 /** 채팅방 last message preview. */
@@ -734,7 +735,8 @@ export interface LastMessageResponse {
     senderProfileUrl?: string | null;
     content: string;
     messageType: string;
-    sentAt: string;
+    /** 마지막 메시지 시각(epoch millis). */
+    sentAt: number;
     /**
      * 파일 메시지일 때 첫 파일의 사용자 metadata (opaque pass-through).
      * <p>고객사가 파일 업로드 시 함께 보낸 데이터 (스티커 ID 등) 가 채팅방 리스트에서도 식별 가능하도록 보존.
@@ -771,8 +773,10 @@ export interface ChatRoomResponse {
     pinnedMessageId?: string | null;
     participants?: ParticipantResponse[];
     lastMessage?: LastMessageResponse | null;
-    lastMessageAt?: string | null;
-    createdAt: string;
+    /** 마지막 메시지 시각(epoch millis) — 방 목록 정렬용. */
+    lastMessageAt?: number | null;
+    /** 방 생성 시각(epoch millis). */
+    createdAt: number;
 }
 
 /** 커서 페이지네이션 응답. */
@@ -825,6 +829,10 @@ export interface RoomListUpdateEvent {
     eventType: RoomListEventTypeValue;
     roomId: string;
     actorId?: string;
+    /** {@code MESSAGE_*} 이벤트의 방 마지막 메시지 시각(epoch millis). 그 외 이벤트에서는 undefined. */
+    lastMessageAt?: number | null;
+    /** 이벤트 발행 시각(epoch millis). */
+    timestamp?: number;
     cutoffTime?: number;
     /** {@code ROOM_UPDATED} 전용 — 저장된 최신 메타 snapshot. 다른 eventType 에서는 undefined. */
     room?: RoomMeta;
@@ -926,10 +934,35 @@ export interface TalkFlowClientOptions {
     serverUrl?: string;
     /** SockJS 사용 여부. 기본 true. */
     useSockJS?: boolean;
-    /** 재연결 지연 (ms). 기본 5000. */
+    /** 최초 재연결 지연 (ms). 기본 5000. 이후 지수적으로 증가한다. */
     reconnectDelay?: number;
+    /** 지수 백오프 상한 (ms). 기본 30000. */
+    maxReconnectDelay?: number;
     /** 최대 재연결 시도. 기본 10. */
     maxReconnectAttempts?: number;
+    /** 수신 하트비트 간격 (ms). 기본 10000. */
+    heartbeatIncoming?: number;
+    /** 발신 하트비트 간격 (ms). 기본 10000. */
+    heartbeatOutgoing?: number;
+    /**
+     * 탭 복귀(visibilitychange/pageshow) · 네트워크 복구(online) 시 자동 재연결. 기본 true.
+     *
+     * <p>재시도 횟수를 소진해 죽은 연결도 되살린다. 단 {@code connect()} 를 한 번도 호출하지 않았거나
+     * {@code disconnect()} 로 명시적으로 끊은 경우에는 동작하지 않는다.</p>
+     */
+    resumeOnVisibility?: boolean;
+    /**
+     * 재연결/복귀 후 끊긴 구간의 메시지를 자동으로 다시 불러올지. 기본 true.
+     *
+     * <p>복구된 메시지는 일반 `chatMessage` 이벤트로 재생되므로 수신 코드를 바꿀 필요가 없다.</p>
+     */
+    syncOnReconnect?: boolean;
+    /** 갭 복구 첫 페이지에만 적용되는 되감기 폭 (ms). 기본 3000. 서버가 상한 clamp 후 1회 차감. */
+    rewindMillis?: number;
+    /** 갭 복구 페이지 상한. 기본 5. 초과 시 최신 페이지 재로드로 전환하고 `gapTruncated` 를 발행. */
+    maxSyncPages?: number;
+    /** 갭 복구 페이지 크기. 기본 100. */
+    syncPageSize?: number;
     /** WebRTC ICE 서버. */
     iceServers?: RTCIceServer[];
     /** connect() 시 채팅방 리스트 자동 구독. 기본 true. */
@@ -1229,7 +1262,7 @@ export interface RetentionCleanupPayload {
 /**
  * TalkFlowClient 이벤트 맵 — 런타임 {@code TalkFlowClient.js} 의 {@code this.emit(...)} 호출 기반.
  *
- * <p><b>Connection 관련</b>: stateChange, connected, disconnected, reconnecting, connectionError, tokenSet, loggedOut</p>
+ * <p><b>Connection 관련</b>: stateChange, connected, disconnected, reconnecting, reconnected, resumed, connectionError, tokenSet, loggedOut</p>
  * <p><b>Chat 관련 (ChatClient 이벤트를 이 이름으로 re-emit)</b>: chatMessage, newChatMessage, messageUpdated, messageDeleted, reactionChanged, linkPreviewAttached, messageRead, typing, assistantProgress, memberJoined, memberLeft, roomSubscribed, roomUnsubscribed, roomListSubscribed, roomListUnsubscribed, roomListUpdate, roomListMessage, roomListCreated, roomListJoined, roomListLeft, roomListSelfLeft, roomListRoomUpdated, retentionCleanup</p>
  * <p><b>Push 관련</b>: pushEnabled, pushFailed, pushNotification</p>
  * <p><b>WebRTC 관련</b>: localStreamStarted, localStreamStopped, remoteTrack, screenShareStarted, screenShareEnded, deviceChange, mediaStateChanged, callStarted, callEnded, callRequested, callAccepted, callRejected, callCancelled, callInvitation, callBusy, incomingCall, incomingCallWhileBusy, userJoined, userLeft, participantLeft, participantMediaState, peerConnected, peerDisconnected, peerClosed, webrtcError</p>
@@ -1240,6 +1273,20 @@ export interface TalkFlowClientEvents {
     connected: unknown;
     disconnected: unknown;
     reconnecting: { attempt: number };
+    /**
+     * 재연결 **성공**. 최초 연결에는 발행되지 않는다.
+     *
+     * <p>{@link TalkFlowClientEvents.resumed} 와 상호 배타적 — 재동기화 시점을 모두 잡으려면 둘 다 구독한다.</p>
+     */
+    reconnected: { attempts: number };
+    /**
+     * 탭 복귀 / 네트워크 복구 감지 — **연결이 살아 있어 재연결이 불필요했던** 경우에만 발행된다.
+     *
+     * <p>백그라운드 동안 프레임을 놓쳤을 수 있으므로 소비자는 이 시점에도 재동기화해야 한다.
+     * 복귀가 재연결을 유발한 경우에는 이 이벤트 대신 {@link TalkFlowClientEvents.reconnected} 가
+     * 발행된다(두 이벤트가 겹치지 않아 재동기화가 중복 실행되지 않는다).</p>
+     */
+    resumed: { reason: 'visibilitychange' | 'pageshow' | 'online' };
     connectionError: unknown;
     tokenSet: { userId: string };
     loggedOut: void;
@@ -1288,6 +1335,21 @@ export interface TalkFlowClientEvents {
     roomListRoomUpdated: RoomListUpdateEvent;
     retentionCleanup: RetentionCleanupPayload;
 
+    // 갭 복구 — 복구된 메시지 자체는 일반 chatMessage 로 재생되므로 아래는 모두 선택 구독용.
+    /** 갭 복구 시작 (전 방 1회). */
+    syncStarted: { roomIds: string[]; reason: string };
+    /** 갭 복구 완료 (전 방 1회). */
+    syncCompleted: {
+        rooms: Array<{ roomId: string; recovered: number; truncated: boolean; durationMs: number }>;
+        totalRecovered: number;
+        durationMs: number;
+        reason: string;
+    };
+    /** 갭이 `maxSyncPages` 를 넘거나 커서가 만료돼 최신 페이지 재로드로 전환됨 (방 단위). */
+    gapTruncated: { roomId: string; fetched: number; reason?: 'cursorExpired' };
+    /** 재연결 시 방 목록 전체 스냅샷. delta 계약인 `roomListUpdate` 와 별개. */
+    roomListSynced: { rooms: ChatRoomResponse[]; reason: string };
+
     // Push
     pushEnabled: void;
     /**