@vibexnpm/talkx 5.2.0 → 5.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@vibexnpm/talkx",
-    "version": "5.2.0",
+    "version": "5.3.0",
     "type": "module",
     "description": "TalkFlow SDK - Chat & WebRTC unified client",
     "main": "dist/talkflow-sdk.umd.js",

package/src/chat/ChatClient.js

@@ -320,6 +320,21 @@ class ChatClient extends EventEmitter {
         // 1) WebSocket 구독을 먼저 — 이후 서버 read 이벤트 유실 방지
         if (!wasAlreadySubscribed) {
             await this.subscribeRoom(roomId);
+        } else if (this.assistantStreamReplay) {
+            // ⭐ <b>이미 구독 중인 방으로 재입장</b> — 구독을 유지한 채 방 화면만 나갔다 들어오는 흐름이다
+            // (목록 화면에서 unread 를 받으려면 구독을 끊지 않는 것이 정상 구현이다). 이때 subscribeRoom 이
+            // 통째로 건너뛰어져 <b>스냅샷 트리거가 하나도 돌지 않는다</b> — 재개 경로는 여기와 재연결
+            // (`resumeAssistantStreams`) 둘뿐이기 때문이다.
+            //
+            // 진행 표시는 transient 이벤트라 화면이 언마운트되면 프론트에서 사라지는데, SDK 슬롯에만 남은
+            // 그 상태를 다시 그려줄 신호가 없다 → 다음 PHASE 가 올 때까지(워커 heartbeat 간격 15초) 배지가
+            // 안 뜬다. 스냅샷을 다시 받아 그 공백을 없앤다.
+            //
+            // await 하지 않는다 — 구독은 살아 있으므로 그 사이 도착분은 보류함에 쌓였다가 병합 후 순서대로
+            // 풀린다(§6.1). 실패해도 보류분은 반드시 풀리므로 라이브만으로 계속 동작한다.
+            const generation = this._armAssistantSnapshot(roomId);
+            this._loadAssistantSnapshot(roomId, generation)
+                .catch((error) => this.logger.warn(`Assistant snapshot on re-enter failed: room=${roomId}`, error));
         }
         // 2) 자동 읽음 처리 활성 방 지정
         this.setActiveRoom(roomId);
@@ -3490,17 +3505,29 @@ class ChatClient extends EventEmitter {
      * @private
      */
     _emitAssistantRoomProgress(roomId) {
+        // 이벤트 계약은 종전 그대로 둔다 — stream 목록은 getter 전용(이벤트로 매 틱 배열을 실어 보내면
+        // DELTA 마다 방 전체 스트림을 다시 만들어 흘리는 셈이다).
+        const { streams, ...event } = this._assistantRoomProgressPayload(roomId);
+        this.emit('assistantRoomProgress', event);
+    }
+
+    /**
+     * 방 단위 집계 payload 생성 — {@link #_emitAssistantRoomProgress} 와 {@link #getAssistantProgress} 의
+     * <b>공통 SSOT</b>. 두 곳에서 각자 조립하면 "이벤트로 본 상태"와 "물어봐서 본 상태"가 갈린다.
+     * @private
+     */
+    _assistantRoomProgressPayload(roomId) {
         const slots = this._assistantProgress.get(roomId);
         const alive = slots ? Array.from(slots.entries()) : [];
         if (alive.length === 0) {
-            this.emit('assistantRoomProgress', {
+            return {
                 roomId, active: false, streamCount: 0,
-                streamId: null, personaId: null, phase: null, label: null, text: null, textAvailable: true
-            });
-            return;
+                streamId: null, personaId: null, phase: null, label: null, text: null, textAvailable: true,
+                streams: []
+            };
         }
         const [streamId, slot] = alive.reduce((a, b) => (b[1].order > a[1].order ? b : a));
-        this.emit('assistantRoomProgress', {
+        return {
             roomId,
             active: true,
             streamCount: alive.length,
@@ -3509,8 +3536,43 @@ class ChatClient extends EventEmitter {
             phase: slot.phase,
             label: slot.phase ? (this._assistantPhaseLabels[slot.phase] || null) : null,
             text: slot.textAvailable ? (slot.text || null) : null,
-            textAvailable: slot.textAvailable
-        });
+            textAvailable: slot.textAvailable,
+            // stream 단위 UI(권장 (B))가 마운트 즉시 버블을 복원할 수 있도록 전부 싣는다.
+            // 도착 순서(order)대로 — 소비자가 "가장 최근"을 다시 계산하지 않아도 되게 한다.
+            streams: alive
+                .sort((a, b) => a[1].order - b[1].order)
+                .map(([id, s]) => ({
+                    streamId: id,
+                    personaId: s.personaId,
+                    phase: s.phase,
+                    label: s.phase ? (this._assistantPhaseLabels[s.phase] || null) : null,
+                    text: s.textAvailable ? (s.text || null) : null,
+                    textAvailable: s.textAvailable,
+                    resumed: s.resumed === true
+                }))
+        };
+    }
+
+    /**
+     * 방의 <b>현재</b> AI 진행 상태를 즉시 반환 (네트워크 호출 없음).
+     *
+     * <p>{@code assistantProgress} / {@code assistantRoomProgress} 는 transient 이벤트라, 방 화면을 나갔다
+     * 들어오면 프론트 상태가 비어 있는데 <b>이미 지나간 이벤트는 다시 오지 않는다</b>. 마운트 시점에 이걸
+     * 한 번 읽으면 다음 이벤트를 기다리지 않고 바로 그릴 수 있다 — 재입장 스냅샷(1 RTT)보다도 빠르다.</p>
+     *
+     * <p>반환 형태는 {@code assistantRoomProgress} 이벤트와 동일하고, stream 단위 UI 를 위해 {@code streams}
+     * 배열이 추가된다. 진행 중인 것이 없으면 {@code active:false} + 빈 배열.</p>
+     *
+     * @param {string} roomId - 채팅방 ID
+     * @returns {Object} { roomId, active, streamCount, streamId, personaId, phase, label, text, textAvailable, streams[] }
+     *
+     * @example
+     * // 방 화면 마운트 시 — 이벤트를 기다리지 않고 즉시 복원
+     * const p = client.chat.getAssistantProgress(roomId);
+     * if (p.active) renderBubble(p);
+     */
+    getAssistantProgress(roomId) {
+        return this._assistantRoomProgressPayload(roomId);
     }
 
     /**

package/src/talkflow/delegates.js

@@ -52,6 +52,10 @@ const CHAT_DELEGATE_METHODS = [
     'isSubscribed',
     'startTyping',
     'stopTyping',
+    // AI 진행 표시 — 마운트 즉시 복원용 동기 조회 + 수동 재개. 여기 없으면 최상위 클라이언트에서
+    // 런타임 undefined 가 된다(타입 선언만 있고 배선이 없으면 타입이 거짓말을 한다).
+    'getAssistantProgress',
+    'resumeAssistantStreams',
     'getAssistants',
     'getRoomAiMeta',
     'rateAssistantMessage',

package/types/index.d.ts

@@ -1260,6 +1260,29 @@ export interface AssistantRoomProgressEvent {
     textAvailable?: boolean;
 }
 
+/** {@link ChatClient.getAssistantProgress} 가 돌려주는 stream 1건. */
+export interface AssistantProgressStreamSnapshot {
+    streamId: string;
+    personaId: string | null;
+    phase: 'THINKING' | 'SEARCHING' | 'PLANNING' | 'WRITING' | null;
+    label: string | null;
+    text: string | null;
+    textAvailable: boolean;
+    /** 서버 스냅샷으로 복원된 진행분이면 true. */
+    resumed: boolean;
+}
+
+/**
+ * 방의 **현재** AI 진행 상태 (v5.3.0 — {@link ChatClient.getAssistantProgress} 반환).
+ *
+ * <p>{@link AssistantRoomProgressEvent} 와 같은 형태에 stream 단위 UI 를 위한 `streams` 가 더해진다.
+ * 이벤트는 transient 라 화면을 나갔다 들어오면 다시 오지 않는다 — 마운트 시 이걸 한 번 읽는다.</p>
+ */
+export interface AssistantProgressSnapshot extends AssistantRoomProgressEvent {
+    /** 살아 있는 stream 전체 (도착 순서). 없으면 빈 배열. */
+    streams: AssistantProgressStreamSnapshot[];
+}
+
 // ============================================================================
 // Options — constructor & method
 // ============================================================================
@@ -2017,6 +2040,17 @@ export class ChatClient implements SdkEventEmitter<ChatClientEvents> {
 
     startTyping(roomId: string): void;
     stopTyping(roomId: string): void;
+
+    /**
+     * 방의 현재 AI 진행 상태를 즉시 반환 (네트워크 호출 없음, v5.3.0).
+     * 진행 표시 이벤트는 transient 라 방 화면 마운트 시 이걸 읽어 버블을 복원한다.
+     */
+    getAssistantProgress(roomId: string): AssistantProgressSnapshot;
+    /**
+     * 구독 중인 모든 방의 진행 스트림 스냅샷을 서버에서 다시 받는다 (v5.1.0).
+     * 재연결·탭 복귀 때 SDK 가 자동 호출하므로 보통은 직접 부를 일이 없다.
+     */
+    resumeAssistantStreams(reason?: string): Promise<void>;
 }
 
 export class WebRTCClient implements SdkEventEmitter<WebRTCClientEvents> {
@@ -2400,6 +2434,17 @@ export default class TalkFlowClient implements SdkEventEmitter<TalkFlowClientEve
     startTyping(roomId: string): void;
     stopTyping(roomId: string): void;
 
+    /**
+     * 방의 현재 AI 진행 상태를 즉시 반환 (네트워크 호출 없음, v5.3.0).
+     * 진행 표시 이벤트는 transient 라 방 화면 마운트 시 이걸 읽어 버블을 복원한다.
+     */
+    getAssistantProgress(roomId: string): AssistantProgressSnapshot;
+    /**
+     * 구독 중인 모든 방의 진행 스트림 스냅샷을 서버에서 다시 받는다 (v5.1.0).
+     * 재연결·탭 복귀 때 SDK 가 자동 호출하므로 보통은 직접 부를 일이 없다.
+     */
+    resumeAssistantStreams(reason?: string): Promise<void>;
+
     // WebRTC delegations
     initializeIceServers(): Promise<RTCIceServer[]>;
     getTurnCredentials(): Promise<{ iceServers: RTCIceServer[] }>;