@noverachat/sdk-web 0.4.0 → 0.5.1

package/dist/index.cjs

@@ -58,6 +58,7 @@ function parseUnreadRoomItem(j) {
     lastMessageId: j["last_message_id"],
     lastReadMessageId: j["last_read_message_id"],
     lastMessagePreview: j["last_message_preview"],
+    lastMessageAt: j["last_message_at"],
     memberCount: j["member_count"],
     membersPreview: j["members_preview"] == null ? void 0 : j["members_preview"].map((e) => parseMemberPreview(e))
   };
@@ -812,23 +813,71 @@ var MessageCollection = class {
     this.emit("hydrated");
   }
   /**
-   * API 최신 페이지를 컬렉션에 반영한다 — **diff 병합 진입점**.
-   * replaceByApi(현재 유일 정책)는 스냅샷을 걷어내고 통째 교체하고,
-   * mergeDiff는 서버 무효화 규칙 확정 후 이 분기 안에 병합 함수가 채워진다.
+   * API 최신 페이지를 컬렉션에 반영한다.
+   * replaceByApi(기본)는 스냅샷을 걷어내고 통째 교체하고, mergeDiff는
+   * 스냅샷의 옛 메시지를 보존·병합한다(`mergeFresh`).
    */
   applyFresh(page) {
-    if (this.policy === "mergeDiff") {
-      throw new Error('CachePolicy "mergeDiff" \uB294 \uC544\uC9C1 \uBBF8\uAD6C\uD604 \u2014 \uC11C\uBC84 \uBB34\uD6A8\uD654 \uADDC\uCE59 \uD655\uC815 \uD6C4 \uC9C0\uC6D0 \uC608\uC815');
+    if (this.policy === "mergeDiff" && this.hydratedCount > 0) {
+      this.mergeFresh(page);
+      return;
     }
     if (this.hydratedCount > 0) {
       this._messages.splice(0, this.hydratedCount);
       this.hydratedCount = 0;
     }
-    this._messages.unshift(...page.items.map(chatMessageFromHistory));
+    const indexById = /* @__PURE__ */ new Map();
+    this._messages.forEach((m, i) => indexById.set(m.id, i));
+    const fresh = [];
+    for (const item of page.items.map(chatMessageFromHistory)) {
+      const at = indexById.get(item.id);
+      if (at === void 0) fresh.push(item);
+      else this._messages[at] = item;
+    }
+    this._messages.unshift(...fresh);
     this.oldestCursor = page.nextCursor;
     this._hasMore = page.hasMore;
     this.emit("replaced");
   }
+  /**
+   * diff 병합 — 스냅샷의 옛 메시지를 보존해 fresh 페이지 아래에 잇는다.
+   *
+   * 판정 규칙(서버 계약, 07-23 확정):
+   * - **컷오프분**: `history_from`(히스토리 하한, unix ms)보다 오래된 캐시
+   *   메시지는 재입장 컷/대화 지우기로 볼 수 없게 된 것 → 폐기.
+   * - **삭제분**: fresh 커버 구간(id ≥ fresh 최저 id)에 있는데 fresh에
+   *   없는 캐시 메시지는 그 사이 삭제된 것(타이머 만료 포함) → 폐기.
+   * - **갭 폴백**: 캐시의 최신 메시지가 fresh와 겹치지 않으면 누락 구간이
+   *   있을 수 있으므로 병합하지 않고 통째 교체.
+   *
+   * 겹치는 구간은 항상 fresh가 정답(수정 반영) — 보존되는 건 fresh 범위
+   * **밖**의 옛 메시지뿐이라 "서버가 항상 이긴다" 불변식은 유지된다.
+   */
+  mergeFresh(page) {
+    const cachedHead = this._messages.slice(0, this.hydratedCount);
+    this._messages.splice(0, this.hydratedCount);
+    this.hydratedCount = 0;
+    const freshIds = new Set(page.items.map((m) => m.messageId));
+    const freshOldest = page.items.length > 0 ? page.items[0].messageId : null;
+    const hf = page.historyFrom ?? null;
+    const overlaps = cachedHead.length > 0 && freshOldest != null && freshIds.has(cachedHead.at(-1).id);
+    let preserved = [];
+    if (overlaps && page.hasMore) {
+      preserved = cachedHead.filter((m) => {
+        if (freshIds.has(m.id)) return false;
+        if (!idGreater(freshOldest, m.id)) return false;
+        if (hf != null && m.createdAtMs != null && m.createdAtMs < hf) {
+          return false;
+        }
+        return true;
+      });
+    }
+    this._messages.unshift(...page.items.map(chatMessageFromHistory));
+    this._messages.unshift(...preserved);
+    this.oldestCursor = preserved.length > 0 ? preserved[0].id : page.nextCursor;
+    this._hasMore = page.hasMore;
+    this.emit("replaced");
+  }
   // ── optimistic sends ────────────────────────────────────────────
   /**
    * Send `text` optimistically: a `sending` bubble appears immediately (one
@@ -956,8 +1005,26 @@ var MessageCollection = class {
     this.bus.removeAll();
   }
   // ── event handlers ──────────────────────────────────────────────
+  /**
+   * 수신 프레임을 컬렉션에 넣는다.
+   *
+   * 두 가지를 방어한다 — backfill(`chat.backfill()`)은 재연결 시 앵커
+   * 이후를 **다시** 실어오므로, 이미 들고 있는 메시지가 섞여 오고 화면보다
+   * 오래된 메시지도 함께 온다:
+   * - **중복**: 같은 id가 이미 있으면 무시한다.
+   * - **순서**: 뒤에서부터 자리를 찾아 꽂는다. 실시간 프레임은 항상 마지막
+   *   메시지보다 새로우므로 비교 1번으로 끝나고(빠른 경로), 옛 메시지가
+   *   섞여 올 때만 탐색이 일어난다.
+   */
   onIncoming(f) {
-    this._messages.push(chatMessageFromLive(f));
+    const msg = chatMessageFromLive(f);
+    let i = this._messages.length - 1;
+    for (; i >= 0; i--) {
+      const cur = this._messages[i];
+      if (cur.id === msg.id) return;
+      if (!idGreater(cur.id, msg.id)) break;
+    }
+    this._messages.splice(i + 1, 0, msg);
     this.emit("inserted");
   }
   onUpdated(f) {
@@ -1141,9 +1208,6 @@ var Room = class _Room {
   cacheStore;
   cachePolicy;
   logger;
-  /** 삭제 타이머 여부 세션 메모 — null=미확인, 값=마지막 detail() 결과. */
-  timerSeconds = null;
-  timerKnown = false;
   /**
    * 이 방의 메시지 상태를 소유하는 `MessageCollection`을 만든다.
    *
@@ -1621,7 +1685,8 @@ var Room = class _Room {
       items: raw.items.map(toMessageOut),
       // 파싱 성공한 응답만 캐시에 넣는다
       nextCursor: raw.next_cursor,
-      hasMore: raw.has_more
+      hasMore: raw.has_more,
+      historyFrom: raw.history_from ?? null
     };
     void this.cacheWriteRecent(raw);
     return page;
@@ -1632,10 +1697,7 @@ var Room = class _Room {
       "GET",
       `/api/v1/rooms/${this.roomId}`
     );
-    const out = parseRoomOut(raw);
-    this.timerSeconds = out.timerSeconds;
-    this.timerKnown = true;
-    return out;
+    return parseRoomOut(raw);
   }
   /**
    * 히스토리 최신 페이지의 캐시 스냅샷 — 마지막 `listRecent()` 성공 응답의
@@ -1657,7 +1719,8 @@ var Room = class _Room {
       return {
         items: j.items.map(toMessageOut),
         nextCursor: j.next_cursor,
-        hasMore: j.has_more
+        hasMore: j.has_more,
+        historyFrom: j.history_from ?? null
       };
     } catch (err) {
       this.logger?.("warn", `cache_read_failed key=${key}`, err);
@@ -1669,20 +1732,15 @@ var Room = class _Room {
     }
   }
   /**
-   * 최신 페이지 스냅샷 저장. 삭제 타이머가 켜진 방은 저장하지 않고 기존
-   * 스냅샷도 지운다 — 타이머 만료로 서버에서 사라진 메시지가 로컬 캐시에
-   * 살아남는 보안 충돌을 원천 차단한다.
+   * 최신 페이지 스냅샷 저장. 삭제 타이머 방도 저장한다 — 서버가 만료를
+   * 일반 `message_deleted` 프레임으로 브로드캐스트하고 히스토리에서도
+   * 즉시 제외하므로, 만료분은 라이브 이벤트/`history_from` diff로 정리된다.
    */
   async cacheWriteRecent(raw) {
     const store = this.cacheStore;
     if (!store) return;
     const key = CacheKeys.msgs(this.roomId);
     try {
-      if (!this.timerKnown) await this.detail();
-      if (this.timerSeconds != null) {
-        await store.remove(key);
-        return;
-      }
       await store.write(key, JSON.stringify(raw));
     } catch (err) {
       this.logger?.("warn", `cache_write_failed key=${key}`, err);
@@ -2076,11 +2134,6 @@ var NoveraChat = class {
     if (!opts.appId) throw new Error("appId required");
     if (!opts.endpoint) throw new Error("endpoint required");
     if (!opts.tokenProvider) throw new Error("tokenProvider required");
-    if (opts.cachePolicy === "mergeDiff") {
-      throw new Error(
-        'CachePolicy "mergeDiff" \uB294 \uC544\uC9C1 \uBBF8\uAD6C\uD604 \u2014 \uD604\uC7AC "replaceByApi"\uB9CC \uC9C0\uC6D0'
-      );
-    }
     this.readDebounceMs = opts.readWatermarkDebounceMs ?? 400;
     this.logger = opts.logger;
     if (opts.initialLastMessageIds) {
@@ -2136,6 +2189,16 @@ var NoveraChat = class {
   readDebounceMs;
   logger;
   connectedOnce = false;
+  /**
+   * 방별 "실시간 파이프라인으로 본 최대 message_id" — 재연결 핸드셰이크의
+   * `?since=`와 backfill 시작점.
+   *
+   * **의도적으로 낮게 유지한다.** 히스토리 로드(REST)는 이 값을 올리지
+   * 않는다 — 앵커가 낮으면 backfill이 이미 가진 것까지 다시 주는 쪽으로
+   * (안전), 높으면 못 받은 것을 영영 건너뛰는 쪽으로(치명) 실패하기
+   * 때문이다. 중복은 수신 측(`MessageCollection.onIncoming`)의 id dedupe가
+   * 흡수하므로, "빠뜨린 갱신"으로 보고 올리지 말 것.
+   */
   lastMessageIdByRoom = /* @__PURE__ */ new Map();
   /** Most recently dispatched presence event key, `${userId}:${at}:${online}`.
    *  Used to drop the N-1 shared-room copies of a single online/offline

package/dist/index.d.cts

@@ -225,6 +225,7 @@ interface UnreadRoomItem {
     lastMessageId?: string | null;
     lastReadMessageId?: string | null;
     lastMessagePreview?: string | null;
+    lastMessageAt?: number | null;
     memberCount?: number;
     membersPreview?: MemberPreview[];
 }
@@ -380,11 +381,12 @@ type PushTrigger = "ALL" | "MENTION_ONLY" | "OFF";
  *
  * 원칙:
  *   1. 캐시 = 렌더 힌트, 서버가 항상 이긴다 — 시작 시 스냅샷 즉시 렌더,
- *      API 도착 시 통째 교체(diff 병합 없음).
+ *      API 도착 시 기본 통째 교체(replaceByApi). 옵트인 mergeDiff는
+ *      fresh보다 오래된 메시지만 보존하는 병합(서버를 덮어쓰지 않음).
  *   2. 저장소는 SDK가 정하지 않는다 — `CacheStore` 인터페이스만 정의,
  *      구현은 앱이 주입(localStorage/IndexedDB 등).
  *   3. 버전 스탬프 + 통째 폐기 — 키에 스키마 버전(`nc.v1.…`), 파싱 실패
- *      시 해당 키를 드랍. 삭제 타이머 켜진 방은 캐시 대상에서 제외.
+ *      시 해당 키를 드랍.
  */
 /**
  * 앱이 주입하는 key-value 스냅샷 저장소.
@@ -417,9 +419,10 @@ interface CacheStore {
 /**
  * 캐시 스냅샷과 API 응답을 어떻게 합칠지.
  *
- * 현재는 `"replaceByApi"`만 구현되어 있다 — `"mergeDiff"`는 서버 측
- * 무효화 규칙(삭제 타이머 만료 통지·재입장 컷오프 등)이 확정된 뒤
- * 병합 함수가 채워질 진입점이다.
+ * - `"replaceByApi"` (기본) — 스냅샷 즉시 렌더 후 API 도착 시 통째 교체.
+ * - `"mergeDiff"` — fresh 페이지보다 오래된 캐시 메시지를 보존·병합해 더
+ *   긴 연속 히스토리 유지. `history_from`으로 컷오프분을, fresh 대조로
+ *   삭제분을 걸러내고, 캐시·fresh 사이 갭(겹침 없음)이면 통째 교체 폴백.
  */
 type CachePolicy = "replaceByApi" | "mergeDiff";
 /**
@@ -597,7 +600,8 @@ interface ClientOptions {
      * 렌더에 쓸 수 있다. 자세한 건 `CacheStore` 문서 참조.
      */
     cacheStore?: CacheStore;
-    /** 캐시 스냅샷과 API 응답의 합성 방식. 현재 `"replaceByApi"`만 지원. */
+    /** 캐시 스냅샷과 API 응답의 합성 방식. 기본 `"replaceByApi"`(통째 교체),
+     *  `"mergeDiff"`는 옵트인 — 옛 캐시 메시지를 보존·병합. */
     cachePolicy?: CachePolicy;
     autoReconnect?: boolean;
     pingIntervalMs?: number;
@@ -760,8 +764,8 @@ declare function pendingFileChatMessage(p: {
  * RoomStore(sdk-react)에 있던 이벤트 반영·낙관적 전송·캐시 hydrate→교체
  * 로직의 코어 이관본. 바인딩(React·Flutter)은 이 컬렉션을 감싸는 얇은
  * 접착층이 되고, "캐시는 렌더 힌트, 서버가 항상 이긴다" 같은 불변식은
- * 코어가 강제한다. 추후 diff 병합은 `applyFresh`의 mergeDiff 분기
- * 하나로 들어온다.
+ * 코어가 강제한다. diff 병합(mergeDiff)은 `applyFresh`→`mergeFresh`로
+ * 들어온다.
  */
 
 /**
@@ -854,11 +858,26 @@ declare class MessageCollection {
      *  힌트일 뿐). */
     private hydrateFromCache;
     /**
-     * API 최신 페이지를 컬렉션에 반영한다 — **diff 병합 진입점**.
-     * replaceByApi(현재 유일 정책)는 스냅샷을 걷어내고 통째 교체하고,
-     * mergeDiff는 서버 무효화 규칙 확정 후 이 분기 안에 병합 함수가 채워진다.
+     * API 최신 페이지를 컬렉션에 반영한다.
+     * replaceByApi(기본)는 스냅샷을 걷어내고 통째 교체하고, mergeDiff는
+     * 스냅샷의 옛 메시지를 보존·병합한다(`mergeFresh`).
      */
     private applyFresh;
+    /**
+     * diff 병합 — 스냅샷의 옛 메시지를 보존해 fresh 페이지 아래에 잇는다.
+     *
+     * 판정 규칙(서버 계약, 07-23 확정):
+     * - **컷오프분**: `history_from`(히스토리 하한, unix ms)보다 오래된 캐시
+     *   메시지는 재입장 컷/대화 지우기로 볼 수 없게 된 것 → 폐기.
+     * - **삭제분**: fresh 커버 구간(id ≥ fresh 최저 id)에 있는데 fresh에
+     *   없는 캐시 메시지는 그 사이 삭제된 것(타이머 만료 포함) → 폐기.
+     * - **갭 폴백**: 캐시의 최신 메시지가 fresh와 겹치지 않으면 누락 구간이
+     *   있을 수 있으므로 병합하지 않고 통째 교체.
+     *
+     * 겹치는 구간은 항상 fresh가 정답(수정 반영) — 보존되는 건 fresh 범위
+     * **밖**의 옛 메시지뿐이라 "서버가 항상 이긴다" 불변식은 유지된다.
+     */
+    private mergeFresh;
     /**
      * Send `text` optimistically: a `sending` bubble appears immediately (one
      * microtask later — `Room.send` is async), then flips to `sent` (with the
@@ -893,6 +912,17 @@ declare class MessageCollection {
     /** Unsubscribe from the room and flush the pending read watermark. The
      *  collection must not be used afterwards. */
     dispose(): void;
+    /**
+     * 수신 프레임을 컬렉션에 넣는다.
+     *
+     * 두 가지를 방어한다 — backfill(`chat.backfill()`)은 재연결 시 앵커
+     * 이후를 **다시** 실어오므로, 이미 들고 있는 메시지가 섞여 오고 화면보다
+     * 오래된 메시지도 함께 온다:
+     * - **중복**: 같은 id가 이미 있으면 무시한다.
+     * - **순서**: 뒤에서부터 자리를 찾아 꽂는다. 실시간 프레임은 항상 마지막
+     *   메시지보다 새로우므로 비교 1번으로 끝나고(빠른 경로), 옛 메시지가
+     *   섞여 올 때만 탐색이 일어난다.
+     */
     private onIncoming;
     private onUpdated;
     private onDeleted;
@@ -946,9 +976,6 @@ declare class Room {
     private readonly cacheStore;
     private readonly cachePolicy;
     private readonly logger;
-    /** 삭제 타이머 여부 세션 메모 — null=미확인, 값=마지막 detail() 결과. */
-    private timerSeconds;
-    private timerKnown;
     constructor(roomId: string, http: HttpClient, ws: ReconnectingWs, readDebounceMs: number, opts?: {
         cacheStore?: CacheStore;
         cachePolicy?: CachePolicy;
@@ -1150,6 +1177,8 @@ declare class Room {
         items: MessageOut[];
         nextCursor: MessageIdStr | null;
         hasMore: boolean;
+        /** 히스토리 하한(unix ms). null=컷 없음 — 재입장 컷·대화 지우기가 수렴. */
+        historyFrom: number | null;
     }>;
     /** 이 방의 상세 정보 (`GET /rooms/{id}`) — 이름·멤버 수·삭제 타이머 등. */
     detail(): Promise<RoomOut>;
@@ -1166,11 +1195,12 @@ declare class Room {
         items: MessageOut[];
         nextCursor: MessageIdStr | null;
         hasMore: boolean;
+        historyFrom: number | null;
     } | null>;
     /**
-     * 최신 페이지 스냅샷 저장. 삭제 타이머가 켜진 방은 저장하지 않고 기존
-     * 스냅샷도 지운다 — 타이머 만료로 서버에서 사라진 메시지가 로컬 캐시에
-     * 살아남는 보안 충돌을 원천 차단한다.
+     * 최신 페이지 스냅샷 저장. 삭제 타이머 방도 저장한다 — 서버가 만료를
+     * 일반 `message_deleted` 프레임으로 브로드캐스트하고 히스토리에서도
+     * 즉시 제외하므로, 만료분은 라이브 이벤트/`history_from` diff로 정리된다.
      */
     private cacheWriteRecent;
     /**
@@ -1367,6 +1397,16 @@ declare class NoveraChat {
     private readDebounceMs;
     private logger;
     private connectedOnce;
+    /**
+     * 방별 "실시간 파이프라인으로 본 최대 message_id" — 재연결 핸드셰이크의
+     * `?since=`와 backfill 시작점.
+     *
+     * **의도적으로 낮게 유지한다.** 히스토리 로드(REST)는 이 값을 올리지
+     * 않는다 — 앵커가 낮으면 backfill이 이미 가진 것까지 다시 주는 쪽으로
+     * (안전), 높으면 못 받은 것을 영영 건너뛰는 쪽으로(치명) 실패하기
+     * 때문이다. 중복은 수신 측(`MessageCollection.onIncoming`)의 id dedupe가
+     * 흡수하므로, "빠뜨린 갱신"으로 보고 올리지 말 것.
+     */
     private lastMessageIdByRoom;
     /** Most recently dispatched presence event key, `${userId}:${at}:${online}`.
      *  Used to drop the N-1 shared-room copies of a single online/offline

package/dist/index.d.ts

@@ -225,6 +225,7 @@ interface UnreadRoomItem {
     lastMessageId?: string | null;
     lastReadMessageId?: string | null;
     lastMessagePreview?: string | null;
+    lastMessageAt?: number | null;
     memberCount?: number;
     membersPreview?: MemberPreview[];
 }
@@ -380,11 +381,12 @@ type PushTrigger = "ALL" | "MENTION_ONLY" | "OFF";
  *
  * 원칙:
  *   1. 캐시 = 렌더 힌트, 서버가 항상 이긴다 — 시작 시 스냅샷 즉시 렌더,
- *      API 도착 시 통째 교체(diff 병합 없음).
+ *      API 도착 시 기본 통째 교체(replaceByApi). 옵트인 mergeDiff는
+ *      fresh보다 오래된 메시지만 보존하는 병합(서버를 덮어쓰지 않음).
  *   2. 저장소는 SDK가 정하지 않는다 — `CacheStore` 인터페이스만 정의,
  *      구현은 앱이 주입(localStorage/IndexedDB 등).
  *   3. 버전 스탬프 + 통째 폐기 — 키에 스키마 버전(`nc.v1.…`), 파싱 실패
- *      시 해당 키를 드랍. 삭제 타이머 켜진 방은 캐시 대상에서 제외.
+ *      시 해당 키를 드랍.
  */
 /**
  * 앱이 주입하는 key-value 스냅샷 저장소.
@@ -417,9 +419,10 @@ interface CacheStore {
 /**
  * 캐시 스냅샷과 API 응답을 어떻게 합칠지.
  *
- * 현재는 `"replaceByApi"`만 구현되어 있다 — `"mergeDiff"`는 서버 측
- * 무효화 규칙(삭제 타이머 만료 통지·재입장 컷오프 등)이 확정된 뒤
- * 병합 함수가 채워질 진입점이다.
+ * - `"replaceByApi"` (기본) — 스냅샷 즉시 렌더 후 API 도착 시 통째 교체.
+ * - `"mergeDiff"` — fresh 페이지보다 오래된 캐시 메시지를 보존·병합해 더
+ *   긴 연속 히스토리 유지. `history_from`으로 컷오프분을, fresh 대조로
+ *   삭제분을 걸러내고, 캐시·fresh 사이 갭(겹침 없음)이면 통째 교체 폴백.
  */
 type CachePolicy = "replaceByApi" | "mergeDiff";
 /**
@@ -597,7 +600,8 @@ interface ClientOptions {
      * 렌더에 쓸 수 있다. 자세한 건 `CacheStore` 문서 참조.
      */
     cacheStore?: CacheStore;
-    /** 캐시 스냅샷과 API 응답의 합성 방식. 현재 `"replaceByApi"`만 지원. */
+    /** 캐시 스냅샷과 API 응답의 합성 방식. 기본 `"replaceByApi"`(통째 교체),
+     *  `"mergeDiff"`는 옵트인 — 옛 캐시 메시지를 보존·병합. */
     cachePolicy?: CachePolicy;
     autoReconnect?: boolean;
     pingIntervalMs?: number;
@@ -760,8 +764,8 @@ declare function pendingFileChatMessage(p: {
  * RoomStore(sdk-react)에 있던 이벤트 반영·낙관적 전송·캐시 hydrate→교체
  * 로직의 코어 이관본. 바인딩(React·Flutter)은 이 컬렉션을 감싸는 얇은
  * 접착층이 되고, "캐시는 렌더 힌트, 서버가 항상 이긴다" 같은 불변식은
- * 코어가 강제한다. 추후 diff 병합은 `applyFresh`의 mergeDiff 분기
- * 하나로 들어온다.
+ * 코어가 강제한다. diff 병합(mergeDiff)은 `applyFresh`→`mergeFresh`로
+ * 들어온다.
  */
 
 /**
@@ -854,11 +858,26 @@ declare class MessageCollection {
      *  힌트일 뿐). */
     private hydrateFromCache;
     /**
-     * API 최신 페이지를 컬렉션에 반영한다 — **diff 병합 진입점**.
-     * replaceByApi(현재 유일 정책)는 스냅샷을 걷어내고 통째 교체하고,
-     * mergeDiff는 서버 무효화 규칙 확정 후 이 분기 안에 병합 함수가 채워진다.
+     * API 최신 페이지를 컬렉션에 반영한다.
+     * replaceByApi(기본)는 스냅샷을 걷어내고 통째 교체하고, mergeDiff는
+     * 스냅샷의 옛 메시지를 보존·병합한다(`mergeFresh`).
      */
     private applyFresh;
+    /**
+     * diff 병합 — 스냅샷의 옛 메시지를 보존해 fresh 페이지 아래에 잇는다.
+     *
+     * 판정 규칙(서버 계약, 07-23 확정):
+     * - **컷오프분**: `history_from`(히스토리 하한, unix ms)보다 오래된 캐시
+     *   메시지는 재입장 컷/대화 지우기로 볼 수 없게 된 것 → 폐기.
+     * - **삭제분**: fresh 커버 구간(id ≥ fresh 최저 id)에 있는데 fresh에
+     *   없는 캐시 메시지는 그 사이 삭제된 것(타이머 만료 포함) → 폐기.
+     * - **갭 폴백**: 캐시의 최신 메시지가 fresh와 겹치지 않으면 누락 구간이
+     *   있을 수 있으므로 병합하지 않고 통째 교체.
+     *
+     * 겹치는 구간은 항상 fresh가 정답(수정 반영) — 보존되는 건 fresh 범위
+     * **밖**의 옛 메시지뿐이라 "서버가 항상 이긴다" 불변식은 유지된다.
+     */
+    private mergeFresh;
     /**
      * Send `text` optimistically: a `sending` bubble appears immediately (one
      * microtask later — `Room.send` is async), then flips to `sent` (with the
@@ -893,6 +912,17 @@ declare class MessageCollection {
     /** Unsubscribe from the room and flush the pending read watermark. The
      *  collection must not be used afterwards. */
     dispose(): void;
+    /**
+     * 수신 프레임을 컬렉션에 넣는다.
+     *
+     * 두 가지를 방어한다 — backfill(`chat.backfill()`)은 재연결 시 앵커
+     * 이후를 **다시** 실어오므로, 이미 들고 있는 메시지가 섞여 오고 화면보다
+     * 오래된 메시지도 함께 온다:
+     * - **중복**: 같은 id가 이미 있으면 무시한다.
+     * - **순서**: 뒤에서부터 자리를 찾아 꽂는다. 실시간 프레임은 항상 마지막
+     *   메시지보다 새로우므로 비교 1번으로 끝나고(빠른 경로), 옛 메시지가
+     *   섞여 올 때만 탐색이 일어난다.
+     */
     private onIncoming;
     private onUpdated;
     private onDeleted;
@@ -946,9 +976,6 @@ declare class Room {
     private readonly cacheStore;
     private readonly cachePolicy;
     private readonly logger;
-    /** 삭제 타이머 여부 세션 메모 — null=미확인, 값=마지막 detail() 결과. */
-    private timerSeconds;
-    private timerKnown;
     constructor(roomId: string, http: HttpClient, ws: ReconnectingWs, readDebounceMs: number, opts?: {
         cacheStore?: CacheStore;
         cachePolicy?: CachePolicy;
@@ -1150,6 +1177,8 @@ declare class Room {
         items: MessageOut[];
         nextCursor: MessageIdStr | null;
         hasMore: boolean;
+        /** 히스토리 하한(unix ms). null=컷 없음 — 재입장 컷·대화 지우기가 수렴. */
+        historyFrom: number | null;
     }>;
     /** 이 방의 상세 정보 (`GET /rooms/{id}`) — 이름·멤버 수·삭제 타이머 등. */
     detail(): Promise<RoomOut>;
@@ -1166,11 +1195,12 @@ declare class Room {
         items: MessageOut[];
         nextCursor: MessageIdStr | null;
         hasMore: boolean;
+        historyFrom: number | null;
     } | null>;
     /**
-     * 최신 페이지 스냅샷 저장. 삭제 타이머가 켜진 방은 저장하지 않고 기존
-     * 스냅샷도 지운다 — 타이머 만료로 서버에서 사라진 메시지가 로컬 캐시에
-     * 살아남는 보안 충돌을 원천 차단한다.
+     * 최신 페이지 스냅샷 저장. 삭제 타이머 방도 저장한다 — 서버가 만료를
+     * 일반 `message_deleted` 프레임으로 브로드캐스트하고 히스토리에서도
+     * 즉시 제외하므로, 만료분은 라이브 이벤트/`history_from` diff로 정리된다.
      */
     private cacheWriteRecent;
     /**
@@ -1367,6 +1397,16 @@ declare class NoveraChat {
     private readDebounceMs;
     private logger;
     private connectedOnce;
+    /**
+     * 방별 "실시간 파이프라인으로 본 최대 message_id" — 재연결 핸드셰이크의
+     * `?since=`와 backfill 시작점.
+     *
+     * **의도적으로 낮게 유지한다.** 히스토리 로드(REST)는 이 값을 올리지
+     * 않는다 — 앵커가 낮으면 backfill이 이미 가진 것까지 다시 주는 쪽으로
+     * (안전), 높으면 못 받은 것을 영영 건너뛰는 쪽으로(치명) 실패하기
+     * 때문이다. 중복은 수신 측(`MessageCollection.onIncoming`)의 id dedupe가
+     * 흡수하므로, "빠뜨린 갱신"으로 보고 올리지 말 것.
+     */
     private lastMessageIdByRoom;
     /** Most recently dispatched presence event key, `${userId}:${at}:${online}`.
      *  Used to drop the N-1 shared-room copies of a single online/offline

package/dist/index.js

@@ -23,6 +23,7 @@ function parseUnreadRoomItem(j) {
     lastMessageId: j["last_message_id"],
     lastReadMessageId: j["last_read_message_id"],
     lastMessagePreview: j["last_message_preview"],
+    lastMessageAt: j["last_message_at"],
     memberCount: j["member_count"],
     membersPreview: j["members_preview"] == null ? void 0 : j["members_preview"].map((e) => parseMemberPreview(e))
   };
@@ -777,23 +778,71 @@ var MessageCollection = class {
     this.emit("hydrated");
   }
   /**
-   * API 최신 페이지를 컬렉션에 반영한다 — **diff 병합 진입점**.
-   * replaceByApi(현재 유일 정책)는 스냅샷을 걷어내고 통째 교체하고,
-   * mergeDiff는 서버 무효화 규칙 확정 후 이 분기 안에 병합 함수가 채워진다.
+   * API 최신 페이지를 컬렉션에 반영한다.
+   * replaceByApi(기본)는 스냅샷을 걷어내고 통째 교체하고, mergeDiff는
+   * 스냅샷의 옛 메시지를 보존·병합한다(`mergeFresh`).
    */
   applyFresh(page) {
-    if (this.policy === "mergeDiff") {
-      throw new Error('CachePolicy "mergeDiff" \uB294 \uC544\uC9C1 \uBBF8\uAD6C\uD604 \u2014 \uC11C\uBC84 \uBB34\uD6A8\uD654 \uADDC\uCE59 \uD655\uC815 \uD6C4 \uC9C0\uC6D0 \uC608\uC815');
+    if (this.policy === "mergeDiff" && this.hydratedCount > 0) {
+      this.mergeFresh(page);
+      return;
     }
     if (this.hydratedCount > 0) {
       this._messages.splice(0, this.hydratedCount);
       this.hydratedCount = 0;
     }
-    this._messages.unshift(...page.items.map(chatMessageFromHistory));
+    const indexById = /* @__PURE__ */ new Map();
+    this._messages.forEach((m, i) => indexById.set(m.id, i));
+    const fresh = [];
+    for (const item of page.items.map(chatMessageFromHistory)) {
+      const at = indexById.get(item.id);
+      if (at === void 0) fresh.push(item);
+      else this._messages[at] = item;
+    }
+    this._messages.unshift(...fresh);
     this.oldestCursor = page.nextCursor;
     this._hasMore = page.hasMore;
     this.emit("replaced");
   }
+  /**
+   * diff 병합 — 스냅샷의 옛 메시지를 보존해 fresh 페이지 아래에 잇는다.
+   *
+   * 판정 규칙(서버 계약, 07-23 확정):
+   * - **컷오프분**: `history_from`(히스토리 하한, unix ms)보다 오래된 캐시
+   *   메시지는 재입장 컷/대화 지우기로 볼 수 없게 된 것 → 폐기.
+   * - **삭제분**: fresh 커버 구간(id ≥ fresh 최저 id)에 있는데 fresh에
+   *   없는 캐시 메시지는 그 사이 삭제된 것(타이머 만료 포함) → 폐기.
+   * - **갭 폴백**: 캐시의 최신 메시지가 fresh와 겹치지 않으면 누락 구간이
+   *   있을 수 있으므로 병합하지 않고 통째 교체.
+   *
+   * 겹치는 구간은 항상 fresh가 정답(수정 반영) — 보존되는 건 fresh 범위
+   * **밖**의 옛 메시지뿐이라 "서버가 항상 이긴다" 불변식은 유지된다.
+   */
+  mergeFresh(page) {
+    const cachedHead = this._messages.slice(0, this.hydratedCount);
+    this._messages.splice(0, this.hydratedCount);
+    this.hydratedCount = 0;
+    const freshIds = new Set(page.items.map((m) => m.messageId));
+    const freshOldest = page.items.length > 0 ? page.items[0].messageId : null;
+    const hf = page.historyFrom ?? null;
+    const overlaps = cachedHead.length > 0 && freshOldest != null && freshIds.has(cachedHead.at(-1).id);
+    let preserved = [];
+    if (overlaps && page.hasMore) {
+      preserved = cachedHead.filter((m) => {
+        if (freshIds.has(m.id)) return false;
+        if (!idGreater(freshOldest, m.id)) return false;
+        if (hf != null && m.createdAtMs != null && m.createdAtMs < hf) {
+          return false;
+        }
+        return true;
+      });
+    }
+    this._messages.unshift(...page.items.map(chatMessageFromHistory));
+    this._messages.unshift(...preserved);
+    this.oldestCursor = preserved.length > 0 ? preserved[0].id : page.nextCursor;
+    this._hasMore = page.hasMore;
+    this.emit("replaced");
+  }
   // ── optimistic sends ────────────────────────────────────────────
   /**
    * Send `text` optimistically: a `sending` bubble appears immediately (one
@@ -921,8 +970,26 @@ var MessageCollection = class {
     this.bus.removeAll();
   }
   // ── event handlers ──────────────────────────────────────────────
+  /**
+   * 수신 프레임을 컬렉션에 넣는다.
+   *
+   * 두 가지를 방어한다 — backfill(`chat.backfill()`)은 재연결 시 앵커
+   * 이후를 **다시** 실어오므로, 이미 들고 있는 메시지가 섞여 오고 화면보다
+   * 오래된 메시지도 함께 온다:
+   * - **중복**: 같은 id가 이미 있으면 무시한다.
+   * - **순서**: 뒤에서부터 자리를 찾아 꽂는다. 실시간 프레임은 항상 마지막
+   *   메시지보다 새로우므로 비교 1번으로 끝나고(빠른 경로), 옛 메시지가
+   *   섞여 올 때만 탐색이 일어난다.
+   */
   onIncoming(f) {
-    this._messages.push(chatMessageFromLive(f));
+    const msg = chatMessageFromLive(f);
+    let i = this._messages.length - 1;
+    for (; i >= 0; i--) {
+      const cur = this._messages[i];
+      if (cur.id === msg.id) return;
+      if (!idGreater(cur.id, msg.id)) break;
+    }
+    this._messages.splice(i + 1, 0, msg);
     this.emit("inserted");
   }
   onUpdated(f) {
@@ -1106,9 +1173,6 @@ var Room = class _Room {
   cacheStore;
   cachePolicy;
   logger;
-  /** 삭제 타이머 여부 세션 메모 — null=미확인, 값=마지막 detail() 결과. */
-  timerSeconds = null;
-  timerKnown = false;
   /**
    * 이 방의 메시지 상태를 소유하는 `MessageCollection`을 만든다.
    *
@@ -1586,7 +1650,8 @@ var Room = class _Room {
       items: raw.items.map(toMessageOut),
       // 파싱 성공한 응답만 캐시에 넣는다
       nextCursor: raw.next_cursor,
-      hasMore: raw.has_more
+      hasMore: raw.has_more,
+      historyFrom: raw.history_from ?? null
     };
     void this.cacheWriteRecent(raw);
     return page;
@@ -1597,10 +1662,7 @@ var Room = class _Room {
       "GET",
       `/api/v1/rooms/${this.roomId}`
     );
-    const out = parseRoomOut(raw);
-    this.timerSeconds = out.timerSeconds;
-    this.timerKnown = true;
-    return out;
+    return parseRoomOut(raw);
   }
   /**
    * 히스토리 최신 페이지의 캐시 스냅샷 — 마지막 `listRecent()` 성공 응답의
@@ -1622,7 +1684,8 @@ var Room = class _Room {
       return {
         items: j.items.map(toMessageOut),
         nextCursor: j.next_cursor,
-        hasMore: j.has_more
+        hasMore: j.has_more,
+        historyFrom: j.history_from ?? null
       };
     } catch (err) {
       this.logger?.("warn", `cache_read_failed key=${key}`, err);
@@ -1634,20 +1697,15 @@ var Room = class _Room {
     }
   }
   /**
-   * 최신 페이지 스냅샷 저장. 삭제 타이머가 켜진 방은 저장하지 않고 기존
-   * 스냅샷도 지운다 — 타이머 만료로 서버에서 사라진 메시지가 로컬 캐시에
-   * 살아남는 보안 충돌을 원천 차단한다.
+   * 최신 페이지 스냅샷 저장. 삭제 타이머 방도 저장한다 — 서버가 만료를
+   * 일반 `message_deleted` 프레임으로 브로드캐스트하고 히스토리에서도
+   * 즉시 제외하므로, 만료분은 라이브 이벤트/`history_from` diff로 정리된다.
    */
   async cacheWriteRecent(raw) {
     const store = this.cacheStore;
     if (!store) return;
     const key = CacheKeys.msgs(this.roomId);
     try {
-      if (!this.timerKnown) await this.detail();
-      if (this.timerSeconds != null) {
-        await store.remove(key);
-        return;
-      }
       await store.write(key, JSON.stringify(raw));
     } catch (err) {
       this.logger?.("warn", `cache_write_failed key=${key}`, err);
@@ -2041,11 +2099,6 @@ var NoveraChat = class {
     if (!opts.appId) throw new Error("appId required");
     if (!opts.endpoint) throw new Error("endpoint required");
     if (!opts.tokenProvider) throw new Error("tokenProvider required");
-    if (opts.cachePolicy === "mergeDiff") {
-      throw new Error(
-        'CachePolicy "mergeDiff" \uB294 \uC544\uC9C1 \uBBF8\uAD6C\uD604 \u2014 \uD604\uC7AC "replaceByApi"\uB9CC \uC9C0\uC6D0'
-      );
-    }
     this.readDebounceMs = opts.readWatermarkDebounceMs ?? 400;
     this.logger = opts.logger;
     if (opts.initialLastMessageIds) {
@@ -2101,6 +2154,16 @@ var NoveraChat = class {
   readDebounceMs;
   logger;
   connectedOnce = false;
+  /**
+   * 방별 "실시간 파이프라인으로 본 최대 message_id" — 재연결 핸드셰이크의
+   * `?since=`와 backfill 시작점.
+   *
+   * **의도적으로 낮게 유지한다.** 히스토리 로드(REST)는 이 값을 올리지
+   * 않는다 — 앵커가 낮으면 backfill이 이미 가진 것까지 다시 주는 쪽으로
+   * (안전), 높으면 못 받은 것을 영영 건너뛰는 쪽으로(치명) 실패하기
+   * 때문이다. 중복은 수신 측(`MessageCollection.onIncoming`)의 id dedupe가
+   * 흡수하므로, "빠뜨린 갱신"으로 보고 올리지 말 것.
+   */
   lastMessageIdByRoom = /* @__PURE__ */ new Map();
   /** Most recently dispatched presence event key, `${userId}:${at}:${online}`.
    *  Used to drop the N-1 shared-room copies of a single online/offline

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noverachat/sdk-web",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "NoveraChat browser/Node SDK — WebSocket + REST client with optimistic UI, reconnection and gap-fill",
   "license": "MIT",
   "type": "module",

package/src/cache.ts

@@ -4,11 +4,12 @@
  *
  * 원칙:
  *   1. 캐시 = 렌더 힌트, 서버가 항상 이긴다 — 시작 시 스냅샷 즉시 렌더,
- *      API 도착 시 통째 교체(diff 병합 없음).
+ *      API 도착 시 기본 통째 교체(replaceByApi). 옵트인 mergeDiff는
+ *      fresh보다 오래된 메시지만 보존하는 병합(서버를 덮어쓰지 않음).
  *   2. 저장소는 SDK가 정하지 않는다 — `CacheStore` 인터페이스만 정의,
  *      구현은 앱이 주입(localStorage/IndexedDB 등).
  *   3. 버전 스탬프 + 통째 폐기 — 키에 스키마 버전(`nc.v1.…`), 파싱 실패
- *      시 해당 키를 드랍. 삭제 타이머 켜진 방은 캐시 대상에서 제외.
+ *      시 해당 키를 드랍.
  */
 
 /**
@@ -43,9 +44,10 @@ export interface CacheStore {
 /**
  * 캐시 스냅샷과 API 응답을 어떻게 합칠지.
  *
- * 현재는 `"replaceByApi"`만 구현되어 있다 — `"mergeDiff"`는 서버 측
- * 무효화 규칙(삭제 타이머 만료 통지·재입장 컷오프 등)이 확정된 뒤
- * 병합 함수가 채워질 진입점이다.
+ * - `"replaceByApi"` (기본) — 스냅샷 즉시 렌더 후 API 도착 시 통째 교체.
+ * - `"mergeDiff"` — fresh 페이지보다 오래된 캐시 메시지를 보존·병합해 더
+ *   긴 연속 히스토리 유지. `history_from`으로 컷오프분을, fresh 대조로
+ *   삭제분을 걸러내고, 캐시·fresh 사이 갭(겹침 없음)이면 통째 교체 폴백.
  */
 export type CachePolicy = "replaceByApi" | "mergeDiff";
 

package/src/client.ts

@@ -57,6 +57,16 @@ export class NoveraChat {
   private readDebounceMs: number;
   private logger: ClientOptions["logger"];
   private connectedOnce = false;
+  /**
+   * 방별 "실시간 파이프라인으로 본 최대 message_id" — 재연결 핸드셰이크의
+   * `?since=`와 backfill 시작점.
+   *
+   * **의도적으로 낮게 유지한다.** 히스토리 로드(REST)는 이 값을 올리지
+   * 않는다 — 앵커가 낮으면 backfill이 이미 가진 것까지 다시 주는 쪽으로
+   * (안전), 높으면 못 받은 것을 영영 건너뛰는 쪽으로(치명) 실패하기
+   * 때문이다. 중복은 수신 측(`MessageCollection.onIncoming`)의 id dedupe가
+   * 흡수하므로, "빠뜨린 갱신"으로 보고 올리지 말 것.
+   */
   private lastMessageIdByRoom = new Map<string, MessageIdStr>();
   /** Most recently dispatched presence event key, `${userId}:${at}:${online}`.
    *  Used to drop the N-1 shared-room copies of a single online/offline
@@ -68,11 +78,6 @@ export class NoveraChat {
     if (!opts.appId) throw new Error("appId required");
     if (!opts.endpoint) throw new Error("endpoint required");
     if (!opts.tokenProvider) throw new Error("tokenProvider required");
-    if (opts.cachePolicy === "mergeDiff") {
-      throw new Error(
-        'CachePolicy "mergeDiff" 는 아직 미구현 — 현재 "replaceByApi"만 지원',
-      );
-    }
 
     // 400ms is the read-receipt-UX sweet spot for chat apps. Shorter and
     // we waste WS frames on every micro-scroll; longer and the "✓ read"

package/src/features/message-collection.ts

@@ -4,8 +4,8 @@
  * RoomStore(sdk-react)에 있던 이벤트 반영·낙관적 전송·캐시 hydrate→교체
  * 로직의 코어 이관본. 바인딩(React·Flutter)은 이 컬렉션을 감싸는 얇은
  * 접착층이 되고, "캐시는 렌더 힌트, 서버가 항상 이긴다" 같은 불변식은
- * 코어가 강제한다. 추후 diff 병합은 `applyFresh`의 mergeDiff 분기
- * 하나로 들어온다.
+ * 코어가 강제한다. diff 병합(mergeDiff)은 `applyFresh`→`mergeFresh`로
+ * 들어온다.
  */
 
 import type {
@@ -205,28 +205,96 @@ export class MessageCollection {
   }
 
   /**
-   * API 최신 페이지를 컬렉션에 반영한다 — **diff 병합 진입점**.
-   * replaceByApi(현재 유일 정책)는 스냅샷을 걷어내고 통째 교체하고,
-   * mergeDiff는 서버 무효화 규칙 확정 후 이 분기 안에 병합 함수가 채워진다.
+   * API 최신 페이지를 컬렉션에 반영한다.
+   * replaceByApi(기본)는 스냅샷을 걷어내고 통째 교체하고, mergeDiff는
+   * 스냅샷의 옛 메시지를 보존·병합한다(`mergeFresh`).
    */
   private applyFresh(page: {
     items: MessageOut[];
     nextCursor: MessageIdStr | null;
     hasMore: boolean;
+    historyFrom?: number | null;
   }): void {
-    if (this.policy === "mergeDiff") {
-      throw new Error('CachePolicy "mergeDiff" 는 아직 미구현 — 서버 무효화 규칙 확정 후 지원 예정');
+    if (this.policy === "mergeDiff" && this.hydratedCount > 0) {
+      this.mergeFresh(page);
+      return;
     }
     if (this.hydratedCount > 0) {
       this._messages.splice(0, this.hydratedCount); // 스냅샷 통째 폐기 → 서버가 이긴다
       this.hydratedCount = 0;
     }
-    this._messages.unshift(...page.items.map(chatMessageFromHistory));
+    // id 기준 upsert — 이미 들고 있는 메시지는 서버 버전으로 교체하고, 없는
+    // 것만 앞에 잇는다. `load()`가 두 번 불려도(React StrictMode의 mount →
+    // cleanup → mount 사이클처럼) 같은 페이지가 겹쳐 쌓이지 않는다.
+    const indexById = new Map<string, number>();
+    this._messages.forEach((m, i) => indexById.set(m.id, i));
+    const fresh: ChatMessage[] = [];
+    for (const item of page.items.map(chatMessageFromHistory)) {
+      const at = indexById.get(item.id);
+      if (at === undefined) fresh.push(item);
+      else this._messages[at] = item; // 겹치는 구간은 서버가 이긴다
+    }
+    this._messages.unshift(...fresh);
     this.oldestCursor = page.nextCursor;
     this._hasMore = page.hasMore;
     this.emit("replaced");
   }
 
+  /**
+   * diff 병합 — 스냅샷의 옛 메시지를 보존해 fresh 페이지 아래에 잇는다.
+   *
+   * 판정 규칙(서버 계약, 07-23 확정):
+   * - **컷오프분**: `history_from`(히스토리 하한, unix ms)보다 오래된 캐시
+   *   메시지는 재입장 컷/대화 지우기로 볼 수 없게 된 것 → 폐기.
+   * - **삭제분**: fresh 커버 구간(id ≥ fresh 최저 id)에 있는데 fresh에
+   *   없는 캐시 메시지는 그 사이 삭제된 것(타이머 만료 포함) → 폐기.
+   * - **갭 폴백**: 캐시의 최신 메시지가 fresh와 겹치지 않으면 누락 구간이
+   *   있을 수 있으므로 병합하지 않고 통째 교체.
+   *
+   * 겹치는 구간은 항상 fresh가 정답(수정 반영) — 보존되는 건 fresh 범위
+   * **밖**의 옛 메시지뿐이라 "서버가 항상 이긴다" 불변식은 유지된다.
+   */
+  private mergeFresh(page: {
+    items: MessageOut[];
+    nextCursor: MessageIdStr | null;
+    hasMore: boolean;
+    historyFrom?: number | null;
+  }): void {
+    const cachedHead = this._messages.slice(0, this.hydratedCount);
+    this._messages.splice(0, this.hydratedCount);
+    this.hydratedCount = 0;
+
+    const freshIds = new Set(page.items.map((m) => m.messageId));
+    const freshOldest = page.items.length > 0 ? page.items[0]!.messageId : null;
+    const hf = page.historyFrom ?? null;
+
+    // 갭 폴백: 캐시 최신이 fresh에 없으면 연속성 보장 불가 → 통째 교체.
+    // fresh가 방 전체(hasMore=false)인데 범위 밖 캐시가 남는 경우도 유령이므로 교체.
+    const overlaps =
+      cachedHead.length > 0 &&
+      freshOldest != null &&
+      freshIds.has(cachedHead.at(-1)!.id);
+    let preserved: ChatMessage[] = [];
+    if (overlaps && page.hasMore) {
+      preserved = cachedHead.filter((m) => {
+        if (freshIds.has(m.id)) return false; // 겹침 → fresh가 대체
+        if (!idGreater(freshOldest, m.id)) return false; // fresh 구간 내 부재 → 삭제분
+        if (hf != null && m.createdAtMs != null && m.createdAtMs < hf) {
+          return false; // 컷오프분
+        }
+        return true;
+      });
+    }
+
+    this._messages.unshift(...page.items.map(chatMessageFromHistory));
+    this._messages.unshift(...preserved);
+    // 보존분이 있으면 스크롤백 커서를 보존분의 최저 id로 — 중복 로드 방지.
+    this.oldestCursor =
+      preserved.length > 0 ? preserved[0]!.id : page.nextCursor;
+    this._hasMore = page.hasMore;
+    this.emit("replaced");
+  }
+
   // ── optimistic sends ────────────────────────────────────────────
 
   /**
@@ -382,8 +450,26 @@ export class MessageCollection {
 
   // ── event handlers ──────────────────────────────────────────────
 
+  /**
+   * 수신 프레임을 컬렉션에 넣는다.
+   *
+   * 두 가지를 방어한다 — backfill(`chat.backfill()`)은 재연결 시 앵커
+   * 이후를 **다시** 실어오므로, 이미 들고 있는 메시지가 섞여 오고 화면보다
+   * 오래된 메시지도 함께 온다:
+   * - **중복**: 같은 id가 이미 있으면 무시한다.
+   * - **순서**: 뒤에서부터 자리를 찾아 꽂는다. 실시간 프레임은 항상 마지막
+   *   메시지보다 새로우므로 비교 1번으로 끝나고(빠른 경로), 옛 메시지가
+   *   섞여 올 때만 탐색이 일어난다.
+   */
   private onIncoming(f: WsChatReceive): void {
-    this._messages.push(chatMessageFromLive(f));
+    const msg = chatMessageFromLive(f);
+    let i = this._messages.length - 1;
+    for (; i >= 0; i--) {
+      const cur = this._messages[i]!;
+      if (cur.id === msg.id) return; // 이미 있음 — 재전송분
+      if (!idGreater(cur.id, msg.id)) break; // 여기가 삽입 자리
+    }
+    this._messages.splice(i + 1, 0, msg);
     this.emit("inserted");
   }
 

package/src/features/room.ts

@@ -205,10 +205,6 @@ export class Room {
   private readonly cacheStore: CacheStore | null;
   private readonly cachePolicy: CachePolicy;
   private readonly logger: ClientOptions["logger"];
-  /** 삭제 타이머 여부 세션 메모 — null=미확인, 값=마지막 detail() 결과. */
-  private timerSeconds: number | null = null;
-  private timerKnown = false;
-
   constructor(
     public readonly roomId: string,
     private http: HttpClient,
@@ -827,14 +823,18 @@ export class Room {
     items: MessageOut[];
     nextCursor: MessageIdStr | null;
     hasMore: boolean;
+    /** 히스토리 하한(unix ms). null=컷 없음 — 재입장 컷·대화 지우기가 수렴. */
+    historyFrom: number | null;
   }> {
     const raw = await this.http.request<{
       items: unknown[]; next_cursor: string | null; has_more: boolean;
+      history_from?: number | null;
     }>("GET", `/api/v1/rooms/${this.roomId}/messages`, undefined, { limit });
     const page = {
       items: raw.items.map(toMessageOut), // 파싱 성공한 응답만 캐시에 넣는다
       nextCursor: raw.next_cursor,
       hasMore: raw.has_more,
+      historyFrom: raw.history_from ?? null,
     };
     void this.cacheWriteRecent(raw);
     return page;
@@ -845,10 +845,7 @@ export class Room {
     const raw = await this.http.request<unknown>(
       "GET", `/api/v1/rooms/${this.roomId}`,
     );
-    const out = parseRoomOut(raw);
-    this.timerSeconds = out.timerSeconds;
-    this.timerKnown = true;
-    return out;
+    return parseRoomOut(raw);
   }
 
   /**
@@ -864,6 +861,7 @@ export class Room {
     items: MessageOut[];
     nextCursor: MessageIdStr | null;
     hasMore: boolean;
+    historyFrom: number | null;
   } | null> {
     const store = this.cacheStore;
     if (!store) return null;
@@ -873,11 +871,13 @@ export class Room {
       if (raw == null) return null;
       const j = JSON.parse(raw) as {
         items: unknown[]; next_cursor: string | null; has_more: boolean;
+        history_from?: number | null;
       };
       return {
         items: j.items.map(toMessageOut),
         nextCursor: j.next_cursor,
         hasMore: j.has_more,
+        historyFrom: j.history_from ?? null,
       };
     } catch (err) {
       this.logger?.("warn", `cache_read_failed key=${key}`, err);
@@ -891,23 +891,17 @@ export class Room {
   }
 
   /**
-   * 최신 페이지 스냅샷 저장. 삭제 타이머가 켜진 방은 저장하지 않고 기존
-   * 스냅샷도 지운다 — 타이머 만료로 서버에서 사라진 메시지가 로컬 캐시에
-   * 살아남는 보안 충돌을 원천 차단한다.
+   * 최신 페이지 스냅샷 저장. 삭제 타이머 방도 저장한다 — 서버가 만료를
+   * 일반 `message_deleted` 프레임으로 브로드캐스트하고 히스토리에서도
+   * 즉시 제외하므로, 만료분은 라이브 이벤트/`history_from` diff로 정리된다.
    */
   private async cacheWriteRecent(raw: unknown): Promise<void> {
     const store = this.cacheStore;
     if (!store) return;
     const key = CacheKeys.msgs(this.roomId);
     try {
-      if (!this.timerKnown) await this.detail(); // 세션당 1회 — 이후는 메모 재사용
-      if (this.timerSeconds != null) {
-        await store.remove(key);
-        return;
-      }
       await store.write(key, JSON.stringify(raw));
     } catch (err) {
-      // 타이머 확인 실패 포함 — 확신 없으면 저장하지 않는 쪽으로 기운다.
       this.logger?.("warn", `cache_write_failed key=${key}`, err);
     }
   }

package/src/generated/rest.ts

@@ -44,6 +44,7 @@ export interface UnreadRoomItem {
   lastMessageId?: string | null;
   lastReadMessageId?: string | null;
   lastMessagePreview?: string | null;
+  lastMessageAt?: number | null;
   memberCount?: number;
   membersPreview?: MemberPreview[];
 }
@@ -57,6 +58,7 @@ export function parseUnreadRoomItem(j: any): UnreadRoomItem {
     lastMessageId: j["last_message_id"],
     lastReadMessageId: j["last_read_message_id"],
     lastMessagePreview: j["last_message_preview"],
+    lastMessageAt: j["last_message_at"],
     memberCount: j["member_count"],
     membersPreview: j["members_preview"] == null ? undefined : (j["members_preview"] as unknown[]).map((e: any) => parseMemberPreview(e)),
   } as UnreadRoomItem;
@@ -155,6 +157,7 @@ export interface MessageListResponse {
   items: MessageOut[];
   nextCursor?: string | null;
   hasMore: boolean;
+  historyFrom?: number | null;
 }
 
 export function parseMessageListResponse(j: any): MessageListResponse {
@@ -162,6 +165,7 @@ export function parseMessageListResponse(j: any): MessageListResponse {
     items: (j["items"] as unknown[]).map((e: any) => parseMessageOut(e)),
     nextCursor: j["next_cursor"],
     hasMore: j["has_more"],
+    historyFrom: j["history_from"],
   } as MessageListResponse;
 }
 
@@ -489,6 +493,20 @@ export function parseJoinRequestCreateResponse(j: any): JoinRequestCreateRespons
   } as JoinRequestCreateResponse;
 }
 
+export interface RoomFilesResponse {
+  items: RoomFileItem[];
+  nextCursor?: string | null;
+  hasMore?: boolean;
+}
+
+export function parseRoomFilesResponse(j: any): RoomFilesResponse {
+  return {
+    items: (j["items"] as unknown[]).map((e: any) => parseRoomFileItem(e)),
+    nextCursor: j["next_cursor"],
+    hasMore: j["has_more"],
+  } as RoomFilesResponse;
+}
+
 /** Minimal sender identity — no friend/block/profile-url fluff. */
 export interface SenderMini {
   userId: string;
@@ -527,3 +545,49 @@ export type JoinPolicy = "OPEN" | "APPROVAL_REQUIRED";
 export type MemberRole = "OPERATOR" | "MEMBER" | "KICKED";
 
 export type PushTrigger = "ALL" | "MENTION_ONLY" | "OFF";
+
+/** 방에서 공유된 파일 1건 — 전달(forward)이면 메시지마다 한 번씩. */
+export interface RoomFileItem {
+  messageId: string;
+  senderId: string;
+  createdAtMs: number;
+  file: RoomFileInfo;
+}
+
+export function parseRoomFileItem(j: any): RoomFileItem {
+  return {
+    messageId: j["message_id"],
+    senderId: j["sender_id"],
+    createdAtMs: j["created_at_ms"],
+    file: parseRoomFileInfo(j["file"]),
+  } as RoomFileItem;
+}
+
+/** 한 파일의 메타 (rooms/{id}/files 항목의 file 필드). */
+export interface RoomFileInfo {
+  id: string;
+  kind: string;
+  mime?: string | null;
+  sizeBytes?: number | null;
+  originalName?: string | null;
+  width?: number | null;
+  height?: number | null;
+  durationSec?: number | null;
+  thumbnailStatus?: string | null;
+  forwardBlocked?: boolean;
+}
+
+export function parseRoomFileInfo(j: any): RoomFileInfo {
+  return {
+    id: j["id"],
+    kind: j["kind"],
+    mime: j["mime"],
+    sizeBytes: j["size_bytes"],
+    originalName: j["original_name"],
+    width: j["width"],
+    height: j["height"],
+    durationSec: j["duration_sec"],
+    thumbnailStatus: j["thumbnail_status"],
+    forwardBlocked: j["forward_blocked"],
+  } as RoomFileInfo;
+}

package/src/types.ts

@@ -251,7 +251,8 @@ export interface ClientOptions {
    * 렌더에 쓸 수 있다. 자세한 건 `CacheStore` 문서 참조.
    */
   cacheStore?: CacheStore;
-  /** 캐시 스냅샷과 API 응답의 합성 방식. 현재 `"replaceByApi"`만 지원. */
+  /** 캐시 스냅샷과 API 응답의 합성 방식. 기본 `"replaceByApi"`(통째 교체),
+   *  `"mergeDiff"`는 옵트인 — 옛 캐시 메시지를 보존·병합. */
   cachePolicy?: CachePolicy;
   autoReconnect?: boolean;         // default true
   pingIntervalMs?: number;         // default 20_000