@convokitapp/vue-ui 0.4.1 → 0.6.0

package/dist/index.js

@@ -9,6 +9,10 @@ function createConvoKitUiClient(client) {
       onEvent: handler,
       ...onError ? { onError } : {}
     }),
+    onInboxActivity: (handler, onError) => client.realtime.onInboxActivity(client.clientId, {
+      onEvent: handler,
+      ...onError ? { onError } : {}
+    }),
     onMessageDeleted: (conversationId, handler, onError) => client.realtime.onMessageDeleted(conversationId, {
       onEvent: handler,
       ...onError ? { onError } : {}
@@ -17,11 +21,12 @@ function createConvoKitUiClient(client) {
       return client.connected ? client.currentUserId : "";
     },
     getConversations: (options) => client.getConversations(options),
+    listInbox: (options) => client.listInbox(options),
     getConversation: (conversationId) => client.getConversation(conversationId),
     getMessages: (options) => client.getMessages(options),
     getMessage: (id) => client.getMessage(id),
     sendMessage: (input) => client.sendMessage(input),
-    markConversationRead: (conversationId) => client.markConversationRead(conversationId),
+    markConversationRead: (conversationId, options) => client.markConversationRead(conversationId, options),
     sendTyping: (input) => client.sendTyping(input),
     onMessage: (conversationId, handler, onError) => client.realtime.onMessage(conversationId, {
       onEvent: handler,
@@ -43,9 +48,13 @@ import { AvatarFallback, AvatarImage, AvatarRoot } from "reka-ui";
 import { defineComponent, h } from "vue";
 
 // src/utils.ts
+import { readThrough } from "@convokitapp/sdk";
 import { clsx } from "clsx";
 import { normalizeClass } from "vue";
 var pendingMessageIdPrefix = "convokit-pending-";
+function compareMessageOrder(left, right) {
+  return left.createdAt.getTime() - right.createdAt.getTime() || (left.id < right.id ? -1 : left.id > right.id ? 1 : 0);
+}
 function isConvoKitPendingMessage(message) {
   return message.id.startsWith(pendingMessageIdPrefix);
 }
@@ -87,6 +96,31 @@ function mergeConversations(current, incoming) {
   for (const conversation of incoming) byId.set(conversation.id, conversation);
   return [...byId.values()];
 }
+function compareInboxOrder(left, right) {
+  return right.activityAt.getTime() - left.activityAt.getTime() || (left.conversation.id < right.conversation.id ? 1 : left.conversation.id > right.conversation.id ? -1 : 0);
+}
+function mergeInboxEntries(current, incoming) {
+  const byId = new Map(current.map((entry) => [entry.conversation.id, entry]));
+  for (const entry of incoming) byId.set(entry.conversation.id, entry);
+  return [...byId.values()].sort(compareInboxOrder);
+}
+function inboxPreview(conversation, summary, currentUserId) {
+  const message = summary?.latestMessage;
+  if (!message) return "";
+  const first = message.media[0];
+  const body = message.text?.trim() || (!first ? "" : first.type === "image" ? "Photo" : first.type === "file" ? first.name?.trim() || "File" : first.type === "location" ? "Location" : first.type === "contact" ? "Contact" : "");
+  if (!body) return "";
+  if (currentUserId !== void 0 && message.senderId === currentUserId) return `You: ${body}`;
+  if (conversation.participants.length > 2) {
+    const sender = conversation.participants.find((participant) => participant.appUserId === message.senderId || participant.id === message.senderId);
+    const name = sender?.name.trim();
+    if (name) return `${name}: ${body}`;
+  }
+  return body;
+}
+function formatMessageTime(date) {
+  return new Intl.DateTimeFormat(void 0, { hour: "numeric", minute: "2-digit" }).format(date);
+}
 function mergeMessages(current, incoming) {
   const byId = new Map(current.map((message) => [message.id, message]));
   for (const message of incoming) byId.set(message.id, message);
@@ -94,13 +128,16 @@ function mergeMessages(current, incoming) {
     const leftPending = isConvoKitPendingMessage(left);
     const rightPending = isConvoKitPendingMessage(right);
     if (leftPending !== rightPending) return leftPending ? 1 : -1;
-    const byTime = left.createdAt.getTime() - right.createdAt.getTime();
-    return byTime === 0 ? left.id.localeCompare(right.id) : byTime;
+    return compareMessageOrder(left, right);
   });
 }
-function readerIdsFor(message, readAtByUserId) {
+function readerIdsFor(message, readAtByUserId, readPositionByUserId = /* @__PURE__ */ new Map()) {
   if (isConvoKitPendingMessage(message)) return /* @__PURE__ */ new Set();
-  return new Set([...readAtByUserId.entries()].filter(([userId, readAt]) => userId !== message.senderId && readAt.getTime() >= message.createdAt.getTime()).map(([userId]) => userId));
+  const userIds = /* @__PURE__ */ new Set([...readAtByUserId.keys(), ...readPositionByUserId.keys()]);
+  return new Set([...userIds].filter((userId) => userId !== message.senderId && readThrough({
+    readPosition: readPositionByUserId.get(userId) ?? null,
+    lastReadAt: readAtByUserId.get(userId) ?? null
+  }, message)));
 }
 function partClass(part, appearance, defaultClass) {
   return cx(!appearance.unstyled && defaultClass, appearance.classNames?.[part]);
@@ -151,6 +188,7 @@ import { ArrowLeft, LoaderCircle as LoaderCircle2, Paperclip, RefreshCw, Send }
 import {
   defineComponent as defineComponent3,
   h as h3,
+  onBeforeUnmount,
   ref as ref2,
   watchEffect
 } from "vue";
@@ -169,8 +207,20 @@ function hasContent(message) {
 function newest(current, incoming, incomingComplete = true) {
   return version(current) > version(incoming) || !incomingComplete && version(current) === version(incoming) ? current : incoming;
 }
-function compare(left, right) {
-  return left.createdAt.getTime() - right.createdAt.getTime() || (left.id < right.id ? -1 : left.id > right.id ? 1 : 0);
+var compare = compareMessageOrder;
+function positionCursor(position) {
+  return { createdAt: position.createdAt, id: position.messageId };
+}
+function readEntry(participant) {
+  return { userId: participant.appUserId, readAt: participant.lastReadAt, readPosition: participant.readPosition };
+}
+function acknowledgement() {
+  return { inFlight: void 0, followUp: false, suppressed: false, target: void 0, acknowledged: void 0, unacknowledgeable: /* @__PURE__ */ new Set() };
+}
+function isTargetMiss(cause) {
+  if (typeof cause !== "object" || cause === null) return false;
+  const { code, status } = cause;
+  return code === "MESSAGE_NOT_FOUND" || code === void 0 && status === 404;
 }
 function blank(currentUserId = "") {
   return {
@@ -178,6 +228,7 @@ function blank(currentUserId = "") {
     messages: [],
     typingUserIds: /* @__PURE__ */ new Set(),
     readAtByUserId: /* @__PURE__ */ new Map(),
+    readPositionByUserId: /* @__PURE__ */ new Map(),
     isInitialLoading: false,
     isLoadingOlder: false,
     isReconciling: false,
@@ -225,6 +276,9 @@ var ConversationStore = class {
   hydrationPool = { running: /* @__PURE__ */ new Set(), queued: /* @__PURE__ */ new Map() };
   // Keep tombstones until an explicit reload/session change, including across refreshes.
   deleted = /* @__PURE__ */ new Set();
+  ack = acknowledgement();
+  // Visible until the platform reports otherwise; unknown/prerender/no document count as visible.
+  visible = true;
   sendRevision;
   activeSend;
   refreshQueued = false;
@@ -287,6 +341,7 @@ var ConversationStore = class {
     this.hydrations.clear();
     this.hydrationPool.queued.clear();
     this.deleted.clear();
+    this.ack = acknowledgement();
     this.sendRevision = void 0;
     this.activeSend = void 0;
     this.refreshQueued = false;
@@ -342,8 +397,8 @@ var ConversationStore = class {
         if (!this.alive(generation) || conversationId !== this.room || !id.trim()) return;
         this.removeMessage(id);
       }, report));
-      add(() => this.client.onReadReceipt(this.room, ({ userId, readAt }) => {
-        if (this.alive(generation)) this.mergeReads([[userId, readAt]]);
+      add(() => this.client.onReadReceipt(this.room, ({ userId, readAt, readPosition }) => {
+        if (this.alive(generation)) this.mergeReads([{ userId, readAt, readPosition }]);
       }, report));
       add(() => this.client.onTyping(this.room, ({ userId, isTyping }) => {
         if (!this.alive(generation) || !userId.trim() || userId === this.user) return;
@@ -386,9 +441,6 @@ var ConversationStore = class {
     this.hydrations.set(message.id, job);
     this.hydrationPool.queued.set(message.id, job);
     this.drainHydration();
-    if (type === "insert" && !existing && message.senderId !== this.user && (this.options.markReadOnReceive ?? true)) {
-      void this.markRead();
-    }
   }
   record(message, insert, revision, complete) {
     const existing = this.state.messages.find((item) => item.id === message.id);
@@ -398,7 +450,9 @@ var ConversationStore = class {
       this.confirmSend(message);
     }
     this.changes.set(message.id, { revision, message, insert, complete });
-    if (existing || insert && hasContent(message)) this.patch({ messages: mergeMessages(this.state.messages, [message]) });
+    if (!existing && !(insert && hasContent(message))) return;
+    this.patch({ messages: mergeMessages(this.state.messages, [message]) });
+    if (!existing && message.senderId !== this.user && (this.options.markReadOnReceive ?? true)) void this.acknowledge(true);
   }
   confirmSend(message) {
     const send = this.activeSend;
@@ -410,11 +464,19 @@ var ConversationStore = class {
     return this.alive(job.generation) && !this.deleted.has(job.message.id) && this.hydrations.get(job.message.id) === job;
   }
   removeMessage(id) {
+    this.forget(id);
+    this.patch({ messages: this.state.messages.filter((message) => message.id !== id) });
+  }
+  /** Tombstone a row learned to be gone; a removed acknowledgement target is re-resolved from what remains. */
+  forget(id) {
     this.deleted.add(id);
     this.changes.delete(id);
     this.hydrations.delete(id);
     this.hydrationPool.queued.delete(id);
-    this.patch({ messages: this.state.messages.filter((message) => message.id !== id) });
+    const ack = this.ack;
+    if (ack.target !== id && ack.acknowledged?.id !== id) return;
+    ack.unacknowledgeable.add(id);
+    if (ack.target === id) ack.followUp = true;
   }
   drainHydration() {
     const pool = this.hydrationPool;
@@ -451,13 +513,23 @@ var ConversationStore = class {
       });
     }
   }
+  /** Both maps only ever advance: acknowledgement times by time, positions by (createdAt, id). Participants and
+   * read events are the only sources; the local user's own read is never written from the device clock.
+   */
   mergeReads(entries) {
-    const next = new Map(this.state.readAtByUserId);
-    for (const [userId, readAt] of entries) {
-      if (!userId.trim() || !Number.isFinite(readAt.getTime())) continue;
-      if (readAt.getTime() > (next.get(userId)?.getTime() ?? -Infinity)) next.set(userId, readAt);
+    const readAt = new Map(this.state.readAtByUserId);
+    const positions = new Map(this.state.readPositionByUserId);
+    for (const entry of entries) {
+      const { userId, readPosition } = entry;
+      if (!userId.trim()) continue;
+      if (entry.readAt && Number.isFinite(entry.readAt.getTime()) && entry.readAt.getTime() > (readAt.get(userId)?.getTime() ?? -Infinity)) {
+        readAt.set(userId, entry.readAt);
+      }
+      if (!readPosition || typeof readPosition.messageId !== "string" || !readPosition.messageId.trim() || !(readPosition.createdAt instanceof Date) || !Number.isFinite(readPosition.createdAt.getTime())) continue;
+      const current = positions.get(userId);
+      if (!current || compare(positionCursor(readPosition), positionCursor(current)) > 0) positions.set(userId, readPosition);
     }
-    this.patch({ readAtByUserId: next });
+    this.patch({ readAtByUserId: readAt, readPositionByUserId: positions });
   }
   validatePage(page, before) {
     if (page.length > this.pageSize) throw new Error("Message page exceeds the requested limit");
@@ -514,9 +586,9 @@ var ConversationStore = class {
       this.validatePage(page);
       this.cursor = page.at(-1);
       this.patch({ conversation, messages: this.overlay(page, revision), hasOlderMessages: page.length === this.pageSize });
-      this.mergeReads(conversation.participants.flatMap((participant) => participant.lastReadAt ? [[participant.appUserId, participant.lastReadAt]] : []));
+      this.mergeReads(conversation.participants.map(readEntry));
       this.prune(revision);
-      if (this.options.markReadOnLoad ?? true) await this.markRead();
+      if (this.options.markReadOnLoad ?? true) await this.acknowledge(true);
     } catch (cause) {
       this.fail(cause, generation, true);
     } finally {
@@ -572,14 +644,9 @@ var ConversationStore = class {
       const reconciled = this.overlay(rows, revision);
       const survivingIds = new Set(reconciled.map((message) => message.id));
       const known = this.state.messages.filter((message) => !isConvoKitPendingMessage(message)).map((message) => message.id).concat([...this.changes].filter(([, change]) => change.insert && change.revision <= revision).map(([id]) => id));
-      for (const id of known) if (!survivingIds.has(id)) {
-        this.deleted.add(id);
-        this.changes.delete(id);
-        this.hydrations.delete(id);
-        this.hydrationPool.queued.delete(id);
-      }
+      for (const id of known) if (!survivingIds.has(id)) this.forget(id);
       this.patch({ conversation, messages: reconciled, hasOlderMessages: hasOlder });
-      this.mergeReads(conversation.participants.flatMap((participant) => participant.lastReadAt ? [[participant.appUserId, participant.lastReadAt]] : []));
+      this.mergeReads(conversation.participants.map(readEntry));
       this.prune(revision);
     } catch (cause) {
       this.fail(cause, generation, true);
@@ -614,15 +681,68 @@ var ConversationStore = class {
       }
     }
   };
-  markRead = async () => {
-    if (!this.alive()) return;
-    const generation = this.generation;
+  /** Acknowledge through the newest rendered row now, regardless of visibility; no request without a target. */
+  markRead = () => this.alive() ? this.acknowledge(false) : Promise.resolve();
+  /** Automatic acknowledgements wait while hidden and are re-issued (once) on becoming visible. */
+  setVisible = (visible) => {
+    this.visible = visible;
+    if (!visible || !this.ack.suppressed || !this.alive()) return;
+    this.ack.suppressed = false;
+    void this.acknowledge(true);
+  };
+  /** The newest non-pending rendered row by (createdAt, id), never by list index and never a raw realtime
+   * row; rows the server does not know are skipped, and nothing at or before the accepted target is re-sent.
+   */
+  ackTarget(ack) {
+    let target;
+    for (const message of this.state.messages) {
+      if (isConvoKitPendingMessage(message) || ack.unacknowledgeable.has(message.id)) continue;
+      if (!target || compare(message, target) > 0) target = { createdAt: message.createdAt, id: message.id };
+    }
+    return target && (!ack.acknowledged || compare(target, ack.acknowledged) > 0) ? target : void 0;
+  }
+  /** Resolves when the request this call issued or joined settles; a follow-up is issued, not awaited. */
+  acknowledge(automatic) {
+    const ack = this.ack;
+    if (automatic && !this.visible) {
+      ack.suppressed = true;
+      return Promise.resolve();
+    }
+    if (ack.inFlight) {
+      ack.followUp = true;
+      return ack.inFlight;
+    }
+    return this.issue(ack, this.generation) ?? Promise.resolve();
+  }
+  issue(ack, generation) {
+    ack.followUp = false;
+    const target = this.ackTarget(ack);
+    if (!target) return void 0;
+    ack.target = target.id;
+    ack.inFlight = this.send(ack, generation, target).finally(() => {
+      ack.inFlight = void 0;
+      ack.target = void 0;
+      if (!this.alive(generation) || !ack.followUp) return;
+      if (!this.visible) {
+        ack.followUp = false;
+        ack.suppressed = true;
+      } else this.issue(ack, generation);
+    });
+    return ack.inFlight;
+  }
+  async send(ack, generation, target) {
     try {
-      await this.client.markConversationRead(this.room);
+      await this.client.markConversationRead(this.room, { throughMessageId: target.id });
+      if (!this.alive(generation)) return;
+      if (!ack.acknowledged || compare(target, ack.acknowledged) > 0) ack.acknowledged = target;
     } catch (cause) {
-      this.fail(cause, generation);
+      if (!this.alive(generation)) return;
+      if (isTargetMiss(cause)) {
+        ack.unacknowledgeable.add(target.id);
+        ack.followUp = true;
+      } else this.fail(cause, generation);
     }
-  };
+  }
   updateTyping = async (isTyping) => {
     if (!this.alive()) return;
     const generation = this.generation;
@@ -705,7 +825,7 @@ var ConversationStore = class {
       }
     }
   };
-  readerIdsFor = (message) => readerIdsFor(message, this.state.readAtByUserId);
+  readerIdsFor = (message) => readerIdsFor(message, this.state.readAtByUserId, this.state.readPositionByUserId);
 };
 
 // src/composables/use-conversation.ts
@@ -718,6 +838,7 @@ function useConversation(options) {
   let store = createStore();
   const snapshot = shallowRef(store.getSnapshot());
   let unsubscribe;
+  let visible = true;
   const stop = watch(
     () => [toValue(options.client), toValue(options.client).sessionIdentity, toValue(options.conversationId)],
     () => {
@@ -728,6 +849,7 @@ function useConversation(options) {
       unsubscribe = store.subscribe(() => {
         snapshot.value = store.getSnapshot();
       });
+      store.setVisible(visible);
       store.start(options.autoLoad ?? true);
     },
     { immediate: true, flush: "sync" }
@@ -747,6 +869,7 @@ function useConversation(options) {
     messages: field("messages"),
     typingUserIds: field("typingUserIds"),
     readAtByUserId: field("readAtByUserId"),
+    readPositionByUserId: field("readPositionByUserId"),
     isInitialLoading: field("isInitialLoading"),
     isLoadingOlder: field("isLoadingOlder"),
     isReconciling: field("isReconciling"),
@@ -762,6 +885,10 @@ function useConversation(options) {
     sendMessage: (input) => store.sendMessage(input),
     markRead: () => store.markRead(),
     updateTyping: (isTyping) => store.updateTyping(isTyping),
+    setVisible: (value) => {
+      visible = value;
+      store.setVisible(value);
+    },
     dispose
   };
 }
@@ -792,9 +919,6 @@ var appearanceProps = {
   density: { type: String, default: "comfortable" },
   unstyled: { type: Boolean, default: false }
 };
-function defaultFormatTime(date) {
-  return new Intl.DateTimeFormat(void 0, { hour: "numeric", minute: "2-digit" }).format(date);
-}
 function defaultMedia(media, open, imageLoading) {
   const tag = open ? "button" : "div";
   const interactive = open ? { type: "button", onClick: open } : {};
@@ -834,6 +958,7 @@ var MessageListView = defineComponent2({
     messages: { type: Array, required: true },
     currentUserId: { type: String, required: true },
     readAtByUserId: { type: Object, default: () => /* @__PURE__ */ new Map() },
+    readPositionByUserId: { type: Object, default: () => /* @__PURE__ */ new Map() },
     readersResolver: { type: Function, default: void 0 },
     onLoadOlder: { type: Function, default: void 0 },
     hasOlderMessages: { type: Boolean, default: false },
@@ -844,7 +969,7 @@ var MessageListView = defineComponent2({
     paginationThreshold: { type: Number, default: 240 },
     reverse: { type: Boolean, default: true },
     stickToBottom: { type: Boolean, default: true },
-    formatTime: { type: Function, default: defaultFormatTime },
+    formatTime: { type: Function, default: formatMessageTime },
     imageLoading: { type: String, default: "lazy" }
   },
   emits: ["load-older", "attachment-click"],
@@ -893,7 +1018,7 @@ var MessageListView = defineComponent2({
       const isCurrentUser = message.senderId === props.currentUserId;
       const sender = participants.value.get(message.senderId);
       const isPending = isConvoKitPendingMessage(message);
-      const readerIds = isPending ? /* @__PURE__ */ new Set() : props.readersResolver ? props.readersResolver(message) : readerIdsFor(message, props.readAtByUserId);
+      const readerIds = isPending ? /* @__PURE__ */ new Set() : props.readersResolver ? props.readersResolver(message) : readerIdsFor(message, props.readAtByUserId, props.readPositionByUserId);
       const slotProps = { message, chronologicalIndex: index, isCurrentUser, sender, readerIds };
       const custom = slots.message?.(slotProps);
       if (custom) return h2("div", { key: message.id, role: "listitem" }, custom);
@@ -992,8 +1117,8 @@ var MessageListView = defineComponent2({
     };
   }
 });
-function defaultReadersResolver(readAtByUserId) {
-  return (message) => readerIdsFor(message, readAtByUserId);
+function defaultReadersResolver(readAtByUserId, readPositionByUserId = /* @__PURE__ */ new Map()) {
+  return (message) => readerIdsFor(message, readAtByUserId, readPositionByUserId);
 }
 
 // src/components/conversation.ts
@@ -1011,6 +1136,7 @@ var viewProps = {
   onSendMessage: { type: Function, required: true },
   typingUserIds: { type: Object, default: () => /* @__PURE__ */ new Set() },
   readAtByUserId: { type: Object, default: () => /* @__PURE__ */ new Map() },
+  readPositionByUserId: { type: Object, default: () => /* @__PURE__ */ new Map() },
   readersResolver: { type: Function, default: void 0 },
   onBack: { type: Function, default: void 0 },
   onRefresh: { type: Function, default: void 0 },
@@ -1239,6 +1365,7 @@ var ConversationView = defineComponent3({
         messages: props.messages,
         currentUserId: props.currentUserId,
         readAtByUserId: props.readAtByUserId,
+        readPositionByUserId: props.readPositionByUserId,
         ...props.readersResolver ? { readersResolver: props.readersResolver } : {},
         ...props.onLoadOlder ? { onLoadOlder: loadOlder } : {},
         hasOlderMessages: props.hasOlderMessages,
@@ -1301,6 +1428,12 @@ var Conversation = defineComponent3({
     watchEffect(() => {
       emit("controller-change", controller);
     });
+    if (typeof document !== "undefined") {
+      const syncVisibility = () => controller.setVisible(document.visibilityState !== "hidden");
+      syncVisibility();
+      document.addEventListener("visibilitychange", syncVisibility);
+      onBeforeUnmount(() => document.removeEventListener("visibilitychange", syncVisibility));
+    }
     return () => {
       const loadedConversation = controller.conversation.value;
       if (!loadedConversation) {
@@ -1335,6 +1468,7 @@ var Conversation = defineComponent3({
         onSendMessage: _onSendMessage,
         typingUserIds: _typingUserIds,
         readAtByUserId: _readAtByUserId,
+        readPositionByUserId: _readPositionByUserId,
         onRefresh: _onRefresh,
         onLoadOlder: _onLoadOlder,
         onTypingChange: _onTypingChange,
@@ -1357,6 +1491,7 @@ var Conversation = defineComponent3({
         },
         typingUserIds: controller.typingUserIds.value,
         readAtByUserId: controller.readAtByUserId.value,
+        readPositionByUserId: controller.readPositionByUserId.value,
         onRefresh: controller.refresh,
         onLoadOlder: controller.loadOlderMessages,
         onTypingChange: controller.updateTyping,
@@ -1396,30 +1531,64 @@ import {
 import { computed as computed3, getCurrentScope as getCurrentScope2, onScopeDispose as onScopeDispose2, shallowRef as shallowRef2, toValue as toValue2, watch as watch3 } from "vue";
 
 // src/conversation-list-store.ts
+var defaultActivityRefreshWindowMs = 500;
 function blank2(filter) {
-  return { conversations: [], filter, isInitialLoading: false, isLoadingMore: false, hasMore: true, hasLoaded: false, error: null };
+  return {
+    conversations: [],
+    summaries: /* @__PURE__ */ new Map(),
+    currentUserId: "",
+    filter,
+    isInitialLoading: false,
+    isLoadingMore: false,
+    hasMore: true,
+    hasLoaded: false,
+    error: null
+  };
+}
+function statusOf(cause) {
+  return typeof cause === "object" && cause !== null && "status" in cause ? cause.status : void 0;
+}
+function summaryOf(entry) {
+  const { conversation: _conversation, ...summary } = entry;
+  return summary;
+}
+function ids(entries) {
+  return entries.map((entry) => entry.conversation);
 }
 var ConversationListStore = class {
   constructor(options) {
     this.options = options;
     this.owner = options.client.sessionIdentity;
+    this.user = this.owner ? options.client.currentUserId : "";
     this.pageSize = options.pageSize ?? 30;
     if (!Number.isInteger(this.pageSize) || this.pageSize < 1 || this.pageSize > 100) {
       throw new RangeError("pageSize must be an integer between 1 and 100");
     }
+    this.activityRefreshWindowMs = options.activityRefreshWindowMs ?? defaultActivityRefreshWindowMs;
+    if (!Number.isFinite(this.activityRefreshWindowMs) || this.activityRefreshWindowMs < 0) {
+      throw new RangeError("activityRefreshWindowMs must be a non-negative number");
+    }
     this.state = blank2(options.initialFilter ?? {});
   }
   options;
   owner;
+  user;
   pageSize;
+  activityRefreshWindowMs;
   state;
   source = [];
+  entries = [];
   offset = 0;
+  cursor = null;
+  inboxUnavailable = false;
+  inboxWarned = false;
   generation = 0;
   lifecycleGeneration = 0;
   disposed = true;
   lifecycle;
   inbox;
+  activity;
+  activityTimer;
   refreshQueued = false;
   refreshing = false;
   listeners = /* @__PURE__ */ new Set();
@@ -1437,12 +1606,27 @@ var ConversationListStore = class {
   alive(generation = this.generation) {
     return !this.disposed && generation === this.generation && this.owner !== null && this.options.client.sessionIdentity === this.owner;
   }
+  get inboxMode() {
+    return !this.options.pageLoader && typeof this.options.client.listInbox === "function" && !this.inboxUnavailable;
+  }
+  currentUserId() {
+    return this.inboxMode ? this.user : "";
+  }
   start = (autoLoad = true) => {
     if (!this.owner || this.options.client.sessionIdentity !== this.owner) return;
     if (!this.disposed) return;
     this.disposed = false;
+    this.inboxUnavailable = false;
     const lifecycleGeneration = ++this.lifecycleGeneration;
+    const current = () => this.alive() && lifecycleGeneration === this.lifecycleGeneration;
+    const reconcile = (cause) => {
+      if (current()) {
+        this.patch({ error: cause });
+        this.queueRefresh();
+      }
+    };
     try {
+      this.patch({ currentUserId: this.currentUserId() });
       const subscription = this.options.client.onConnectionEvent({
         onEvent: () => {
         },
@@ -1454,15 +1638,20 @@ var ConversationListStore = class {
       else void subscription.unsubscribe().catch(() => void 0);
       if (!this.alive()) return;
       const inbox = this.options.client.onInboxChanged(() => {
-        if (this.alive() && lifecycleGeneration === this.lifecycleGeneration) this.queueRefresh();
-      }, (cause) => {
-        if (this.alive() && lifecycleGeneration === this.lifecycleGeneration) {
-          this.patch({ error: cause });
-          this.queueRefresh();
-        }
-      });
+        if (!current()) return;
+        this.clearActivityTimer();
+        this.queueRefresh();
+      }, reconcile);
       if (this.alive()) this.inbox = inbox;
       else void inbox.unsubscribe().catch(() => void 0);
+      if (!this.alive()) return;
+      if (this.inboxMode && typeof this.options.client.onInboxActivity === "function") {
+        const activity = this.options.client.onInboxActivity(() => {
+          if (current()) this.scheduleActivityRefresh(lifecycleGeneration);
+        }, reconcile);
+        if (this.alive()) this.activity = activity;
+        else void activity.unsubscribe().catch(() => void 0);
+      }
       if (autoLoad) void this.loadInitial();
     } catch (cause) {
       if (this.alive()) this.patch({ error: cause });
@@ -1472,27 +1661,109 @@ var ConversationListStore = class {
     this.disposed = true;
     this.generation++;
     this.lifecycleGeneration++;
+    this.clearActivityTimer();
     const subscription = this.lifecycle;
     this.lifecycle = void 0;
     if (subscription) void subscription.unsubscribe().catch(() => void 0);
     if (this.inbox) void this.inbox.unsubscribe().catch(() => void 0);
     this.inbox = void 0;
+    this.stopActivity();
     this.refreshQueued = false;
     this.refreshing = false;
     this.source = [];
+    this.entries = [];
     this.offset = 0;
+    this.cursor = null;
     this.patch(blank2(this.state.filter));
   };
+  stopActivity() {
+    if (this.activity) void this.activity.unsubscribe().catch(() => void 0);
+    this.activity = void 0;
+  }
+  clearActivityTimer() {
+    if (this.activityTimer !== void 0) clearTimeout(this.activityTimer);
+    this.activityTimer = void 0;
+  }
+  /** Max-wait throttle: the first signal opens a window; later signals wait for it; one refresh runs when it closes. */
+  scheduleActivityRefresh(lifecycleGeneration) {
+    if (this.activityRefreshWindowMs === 0) return this.queueRefresh();
+    if (this.activityTimer !== void 0) return;
+    const timer = setTimeout(() => {
+      this.activityTimer = void 0;
+      if (this.alive() && lifecycleGeneration === this.lifecycleGeneration) this.queueRefresh();
+    }, this.activityRefreshWindowMs);
+    timer.unref?.();
+    this.activityTimer = timer;
+  }
   fail(cause, generation) {
     if (!this.alive(generation)) return;
-    const status = typeof cause === "object" && cause !== null && "status" in cause ? cause.status : void 0;
+    const status = statusOf(cause);
     if (status === 401 || status === 403 || status === 404) {
       this.source = [];
+      this.entries = [];
       this.offset = 0;
-      this.patch({ conversations: [], hasMore: false });
+      this.cursor = null;
+      this.patch({ conversations: [], summaries: /* @__PURE__ */ new Map(), hasMore: false });
     }
     this.patch({ error: cause });
   }
+  /** Run an operation in inbox mode, falling back to the legacy path for the rest of this store's life when the
+   * inbox route is absent (404: rollback, staging). Loaded rows are kept and the same operation continues.
+   */
+  async withFallback(generation, inbox, legacy) {
+    if (!this.inboxMode) return legacy();
+    try {
+      await inbox();
+    } catch (cause) {
+      if (!this.alive(generation) || statusOf(cause) !== 404) throw cause;
+      this.inboxUnavailable = true;
+      this.clearActivityTimer();
+      this.stopActivity();
+      this.entries = [];
+      this.cursor = null;
+      this.offset = this.source.length;
+      if (!this.inboxWarned) {
+        this.inboxWarned = true;
+        console.warn("ConvoKit inbox endpoint unavailable (404); using getConversations without previews or unread counts.");
+      }
+      this.patch({ summaries: /* @__PURE__ */ new Map(), currentUserId: "" });
+      await legacy();
+    }
+  }
+  validateInboxPage(page, limit, requestedCursor) {
+    const seen = /* @__PURE__ */ new Set();
+    for (const entry of page.entries) {
+      const id = entry.conversation.id;
+      if (!id.trim() || seen.has(id)) throw new Error("Invalid conversation page");
+      seen.add(id);
+    }
+    if (page.entries.length > limit) throw new Error("Invalid conversation page");
+    if (page.nextCursor !== null && (page.nextCursor === requestedCursor || page.entries.length === 0)) {
+      throw new Error("Inbox pagination did not advance");
+    }
+  }
+  /** Swap rows, summaries, cursor and hasMore together, filtered by the filter current at commit time. */
+  commitInbox(entries, cursor) {
+    this.entries = entries;
+    this.source = ids(entries);
+    this.cursor = cursor;
+    this.patch({
+      conversations: applyConversationFilter(this.source, this.state.filter),
+      summaries: new Map(entries.map((entry) => [entry.conversation.id, summaryOf(entry)])),
+      hasMore: cursor !== null
+    });
+  }
+  async loadInboxUntilVisible(generation, filter) {
+    const visibleBefore = applyConversationFilter(this.source, filter).length;
+    while (this.alive(generation)) {
+      const requested = this.cursor;
+      const page = await this.options.client.listInbox({ limit: this.pageSize, cursor: requested, archived: filter.archived ?? false });
+      if (!this.alive(generation)) return;
+      this.validateInboxPage(page, this.pageSize, requested);
+      this.commitInbox(mergeInboxEntries(this.entries, page.entries), page.nextCursor);
+      if (page.nextCursor === null || this.state.conversations.length > visibleBefore) return;
+    }
+  }
   async loadUntilVisible(generation, filter) {
     const visibleBefore = applyConversationFilter(this.source, filter).length;
     while (this.alive(generation)) {
@@ -1519,10 +1790,17 @@ var ConversationListStore = class {
     const generation = ++this.generation;
     this.refreshing = false;
     this.source = [];
+    this.entries = [];
     this.offset = 0;
-    this.patch({ ...blank2(this.state.filter), isInitialLoading: true });
+    this.cursor = null;
+    this.patch({ ...blank2(this.state.filter), currentUserId: this.currentUserId(), isInitialLoading: true });
+    const filter = this.state.filter;
     try {
-      await this.loadUntilVisible(generation, this.state.filter);
+      await this.withFallback(
+        generation,
+        () => this.loadInboxUntilVisible(generation, filter),
+        () => this.loadUntilVisible(generation, filter)
+      );
     } catch (cause) {
       this.fail(cause, generation);
     } finally {
@@ -1544,6 +1822,47 @@ var ConversationListStore = class {
       void this.refresh();
     });
   }
+  /** Re-walk the inbox from the head until the loaded window is covered and something is visible, or the inbox
+   * ends. Rooms that moved are re-positioned by the merge; an exhausted inbox publishes what it found.
+   */
+  async refreshInbox(generation, filter) {
+    const target = Math.max(this.pageSize, this.entries.length);
+    let rows = [], consumed = 0, cursor = null;
+    while (this.alive(generation)) {
+      const remaining = target - consumed;
+      const limit = remaining >= 1 ? Math.min(100, remaining) : this.pageSize;
+      const page = await this.options.client.listInbox({ limit, cursor, archived: filter.archived ?? false });
+      if (!this.alive(generation)) return;
+      this.validateInboxPage(page, limit, cursor);
+      rows = mergeInboxEntries(rows, page.entries);
+      consumed += page.entries.length;
+      cursor = page.nextCursor;
+      if (cursor === null || consumed >= target && applyConversationFilter(ids(rows), this.state.filter).length > 0) break;
+    }
+    if (!this.alive(generation)) return;
+    this.commitInbox(rows, cursor);
+  }
+  async refreshLegacy(generation, filter) {
+    const target = Math.max(this.pageSize, this.offset);
+    const compare2 = (a, b) => a.createdAt.getTime() - b.createdAt.getTime() || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+    const boundary = this.options.pageLoader ? void 0 : this.source.reduce((oldest, row) => !oldest || compare2(row, oldest) < 0 ? row : oldest, void 0);
+    let rows = [], offset = 0, hasMore = true;
+    while (this.alive(generation)) {
+      const page = this.options.pageLoader ? await this.options.pageLoader({ limit: this.pageSize, offset, filter }) : await this.options.client.getConversations({ limit: this.pageSize, offset, archived: filter.archived ?? false });
+      if (!this.alive(generation)) return;
+      if (page.length > this.pageSize || page.some((row) => !row.id.trim())) throw new Error("Invalid conversation page");
+      const merged = mergeConversations(rows, page);
+      if (page.length === this.pageSize && merged.length === rows.length) throw new Error("Conversation pagination did not advance");
+      rows = merged;
+      offset += page.length;
+      hasMore = page.length === this.pageSize;
+      if (!hasMore || offset >= target && applyConversationFilter(rows, this.state.filter).length > 0 && (!boundary || page.some((row) => compare2(row, boundary) <= 0))) break;
+    }
+    if (!this.alive(generation)) return;
+    this.source = rows;
+    this.offset = offset;
+    this.patch({ conversations: applyConversationFilter(rows, this.state.filter), hasMore });
+  }
   /** Replace the loaded window atomically, retaining filters and rows during transient failures. */
   refresh = async () => {
     if (!this.alive()) return;
@@ -1554,28 +1873,14 @@ var ConversationListStore = class {
     if (!this.state.hasLoaded) return this.loadInitial();
     const generation = this.generation;
     const filter = this.state.filter;
-    const target = Math.max(this.pageSize, this.offset);
-    const compare2 = (a, b) => a.createdAt.getTime() - b.createdAt.getTime() || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
-    const boundary = this.options.pageLoader ? void 0 : this.source.reduce((oldest, row) => !oldest || compare2(row, oldest) < 0 ? row : oldest, void 0);
     this.refreshing = true;
     this.patch({ error: null });
     try {
-      let rows = [], offset = 0, hasMore = true;
-      while (this.alive(generation)) {
-        const page = this.options.pageLoader ? await this.options.pageLoader({ limit: this.pageSize, offset, filter }) : await this.options.client.getConversations({ limit: this.pageSize, offset, archived: filter.archived ?? false });
-        if (!this.alive(generation)) return;
-        if (page.length > this.pageSize || page.some((row) => !row.id.trim())) throw new Error("Invalid conversation page");
-        const merged = mergeConversations(rows, page);
-        if (page.length === this.pageSize && merged.length === rows.length) throw new Error("Conversation pagination did not advance");
-        rows = merged;
-        offset += page.length;
-        hasMore = page.length === this.pageSize;
-        if (!hasMore || offset >= target && applyConversationFilter(rows, this.state.filter).length > 0 && (!boundary || page.some((row) => compare2(row, boundary) <= 0))) break;
-      }
-      if (!this.alive(generation)) return;
-      this.source = rows;
-      this.offset = offset;
-      this.patch({ conversations: applyConversationFilter(rows, this.state.filter), hasMore });
+      await this.withFallback(
+        generation,
+        () => this.refreshInbox(generation, filter),
+        () => this.refreshLegacy(generation, filter)
+      );
     } catch (cause) {
       this.fail(cause, generation);
     } finally {
@@ -1588,9 +1893,14 @@ var ConversationListStore = class {
   loadMore = async () => {
     if (!this.alive() || this.refreshing || this.state.isInitialLoading || this.state.isLoadingMore || !this.state.hasMore) return;
     const generation = this.generation;
+    const filter = this.state.filter;
     this.patch({ isLoadingMore: true, error: null });
     try {
-      await this.loadUntilVisible(generation, this.state.filter);
+      await this.withFallback(
+        generation,
+        () => this.loadInboxUntilVisible(generation, filter),
+        () => this.loadUntilVisible(generation, filter)
+      );
     } catch (cause) {
       this.fail(cause, generation);
     } finally {
@@ -1642,6 +1952,8 @@ function useConversationList(options) {
   });
   return {
     conversations: field("conversations"),
+    summaries: field("summaries"),
+    currentUserId: field("currentUserId"),
     filter: field("filter"),
     isInitialLoading: field("isInitialLoading"),
     isLoadingMore: field("isLoadingMore"),
@@ -1667,6 +1979,8 @@ var appearanceProps3 = {
 var listViewProps = {
   ...appearanceProps3,
   conversations: { type: Array, required: true },
+  summaries: { type: Object, default: void 0 },
+  currentUserId: { type: String, default: void 0 },
   selectedConversationId: { type: String, default: void 0 },
   onConversationSelect: { type: Function, default: void 0 },
   onRefresh: { type: Function, default: void 0 },
@@ -1716,6 +2030,25 @@ var ConversationListView = defineComponent4({
     const refresh = () => {
       return props.onRefresh?.();
     };
+    const inlineRetry = () => {
+      if (props.hasMore && props.onLoadMore) return () => {
+        lastRequestedLength = null;
+        void requestMore();
+      };
+      if (props.onRefresh) return () => {
+        void refresh();
+      };
+      return void 0;
+    };
+    const unreadBadge = (summary) => {
+      if (summary.unreadCount <= 0 && !summary.unreadCountCapped) return null;
+      const capped = summary.unreadCountCapped || summary.unreadCount > 99;
+      return h4("span", {
+        class: "ckui-unread-badge",
+        role: "img",
+        "aria-label": `${summary.unreadCountCapped ? "99+" : summary.unreadCount} unread`
+      }, [h4("span", { "aria-hidden": "true" }, capped ? "99+" : String(summary.unreadCount))]);
+    };
     const renderContent = () => {
       const currentAppearance = appearance();
       if (props.isInitialLoading && props.conversations.length === 0) {
@@ -1747,10 +2080,21 @@ var ConversationListView = defineComponent4({
       const children = props.conversations.flatMap((conversation, index) => {
         const selected = props.selectedConversationId === conversation.id;
         const select = () => selectConversation(conversation);
-        const slotProps = { conversation, index, selected, select };
+        const summary = props.summaries?.get(conversation.id);
+        const slotProps = {
+          conversation,
+          index,
+          selected,
+          select,
+          ...summary ? { summary } : {},
+          ...props.currentUserId === void 0 ? {} : { currentUserId: props.currentUserId }
+        };
+        const preview = inboxPreview(conversation, summary, props.currentUserId);
+        const unread = summary !== void 0 && (summary.unreadCount > 0 || summary.unreadCountCapped);
         const item = slots["conversation-item"]?.(slotProps) ?? h4("button", {
           type: "button",
           "data-selected": selected || void 0,
+          "data-unread": unread || void 0,
           "aria-current": selected ? "true" : void 0,
           onClick: select,
           class: partClass("listItem", currentAppearance, "ckui-conversation-item"),
@@ -1764,8 +2108,14 @@ var ConversationListView = defineComponent4({
           }),
           h4("span", { class: "ckui-conversation-item__body" }, [
             h4("strong", conversation.displayTitle),
-            h4("span", conversation.participants.map((participant) => participant.name).join(", ") || conversation.description || "No participants")
+            h4("span", preview || conversation.participants.map((participant) => participant.name).join(", ") || conversation.description || "No participants")
           ]),
+          // Spread rather than emit `null`: a null child renders a `<!---->` comment, and rows without a
+          // summary must keep 0.5's exact markup.
+          ...summary ? [h4("span", { class: "ckui-conversation-item__meta" }, [
+            h4("time", { class: "ckui-conversation-item__time", datetime: summary.activityAt.toISOString() }, formatMessageTime(summary.activityAt)),
+            unreadBadge(summary)
+          ])] : [],
           h4(ChevronRight, { size: 18, "aria-hidden": "true" })
         ]);
         const nodes = [h4("div", { key: conversation.id, role: "listitem" }, [item])];
@@ -1775,13 +2125,15 @@ var ConversationListView = defineComponent4({
         return nodes;
       });
       if (props.error) {
-        children.push(slots.error?.({ error: props.error, retry: requestMore }) ?? h4("div", {
+        const retry = inlineRetry();
+        children.push(slots.error?.({ error: props.error, ...retry ? { retry } : {} }) ?? h4("div", {
           class: partClass("error", currentAppearance, "ckui-inline-state ckui-state--error"),
           style: partStyle("error", currentAppearance),
           role: "alert"
-        }, [h4("span", errorMessage(props.error)), h4("button", { type: "button", class: "ckui-link-button", onClick: () => {
-          void requestMore();
-        } }, "Retry")]));
+        }, [
+          h4("span", errorMessage(props.error)),
+          ...retry ? [h4("button", { type: "button", class: "ckui-link-button", onClick: retry }, "Retry")] : []
+        ]));
       } else if (props.isLoadingMore) {
         children.push(slots["load-more"]?.() ?? h4("div", {
           class: partClass("loading", currentAppearance, "ckui-inline-state"),
@@ -1842,6 +2194,7 @@ var ConversationList = defineComponent4({
     initialFilter: { type: Object, default: void 0 },
     pageSize: { type: Number, default: 30 },
     autoLoad: { type: Boolean, default: true },
+    activityRefreshWindowMs: { type: Number, default: void 0 },
     onControllerChange: { type: Function, default: void 0 }
   },
   emits: ["conversation-select", "controller-change"],
@@ -1851,7 +2204,8 @@ var ConversationList = defineComponent4({
       ...props.pageLoader ? { pageLoader: props.pageLoader } : {},
       ...props.initialFilter ? { initialFilter: props.initialFilter } : {},
       pageSize: props.pageSize,
-      autoLoad: props.autoLoad
+      autoLoad: props.autoLoad,
+      ...props.activityRefreshWindowMs === void 0 ? {} : { activityRefreshWindowMs: props.activityRefreshWindowMs }
     });
     expose({ controller });
     watchEffect2(() => {
@@ -1864,8 +2218,11 @@ var ConversationList = defineComponent4({
         initialFilter: _initialFilter,
         pageSize: _pageSize,
         autoLoad: _autoLoad,
+        activityRefreshWindowMs: _activityRefreshWindowMs,
         onControllerChange: _onControllerChange,
         conversations: _conversations,
+        summaries: _summaries,
+        currentUserId: _currentUserId,
         onRefresh: _onRefresh,
         onLoadMore: _onLoadMore,
         isInitialLoading: _isInitialLoading,
@@ -1878,6 +2235,8 @@ var ConversationList = defineComponent4({
         ...attrs,
         ...forwarded,
         conversations: controller.conversations.value,
+        summaries: controller.summaries.value,
+        currentUserId: controller.currentUserId.value,
         onRefresh: controller.refresh,
         onLoadMore: controller.loadMore,
         isInitialLoading: controller.isInitialLoading.value,
@@ -1911,6 +2270,7 @@ var defaultConvoKitTheme = {
   incomingBubble: "#f4f4f5",
   outgoingBubble: "#18181b",
   outgoingText: "#fafafa",
+  badge: "#18181b",
   radius: "10px",
   avatarSize: "40px",
   fontFamily: 'ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif'
@@ -1942,6 +2302,7 @@ var ConvoKitThemeProvider = defineComponent5({
         "--ckui-incoming": theme.incomingBubble,
         "--ckui-outgoing": theme.outgoingBubble,
         "--ckui-outgoing-text": theme.outgoingText,
+        "--ckui-badge": theme.badge,
         "--ckui-radius": theme.radius,
         "--ckui-avatar-size": theme.avatarSize,
         "--ckui-font": theme.fontFamily
@@ -1973,6 +2334,7 @@ export {
   isConvoKitPendingMessage,
   matchesConversation,
   mergeConversations,
+  mergeInboxEntries,
   mergeMessages,
   readerIdsFor,
   useConversation,