@convokitapp/vue-ui 0.5.0 → 0.7.0

package/dist/index.cjs

@@ -35,6 +35,7 @@ __export(index_exports, {
   isConvoKitPendingMessage: () => isConvoKitPendingMessage,
   matchesConversation: () => matchesConversation,
   mergeConversations: () => mergeConversations,
+  mergeInboxEntries: () => mergeInboxEntries,
   mergeMessages: () => mergeMessages,
   readerIdsFor: () => readerIdsFor,
   useConversation: () => useConversation,
@@ -54,6 +55,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 } : {}
@@ -62,11 +67,14 @@ 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, options) => client.markConversationRead(conversationId, options),
+    markConversationUnread: (conversationId) => client.markConversationUnread(conversationId),
+    clearConversationUnread: (conversationId, options) => client.clearConversationUnread(conversationId, options),
     sendTyping: (input) => client.sendTyping(input),
     onMessage: (conversationId, handler, onError) => client.realtime.onMessage(conversationId, {
       onEvent: handler,
@@ -136,6 +144,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);
@@ -226,6 +259,10 @@ function readEntry(participant) {
 function acknowledgement() {
   return { inFlight: void 0, followUp: false, suppressed: false, target: void 0, acknowledged: void 0, unacknowledgeable: /* @__PURE__ */ new Set() };
 }
+function capture(conversation) {
+  const membership = conversation?.membership;
+  return { version: membership?.privateStateVersion, clearPending: membership?.unreadMarkedAt != null };
+}
 function isTargetMiss(cause) {
   if (typeof cause !== "object" || cause === null) return false;
   const { code, status } = cause;
@@ -286,6 +323,7 @@ var ConversationStore = class {
   // Keep tombstones until an explicit reload/session change, including across refreshes.
   deleted = /* @__PURE__ */ new Set();
   ack = acknowledgement();
+  captured = capture();
   // Visible until the platform reports otherwise; unknown/prerender/no document count as visible.
   visible = true;
   sendRevision;
@@ -351,6 +389,7 @@ var ConversationStore = class {
     this.hydrationPool.queued.clear();
     this.deleted.clear();
     this.ack = acknowledgement();
+    this.captured = capture();
     this.sendRevision = void 0;
     this.activeSend = void 0;
     this.refreshQueued = false;
@@ -595,9 +634,13 @@ 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.captured = capture(conversation);
       this.mergeReads(conversation.participants.map(readEntry));
       this.prune(revision);
-      if (this.options.markReadOnLoad ?? true) await this.acknowledge(true);
+      if ((this.options.markReadOnLoad ?? true) || this.ack.suppressed) {
+        this.ack.suppressed = false;
+        await this.acknowledge(true);
+      }
     } catch (cause) {
       this.fail(cause, generation, true);
     } finally {
@@ -654,9 +697,12 @@ var ConversationStore = class {
       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.forget(id);
+      const opening = this.state.conversation === null;
       this.patch({ conversation, messages: reconciled, hasOlderMessages: hasOlder });
+      if (opening) this.captured = capture(conversation);
       this.mergeReads(conversation.participants.map(readEntry));
       this.prune(revision);
+      if (opening) void this.resumeAcknowledgement();
     } catch (cause) {
       this.fail(cause, generation, true);
     } finally {
@@ -690,15 +736,22 @@ var ConversationStore = class {
       }
     }
   };
-  /** Acknowledge through the newest rendered row now, regardless of visibility; no request without a target. */
+  /** Acknowledge through the newest rendered row now, regardless of visibility; no acknowledgement without a
+   * target (a room opened with a marker that renders nothing clears the marker instead, once).
+   */
   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);
+    if (!visible || !this.alive()) return;
+    void this.resumeAcknowledgement();
   };
+  /** Re-issue (once) the automatic acknowledgement that waited while hidden or before this open's DTO, if any. */
+  resumeAcknowledgement() {
+    if (!this.ack.suppressed) return Promise.resolve();
+    this.ack.suppressed = false;
+    return 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.
    */
@@ -713,7 +766,7 @@ var ConversationStore = class {
   /** 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) {
+    if (automatic && (!this.visible || this.state.conversation === null)) {
       ack.suppressed = true;
       return Promise.resolve();
     }
@@ -726,9 +779,10 @@ var ConversationStore = class {
   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(() => {
+    const request = target ? this.send(ack, generation, target) : this.clearMarker(ack, generation);
+    if (!request) return void 0;
+    ack.target = target?.id;
+    ack.inFlight = request.finally(() => {
       ack.inFlight = void 0;
       ack.target = void 0;
       if (!this.alive(generation) || !ack.followUp) return;
@@ -739,9 +793,31 @@ var ConversationStore = class {
     });
     return ack.inFlight;
   }
+  /** A room opened with the caller's unread marker that renders no non-pending, acknowledgeable row cannot clear
+   * it through a targeted acknowledgement, so it asks the adapter to clear the marker conditionally on the captured
+   * version, once per open, under the acknowledgement triggers and visibility gating. Rows rendered later clear it
+   * through their acknowledgements; adapters without the member leave it; `cleared: false` is not an error.
+   */
+  clearMarker(ack, generation) {
+    const captured = this.captured;
+    if (!captured.clearPending || captured.version === void 0 || typeof this.client.clearConversationUnread !== "function" || this.state.messages.some((message) => !isConvoKitPendingMessage(message) && !ack.unacknowledgeable.has(message.id))) return void 0;
+    captured.clearPending = false;
+    return this.clearUnread(captured.version, generation);
+  }
+  async clearUnread(version2, generation) {
+    try {
+      await this.client.clearConversationUnread(this.room, { ifVersion: version2 });
+    } catch (cause) {
+      if (this.alive(generation)) this.fail(cause, generation);
+    }
+  }
   async send(ack, generation, target) {
     try {
-      await this.client.markConversationRead(this.room, { throughMessageId: target.id });
+      const version2 = this.captured.version;
+      await this.client.markConversationRead(this.room, {
+        throughMessageId: target.id,
+        ...version2 === void 0 ? {} : { privateStateVersion: version2 }
+      });
       if (!this.alive(generation)) return;
       if (!ack.acknowledged || compare(target, ack.acknowledged) > 0) ack.acknowledged = target;
     } catch (cause) {
@@ -911,9 +987,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 } : {};
@@ -964,7 +1037,7 @@ var MessageListView = (0, import_vue5.defineComponent)({
     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"],
@@ -1521,30 +1594,64 @@ var import_vue10 = require("vue");
 var import_vue8 = require("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();
@@ -1562,12 +1669,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: () => {
         },
@@ -1579,15 +1701,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 });
@@ -1597,27 +1724,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)) {
@@ -1644,10 +1853,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 {
@@ -1669,6 +1885,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;
@@ -1679,28 +1936,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 {
@@ -1713,9 +1956,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 {
@@ -1733,6 +1981,66 @@ var ConversationListStore = class {
     else if (!this.state.conversations.length && this.state.hasMore) await this.loadMore();
   };
   setQuery = (query) => this.setFilter({ ...this.state.filter, query });
+  /** Mark a room unread for the viewer only; the row's summary takes the response (D10). Rejects when the adapter
+   * lacks `markConversationUnread` or the store is not active; a request failure is reported through `error`
+   * without evicting rows and rejects.
+   */
+  markUnread = async (conversationId) => {
+    const client = this.options.client;
+    if (typeof client.markConversationUnread !== "function") {
+      throw new TypeError("markUnread requires a ConvoKitUiClient adapter with markConversationUnread (core SDK 0.7)");
+    }
+    this.assertActive();
+    this.applyPrivateState(conversationId, await this.mutate(client.markConversationUnread(conversationId)));
+  };
+  /** Remove the viewer's marker (conditionally on `options.ifVersion`); resolves to the response's `cleared` ("this
+   * request removed the marker", not "the room is read") and patches the summary on true and false alike (D10).
+   * Rejects when the adapter lacks `clearConversationUnread` or the store is not active; failures are reported like
+   * `markUnread`.
+   */
+  clearUnread = async (conversationId, options) => {
+    const client = this.options.client;
+    if (typeof client.clearConversationUnread !== "function") {
+      throw new TypeError("clearUnread requires a ConvoKitUiClient adapter with clearConversationUnread (core SDK 0.7)");
+    }
+    this.assertActive();
+    const result = await this.mutate(client.clearConversationUnread(conversationId, options));
+    this.applyPrivateState(conversationId, result);
+    return result.cleared;
+  };
+  /** A disposed or session-evicted store never sends a private-state mutation: on a shared client it could go out
+   * under a replacement login. Rejected without touching `error` (there is no live snapshot to report into).
+   */
+  assertActive() {
+    if (!this.alive()) throw new Error("ConversationListStore is not active");
+  }
+  async mutate(request) {
+    try {
+      return await request;
+    } catch (cause) {
+      if (this.alive()) this.patch({ error: cause });
+      throw cause;
+    }
+  }
+  /** Apply a mark/clear response to the row's CURRENT summary (a refresh may have swapped it) as one unit, only while
+   * the store is alive and the response is not older than the stored version: a delayed response never resurrects a
+   * marker a newer action removed (equal versions are an idempotent no-op). `isUnread` is recomputed from the stored
+   * counts and the response marker. Other devices learn of the change through `inbox_activity`.
+   */
+  applyPrivateState(conversationId, state) {
+    if (!this.alive()) return;
+    const current = this.entries.find((entry) => entry.conversation.id === conversationId);
+    if (!current || state.privateStateVersion < current.privateStateVersion) return;
+    const { unreadMarkedAt, privateStateVersion } = state;
+    const patched = {
+      ...current,
+      unreadMarkedAt,
+      privateStateVersion,
+      isUnread: current.unreadCount > 0 || current.unreadCountCapped || unreadMarkedAt !== null
+    };
+    this.entries = this.entries.map((entry) => entry === current ? patched : entry);
+    this.patch({ summaries: new Map(this.entries.map((entry) => [entry.conversation.id, summaryOf(entry)])) });
+  }
 };
 
 // src/composables/use-conversation-list.ts
@@ -1767,6 +2075,8 @@ function useConversationList(options) {
   });
   return {
     conversations: field("conversations"),
+    summaries: field("summaries"),
+    currentUserId: field("currentUserId"),
     filter: field("filter"),
     isInitialLoading: field("isInitialLoading"),
     isLoadingMore: field("isLoadingMore"),
@@ -1778,6 +2088,8 @@ function useConversationList(options) {
     loadMore: () => store.loadMore(),
     setFilter: (filter) => store.setFilter(filter),
     setQuery: (query) => store.setQuery(query),
+    markUnread: (conversationId) => store.markUnread(conversationId),
+    clearUnread: (conversationId, options2) => store.clearUnread(conversationId, options2),
     dispose
   };
 }
@@ -1792,6 +2104,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 },
@@ -1841,6 +2155,28 @@ var ConversationListView = (0, import_vue10.defineComponent)({
     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) {
+        const capped = summary.unreadCountCapped || summary.unreadCount > 99;
+        return [(0, import_vue10.h)("span", {
+          class: "ckui-unread-badge",
+          role: "img",
+          "aria-label": `${summary.unreadCountCapped ? "99+" : summary.unreadCount} unread`
+        }, [(0, import_vue10.h)("span", { "aria-hidden": "true" }, capped ? "99+" : String(summary.unreadCount))])];
+      }
+      if (summary.isUnread) return [(0, import_vue10.h)("span", { class: "ckui-unread-badge ckui-unread-badge--dot", role: "img", "aria-label": "Unread" })];
+      return [];
+    };
     const renderContent = () => {
       const currentAppearance = appearance();
       if (props.isInitialLoading && props.conversations.length === 0) {
@@ -1872,10 +2208,21 @@ var ConversationListView = (0, import_vue10.defineComponent)({
       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.isUnread || summary.unreadCount > 0 || summary.unreadCountCapped);
         const item = slots["conversation-item"]?.(slotProps) ?? (0, import_vue10.h)("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"),
@@ -1889,8 +2236,14 @@ var ConversationListView = (0, import_vue10.defineComponent)({
           }),
           (0, import_vue10.h)("span", { class: "ckui-conversation-item__body" }, [
             (0, import_vue10.h)("strong", conversation.displayTitle),
-            (0, import_vue10.h)("span", conversation.participants.map((participant) => participant.name).join(", ") || conversation.description || "No participants")
+            (0, import_vue10.h)("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 ? [(0, import_vue10.h)("span", { class: "ckui-conversation-item__meta" }, [
+            (0, import_vue10.h)("time", { class: "ckui-conversation-item__time", datetime: summary.activityAt.toISOString() }, formatMessageTime(summary.activityAt)),
+            ...unreadBadge(summary)
+          ])] : [],
           (0, import_vue10.h)(import_vue9.ChevronRight, { size: 18, "aria-hidden": "true" })
         ]);
         const nodes = [(0, import_vue10.h)("div", { key: conversation.id, role: "listitem" }, [item])];
@@ -1900,13 +2253,15 @@ var ConversationListView = (0, import_vue10.defineComponent)({
         return nodes;
       });
       if (props.error) {
-        children.push(slots.error?.({ error: props.error, retry: requestMore }) ?? (0, import_vue10.h)("div", {
+        const retry = inlineRetry();
+        children.push(slots.error?.({ error: props.error, ...retry ? { retry } : {} }) ?? (0, import_vue10.h)("div", {
           class: partClass("error", currentAppearance, "ckui-inline-state ckui-state--error"),
           style: partStyle("error", currentAppearance),
           role: "alert"
-        }, [(0, import_vue10.h)("span", errorMessage(props.error)), (0, import_vue10.h)("button", { type: "button", class: "ckui-link-button", onClick: () => {
-          void requestMore();
-        } }, "Retry")]));
+        }, [
+          (0, import_vue10.h)("span", errorMessage(props.error)),
+          ...retry ? [(0, import_vue10.h)("button", { type: "button", class: "ckui-link-button", onClick: retry }, "Retry")] : []
+        ]));
       } else if (props.isLoadingMore) {
         children.push(slots["load-more"]?.() ?? (0, import_vue10.h)("div", {
           class: partClass("loading", currentAppearance, "ckui-inline-state"),
@@ -1967,6 +2322,7 @@ var ConversationList = (0, import_vue10.defineComponent)({
     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"],
@@ -1976,7 +2332,8 @@ var ConversationList = (0, import_vue10.defineComponent)({
       ...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 });
     (0, import_vue10.watchEffect)(() => {
@@ -1989,8 +2346,11 @@ var ConversationList = (0, import_vue10.defineComponent)({
         initialFilter: _initialFilter,
         pageSize: _pageSize,
         autoLoad: _autoLoad,
+        activityRefreshWindowMs: _activityRefreshWindowMs,
         onControllerChange: _onControllerChange,
         conversations: _conversations,
+        summaries: _summaries,
+        currentUserId: _currentUserId,
         onRefresh: _onRefresh,
         onLoadMore: _onLoadMore,
         isInitialLoading: _isInitialLoading,
@@ -2003,6 +2363,8 @@ var ConversationList = (0, import_vue10.defineComponent)({
         ...attrs,
         ...forwarded,
         conversations: controller.conversations.value,
+        summaries: controller.summaries.value,
+        currentUserId: controller.currentUserId.value,
         onRefresh: controller.refresh,
         onLoadMore: controller.loadMore,
         isInitialLoading: controller.isInitialLoading.value,
@@ -2030,6 +2392,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'
@@ -2061,6 +2424,7 @@ var ConvoKitThemeProvider = (0, import_vue11.defineComponent)({
         "--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
@@ -2093,6 +2457,7 @@ function useConvoKitTheme() {
   isConvoKitPendingMessage,
   matchesConversation,
   mergeConversations,
+  mergeInboxEntries,
   mergeMessages,
   readerIdsFor,
   useConversation,