@ai-matrx/messaging 0.14.0 → 0.15.0

package/dist/react.d.cts

@@ -1019,11 +1019,18 @@ interface MessagingSnapshot {
     } | null;
     /** Conversations whose last open failed, keyed by id. Cleared on the next open. */
     readonly conversationReadFailures: ReadonlyMap<ConversationId, ConversationReadFailure>;
+    /**
+     * The inbox read FAILED (and no later read succeeded). Without it a failed
+     * first read left `hasLoadedConversations` false forever — a skeleton that
+     * never resolves is a screen telling a lie (RC-B12 round 11).
+     */
+    readonly conversationsLoadError: string | null;
 }
 interface MessagingStore {
     snapshot(): MessagingSnapshot;
     subscribe(listener: (snapshot: MessagingSnapshot) => void): () => void;
     setConversations(items: readonly ConversationSummary[], hasMore: boolean): void;
+    setConversationsLoadError(message: string | null): void;
     /**
      * Switch the archive axis. Clears the list and marks it UNLOADED: the rows
      * on screen belong to the old filter, and leaving them there while the new
@@ -1133,6 +1140,8 @@ interface MessagingEngine {
      * refreshes the archived count the reveal label prints.
      */
     setArchiveFilter(next: MessagingArchiveFilter): Promise<void>;
+    /** Read the inbox again (the failed-read view's Try again). Never throws; a failure lands in the snapshot. */
+    refreshInbox(): Promise<void>;
     /** Re-read how many archived conversations exist, for the reveal's label. */
     refreshArchivedCount(): Promise<void>;
     /** Open a conversation: load its thread and subscribe to its channel. */
@@ -1376,6 +1385,10 @@ interface UseConversationsResult {
     hasMore: boolean;
     /** True only on the FIRST load; a refresh must not blank the list. */
     isInitialLoading: boolean;
+    /** The inbox read failed; the list shows the failure (never a skeleton forever, never "empty"). */
+    loadError: string | null;
+    /** Read the inbox again. */
+    retry: () => void;
     totalUnreadConversations: number;
     loadMore: () => void;
     select: (id: ConversationId) => void;

package/dist/react.d.ts

@@ -1019,11 +1019,18 @@ interface MessagingSnapshot {
     } | null;
     /** Conversations whose last open failed, keyed by id. Cleared on the next open. */
     readonly conversationReadFailures: ReadonlyMap<ConversationId, ConversationReadFailure>;
+    /**
+     * The inbox read FAILED (and no later read succeeded). Without it a failed
+     * first read left `hasLoadedConversations` false forever — a skeleton that
+     * never resolves is a screen telling a lie (RC-B12 round 11).
+     */
+    readonly conversationsLoadError: string | null;
 }
 interface MessagingStore {
     snapshot(): MessagingSnapshot;
     subscribe(listener: (snapshot: MessagingSnapshot) => void): () => void;
     setConversations(items: readonly ConversationSummary[], hasMore: boolean): void;
+    setConversationsLoadError(message: string | null): void;
     /**
      * Switch the archive axis. Clears the list and marks it UNLOADED: the rows
      * on screen belong to the old filter, and leaving them there while the new
@@ -1133,6 +1140,8 @@ interface MessagingEngine {
      * refreshes the archived count the reveal label prints.
      */
     setArchiveFilter(next: MessagingArchiveFilter): Promise<void>;
+    /** Read the inbox again (the failed-read view's Try again). Never throws; a failure lands in the snapshot. */
+    refreshInbox(): Promise<void>;
     /** Re-read how many archived conversations exist, for the reveal's label. */
     refreshArchivedCount(): Promise<void>;
     /** Open a conversation: load its thread and subscribe to its channel. */
@@ -1376,6 +1385,10 @@ interface UseConversationsResult {
     hasMore: boolean;
     /** True only on the FIRST load; a refresh must not blank the list. */
     isInitialLoading: boolean;
+    /** The inbox read failed; the list shows the failure (never a skeleton forever, never "empty"). */
+    loadError: string | null;
+    /** Read the inbox again. */
+    retry: () => void;
     totalUnreadConversations: number;
     loadMore: () => void;
     select: (id: ConversationId) => void;

package/dist/react.js

@@ -876,6 +876,7 @@ function createMessagingStore() {
   let threads = /* @__PURE__ */ new Map();
   let activeConversationId = null;
   let conversationReadFailures = /* @__PURE__ */ new Map();
+  let conversationsLoadError = null;
   const listeners = /* @__PURE__ */ new Set();
   let cached = null;
   function snapshot() {
@@ -889,7 +890,8 @@ function createMessagingStore() {
       totalUnreadConversations: conversations.filter((item) => item.unreadCount > 0).length,
       archiveFilter,
       archivedCount,
-      conversationReadFailures
+      conversationReadFailures,
+      conversationsLoadError
     };
     return cached;
   }
@@ -934,6 +936,12 @@ function createMessagingStore() {
       conversations = normalizeConversations(items);
       hasMoreConversations = hasMore;
       hasLoadedConversations = true;
+      conversationsLoadError = null;
+      emit();
+    },
+    setConversationsLoadError(message) {
+      if (message === conversationsLoadError) return;
+      conversationsLoadError = message;
       emit();
     },
     setArchiveFilter(next) {
@@ -1166,10 +1174,20 @@ function createMessagingEngine(options) {
   }
   async function reloadInbox() {
     if (disposed) return;
-    const page = await repository.listConversations({
-      limit: conversationPageSize,
-      archived: store.snapshot().archiveFilter
-    });
+    let page;
+    try {
+      page = await repository.listConversations({
+        limit: conversationPageSize,
+        archived: store.snapshot().archiveFilter
+      });
+    } catch (error) {
+      if (!disposed) {
+        store.setConversationsLoadError(
+          error instanceof Error ? error.message : typeof error === "string" ? error : "The conversation list could not be read."
+        );
+      }
+      throw error;
+    }
     if (disposed) return;
     conversationCursor = page.nextCursor;
     store.setConversations(page.items, page.hasMore);
@@ -1254,6 +1272,13 @@ function createMessagingEngine(options) {
         }
       });
     },
+    async refreshInbox() {
+      try {
+        await reloadInbox();
+      } catch (error) {
+        reportError(error, "inboxRefresh");
+      }
+    },
     async setArchiveFilter(next) {
       if (next === store.snapshot().archiveFilter) return;
       store.setArchiveFilter(next);
@@ -2397,7 +2422,11 @@ function useConversations() {
     hasMore: snapshot?.hasMoreConversations ?? false,
     // "Not loaded yet" is a FACT from the store, never a guess. Showing
     // "No conversations yet" before the first read is a screen telling a lie.
-    isInitialLoading: snapshot === null || !snapshot.hasLoadedConversations,
+    isInitialLoading: snapshot === null || !snapshot.hasLoadedConversations && snapshot.conversationsLoadError === null,
+    loadError: snapshot?.conversationsLoadError ?? null,
+    retry: () => {
+      void host?.engine.refreshInbox();
+    },
     totalUnreadConversations: snapshot?.totalUnreadConversations ?? 0,
     loadMore: () => {
       void host?.engine.loadMoreConversations();
@@ -2984,6 +3013,7 @@ function EmptyState(props) {
 }
 
 // src/react/components.tsx
+import { ErrorBox } from "@ai-matrx/design-system";
 import { Fragment, jsx as jsx4, jsxs as jsxs2 } from "react/jsx-runtime";
 var AI_LABELS = {
   catchUp: "Catch me up",
@@ -3001,7 +3031,9 @@ function ConversationList(props) {
     activeConversationId,
     archiveFilter,
     setArchiveFilter,
-    archivedCount
+    archivedCount,
+    loadError,
+    retry
   } = useConversations();
   const RowChrome = useMessagingHost()?.wrapConversationRow ?? null;
   const [query, setQuery] = useState2("");
@@ -3066,7 +3098,20 @@ function ConversationList(props) {
       }
     ) }) : null,
     /* @__PURE__ */ jsxs2("div", { className: "mx-msg__scroll", children: [
-      isInitialLoading ? /* @__PURE__ */ jsx4(ConversationSkeleton, {}) : visible.length === 0 ? /* @__PURE__ */ jsx4(
+      isInitialLoading ? /* @__PURE__ */ jsx4(ConversationSkeleton, {}) : loadError !== null && visible.length === 0 ? (
+        // A failed read resolves to the failure — never a skeleton forever,
+        // never "No conversations yet" (RC-B12 round 11). ErrorBox is the
+        // design-system error slot: the host fills it with its menu.
+        /* @__PURE__ */ jsx4(
+          ReadFailureBox,
+          {
+            title: "Couldn't load your conversations",
+            message: loadError,
+            operation: "List your conversations",
+            onRetry: retry
+          }
+        )
+      ) : visible.length === 0 ? /* @__PURE__ */ jsx4(
         EmptyState,
         {
           title: query.length > 0 ? "No matches" : showingArchive ? "No archived conversations" : "No conversations yet",
@@ -3243,10 +3288,11 @@ function ConversationView(props) {
         body: "It doesn't exist, or you aren't a member of it."
       }
     ) : conversation.error !== null && messages.length === 0 ? /* @__PURE__ */ jsx4(
-      EmptyState,
+      ReadFailureBox,
       {
         title: "Couldn't load this conversation",
-        body: "Check your connection, then open it again."
+        message: conversation.error.message || "Check your connection, then open it again.",
+        operation: "Open this conversation"
       }
     ) : messages.length === 0 ? /* @__PURE__ */ jsx4(EmptyState, { title: "No messages yet", body: "Say something to get started." }) : /* @__PURE__ */ jsxs2("div", { className: "mx-msg__messages", children: [
       conversation.hasMoreOlder ? /* @__PURE__ */ jsx4(
@@ -3577,6 +3623,29 @@ function MessagingInbox(props) {
     }
   );
 }
+function ReadFailureBox({
+  title,
+  message,
+  operation,
+  onRetry
+}) {
+  return /* @__PURE__ */ jsxs2("div", { className: "mx-msg__empty", role: "alert", children: [
+    /* @__PURE__ */ jsx4(
+      ErrorBox,
+      {
+        as: "div",
+        title,
+        message,
+        operation,
+        origin: "messaging",
+        style: { color: "var(--mx-msg-danger)", fontWeight: 600 },
+        children: title
+      }
+    ),
+    /* @__PURE__ */ jsx4("p", { children: message }),
+    onRetry ? /* @__PURE__ */ jsx4("button", { type: "button", className: "mx-msg__button mx-msg__button--ghost", onClick: onRetry, children: "Try again" }) : null
+  ] });
+}
 export {
   AgentTag,
   AlertIcon,