@noverachat/sdk-web 0.4.0 → 0.5.0

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,13 +813,14 @@ 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);
@@ -829,6 +831,45 @@ var MessageCollection = class {
     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
@@ -1141,9 +1182,6 @@ var Room = class _Room {
   cacheStore;
   cachePolicy;
   logger;
-  /** 삭제 타이머 여부 세션 메모 — null=미확인, 값=마지막 detail() 결과. */
-  timerSeconds = null;
-  timerKnown = false;
   /**
    * 이 방의 메시지 상태를 소유하는 `MessageCollection`을 만든다.
    *
@@ -1621,7 +1659,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 +1671,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 +1693,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 +1706,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 +2108,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) {

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
@@ -946,9 +965,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 +1166,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 +1184,12 @@ declare class Room {
         items: MessageOut[];
         nextCursor: MessageIdStr | null;
         hasMore: boolean;
+        historyFrom: number | null;
     } | null>;
     /**
-     * 최신 페이지 스냅샷 저장. 삭제 타이머가 켜진 방은 저장하지 않고 기존
-     * 스냅샷도 지운다 — 타이머 만료로 서버에서 사라진 메시지가 로컬 캐시에
-     * 살아남는 보안 충돌을 원천 차단한다.
+     * 최신 페이지 스냅샷 저장. 삭제 타이머 방도 저장한다 — 서버가 만료를
+     * 일반 `message_deleted` 프레임으로 브로드캐스트하고 히스토리에서도
+     * 즉시 제외하므로, 만료분은 라이브 이벤트/`history_from` diff로 정리된다.
      */
     private cacheWriteRecent;
     /**

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
@@ -946,9 +965,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 +1166,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 +1184,12 @@ declare class Room {
         items: MessageOut[];
         nextCursor: MessageIdStr | null;
         hasMore: boolean;
+        historyFrom: number | null;
     } | null>;
     /**
-     * 최신 페이지 스냅샷 저장. 삭제 타이머가 켜진 방은 저장하지 않고 기존
-     * 스냅샷도 지운다 — 타이머 만료로 서버에서 사라진 메시지가 로컬 캐시에
-     * 살아남는 보안 충돌을 원천 차단한다.
+     * 최신 페이지 스냅샷 저장. 삭제 타이머 방도 저장한다 — 서버가 만료를
+     * 일반 `message_deleted` 프레임으로 브로드캐스트하고 히스토리에서도
+     * 즉시 제외하므로, 만료분은 라이브 이벤트/`history_from` diff로 정리된다.
      */
     private cacheWriteRecent;
     /**

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,13 +778,14 @@ 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);
@@ -794,6 +796,45 @@ var MessageCollection = class {
     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
@@ -1106,9 +1147,6 @@ var Room = class _Room {
   cacheStore;
   cachePolicy;
   logger;
-  /** 삭제 타이머 여부 세션 메모 — null=미확인, 값=마지막 detail() 결과. */
-  timerSeconds = null;
-  timerKnown = false;
   /**
    * 이 방의 메시지 상태를 소유하는 `MessageCollection`을 만든다.
    *
@@ -1586,7 +1624,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 +1636,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 +1658,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 +1671,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 +2073,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) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noverachat/sdk-web",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "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

@@ -68,11 +68,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,17 +205,19 @@ 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); // 스냅샷 통째 폐기 → 서버가 이긴다
@@ -227,6 +229,61 @@ export class MessageCollection {
     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 ────────────────────────────────────────────
 
   /**

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