stream-chat 9.50.3 → 10.0.0-rc.2

package/src/thread.ts

@@ -1,29 +1,38 @@
 import { StateStore } from './store';
 import {
-  addToMessageList,
-  findIndexInSortedArray,
+  computeOwnReactions,
   formatMessage,
-  throttle,
+  localMessageToNewMessagePayload,
 } from './utils';
+import { applyReactionLocally } from './entityStore';
 import type {
-  AscDesc,
-  EventTypes,
+  DraftResponse,
+  EventAPIResponse,
+  EventType,
   LocalMessage,
-  MessagePaginationOptions,
+  MarkReadRequest,
   MessageResponse,
-  ReadResponse,
-  ThreadResponse,
+  ReactionRequest,
+  ReadStateResponse,
+  SendReactionRequest,
+  SortParamRequest,
+  ThreadStateResponse,
   UserResponse,
 } from './types';
-import type { Channel } from './channel';
+import { isEphemeral } from './errors';
+import type {
+  Channel,
+  DeleteMessageWithStateUpdateParams,
+  SendMessageWithStateUpdateParams,
+  UpdateMessageWithStateUpdateParams,
+} from './channel';
 import type { StreamChat } from './client';
 import type { CustomThreadData } from './custom_types';
 import { MessageComposer } from './messageComposer';
+import { MessageOperations } from './messageOperations';
 import { WithSubscriptions } from './utils/WithSubscriptions';
-
-type QueryRepliesOptions = {
-  sort?: { created_at: AscDesc }[];
-} & MessagePaginationOptions & { user?: UserResponse; user_id?: string };
+import { MessagePaginator } from './pagination';
+import type { PipelineEvent } from './EventHandlerPipeline';
 
 export type ThreadState = {
   /**
@@ -37,27 +46,18 @@ export type ThreadState = {
   deletedAt: Date | null;
   isLoading: boolean;
   isStateStale: boolean;
-  pagination: ThreadRepliesPagination;
   /**
    * Thread is identified by and has a one-to-one relation with its parent message.
    * We use parent message id as a thread id.
    */
   parentMessage: LocalMessage;
-  participants: ThreadResponse['thread_participants'];
+  participants: ThreadStateResponse['thread_participants'];
   read: ThreadReadState;
-  replies: Array<LocalMessage>;
   replyCount: number;
   title: string;
   updatedAt: Date | null;
 };
 
-export type ThreadRepliesPagination = {
-  isLoadingNext: boolean;
-  isLoadingPrev: boolean;
-  nextCursor: string | null;
-  prevCursor: string | null;
-};
-
 export type ThreadUserReadState = {
   lastReadAt: Date;
   unreadMessageCount: number;
@@ -69,51 +69,27 @@ export type ThreadUserReadState = {
 export type ThreadReadState = Record<string, ThreadUserReadState | undefined>;
 
 const DEFAULT_PAGE_LIMIT = 50;
-const DEFAULT_SORT: { created_at: AscDesc }[] = [{ created_at: -1 }];
-const MARK_AS_READ_THROTTLE_TIMEOUT = 1000;
-// TODO: remove this once we move to API v2
-export const THREAD_RESPONSE_RESERVED_KEYS: Record<keyof ThreadResponse, true> = {
-  active_participant_count: true,
-  channel: true,
-  channel_cid: true,
-  created_at: true,
-  created_by: true,
-  created_by_user_id: true,
-  deleted_at: true,
-  draft: true,
-  last_message_at: true,
-  latest_replies: true,
-  parent_message: true,
-  parent_message_id: true,
-  participant_count: true,
-  read: true,
-  reply_count: true,
-  thread_participants: true,
-  title: true,
-  updated_at: true,
-};
+const DEFAULT_SORT: SortParamRequest[] = [{ field: 'created_at', direction: -1 }];
+const DEFAULT_ITEM_ORDER: SortParamRequest[] = [{ field: 'created_at', direction: 1 }];
 
-// TODO: remove this once we move to API v2
-const constructCustomDataObject = <T extends ThreadResponse>(threadData: T) => {
-  const custom: CustomThreadData = {};
+export type CustomThreadMarkReadRequestFn = (params: {
+  thread: Thread;
+  options?: MarkReadRequest;
+}) => Promise<EventAPIResponse | null> | void;
 
-  for (const key in threadData) {
-    if (THREAD_RESPONSE_RESERVED_KEYS[key as keyof ThreadResponse]) {
-      continue;
-    }
-
-    const customKey = key as keyof CustomThreadData;
-
-    custom[customKey] = threadData[customKey];
-  }
-
-  return custom;
+export type ThreadInstanceConfig = {
+  requestHandlers?: {
+    markReadRequest?: CustomThreadMarkReadRequestFn;
+  };
 };
 
 export class Thread extends WithSubscriptions {
+  public readonly configState = new StateStore<ThreadInstanceConfig>({});
   public readonly state: StateStore<ThreadState>;
   public readonly id: string;
   public readonly messageComposer: MessageComposer;
+  public readonly messagePaginator: MessagePaginator;
+  public readonly messageOperations: MessageOperations;
 
   private client: StreamChat;
   private failedRepliesMap: Map<string, LocalMessage> = new Map();
@@ -121,66 +97,203 @@ export class Thread extends WithSubscriptions {
   constructor({
     client,
     threadData,
+    channel,
+    parentMessage,
+    draft,
   }: {
     client: StreamChat;
-    threadData: ThreadResponse;
+    threadData?: ThreadStateResponse;
+    channel?: Channel;
+    parentMessage?: MessageResponse | LocalMessage;
+    draft?: DraftResponse;
   }) {
     super();
+    if (threadData) {
+      if (!threadData.channel) {
+        throw new Error('Thread channel is required when threadData is provided');
+      }
+      if (!threadData.parent_message) {
+        throw new Error('Thread parent_message is required when threadData is provided');
+      }
+      const threadChannel = client.channel(
+        threadData.channel.type,
+        threadData.channel.id,
+        { custom: threadData.channel.custom },
+      );
+      threadChannel._hydrateMembers({
+        members: threadData.channel.members ?? [],
+        overrideCurrentState: false,
+      });
 
-    const channel = client.channel(threadData.channel.type, threadData.channel.id, {
-      // @ts-expect-error name is a "custom" property
-      name: threadData.channel.name,
-    });
-    channel._hydrateMembers({
-      members: threadData.channel.members ?? [],
-      overrideCurrentState: false,
-    });
+      this.state = new StateStore<ThreadState>({
+        // local only
+        active: false,
+        isLoading: false,
+        isStateStale: false,
+        // 99.9% should never change
+        channel: threadChannel,
+        createdAt: new Date(threadData.created_at),
+        // rest
+        deletedAt: threadData.deleted_at ? new Date(threadData.deleted_at) : null,
+        parentMessage: formatMessage(threadData.parent_message),
+        participants: threadData.thread_participants,
+        read: formatReadState(
+          !threadData.read || threadData.read.length === 0
+            ? getPlaceholderReadResponse(client.userID)
+            : threadData.read,
+        ),
+        // Use the parent message's reply_count, not the top-level threadData.reply_count. The
+        // thread endpoints (getThread/queryThreads) return a top level reply_count that EXCLUDES
+        // soft-deleted replies, while parent_message.reply_count (and the channel's own copy)
+        // INCLUDE them so the top level value renders fewer replies than the channel badge shows.
+        // parent_message.reply_count is the authoritative, channel consistent count.
+        replyCount: threadData.parent_message.reply_count ?? 0,
+        updatedAt: threadData.updated_at ? new Date(threadData.updated_at) : null,
+        title: threadData.title,
+        custom: threadData.custom ?? {},
+      });
 
-    // For when read object is undefined and due to that unreadMessageCount for
-    // the current user isn't being incremented on message.new
-    const placeholderReadResponse: ReadResponse[] = client.userID
-      ? [
-          {
-            user: { id: client.userID },
-            unread_messages: 0,
-            last_read: new Date().toISOString(),
-          },
-        ]
-      : [];
+      this.id = threadData.parent_message_id;
+    } else {
+      if (!channel) {
+        throw new Error('Channel is required when threadData is not provided');
+      }
 
-    this.state = new StateStore<ThreadState>({
-      // local only
-      active: false,
-      isLoading: false,
-      isStateStale: false,
-      // 99.9% should never change
-      channel,
-      createdAt: new Date(threadData.created_at),
-      // rest
-      deletedAt: threadData.deleted_at ? new Date(threadData.deleted_at) : null,
-      pagination: repliesPaginationFromInitialThread(threadData),
-      parentMessage: formatMessage(threadData.parent_message),
-      participants: threadData.thread_participants,
-      read: formatReadState(
-        !threadData.read || threadData.read.length === 0
-          ? placeholderReadResponse
-          : threadData.read,
-      ),
-      replies: threadData.latest_replies.map(formatMessage),
-      replyCount: threadData.reply_count ?? 0,
-      updatedAt: threadData.updated_at ? new Date(threadData.updated_at) : null,
-      title: threadData.title,
-      custom: constructCustomDataObject(threadData),
-    });
+      if (!parentMessage || !parentMessage.id) {
+        throw new Error(
+          'Parent message with a valid id is required when threadData is not provided',
+        );
+      }
+
+      const formattedParentMessage = formatMessage(parentMessage);
+      const createdAt = parentMessage.created_at
+        ? new Date(parentMessage.created_at)
+        : new Date();
+
+      this.state = new StateStore<ThreadState>({
+        active: false,
+        channel,
+        createdAt,
+        custom: {},
+        deletedAt: formattedParentMessage.deleted_at ?? null,
+        isLoading: false,
+        isStateStale: false,
+        parentMessage: formattedParentMessage,
+        participants: [],
+        read: formatReadState(getPlaceholderReadResponse(client.userID)),
+        replyCount: parentMessage.reply_count ?? 0,
+        title: '',
+        updatedAt: parentMessage.updated_at ? new Date(parentMessage.updated_at) : null,
+      });
+
+      this.id = parentMessage.id;
+    }
 
-    this.id = threadData.parent_message_id;
     this.client = client;
 
+    this.messagePaginator = new MessagePaginator({
+      channel: this.channel,
+      parentMessageId: this.id,
+      requestSort: DEFAULT_SORT,
+      itemOrder: DEFAULT_ITEM_ORDER,
+      paginatorOptions: {
+        pageSize: DEFAULT_PAGE_LIMIT,
+      },
+    });
+
+    // Seed the reply paginator from the thread's `latest_replies` so a thread we already hold
+    // data for (queried via the ThreadManager or hydrated from a ThreadResponse) renders its
+    // first reply page instantly, without a network fetch on open. `latest_replies` is the most
+    // recent window of replies, so it reaches the head (nothing newer to load); it reaches the
+    // tail only when it already contains every reply. Threads built from a bare parent message
+    // carry no replies to seed and fall back to a paginator fetch on first open.
+    if (threadData?.latest_replies?.length) {
+      this.messagePaginator.setItems({
+        valueOrFactory: threadData.latest_replies.map(formatMessage),
+        isFirstPage: true,
+        isLastPage: threadData.latest_replies.length === (threadData.reply_count ?? 0),
+      });
+    }
+
+    // Seed the reply paginator's lastMessageAt floor from the thread's server-provided
+    // `last_message_at` (analogous to the channel seed in Channel._initializeState), so a thread whose
+    // newest reply is not among `latest_replies` still reports the correct latest-activity timestamp.
+    this.messagePaginator.seedLastMessageAt(threadData?.last_message_at);
+
     this.messageComposer = new MessageComposer({
       client,
-      composition: threadData.draft,
+      composition: threadData?.draft ?? draft,
       compositionContext: this,
     });
+
+    this.messageOperations = new MessageOperations({
+      ingest: (m) => {
+        this.messagePaginator.ingestItem(m);
+        this.channel.getClient().messageStore.flushSubscribers(m.id);
+      },
+      get: (id) => this.messagePaginator.getItem(id),
+      normalizeOutgoingMessage: (m) => ({
+        ...m,
+        parent_id: this.id,
+      }),
+      handlers: () => {
+        const { requestHandlers } = this.channel.configState.getLatestValue();
+        const deleteMessageRequest = requestHandlers?.deleteMessageRequest;
+        const sendMessageRequest = requestHandlers?.sendMessageRequest;
+        const retrySendMessageRequest = requestHandlers?.retrySendMessageRequest;
+        const updateMessageRequest = requestHandlers?.updateMessageRequest;
+        return {
+          delete: deleteMessageRequest
+            ? (p) =>
+                deleteMessageRequest({
+                  localMessage: p.localMessage,
+                  options: p.options,
+                })
+            : undefined,
+          send: sendMessageRequest
+            ? (p) =>
+                sendMessageRequest({
+                  localMessage: p.localMessage,
+                  message: p.message,
+                  options: p.options,
+                })
+            : undefined,
+          retry: retrySendMessageRequest
+            ? (p) =>
+                retrySendMessageRequest({
+                  localMessage: p.localMessage,
+                  message: p.message,
+                  options: p.options,
+                })
+            : undefined,
+          update: updateMessageRequest
+            ? (p) =>
+                updateMessageRequest({
+                  localMessage: p.localMessage,
+                  options: p.options,
+                })
+            : undefined,
+        };
+      },
+      defaults: {
+        delete: async (id, o) => {
+          const result = await this.channel.getClient().deleteMessage({ id, ...o });
+          return { message: result.message };
+        },
+        send: async (m, o) => {
+          const result = await this.channel.sendMessage({ message: m, ...o });
+          return { message: result.message };
+        },
+        update: async (m, o) => {
+          const result = await this.channel.getClient().updateMessage({
+            id: m.id,
+            message: localMessageToNewMessagePayload(m),
+            ...o,
+          });
+          return { message: result.message };
+        },
+      },
+    });
   }
 
   get channel() {
@@ -211,7 +324,11 @@ export class Thread extends WithSubscriptions {
     this.state.partialNext({ isLoading: true });
 
     try {
-      const thread = await this.client.getThread(this.id, { watch: true });
+      const loadedReplyCount = this.messagePaginator.items?.length ?? 0;
+      const thread = await this.client.getThreadAndHydrate(this.id, {
+        watch: true,
+        reply_limit: loadedReplyCount || this.messagePaginator.pageSize,
+      });
       this.hydrateState(thread);
     } finally {
       this.state.partialNext({ isLoading: false });
@@ -239,11 +356,12 @@ export class Thread extends WithSubscriptions {
       participants,
       read,
       replyCount,
-      replies,
       updatedAt,
     } = thread.state.getLatestValue();
 
-    // Preserve pending replies and append them to the updated list of replies
+    // Preserve pending (failed) replies so they survive the hydrate. The messagePaginator is now
+    // the sole reply source, so we merge the incoming newest page into it and re-ingest the
+    // pending replies (mirrors the previous state.replies concat behavior).
     const pendingReplies = Array.from(this.failedRepliesMap.values());
 
     this.state.partialNext({
@@ -255,10 +373,21 @@ export class Thread extends WithSubscriptions {
       participants,
       read,
       replyCount,
-      replies: pendingReplies.length ? replies.concat(pendingReplies) : replies,
       updatedAt,
       isStateStale: false,
     });
+
+    if (parentMessage && this.hasSubscriptions) {
+      this.client.messageStore.upsert(parentMessage);
+    }
+
+    this.messagePaginator.mergeNewestPage(
+      thread.messagePaginator.state.getLatestValue().items ?? [],
+    );
+    pendingReplies.forEach((reply) => this.messagePaginator.ingestItem(reply));
+    // Carry the re-queried thread's last-activity floor so lastMessageAt stays fresh even when the
+    // merged page does not include the newest reply. Monotonic, so an older value is a no-op.
+    this.messagePaginator.seedLastMessageAt(thread.messagePaginator.lastMessageAt);
   };
 
   public registerSubscriptions = () => {
@@ -267,6 +396,7 @@ export class Thread extends WithSubscriptions {
       return;
     }
 
+    this.addUnsubscribeFunction(this.subscribeParentMessageFromStore());
     this.addUnsubscribeFunction(this.subscribeThreadUpdated());
     this.addUnsubscribeFunction(this.subscribeMarkActiveThreadRead());
     this.addUnsubscribeFunction(this.subscribeReloadActiveStaleThread());
@@ -276,6 +406,7 @@ export class Thread extends WithSubscriptions {
     this.addUnsubscribeFunction(this.subscribeRepliesUnread());
     this.addUnsubscribeFunction(this.subscribeMessageDeleted());
     this.addUnsubscribeFunction(this.subscribeMessageUpdated());
+    this.addUnsubscribeFunction(this.subscribeUserMessagesDeleted());
   };
 
   private subscribeThreadUpdated = () =>
@@ -290,8 +421,7 @@ export class Thread extends WithSubscriptions {
         title: threadData.title,
         updatedAt: new Date(threadData.updated_at),
         deletedAt: threadData.deleted_at ? new Date(threadData.deleted_at) : null,
-        // TODO: use threadData.custom once we move to API v2
-        custom: constructCustomDataObject(threadData),
+        custom: threadData.custom ?? {},
       });
     }).unsubscribe;
 
@@ -303,7 +433,7 @@ export class Thread extends WithSubscriptions {
       }),
       ({ active, unreadMessageCount }) => {
         if (!active || !unreadMessageCount) return;
-        this.throttledMarkAsRead();
+        this.throttledMarkRead();
       },
     );
 
@@ -318,7 +448,7 @@ export class Thread extends WithSubscriptions {
     );
 
   private subscribeMarkThreadStale = () =>
-    this.client.on('user.watching.stop', (event) => {
+    this.client.on('user.watching.stop', (event: PipelineEvent) => {
       const { channel } = this.state.getLatestValue();
 
       if (
@@ -370,13 +500,13 @@ export class Thread extends WithSubscriptions {
 
       this.upsertReplyLocally({
         message: event.message,
-        // Message from current user could have been added optimistically,
+        // MessageRequest from current user could have been added optimistically,
         // so the actual timestamp might differ in the event
         timestampChanged: isOwnMessage,
       });
 
       if (active) {
-        this.throttledMarkAsRead();
+        this.throttledMarkRead();
       }
 
       const nextRead: ThreadReadState = {};
@@ -439,6 +569,7 @@ export class Thread extends WithSubscriptions {
   private subscribeMessageDeleted = () =>
     this.client.on('message.deleted', (event) => {
       if (!event.message) return;
+      const formattedMessage = formatMessage(event.message);
 
       // Deleted message is a reply of this thread
       if (event.message.parent_id === this.id) {
@@ -454,62 +585,161 @@ export class Thread extends WithSubscriptions {
       if (event.message.id === this.id) {
         this.updateParentMessageLocally({ message: event.message });
       }
+
+      this.messagePaginator.reflectQuotedMessageUpdate(formattedMessage);
     }).unsubscribe;
 
   private subscribeMessageUpdated = () => {
-    const eventTypes: EventTypes[] = [
-      'message.updated',
+    const messageUpdateTypes: EventType[] = ['message.updated', 'message.undeleted'];
+    const reactionTypes: EventType[] = [
       'reaction.new',
       'reaction.deleted',
       'reaction.updated',
     ];
 
-    const unsubscribeFunctions = eventTypes.map(
+    const unsubscribeMessageUpdated = messageUpdateTypes.map(
+      (eventType) =>
+        this.client.on(eventType, (event: PipelineEvent) => {
+          if (!event.message) return;
+          // A `message.updated` WS event carries `own_reactions: []`; upserting it verbatim would
+          // wipe the current user's reactions on an edit. Preserve them off the copy we already hold
+          // — the reply paginator for a reply, `state.parentMessage` for the parent (the parent is
+          // not held in any paginator, so it needs the same treatment directly).
+          const message =
+            event.message.parent_id === this.id
+              ? {
+                  ...event.message,
+                  own_reactions:
+                    this.messagePaginator.getItem(event.message.id)?.own_reactions ??
+                    event.message.own_reactions,
+                }
+              : !event.message.parent_id && event.message.id === this.id
+                ? {
+                    ...event.message,
+                    own_reactions:
+                      this.state.getLatestValue().parentMessage?.own_reactions ??
+                      event.message.own_reactions,
+                  }
+                : event.message;
+          this.updateParentMessageOrReplyLocally(message);
+          this.messagePaginator.reflectQuotedMessageUpdate(formatMessage(event.message));
+        }).unsubscribe,
+    );
+
+    const unsubscribeReactions = reactionTypes.map(
       (eventType) =>
-        this.client.on(eventType, (event) => {
-          if (event.message) {
-            this.updateParentMessageOrReplyLocally(event.message);
+        this.client.on(eventType, (event: PipelineEvent) => {
+          if (!event.message || !event.reaction) return;
+          const { message, reaction } = event;
+          if (message.parent_id === this.id) {
+            // Preserve/apply the current user's `own_reactions` off the reply paginator itself,
+            // independently of the channel (mirrors the channel's main-list reflectReaction).
+            this.messagePaginator.reflectReaction({
+              enforceUnique: eventType === 'reaction.updated',
+              message,
+              reaction,
+              removed: eventType === 'reaction.deleted',
+            });
+          } else if (!message.parent_id && message.id === this.id) {
+            // Reaction on the PARENT. The parent isn't in a paginator, so apply the current user's
+            // own_reactions delta here (mirroring the reply path's reflectReaction) rather than
+            // copying the WS event verbatim — which would drop own_reactions the event omits.
+            const own_reactions = computeOwnReactions({
+              current:
+                this.state.getLatestValue().parentMessage?.own_reactions ??
+                message.own_reactions ??
+                [],
+              enforceUnique: eventType === 'reaction.updated',
+              reaction,
+              removed: eventType === 'reaction.deleted',
+              userId: this.client.userID,
+            });
+            this.updateParentMessageLocally({ message: { ...message, own_reactions } });
           }
+          this.messagePaginator.reflectQuotedMessageUpdate(formatMessage(message));
         }).unsubscribe,
     );
 
+    const unsubscribeFunctions = [...unsubscribeMessageUpdated, ...unsubscribeReactions];
+
     return () => unsubscribeFunctions.forEach((unsubscribe) => unsubscribe());
   };
 
+  private subscribeUserMessagesDeleted = () => {
+    // Apply a user ban / deletion to this thread's own reply list. Previously
+    // channel.state.deleteUserMessages marked banned-user replies deleted in the (now removed)
+    // channel.state.threads shadow; the reply paginator is the thread's source of truth now.
+    const eventTypes: EventType[] = ['user.messages.deleted', 'user.deleted'];
+
+    const unsubscribeFunctions = eventTypes.map(
+      (eventType) =>
+        this.client.on(eventType, (event: PipelineEvent) => {
+          if (!event.user) return;
+          // user.deleted carries the deletion time on the user; user.messages.deleted on the event.
+          const deletedAtSource =
+            eventType === 'user.deleted' ? event.user.deleted_at : event.created_at;
+          this.messagePaginator.applyMessageDeletionForUser({
+            userId: event.user.id,
+            hardDelete: !!event.hard_delete,
+            deletedAt: deletedAtSource ? new Date(deletedAtSource) : new Date(),
+          });
+        }).unsubscribe,
+    );
+
+    return () => unsubscribeFunctions.forEach((unsubscribe) => unsubscribe());
+  };
+
+  // The parent message lives in the client-global message store (one canonical POJO per id);
+  // `state.parentMessage` and the fields derived from it are a projection of that copy. Every update
+  // to the parent — optimistic reaction, WS reaction/edit/delete, reply-count bump — writes the
+  // store, which reflects it here through this single subscription (one per thread, not one per
+  // message). Seeds the store on first subscribe when no other collection holds the parent yet
+  // (e.g. a thread opened from a notification, its parent not in the channel window).
+  private subscribeParentMessageFromStore = () => {
+    const store = this.client.messageStore;
+    const parent = this.state.getLatestValue().parentMessage;
+    if (parent && !store.has(parent.id)) store.upsert(parent);
+
+    return store.subscribe(this.id, (message) => {
+      if (!message) return;
+      this.state.next((current) => ({
+        ...current,
+        deletedAt: message.deleted_at ?? null,
+        parentMessage: message,
+        participants:
+          normalizeThreadParticipants(message.thread_participants, current.channel.cid) ??
+          current.participants,
+        replyCount: message.reply_count ?? current.replyCount,
+      }));
+    });
+  };
+
   public unregisterSubscriptions = () => {
     const symbol = super.unregisterSubscriptions();
+    // Release the reply paginator's hold on the shared message store. The parent subscription is
+    // torn down by `super.unregisterSubscriptions()` (it was added as an unsubscribe function), but
+    // the reply paginator's per-id links live in its item index, not in the subscription list — so a
+    // removed thread would otherwise stay pinned by `messageStore.subscribers` and keep its replies
+    // alive. `getThread` builds a fresh instance if this thread is re-opened, so this is a discard.
+    this.messagePaginator.dispose();
     this.state.partialNext({ isStateStale: true });
     return symbol;
   };
 
+  // todo: can be removed with the next breaking change and use MessagePaginator only
   public deleteReplyLocally = ({ message }: { message: MessageResponse }) => {
-    const { replies } = this.state.getLatestValue();
-
-    const index = findIndexInSortedArray({
-      needle: formatMessage(message),
-      sortedArray: replies,
-      sortDirection: 'ascending',
-      selectValueToCompare: (reply) => reply.created_at.getTime(),
-      selectKey: (reply) => reply.id,
-    });
-
-    if (replies[index]?.id !== message.id) {
-      return;
-    }
-
-    const updatedReplies = [...replies];
-    updatedReplies.splice(index, 1);
-
-    this.state.partialNext({
-      replies: updatedReplies,
-    });
+    // The reply messagePaginator is the reply list source. removeItem is a no-op when the reply
+    // isn't loaded, so it's safe to run unconditionally.
+    this.messagePaginator.removeItem({ id: message.id });
   };
 
+  // todo: can be removed with the next breaking change and use MessagePaginator only
   public upsertReplyLocally = ({
     message,
-    timestampChanged = false,
   }: {
     message: MessageResponse | LocalMessage;
+    // Accepted for backward compatibility but no longer used — the messagePaginator repositions
+    // by created_at on ingest, so a changed timestamp is handled without an explicit flag.
     timestampChanged?: boolean;
   }) => {
     if (message.parent_id !== this.id) {
@@ -518,36 +748,33 @@ export class Thread extends WithSubscriptions {
 
     const formattedMessage = formatMessage(message);
 
-    if (message.status === 'failed') {
+    // todo: do we really need to keep the failedRepliesMap?
+    if (formattedMessage.status === 'failed') {
       // store failed reply so that it's not lost when reloading or hydrating
       this.failedRepliesMap.set(formattedMessage.id, formattedMessage);
     } else if (this.failedRepliesMap.has(message.id)) {
       this.failedRepliesMap.delete(message.id);
     }
 
-    this.state.next((current) => ({
-      ...current,
-      replies: addToMessageList(current.replies, formattedMessage, timestampChanged),
-    }));
+    // The reply messagePaginator is the reply list source.
+    this.messagePaginator.ingestItem(formattedMessage);
   };
 
+  // todo: can be removed with the next breaking change and use MessagePaginator only
   public updateParentMessageLocally = ({ message }: { message: MessageResponse }) => {
     if (message.id !== this.id) {
       throw new Error('Message does not belong to this thread');
     }
 
-    this.state.next((current) => {
-      const formattedMessage = formatMessage(message);
-
-      return {
-        ...current,
-        deletedAt: formattedMessage.deleted_at,
-        parentMessage: formattedMessage,
-        replyCount: message.reply_count ?? current.replyCount,
-      };
-    });
+    // The parent's content lives in the client-global message store; `state.parentMessage` (and the
+    // fields derived from it) is a projection kept in sync by `subscribeParentMessageFromStore`.
+    // Writing the store fans the change out to every collection holding this id and reflects it here.
+    if (this.client.messageStore.has(message.id)) {
+      this.client.messageStore.upsert(formatMessage(message));
+    }
   };
 
+  // todo: can be removed with the next breaking change and use MessagePaginator only
   public updateParentMessageOrReplyLocally = (message: MessageResponse) => {
     if (message.parent_id === this.id) {
       this.upsertReplyLocally({ message });
@@ -558,85 +785,187 @@ export class Thread extends WithSubscriptions {
     }
   };
 
-  public markAsRead = async ({ force = false }: { force?: boolean } = {}) => {
-    if (this.ownUnreadCount === 0 && !force) {
-      return null;
-    }
-
-    return await this.client.messageDeliveryReporter.markRead(this);
-  };
-
-  private throttledMarkAsRead = throttle(
-    () => this.markAsRead(),
-    MARK_AS_READ_THROTTLE_TIMEOUT,
-    { trailing: true },
-  );
-
-  public queryReplies = ({
-    limit = DEFAULT_PAGE_LIMIT,
-    sort = DEFAULT_SORT,
-    ...otherOptions
-  }: QueryRepliesOptions = {}) =>
-    this.channel.getReplies(this.id, { limit, ...otherOptions }, sort);
+  /**
+   * Sends a message with optimistic local state update.
+   */
+  async sendMessageWithLocalUpdate({
+    localMessage,
+    message,
+    options,
+    sendMessageRequestFn,
+  }: SendMessageWithStateUpdateParams): Promise<void> {
+    await this.messageOperations.send(
+      {
+        localMessage,
+        message,
+        options,
+      },
+      sendMessageRequestFn,
+    );
+  }
 
-  public loadNextPage = ({ limit = DEFAULT_PAGE_LIMIT }: { limit?: number } = {}) =>
-    this.loadPage(limit);
+  /**
+   * Retry sending a failed message.
+   */
+  async retrySendMessageWithLocalUpdate(
+    params: Omit<SendMessageWithStateUpdateParams, 'message'>,
+  ) {
+    await this.messageOperations.retry(
+      {
+        localMessage: { ...params.localMessage, type: 'regular' },
+        options: params.options,
+      },
+      params.sendMessageRequestFn,
+    );
+  }
 
-  public loadPrevPage = ({ limit = DEFAULT_PAGE_LIMIT }: { limit?: number } = {}) =>
-    this.loadPage(-limit);
+  /**
+   * Updates a message with optimistic local state update.
+   *
+   * The update flows through `messagePaginator`, which is the sole reply source.
+   */
+  async updateMessageWithLocalUpdate(params: UpdateMessageWithStateUpdateParams) {
+    await this.messageOperations.update(
+      {
+        localMessage: params.localMessage,
+        options: params.options,
+      },
+      params.updateMessageRequestFn,
+    );
+  }
 
-  private loadPage = async (count: number) => {
-    const { pagination } = this.state.getLatestValue();
-    const [loadingKey, cursorKey, insertionMethodKey] =
-      count > 0
-        ? (['isLoadingNext', 'nextCursor', 'push'] as const)
-        : (['isLoadingPrev', 'prevCursor', 'unshift'] as const);
+  /**
+   * Deletes a message with local state update.
+   */
+  async deleteMessageWithLocalUpdate(params: DeleteMessageWithStateUpdateParams) {
+    await this.messageOperations.delete(
+      {
+        localMessage: params.localMessage,
+        options: params.options,
+      },
+      params.deleteMessageRequestFn,
+    );
+  }
 
-    if (pagination[loadingKey] || pagination[cursorKey] === null) return;
+  /**
+   * Adds a reaction to a reply with an optimistic local state update, mirroring
+   * {@link Channel.addReactionWithLocalUpdate}. The optimistic message is applied to THIS thread's
+   * paginator (so pure replies get optimism the channel paginator can't give); the request routes
+   * through the parent channel since reactions are channel-level.
+   */
+  async addReactionWithLocalUpdate({
+    messageId,
+    reaction,
+    options,
+  }: {
+    messageId: string;
+    reaction: ReactionRequest;
+    options?: Pick<SendReactionRequest, 'enforce_unique' | 'skip_push'>;
+  }) {
+    const client = this.channel.getClient();
+    const undo = applyReactionLocally(client, {
+      enforceUnique: options?.enforce_unique ?? false,
+      messageId,
+      reaction,
+    });
 
-    const queryOptions = { [count > 0 ? 'id_gt' : 'id_lt']: pagination[cursorKey] };
-    const limit = Math.abs(count);
+    try {
+      const response = await this.channel.sendReaction({
+        id: messageId,
+        reaction,
+        ...options,
+      });
+      // reconcile the server copy only if we still hold it — a bare upsert of an unheld id would
+      // orphan it (the store's refcount GC only reclaims held ids).
+      if (response?.message && client.messageStore.has(response.message.id)) {
+        client.messageStore.upsert(formatMessage(response.message));
+      }
+    } catch (error) {
+      if (undo && (!client.offlineDb || !isEphemeral(error as Error))) {
+        undo();
+      }
+      throw error;
+    }
+  }
 
-    this.state.partialNext({ pagination: { ...pagination, [loadingKey]: true } });
+  /**
+   * Removes the current user's reaction from a reply with an optimistic local state update,
+   * mirroring {@link Thread.addReactionWithLocalUpdate}.
+   */
+  async deleteReactionWithLocalUpdate({
+    messageId,
+    type,
+  }: {
+    messageId: string;
+    type: string;
+  }) {
+    const client = this.channel.getClient();
+    const undo = applyReactionLocally(client, {
+      messageId,
+      reaction: { type },
+      removed: true,
+    });
 
     try {
-      const data = await this.queryReplies({ ...queryOptions, limit });
-      const replies = data.messages.map(formatMessage);
-      const maybeNextCursor = replies.at(count > 0 ? -1 : 0)?.id ?? null;
+      const response = await this.channel.deleteReaction({ id: messageId, type });
+      // reconcile the server copy only if we still hold it — a bare upsert of an unheld id would
+      // orphan it (the store's refcount GC only reclaims held ids).
+      if (response?.message && client.messageStore.has(response.message.id)) {
+        client.messageStore.upsert(formatMessage(response.message));
+      }
+    } catch (error) {
+      if (undo && (!client.offlineDb || !isEphemeral(error as Error))) {
+        undo();
+      }
+      throw error;
+    }
+  }
 
-      this.state.next((current) => {
-        let nextReplies = current.replies;
+  public markRead = async ({ force = false }: { force?: boolean } = {}) => {
+    if (this.ownUnreadCount === 0 && !force) {
+      return null;
+    }
 
-        // prevent re-creating array if there's nothing to add to the current one
-        if (replies.length > 0) {
-          nextReplies = [...current.replies];
-          nextReplies[insertionMethodKey](...replies);
-        }
+    return await this.client.messageDeliveryReporter.markRead(this);
+  };
 
-        return {
-          ...current,
-          replies: nextReplies,
-          pagination: {
-            ...current.pagination,
-            [cursorKey]: data.messages.length < limit ? null : maybeNextCursor,
-            [loadingKey]: false,
-          },
-        };
-      });
-    } catch (error) {
-      this.client.logger('error', (error as Error).message);
-      this.state.next((current) => ({
-        ...current,
-        pagination: {
-          ...current.pagination,
-          [loadingKey]: false,
-        },
-      }));
-    }
+  private throttledMarkRead = () => {
+    this.client.messageDeliveryReporter.throttledMarkRead(this);
   };
+
+  /**
+   * @deprecated Use `thread.markRead` instead.
+   */
+  public markAsRead = ({ force = false }: { force?: boolean } = {}) =>
+    this.markRead({ force });
 }
 
-const formatReadState = (read: ReadResponse[]): ThreadReadState =>
+type MessageThreadParticipant = NonNullable<
+  MessageResponse['thread_participants']
+>[number];
+type ThreadParticipant = NonNullable<ThreadStateResponse['thread_participants']>[number];
+
+const normalizeThreadParticipants = (
+  participants: MessageResponse['thread_participants'] | undefined,
+  channelCid: string,
+): ThreadStateResponse['thread_participants'] | undefined => {
+  if (!participants) return undefined;
+
+  const now = new Date();
+
+  return participants.map(
+    (participant: MessageThreadParticipant) =>
+      ({
+        channel_cid: channelCid,
+        created_at: now,
+        last_read_at: now,
+        user: participant as UserResponse,
+        user_id: participant.id,
+      }) as ThreadParticipant,
+  );
+};
+
+const formatReadState = (read: ReadStateResponse[]): ThreadReadState =>
   read.reduce<ThreadReadState>((state, userRead) => {
     state[userRead.user.id] = {
       user: userRead.user,
@@ -647,21 +976,16 @@ const formatReadState = (read: ReadResponse[]): ThreadReadState =>
     return state;
   }, {});
 
-const repliesPaginationFromInitialThread = (
-  thread: ThreadResponse,
-): ThreadRepliesPagination => {
-  const latestRepliesContainsAllReplies =
-    thread.latest_replies.length === thread.reply_count;
-
-  return {
-    nextCursor: null,
-    prevCursor: latestRepliesContainsAllReplies
-      ? null
-      : (thread.latest_replies.at(0)?.id ?? null),
-    isLoadingNext: false,
-    isLoadingPrev: false,
-  };
-};
+const getPlaceholderReadResponse = (currentUserId?: string): ReadStateResponse[] =>
+  currentUserId
+    ? [
+        {
+          user: { id: currentUserId } as UserResponse,
+          unread_messages: 0,
+          last_read: new Date(),
+        },
+      ]
+    : [];
 
 const ownUnreadCountSelector =
   (currentUserId: string | undefined) => (state: ThreadState) =>