@noverachat/sdk-web 0.3.0 → 0.4.0

package/src/features/message-collection.ts

@@ -0,0 +1,504 @@
+/**
+ * 코어 소유 메시지 상태 — noverachat_dart `MessageCollection`의 TS 미러.
+ *
+ * RoomStore(sdk-react)에 있던 이벤트 반영·낙관적 전송·캐시 hydrate→교체
+ * 로직의 코어 이관본. 바인딩(React·Flutter)은 이 컬렉션을 감싸는 얇은
+ * 접착층이 되고, "캐시는 렌더 힌트, 서버가 항상 이긴다" 같은 불변식은
+ * 코어가 강제한다. 추후 diff 병합은 `applyFresh`의 mergeDiff 분기
+ * 하나로 들어온다.
+ */
+
+import type {
+  DeleteScope,
+  MessageIdStr,
+  MessageOut,
+  ReactionEntry,
+  SendFileOptions,
+  WsChatReceive,
+  WsMessageDeleted,
+  WsMessagesCleared,
+  WsMessageUpdated,
+  WsReactionAdded,
+  WsReactionRemoved,
+  WsSyncTick,
+} from "../types.js";
+import type { CachePolicy } from "../cache.js";
+import type { Room } from "./room.js";
+import {
+  chatMessageFromHistory,
+  chatMessageFromLive,
+  pendingChatMessage,
+  pendingFileChatMessage,
+  type ChatMessage,
+} from "../chat-message.js";
+import { EventBus } from "../internal/event-bus.js";
+import { idGreater } from "../internal/compare-id.js";
+
+/**
+ * 컬렉션 상태가 바뀐 이유. 지금 소비자(얇은 래퍼)는 "바뀌었다"만 알면
+ * 되므로 kind만 담는다 — 세밀한 렌더 최적화가 필요해지면 필드를
+ * **추가**(비파괴)로 확장한다.
+ *
+ * - `hydrated`   캐시 스냅샷이 렌더됨 (콜드 스타트 힌트 — 곧 `replaced`가 따라온다)
+ * - `replaced`   API 응답이 스냅샷/기존 페이지를 통째로 대체함 (서버가 이겼다)
+ * - `inserted`   메시지가 추가됨 (라이브 수신·낙관적 버블·스크롤백 페이지)
+ * - `updated`    기존 메시지가 제자리 갱신됨 (수정·삭제 플래그·리액션·ack 플립)
+ * - `watermarks` 읽음 워터마크가 전진함
+ */
+export type CollectionChangeKind =
+  | "hydrated"
+  | "replaced"
+  | "inserted"
+  | "updated"
+  | "watermarks";
+
+/** `MessageCollection`의 `change` 이벤트로 흐르는 변경 통지. */
+export interface CollectionChange {
+  kind: CollectionChangeKind;
+}
+
+interface CollectionEvents {
+  change: CollectionChange;
+}
+
+let uploadSeq = 0;
+
+/**
+ * A `Room`'s message list as owned, live state — the core-side equivalent
+ * of Sendbird's `MessageCollection` (without a local DB).
+ *
+ * Applies the room's events into one `messages` list, drives optimistic
+ * sends, and runs the snapshot-cache contract (`load()` hydrates from cache
+ * instantly, then wholesale-replaces when the API answers). Subscribe with
+ * `on("change", ...)` and re-render `messages` on every event — all state
+ * mutations and change emits are synchronous with the WS dispatch.
+ *
+ * ```ts
+ * const col = chat.room("room_123").collection();
+ * const unsub = col.on("change", () => render(col.messages));
+ * await col.load();
+ * col.send("hello");
+ * col.markRead(col.messages.at(-1)!.id);
+ * // ...
+ * col.dispose(); unsub();
+ * ```
+ */
+export class MessageCollection {
+  private readonly bus = new EventBus<CollectionEvents>();
+  private readonly unsubs: Array<() => void> = [];
+
+  private _messages: ChatMessage[] = [];
+  private _readWatermarks: Record<string, string> = {};
+  private _hasMore = false;
+  private oldestCursor: string | null = null;
+  private loadingMore = false;
+
+  /**
+   * 캐시 스냅샷으로 렌더된 머리쪽 메시지 수 — API 도착 시 이만큼 걷어내고
+   * 통째 교체한다(replaceByApi). 라이브 수신은 리스트 꼬리에 붙으므로
+   * 머리 range 제거로 스냅샷만 정확히 걷힌다.
+   */
+  private hydratedCount = 0;
+
+  constructor(
+    /** The room this collection is bound to. */
+    public readonly room: Room,
+    private readonly policy: CachePolicy = "replaceByApi",
+  ) {
+    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)),
+    );
+  }
+
+  /** The current messages, oldest first. Treat as read-only. */
+  get messages(): readonly ChatMessage[] {
+    return this._messages;
+  }
+
+  /** True when older history remains — fire `loadMore()` from the top of
+   *  the scroll view. */
+  get hasMore(): boolean {
+    return this._hasMore;
+  }
+
+  /** Per-user read watermarks (`userId` → last read `messageId`), kept live
+   *  from `sync_tick` frames. Treat as read-only. */
+  get readWatermarks(): Readonly<Record<string, string>> {
+    return this._readWatermarks;
+  }
+
+  /** State-change notifications. One event per mutation; re-read `messages`
+   *  (and friends) when it fires. Returns an unsubscribe fn. */
+  on(event: "change", fn: (c: CollectionChange) => void): () => void {
+    return this.bus.on(event, fn);
+  }
+
+  /** Whether `userId` has read `messageId` according to the latest watermark. */
+  isReadBy(userId: string, messageId: string): boolean {
+    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: string, userIds: Iterable<string>): number {
+    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): Promise<void> {
+    const pending = this.room.listRecent(limit); // API를 먼저 띄우고
+    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): Promise<number> {
+    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;
+    }
+  }
+
+  /** 캐시 스냅샷 즉시 렌더 — 빈 리스트일 때만. 실패는 조용히 무시(캐시는
+   *  힌트일 뿐). */
+  private async hydrateFromCache(): Promise<void> {
+    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는 서버 무효화 규칙 확정 후 이 분기 안에 병합 함수가 채워진다.
+   */
+  private applyFresh(page: {
+    items: MessageOut[];
+    nextCursor: MessageIdStr | null;
+    hasMore: boolean;
+  }): void {
+    if (this.policy === "mergeDiff") {
+      throw new Error('CachePolicy "mergeDiff" 는 아직 미구현 — 서버 무효화 규칙 확정 후 지원 예정');
+    }
+    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: string,
+    opts?: {
+      replyToId?: string;
+      customType?: string;
+      customMeta?: Record<string, unknown>;
+    },
+  ): void {
+    void (async () => {
+      let tempId: string;
+      let ackPromise: Promise<string>;
+      try {
+        const sent = await this.room.send({
+          content: text,
+          ...(opts?.replyToId ? { replyToId: opts.replyToId } : {}),
+          ...(opts?.customType ? { customType: opts.customType } : {}),
+          ...(opts?.customMeta ? { customMeta: opts.customMeta } : {}),
+        });
+        tempId = sent.tempId;
+        ackPromise = sent.messageId;
+      } catch {
+        // WS not open — surface a failed bubble rather than throwing into
+        // the void (send() is fire-and-forget).
+        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, content: text, ...opts }));
+      this.emit("inserted");
+      this.bindAck(tempId, 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: File, opts?: SendFileOptions): Promise<void> {
+    // Local temp id for the optimistic bubble — the real WS temp id only
+    // exists after the upload commits (sendFile resolves then).
+    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);
+        },
+      });
+      // Upload committed — bind the bubble to the real file id and ack.
+      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: string, content: string): Promise<void> {
+    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: string, scope: DeleteScope = "ALL"): Promise<void> {
+    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: string,
+    key: string,
+    myUserId: string,
+  ): Promise<void> {
+    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: string): void {
+    this.room.markRead(messageId);
+  }
+
+  /** Force-send the pending read watermark now (e.g. on unmount / tab
+   *  backgrounding). */
+  flushMarkRead(): void {
+    this.room.flushMarkRead();
+  }
+
+  /** Unsubscribe from the room and flush the pending read watermark. The
+   *  collection must not be used afterwards. */
+  dispose(): void {
+    this.room.flushMarkRead();
+    for (const u of this.unsubs.splice(0)) u();
+    this.bus.removeAll();
+  }
+
+  // ── event handlers ──────────────────────────────────────────────
+
+  private onIncoming(f: WsChatReceive): void {
+    this._messages.push(chatMessageFromLive(f));
+    this.emit("inserted");
+  }
+
+  private onUpdated(f: WsMessageUpdated): void {
+    this.mutateById(f.message_id, (m) => ({
+      ...m,
+      content: f.content ?? m.content,
+      editedCount: m.editedCount + 1,
+    }));
+  }
+
+  private onDeleted(f: WsMessageDeleted): void {
+    this.mutateById(f.message_id, (m) => ({ ...m, isDeleted: true }));
+  }
+
+  private onCleared(f: WsMessagesCleared): void {
+    // Operator wipe up to (and including) up_to_message_id — flip local
+    // copies. A null cutoff means the whole room was wiped.
+    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");
+  }
+
+  private onReactionAdded(f: WsReactionAdded): void {
+    this.mutateById(f.message_id, (m) => {
+      const next: ReactionEntry[] = m.reactions.map((r) =>
+        r.key === f.reaction_key
+          ? {
+              key: r.key,
+              userIds: [...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 };
+    });
+  }
+
+  private onReactionRemoved(f: WsReactionRemoved): void {
+    this.mutateById(f.message_id, (m) => {
+      const next: ReactionEntry[] = [];
+      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 };
+    });
+  }
+
+  private onSyncTick(f: WsSyncTick): void {
+    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 ─────────────────────────────────────────────────────
+
+  private bindAck(tempId: string, messageId: Promise<string>): void {
+    messageId
+      .then((realId) => {
+        this.mutateByTempId(tempId, (m) => ({
+          ...m,
+          id: realId,
+          status: "sent",
+        }));
+      })
+      .catch(() => {
+        this.mutateByTempId(tempId, (m) => ({ ...m, status: "failed" }));
+      });
+  }
+
+  private mutateById(id: string, f: (m: ChatMessage) => ChatMessage): void {
+    const i = this._messages.findIndex((m) => m.id === id);
+    if (i === -1) return;
+    this._messages[i] = f(this._messages[i]!);
+    this.emit("updated");
+  }
+
+  private mutateByTempId(
+    tempId: string,
+    f: (m: ChatMessage) => ChatMessage,
+  ): void {
+    const i = this._messages.findIndex((m) => m.tempId === tempId);
+    if (i === -1) return;
+    this._messages[i] = f(this._messages[i]!);
+    this.emit("updated");
+  }
+
+  private emit(kind: CollectionChangeKind): void {
+    this.bus.emit("change", { kind });
+  }
+}

package/src/features/room.ts

@@ -12,6 +12,7 @@ import type { HttpClient } from "../transport/http.js";
 import type { ReconnectingWs } from "../transport/ws.js";
 import type {
   Announcement,
+  ClientOptions,
   DeleteScope,
   FileKind,
   FileMeta,
@@ -20,6 +21,7 @@ import type {
   MessageIdStr,
   MessageOut,
   RoomMemberOut,
+  RoomOut,
   RoomUnread,
   SendFileOptions,
   SendParams,
@@ -33,8 +35,10 @@ import type {
   WsSyncTick,
   WsTypingBroadcast,
 } from "../types.js";
+import { CacheKeys, type CachePolicy, type CacheStore } from "../cache.js";
 import { EventBus } from "../internal/event-bus.js";
 import { tempId as newTempId } from "../internal/temp-id.js";
+import { MessageCollection } from "./message-collection.js";
 import {
   parseAnnouncementOut,
   parseBulkDeleteBySenderResult,
@@ -46,6 +50,7 @@ import {
   parseJoinRequestListResponse,
   parseMessageOut,
   parseRoomMemberOut,
+  parseRoomOut,
   parseRoomUnread,
 } from "../generated/rest.js";
 import type {
@@ -89,7 +94,7 @@ function toFileInline(f: {
 // Enhance the GENERATED `parseMessageOut` with the two client-side
 // extras it can't derive from the OpenAPI schema: parse `file`/`files`
 // into the camelCase `FileInline` shape, and lift sender-attached
-// `_customMeta` out of `data` (Phase D #11). Everything else — key
+// `_customMeta` out of `data`. Everything else — key
 // renames, nested sender/reactions — comes straight from the codegen.
 function toMessageOut(j: unknown): MessageOut {
   const base = parseMessageOut(j);
@@ -196,13 +201,47 @@ export class Room {
    */
   private mySentTempIds = new Set<string>();
 
+  // ── 스냅샷 캐시 협력자 (클라이언트 옵션에서 흘러듦) ──────────────
+  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,
     private ws: ReconnectingWs,
     readDebounceMs: number,
+    opts?: {
+      cacheStore?: CacheStore;
+      cachePolicy?: CachePolicy;
+      logger?: ClientOptions["logger"];
+    },
   ) {
     this.readDebounceMs = readDebounceMs;
+    this.cacheStore = opts?.cacheStore ?? null;
+    this.cachePolicy = opts?.cachePolicy ?? "replaceByApi";
+    this.logger = opts?.logger;
+  }
+
+  /**
+   * 이 방의 메시지 상태를 소유하는 `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?: CachePolicy): MessageCollection {
+    return new MessageCollection(this, policy ?? this.cachePolicy);
   }
 
   private _sendPendingMarkRead(): void {
@@ -260,7 +299,7 @@ export class Room {
           forward_blocked: Boolean(p.forwardBlocked),
         }
       : (p.data ?? null);
-    // Phase D #11 — merge client-supplied custom metadata under a reserved
+    // Merge client-supplied custom metadata under a reserved
     // `_customMeta` key in `data`. Backend passes the whole `data` blob
     // through untouched, so receiving clients read it back via
     // `MessageOut.customMeta` (see `toMessageOut`).
@@ -792,11 +831,85 @@ export class Room {
     const raw = await this.http.request<{
       items: unknown[]; next_cursor: string | null; has_more: boolean;
     }>("GET", `/api/v1/rooms/${this.roomId}/messages`, undefined, { limit });
-    return {
-      items: raw.items.map(toMessageOut),
+    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(): Promise<RoomOut> {
+    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;
+  }
+
+  /**
+   * 히스토리 최신 페이지의 캐시 스냅샷 — 마지막 `listRecent()` 성공 응답의
+   * 원문. 콜드 스타트 렌더 힌트 용도다: 있으면 즉시 그리고, `listRecent()`가
+   * 도착하면 통째로 교체할 것. 캐시가 없거나(`cacheStore` 미주입 포함)
+   * 파싱이 실패하면 `null`을 돌려주고, 깨진 스냅샷은 지운다.
+   *
+   * 스냅샷의 `nextCursor`/`hasMore`는 시점이 지난 값이므로 스크롤백
+   * 커서로 쓰지 말 것 — API 응답이 도착한 뒤의 값만 신뢰한다.
+   */
+  async cachedRecent(): Promise<{
+    items: MessageOut[];
+    nextCursor: MessageIdStr | null;
+    hasMore: boolean;
+  } | null> {
+    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) as {
+        items: unknown[]; next_cursor: string | null; has_more: boolean;
+      };
+      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;
+    }
+  }
+
+  /**
+   * 최신 페이지 스냅샷 저장. 삭제 타이머가 켜진 방은 저장하지 않고 기존
+   * 스냅샷도 지운다 — 타이머 만료로 서버에서 사라진 메시지가 로컬 캐시에
+   * 살아남는 보안 충돌을 원천 차단한다.
+   */
+  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);
+    }
   }
 
   /**
@@ -822,7 +935,7 @@ export class Room {
     };
   }
 
-  /** Phase D #2 — 방 내 메시지 검색.
+  /** 방 내 메시지 검색.
    *
    * ``content`` 필드에 대한 대소문자 무시 부분 문자열 매칭 (ILIKE). 삭제된
    * 메시지는 제외. 결과는 최신순 (message_id DESC) 으로 반환되고, ``before``