@noverachat/sdk-web 0.3.0 → 0.4.0

package/dist/index.cjs

@@ -20,10 +20,16 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  CacheKeys: () => CacheKeys,
   ErrorCode: () => ErrorCode,
+  MessageCollection: () => MessageCollection,
   NoveraChat: () => NoveraChat,
   NoveraChatError: () => NoveraChatError,
-  Room: () => Room
+  Room: () => Room,
+  chatMessageFromHistory: () => chatMessageFromHistory,
+  chatMessageFromLive: () => chatMessageFromLive,
+  pendingChatMessage: () => pendingChatMessage,
+  pendingFileChatMessage: () => pendingFileChatMessage
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -176,6 +182,27 @@ function parseFileCreateResponse(j) {
     expiresAtMs: j["expires_at_ms"]
   };
 }
+function parseRoomOut(j) {
+  return {
+    appId: j["app_id"],
+    roomId: j["room_id"],
+    roomType: j["room_type"],
+    customType: j["custom_type"],
+    name: j["name"],
+    coverImageUrl: j["cover_image_url"],
+    isDistinct: j["is_distinct"],
+    isPublic: j["is_public"],
+    isFrozen: j["is_frozen"],
+    joinPolicy: j["join_policy"],
+    timerSeconds: j["timer_seconds"],
+    memberCount: j["member_count"],
+    lastMessageId: j["last_message_id"],
+    lastMessageAt: j["last_message_at"],
+    lastMessagePreview: j["last_message_preview"],
+    currentAnnouncement: j["current_announcement"] == null ? null : parseAnnouncementOut(j["current_announcement"]),
+    createdAt: j["created_at"]
+  };
+}
 function parseBlockOut(j) {
   return {
     blockedUserId: j["blocked_user_id"],
@@ -245,6 +272,16 @@ function parseReactionEntry(j) {
   };
 }
 
+// src/cache.ts
+var CacheKeys = {
+  /** 저장 포맷 스키마 버전. 저장되는 JSON 모양이 바뀌면 올린다. */
+  version: "v1",
+  /** 방 목록 스냅샷 (`GET /users/me/unread` 원문). */
+  rooms: "nc.v1.rooms",
+  /** 방 히스토리 최신 페이지 스냅샷 (`GET /rooms/{id}/messages` 원문). */
+  msgs: (roomId) => `nc.v1.msgs.${roomId}`
+};
+
 // src/errors.ts
 var ErrorCode = {
   INTERNAL: "NC-GEN-001",
@@ -539,6 +576,487 @@ function tempId() {
   return "tmp_" + bytes.map((b) => b.toString(16).padStart(2, "0")).join("");
 }
 
+// src/chat-message.ts
+function fileInlineFromWire(w) {
+  return {
+    id: w.id,
+    kind: w.kind,
+    mime: w.mime,
+    size: w.size,
+    name: w.name ?? null,
+    width: w.width ?? null,
+    height: w.height ?? null,
+    durationSec: w.duration_sec ?? null,
+    thumbnailStatus: w.thumbnail_status,
+    forwardBlocked: Boolean(w.forward_blocked)
+  };
+}
+function chatMessageFromHistory(m) {
+  return {
+    id: m.messageId,
+    senderId: m.senderId ?? null,
+    content: m.content ?? null,
+    createdAtMs: m.createdAtMs,
+    status: "sent",
+    messageType: m.messageType,
+    sender: m.sender ?? null,
+    customType: m.customType ?? null,
+    fileId: m.fileId ?? null,
+    file: m.file ?? null,
+    files: m.files ?? null,
+    replyToId: m.replyToId ?? null,
+    reactions: m.reactions ?? [],
+    customMeta: m.customMeta ?? null,
+    editedCount: m.editedCount ?? 0,
+    uploadProgress: null,
+    tempId: null,
+    isDeleted: m.deletedAt != null
+  };
+}
+function chatMessageFromLive(f) {
+  const data = f.data ?? null;
+  const customMeta = data && typeof data === "object" && "_customMeta" in data ? data._customMeta : null;
+  return {
+    id: f.message_id,
+    senderId: f.sender_id,
+    content: f.content ?? null,
+    createdAtMs: f.created_at,
+    status: "sent",
+    messageType: f.message_type,
+    sender: null,
+    customType: f.custom_type ?? null,
+    fileId: f.file_id ?? null,
+    file: f.file ? fileInlineFromWire(f.file) : null,
+    files: f.files ? f.files.map(fileInlineFromWire) : null,
+    replyToId: f.reply_to_id ?? null,
+    reactions: [],
+    customMeta,
+    editedCount: 0,
+    uploadProgress: null,
+    tempId: null,
+    isDeleted: false
+  };
+}
+function pendingChatMessage(p) {
+  return {
+    id: p.tempId,
+    senderId: null,
+    content: p.content,
+    createdAtMs: Date.now(),
+    status: "sending",
+    messageType: "TEXT",
+    sender: null,
+    customType: p.customType ?? null,
+    fileId: null,
+    file: null,
+    files: null,
+    replyToId: p.replyToId ?? null,
+    reactions: [],
+    customMeta: p.customMeta ?? null,
+    editedCount: 0,
+    uploadProgress: null,
+    tempId: p.tempId,
+    isDeleted: false
+  };
+}
+function pendingFileChatMessage(p) {
+  const mime = p.mime ?? "application/octet-stream";
+  return {
+    id: p.tempId,
+    senderId: null,
+    content: null,
+    createdAtMs: Date.now(),
+    status: "sending",
+    messageType: "FILE",
+    sender: null,
+    customType: null,
+    fileId: null,
+    file: {
+      id: "",
+      kind: mime.startsWith("image/") ? "image" : mime.startsWith("video/") ? "video" : "file",
+      mime,
+      size: p.size ?? 0,
+      name: p.name,
+      thumbnailStatus: "pending",
+      forwardBlocked: false
+    },
+    files: null,
+    replyToId: null,
+    reactions: [],
+    customMeta: null,
+    editedCount: 0,
+    uploadProgress: 0,
+    tempId: p.tempId,
+    isDeleted: false
+  };
+}
+
+// src/internal/compare-id.ts
+function idGreater(a, b) {
+  if (!a || a === "0") return false;
+  if (!b || b === "0") return true;
+  try {
+    return BigInt(a) > BigInt(b);
+  } catch {
+    return a > b;
+  }
+}
+
+// src/features/message-collection.ts
+var uploadSeq = 0;
+var MessageCollection = class {
+  constructor(room, policy = "replaceByApi") {
+    this.room = room;
+    this.policy = policy;
+    this.unsubs.push(
+      room.on("message", (f) => this.onIncoming(f)),
+      room.on("messageUpdated", (f) => this.onUpdated(f)),
+      room.on("messageDeleted", (f) => this.onDeleted(f)),
+      room.on("messagesCleared", (f) => this.onCleared(f)),
+      room.on("reactionAdded", (f) => this.onReactionAdded(f)),
+      room.on("reactionRemoved", (f) => this.onReactionRemoved(f)),
+      room.on("syncTick", (f) => this.onSyncTick(f))
+    );
+  }
+  room;
+  policy;
+  bus = new EventBus();
+  unsubs = [];
+  _messages = [];
+  _readWatermarks = {};
+  _hasMore = false;
+  oldestCursor = null;
+  loadingMore = false;
+  /**
+   * 캐시 스냅샷으로 렌더된 머리쪽 메시지 수 — API 도착 시 이만큼 걷어내고
+   * 통째 교체한다(replaceByApi). 라이브 수신은 리스트 꼬리에 붙으므로
+   * 머리 range 제거로 스냅샷만 정확히 걷힌다.
+   */
+  hydratedCount = 0;
+  /** The current messages, oldest first. Treat as read-only. */
+  get messages() {
+    return this._messages;
+  }
+  /** True when older history remains — fire `loadMore()` from the top of
+   *  the scroll view. */
+  get hasMore() {
+    return this._hasMore;
+  }
+  /** Per-user read watermarks (`userId` → last read `messageId`), kept live
+   *  from `sync_tick` frames. Treat as read-only. */
+  get readWatermarks() {
+    return this._readWatermarks;
+  }
+  /** State-change notifications. One event per mutation; re-read `messages`
+   *  (and friends) when it fires. Returns an unsubscribe fn. */
+  on(event, fn) {
+    return this.bus.on(event, fn);
+  }
+  /** Whether `userId` has read `messageId` according to the latest watermark. */
+  isReadBy(userId, messageId) {
+    const w = this._readWatermarks[userId];
+    if (!w) return false;
+    return !idGreater(messageId, w);
+  }
+  /** How many of the given users have read `messageId`. Pass the room's
+   *  member ids (minus the sender) to get a KakaoTalk-style unread count:
+   *  `members.length - readCount(...)`. */
+  readCount(messageId, userIds) {
+    let n = 0;
+    for (const u of userIds) if (this.isReadBy(u, messageId)) n++;
+    return n;
+  }
+  // ── loading — cache hydrate → API wholesale replace ─────────────
+  /**
+   * Load the most recent page of history.
+   *
+   * `ClientOptions.cacheStore`가 주입돼 있으면 캐시 스냅샷을 먼저 렌더한
+   * 뒤(`hydrated`), API 응답 도착 시 스냅샷을 걷어내고 통째로 교체한다
+   * (`replaced`). 스냅샷 렌더 중에는 `hasMore`/스크롤백을 열지 않는다 —
+   * 커서는 API 응답의 것만 신뢰한다.
+   */
+  async load(limit = 50) {
+    const pending = this.room.listRecent(limit);
+    await this.hydrateFromCache();
+    const page = await pending;
+    this.applyFresh(page);
+  }
+  /** Scrollback: load the page of messages older than what's on screen and
+   *  prepend it. No-op while a previous call is in flight or when `hasMore`
+   *  is false. Returns the number of messages added. */
+  async loadMore(limit = 50) {
+    const cursor = this.oldestCursor;
+    if (this.loadingMore || !this._hasMore || cursor == null) return 0;
+    this.loadingMore = true;
+    try {
+      const page = await this.room.listBefore(cursor, limit);
+      this._messages.unshift(...page.items.map(chatMessageFromHistory));
+      this.oldestCursor = page.nextCursor;
+      this._hasMore = page.hasMore;
+      this.emit("inserted");
+      return page.items.length;
+    } finally {
+      this.loadingMore = false;
+    }
+  }
+  /** 캐시 스냅샷 즉시 렌더 — 빈 리스트일 때만. 실패는 조용히 무시(캐시는
+   *  힌트일 뿐). */
+  async hydrateFromCache() {
+    if (this._messages.length > 0 || this.hydratedCount > 0) return;
+    const cached = await this.room.cachedRecent();
+    if (!cached || cached.items.length === 0 || this._messages.length > 0) {
+      return;
+    }
+    this._messages.unshift(...cached.items.map(chatMessageFromHistory));
+    this.hydratedCount = cached.items.length;
+    this.emit("hydrated");
+  }
+  /**
+   * API 최신 페이지를 컬렉션에 반영한다 — **diff 병합 진입점**.
+   * replaceByApi(현재 유일 정책)는 스냅샷을 걷어내고 통째 교체하고,
+   * mergeDiff는 서버 무효화 규칙 확정 후 이 분기 안에 병합 함수가 채워진다.
+   */
+  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.hydratedCount > 0) {
+      this._messages.splice(0, this.hydratedCount);
+      this.hydratedCount = 0;
+    }
+    this._messages.unshift(...page.items.map(chatMessageFromHistory));
+    this.oldestCursor = page.nextCursor;
+    this._hasMore = page.hasMore;
+    this.emit("replaced");
+  }
+  // ── optimistic sends ────────────────────────────────────────────
+  /**
+   * Send `text` optimistically: a `sending` bubble appears immediately (one
+   * microtask later — `Room.send` is async), then flips to `sent` (with the
+   * real id) on ack, or `failed` on error. Fire-and-forget: a WS-not-open
+   * failure surfaces as a `failed` bubble rather than a rejected promise.
+   */
+  send(text, opts) {
+    void (async () => {
+      let tempId2;
+      let ackPromise;
+      try {
+        const sent = await this.room.send({
+          content: text,
+          ...opts?.replyToId ? { replyToId: opts.replyToId } : {},
+          ...opts?.customType ? { customType: opts.customType } : {},
+          ...opts?.customMeta ? { customMeta: opts.customMeta } : {}
+        });
+        tempId2 = sent.tempId;
+        ackPromise = sent.messageId;
+      } catch {
+        const localId = `failed_${Date.now()}_${uploadSeq++}`;
+        this._messages.push({
+          ...pendingChatMessage({ tempId: localId, content: text, ...opts }),
+          status: "failed"
+        });
+        this.emit("inserted");
+        return;
+      }
+      this._messages.push(pendingChatMessage({ tempId: tempId2, content: text, ...opts }));
+      this.emit("inserted");
+      this.bindAck(tempId2, ackPromise);
+    })();
+  }
+  /** Send a file optimistically. A FILE bubble with `uploadProgress`
+   *  appears immediately; progress advances during the S3 upload, then the
+   *  bubble flips to `sent` on ack (or `failed`). Never throws — failures
+   *  surface as the bubble's status. */
+  async sendFile(file, opts) {
+    const localId = `upload_${Date.now()}_${uploadSeq++}`;
+    this._messages.push(
+      pendingFileChatMessage({
+        tempId: localId,
+        name: opts?.name ?? file.name,
+        mime: file.type,
+        size: file.size
+      })
+    );
+    this.emit("inserted");
+    try {
+      const sent = await this.room.sendFile(file, {
+        ...opts ?? {},
+        onProgress: (p) => {
+          this.mutateByTempId(localId, (m) => ({
+            ...m,
+            uploadProgress: p.ratio
+          }));
+          opts?.onProgress?.(p);
+        }
+      });
+      this.mutateByTempId(localId, (m) => ({
+        ...m,
+        fileId: sent.fileId,
+        file: m.file ? { ...m.file, id: sent.fileId } : m.file,
+        uploadProgress: null
+      }));
+      const realId = await sent.messageId;
+      this.mutateByTempId(localId, (m) => ({
+        ...m,
+        id: realId,
+        status: "sent"
+      }));
+    } catch {
+      this.mutateByTempId(localId, (m) => ({
+        ...m,
+        status: "failed",
+        uploadProgress: null
+      }));
+    }
+  }
+  /** Edit a message's content (server-side; peers get `message_updated`).
+   *  The local copy updates optimistically. */
+  async edit(messageId, content) {
+    await this.room.edit(messageId, { content });
+    this.mutateById(messageId, (m) => ({
+      ...m,
+      content,
+      editedCount: m.editedCount + 1
+    }));
+  }
+  /** Delete a message. `scope: "ALL"` (default) removes it for everyone;
+   *  `"MY"` hides it only for the caller. Local copy flips to deleted. */
+  async delete(messageId, scope = "ALL") {
+    await this.room.delete(messageId, scope);
+    this.mutateById(messageId, (m) => ({ ...m, isDeleted: true }));
+  }
+  /** Add/remove the caller's reaction. Pass `myUserId` so the toggle can
+   *  tell whether the caller already reacted with `key`. The authoritative
+   *  state arrives back via the reaction WS events. */
+  async toggleReaction(messageId, key, myUserId) {
+    const m = this._messages.find((x) => x.id === messageId);
+    const mine = m?.reactions.some(
+      (r) => r.key === key && r.userIds.includes(myUserId)
+    ) ?? false;
+    if (mine) {
+      await this.room.unreact(messageId, key);
+    } else {
+      await this.room.react(messageId, key);
+    }
+  }
+  /** Mark `messageId` read (debounced inside the SDK). */
+  markRead(messageId) {
+    this.room.markRead(messageId);
+  }
+  /** Force-send the pending read watermark now (e.g. on unmount / tab
+   *  backgrounding). */
+  flushMarkRead() {
+    this.room.flushMarkRead();
+  }
+  /** Unsubscribe from the room and flush the pending read watermark. The
+   *  collection must not be used afterwards. */
+  dispose() {
+    this.room.flushMarkRead();
+    for (const u of this.unsubs.splice(0)) u();
+    this.bus.removeAll();
+  }
+  // ── event handlers ──────────────────────────────────────────────
+  onIncoming(f) {
+    this._messages.push(chatMessageFromLive(f));
+    this.emit("inserted");
+  }
+  onUpdated(f) {
+    this.mutateById(f.message_id, (m) => ({
+      ...m,
+      content: f.content ?? m.content,
+      editedCount: m.editedCount + 1
+    }));
+  }
+  onDeleted(f) {
+    this.mutateById(f.message_id, (m) => ({ ...m, isDeleted: true }));
+  }
+  onCleared(f) {
+    const upTo = f.up_to_message_id;
+    let changed = false;
+    this._messages = this._messages.map((m) => {
+      if (!m.isDeleted && (upTo == null || !idGreater(m.id, upTo))) {
+        changed = true;
+        return { ...m, isDeleted: true };
+      }
+      return m;
+    });
+    if (changed) this.emit("updated");
+  }
+  onReactionAdded(f) {
+    this.mutateById(f.message_id, (m) => {
+      const next = m.reactions.map(
+        (r) => r.key === f.reaction_key ? {
+          key: r.key,
+          userIds: [.../* @__PURE__ */ new Set([...r.userIds, f.user_id])],
+          updatedAt: f.updated_at
+        } : r
+      );
+      if (!next.some((r) => r.key === f.reaction_key)) {
+        next.push({
+          key: f.reaction_key,
+          userIds: [f.user_id],
+          updatedAt: f.updated_at
+        });
+      }
+      return { ...m, reactions: next };
+    });
+  }
+  onReactionRemoved(f) {
+    this.mutateById(f.message_id, (m) => {
+      const next = [];
+      for (const r of m.reactions) {
+        if (r.key !== f.reaction_key) {
+          next.push(r);
+          continue;
+        }
+        const users = r.userIds.filter((u) => u !== f.user_id);
+        if (users.length > 0) {
+          next.push({ key: r.key, userIds: users, updatedAt: f.updated_at });
+        }
+      }
+      return { ...m, reactions: next };
+    });
+  }
+  onSyncTick(f) {
+    let changed = false;
+    for (const [userId, mid] of Object.entries(f.read_states)) {
+      const cur = this._readWatermarks[userId];
+      if (!cur || idGreater(mid, cur)) {
+        this._readWatermarks[userId] = mid;
+        changed = true;
+      }
+    }
+    if (changed) this.emit("watermarks");
+  }
+  // ── helpers ─────────────────────────────────────────────────────
+  bindAck(tempId2, messageId) {
+    messageId.then((realId) => {
+      this.mutateByTempId(tempId2, (m) => ({
+        ...m,
+        id: realId,
+        status: "sent"
+      }));
+    }).catch(() => {
+      this.mutateByTempId(tempId2, (m) => ({ ...m, status: "failed" }));
+    });
+  }
+  mutateById(id, f) {
+    const i = this._messages.findIndex((m) => m.id === id);
+    if (i === -1) return;
+    this._messages[i] = f(this._messages[i]);
+    this.emit("updated");
+  }
+  mutateByTempId(tempId2, f) {
+    const i = this._messages.findIndex((m) => m.tempId === tempId2);
+    if (i === -1) return;
+    this._messages[i] = f(this._messages[i]);
+    this.emit("updated");
+  }
+  emit(kind) {
+    this.bus.emit("change", { kind });
+  }
+};
+
 // src/features/room.ts
 function toFileInline(f) {
   return {
@@ -568,11 +1086,14 @@ function toMessageOut(j) {
   };
 }
 var Room = class _Room {
-  constructor(roomId, http, ws, readDebounceMs) {
+  constructor(roomId, http, ws, readDebounceMs, opts) {
     this.roomId = roomId;
     this.http = http;
     this.ws = ws;
     this.readDebounceMs = readDebounceMs;
+    this.cacheStore = opts?.cacheStore ?? null;
+    this.cachePolicy = opts?.cachePolicy ?? "replaceByApi";
+    this.logger = opts?.logger;
   }
   roomId;
   http;
@@ -616,6 +1137,30 @@ var Room = class _Room {
    * fine in practice (small strings, cleared on `chat.disconnect()`).
    */
   mySentTempIds = /* @__PURE__ */ new Set();
+  // ── 스냅샷 캐시 협력자 (클라이언트 옵션에서 흘러듦) ──────────────
+  cacheStore;
+  cachePolicy;
+  logger;
+  /** 삭제 타이머 여부 세션 메모 — null=미확인, 값=마지막 detail() 결과. */
+  timerSeconds = null;
+  timerKnown = false;
+  /**
+   * 이 방의 메시지 상태를 소유하는 `MessageCollection`을 만든다.
+   *
+   * 컬렉션이 이벤트 반영·낙관적 전송·캐시 hydrate→교체를 전부 담당하므로,
+   * 리스트 화면은 컬렉션 하나만 물면 된다. 여러 개 만들 수 있고 각자
+   * `dispose()`로 정리한다.
+   *
+   * ```ts
+   * const col = chat.room("room_123").collection();
+   * const unsub = col.on("change", () => render(col.messages));
+   * await col.load();
+   * col.send("hello");
+   * ```
+   */
+  collection(policy) {
+    return new MessageCollection(this, policy ?? this.cachePolicy);
+  }
   _sendPendingMarkRead() {
     const mid = this.pendingReadMid;
     if (!mid) return;
@@ -1072,11 +1617,76 @@ var Room = class _Room {
    */
   async listRecent(limit = 50) {
     const raw = await this.http.request("GET", `/api/v1/rooms/${this.roomId}/messages`, void 0, { limit });
-    return {
+    const page = {
       items: raw.items.map(toMessageOut),
+      // 파싱 성공한 응답만 캐시에 넣는다
       nextCursor: raw.next_cursor,
       hasMore: raw.has_more
     };
+    void this.cacheWriteRecent(raw);
+    return page;
+  }
+  /** 이 방의 상세 정보 (`GET /rooms/{id}`) — 이름·멤버 수·삭제 타이머 등. */
+  async detail() {
+    const raw = await this.http.request(
+      "GET",
+      `/api/v1/rooms/${this.roomId}`
+    );
+    const out = parseRoomOut(raw);
+    this.timerSeconds = out.timerSeconds;
+    this.timerKnown = true;
+    return out;
+  }
+  /**
+   * 히스토리 최신 페이지의 캐시 스냅샷 — 마지막 `listRecent()` 성공 응답의
+   * 원문. 콜드 스타트 렌더 힌트 용도다: 있으면 즉시 그리고, `listRecent()`가
+   * 도착하면 통째로 교체할 것. 캐시가 없거나(`cacheStore` 미주입 포함)
+   * 파싱이 실패하면 `null`을 돌려주고, 깨진 스냅샷은 지운다.
+   *
+   * 스냅샷의 `nextCursor`/`hasMore`는 시점이 지난 값이므로 스크롤백
+   * 커서로 쓰지 말 것 — API 응답이 도착한 뒤의 값만 신뢰한다.
+   */
+  async cachedRecent() {
+    const store = this.cacheStore;
+    if (!store) return null;
+    const key = CacheKeys.msgs(this.roomId);
+    try {
+      const raw = await store.read(key);
+      if (raw == null) return null;
+      const j = JSON.parse(raw);
+      return {
+        items: j.items.map(toMessageOut),
+        nextCursor: j.next_cursor,
+        hasMore: j.has_more
+      };
+    } catch (err) {
+      this.logger?.("warn", `cache_read_failed key=${key}`, err);
+      try {
+        await store.remove(key);
+      } catch {
+      }
+      return null;
+    }
+  }
+  /**
+   * 최신 페이지 스냅샷 저장. 삭제 타이머가 켜진 방은 저장하지 않고 기존
+   * 스냅샷도 지운다 — 타이머 만료로 서버에서 사라진 메시지가 로컬 캐시에
+   * 살아남는 보안 충돌을 원천 차단한다.
+   */
+  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);
+    }
   }
   /**
    * Scrollback. Fetches the page of `limit` messages immediately preceding
@@ -1095,7 +1705,7 @@ var Room = class _Room {
       hasMore: raw.has_more
     };
   }
-  /** Phase D #2 — 방 내 메시지 검색.
+  /** 방 내 메시지 검색.
    *
    * ``content`` 필드에 대한 대소문자 무시 부분 문자열 매칭 (ILIKE). 삭제된
    * 메시지는 제외. 결과는 최신순 (message_id DESC) 으로 반환되고, ``before``
@@ -1451,7 +2061,7 @@ var Room = class _Room {
 };
 
 // src/client.ts
-function idGreater(a, b) {
+function idGreater2(a, b) {
   if (!a) return false;
   if (!b) return true;
   try {
@@ -1466,6 +2076,11 @@ 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) {
@@ -1537,7 +2152,11 @@ var NoveraChat = class {
   room(roomId) {
     let r = this.rooms.get(roomId);
     if (!r) {
-      r = new Room(roomId, this.http, this.ws, this.readDebounceMs);
+      r = new Room(roomId, this.http, this.ws, this.readDebounceMs, {
+        ...this.opts.cacheStore ? { cacheStore: this.opts.cacheStore } : {},
+        ...this.opts.cachePolicy ? { cachePolicy: this.opts.cachePolicy } : {},
+        ...this.logger ? { logger: this.logger } : {}
+      });
       this.rooms.set(roomId, r);
     }
     return r;
@@ -1582,7 +2201,7 @@ var NoveraChat = class {
     const sid = typeof messageId === "number" ? String(messageId) : messageId;
     if (!sid || sid === "0") return;
     const cur = this.lastMessageIdByRoom.get(roomId);
-    if (idGreater(sid, cur)) this.lastMessageIdByRoom.set(roomId, sid);
+    if (idGreater2(sid, cur)) this.lastMessageIdByRoom.set(roomId, sid);
   }
   /** Server-side aggregate unread state: total count + per-room breakdown
    *  for the authenticated user. Single REST call; cheap enough to poll
@@ -1784,7 +2403,41 @@ var NoveraChat = class {
   }
   async unreadSummary() {
     const raw = await this.http.request("GET", "/api/v1/users/me/unread");
-    return parseUnreadSummary(raw);
+    const out = parseUnreadSummary(raw);
+    void this.cacheWriteRooms(raw);
+    return out;
+  }
+  /**
+   * 방 목록의 캐시 스냅샷 — 마지막 `unreadSummary()` 성공 응답의 원문.
+   *
+   * 콜드 스타트 렌더 힌트 용도다: 있으면 즉시 그리고, `unreadSummary()`가
+   * 도착하면 통째로 교체할 것. 캐시가 없거나(`cacheStore` 미주입 포함)
+   * 파싱이 실패하면 `null`을 돌려주고, 깨진 스냅샷은 지운다.
+   */
+  async cachedUnreadSummary() {
+    const store = this.opts.cacheStore;
+    if (!store) return null;
+    try {
+      const raw = await store.read(CacheKeys.rooms);
+      if (raw == null) return null;
+      return parseUnreadSummary(JSON.parse(raw));
+    } catch (err) {
+      this.logger?.("warn", `cache_read_failed key=${CacheKeys.rooms}`, err);
+      try {
+        await store.remove(CacheKeys.rooms);
+      } catch {
+      }
+      return null;
+    }
+  }
+  async cacheWriteRooms(raw) {
+    const store = this.opts.cacheStore;
+    if (!store) return;
+    try {
+      await store.write(CacheKeys.rooms, JSON.stringify(raw));
+    } catch (err) {
+      this.logger?.("warn", `cache_write_failed key=${CacheKeys.rooms}`, err);
+    }
   }
   /**
    * Accept an invite link — call this in flows where you receive a
@@ -1865,7 +2518,7 @@ var NoveraChat = class {
         return;
       }
       case "ack": {
-        if (idGreater(msg.message_id, this.lastMessageIdByRoom.get(msg.room_id))) {
+        if (idGreater2(msg.message_id, this.lastMessageIdByRoom.get(msg.room_id))) {
           this.lastMessageIdByRoom.set(msg.room_id, msg.message_id);
         }
         const room = this.rooms.get(msg.room_id);
@@ -1882,7 +2535,7 @@ var NoveraChat = class {
         if (!roomId) return;
         const room = this.rooms.get(roomId);
         if (!room) return;
-        if (msg.type === "chat_receive" && idGreater(msg.message_id, this.lastMessageIdByRoom.get(roomId))) {
+        if (msg.type === "chat_receive" && idGreater2(msg.message_id, this.lastMessageIdByRoom.get(roomId))) {
           this.lastMessageIdByRoom.set(roomId, msg.message_id);
         }
         if (msg.type === "chat_receive") {
@@ -1900,7 +2553,7 @@ var NoveraChat = class {
   highestKnownMessageId() {
     let max = null;
     for (const v of this.lastMessageIdByRoom.values()) {
-      if (idGreater(v, max)) max = v;
+      if (idGreater2(v, max)) max = v;
     }
     return max;
   }
@@ -1941,7 +2594,7 @@ var NoveraChat = class {
             created_at: m.createdAtMs,
             server_ts: Date.now()
           });
-          if (idGreater(m.messageId, this.lastMessageIdByRoom.get(roomId))) {
+          if (idGreater2(m.messageId, this.lastMessageIdByRoom.get(roomId))) {
             this.lastMessageIdByRoom.set(roomId, m.messageId);
           }
         }
@@ -1957,8 +2610,14 @@ var NoveraChat = class {
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  CacheKeys,
   ErrorCode,
+  MessageCollection,
   NoveraChat,
   NoveraChatError,
-  Room
+  Room,
+  chatMessageFromHistory,
+  chatMessageFromLive,
+  pendingChatMessage,
+  pendingFileChatMessage
 });