@ai-matrx/messaging 0.10.5 → 0.11.0

package/dist/react.d.cts

@@ -138,6 +138,39 @@ interface Message {
     /** Set only while this message is in the outbox and its last send failed. */
     readonly failureReason?: string | undefined;
 }
+/**
+ * THE ARCHIVED-ITEMS LAW's three states (Arman, 2026-09-09 —
+ * `common-docs/policies/archived-items.md`):
+ *
+ * > "everything should have an archive filter, and the default should always
+ * >  hide archived, but seeing archived items should be one or two clicks
+ * >  away … this is a system wide decision for every single item everywhere in
+ * >  our system, for every single table and every single page."
+ *
+ * | value      | what the list shows      |
+ * |------------|--------------------------|
+ * | `active`   | only un-archived rows    |
+ * | `archived` | only archived rows       |
+ * | `all`      | every row                |
+ *
+ * The same three words the rest of the platform uses — `ArchivedFilter` in
+ * matrx-frontend's `lib/entity-list`, `p_archived` on the `agx_*`/`wfx_*` and
+ * DM list RPCs, `ArchiveFilter` in `@ai-matrx/design-system`. A person meets
+ * ONE control, not one per app.
+ *
+ * 🚨 Three states, never a boolean. A boolean cannot say "archived only",
+ * which is exactly the view someone looking for a conversation they archived
+ * last month needs.
+ */
+type MessagingArchiveFilter = "active" | "archived" | "all";
+/** The platform default: a list hides archived rows until asked. */
+declare const DEFAULT_MESSAGING_ARCHIVE_FILTER: MessagingArchiveFilter;
+/**
+ * Narrow an untrusted value (a stored preference, a URL param, a host knob) to
+ * the tri-state. Anything unrecognised falls back to the default rather than
+ * silently widening a list to archived conversations.
+ */
+declare function toMessagingArchiveFilter(value: unknown, fallback?: MessagingArchiveFilter): MessagingArchiveFilter;
 interface ConversationSummary {
     readonly conversation: Conversation;
     readonly participants: readonly UserSummary[];
@@ -667,7 +700,30 @@ interface MessagingRepository {
     listConversations(args?: {
         limit?: number;
         cursor?: ConversationCursor | null;
+        /**
+         * THE ARCHIVED-ITEMS LAW. Omitted means `active` — archived conversations
+         * are hidden until a caller asks for them. This is a REQUEST to the reader
+         * (the RPC's `p_archived`), never a client-side sieve, so `hasMore` and the
+         * cursor describe the rows the caller actually asked for.
+         */
+        archived?: MessagingArchiveFilter;
     }): Promise<Page<ConversationSummary, ConversationCursor>>;
+    /**
+     * How many ARCHIVED conversations the caller has — the number a reveal
+     * control prints ("Archived (12)").
+     *
+     * 🚨 It is capped, and it says so. A count is read by listing archived rows
+     * up to `limit`; if that many come back the result is `exact: false` and the
+     * UI must render "12+", never a confident "12". A screen never lies: a cap
+     * silently presented as a total is the same defect as a badge counting rows
+     * the list hides.
+     */
+    countArchivedConversations(args?: {
+        limit?: number;
+    }): Promise<{
+        count: number;
+        exact: boolean;
+    }>;
     getConversation(id: ConversationId): Promise<Conversation>;
     listMessages(conversationId: ConversationId, args?: {
         limit?: number;
@@ -754,11 +810,38 @@ interface MessagingSnapshot {
     readonly activeConversationId: ConversationId | null;
     /** Conversations WITH unread, not total unread messages (the origin's semantics). */
     readonly totalUnreadConversations: number;
+    /**
+     * THE ARCHIVED-ITEMS LAW's state for this inbox. `conversations` above is
+     * ALWAYS the rows this filter asked the server for — never a superset a
+     * surface is expected to sieve, so counts and pagination cannot disagree
+     * with what renders.
+     */
+    readonly archiveFilter: MessagingArchiveFilter;
+    /**
+     * How many archived conversations exist, for the reveal control's label, or
+     * `null` before the first count lands. `exact: false` means the count hit its
+     * cap and the label must read "N+" — a capped number shown as a total is the
+     * same lie as a badge counting hidden rows.
+     */
+    readonly archivedCount: {
+        readonly count: number;
+        readonly exact: boolean;
+    } | null;
 }
 interface MessagingStore {
     snapshot(): MessagingSnapshot;
     subscribe(listener: (snapshot: MessagingSnapshot) => void): () => void;
     setConversations(items: readonly ConversationSummary[], hasMore: boolean): 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
+     * page is in flight shows active conversations under an "Archived" heading.
+     */
+    setArchiveFilter(next: MessagingArchiveFilter): void;
+    setArchivedCount(value: {
+        count: number;
+        exact: boolean;
+    } | null): void;
     appendConversations(items: readonly ConversationSummary[], hasMore: boolean): void;
     upsertConversation(item: ConversationSummary): void;
     removeConversation(id: ConversationId): void;
@@ -833,6 +916,15 @@ interface MessagingEngineOptions {
     onIncoming?: ((message: Message) => void) | undefined;
     conversationPageSize?: number | undefined;
     messagePageSize?: number | undefined;
+    /**
+     * 🚨 OPINIONS BECOME KNOBS. THE ARCHIVED-ITEMS LAW's clause 6 says the
+     * filter's initial state is an org/user-configurable setting, not code
+     * taste. The PLATFORM default is `active` (hide archived) and a host that
+     * passes nothing gets exactly that; a host wires this to whatever its own
+     * setting resolves to. The person can always change it from the control on
+     * the list.
+     */
+    archiveFilter?: MessagingArchiveFilter | undefined;
 }
 interface MessagingEngine {
     readonly store: MessagingStore;
@@ -841,6 +933,14 @@ interface MessagingEngine {
     /** Load page one of the inbox and start the inbox channel. */
     start(): Promise<void>;
     loadMoreConversations(): Promise<void>;
+    /**
+     * THE ARCHIVED-ITEMS LAW's control. Re-reads page one under the new state
+     * (the filter is a REQUEST to the server, never a client-side sieve) and
+     * refreshes the archived count the reveal label prints.
+     */
+    setArchiveFilter(next: MessagingArchiveFilter): 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. */
     openConversation(id: ConversationId): Promise<void>;
     closeConversation(id: ConversationId): void;
@@ -1037,6 +1137,15 @@ interface MessagingProviderProps {
     resolveSession?: SessionResolver | undefined;
     /** Override outbox persistence. Defaults to localStorage, then memory. */
     outboxStorage?: OutboxStorage | undefined;
+    /**
+     * 🚨 OPINIONS BECOME KNOBS. THE ARCHIVED-ITEMS LAW (Arman, 2026-09-09 —
+     * `common-docs/policies/archived-items.md`) clause 6: the archive filter's
+     * initial state is an org/user setting, not code taste. The PLATFORM default
+     * is `active` — archived conversations hidden — and a host that passes
+     * nothing gets exactly that. Pass whatever your own setting resolves to; the
+     * person can still flip it from the control on the list.
+     */
+    archiveFilter?: MessagingArchiveFilter | undefined;
     children: ReactNode;
 }
 declare function MessagingProvider(props: MessagingProviderProps): ReactNode;
@@ -1061,6 +1170,22 @@ interface UseConversationsResult {
     select: (id: ConversationId) => void;
     activeConversationId: ConversationId | null;
     startDirect: (otherUserId: UserId) => Promise<ConversationId>;
+    /**
+     * THE ARCHIVED-ITEMS LAW's state. `conversations` above is ALWAYS the rows
+     * this filter asked the SERVER for — never a superset to sieve — so a count
+     * taken over it can never disagree with what renders.
+     */
+    archiveFilter: MessagingArchiveFilter;
+    setArchiveFilter: (next: MessagingArchiveFilter) => void;
+    /**
+     * How many archived conversations exist, for a reveal label, or `null`
+     * before the first count lands. `exact: false` means the count hit its cap
+     * and the label must read "N+".
+     */
+    archivedCount: {
+        count: number;
+        exact: boolean;
+    } | null;
 }
 declare function useConversations(): UseConversationsResult;
 interface UseConversationResult {
@@ -1538,4 +1663,4 @@ declare function summarizeText(content: string, maxLength?: number): string;
 /** Serialize picked references into a fence the platform's other readers accept. */
 declare function composeFence(references: readonly MatrxReference[]): string;
 
-export { type ActionChoice, type ActionContext, type ActionHandler, type ActionOutcome, type ActionReceipt, type ActionRegistry, type ActorPresentation, AgentTag, type AiCallArgs, type AiCapability, type AiResult, AlertIcon, type Attachment, Avatar, BotIcon, CheckIcon, ChevronLeftIcon, type ClientMessageId, ClockIcon, CloseIcon, Composer, type ComposerInputRenderProps, type Conversation, type ConversationCursor, type ConversationId, ConversationList, type ConversationListProps, type ConversationRowWrapperProps, ConversationSkeleton, type ConversationSummary, type ConversationThread, type ConversationType, ConversationView, type ConversationViewProps, type DeliveryState, DeliveryTick, DoubleCheckIcon, type DraftMessage, EmptyState, type EngineDiagnostic, type IncomingMessageContext, type JsonObject, type JsonValue, LinkIcon, MESSAGING_EVENTS, MESSAGING_RPC_SCHEMA, MESSAGING_SCHEMA, type MatrxReference, type Message, type MessageAction, MessageActionChips, type MessageActionRenderProps, type MessageActionRenderer, MessageBubble, type MessageCursor, type MessageGroup, type MessageId, type MessageKind, type MessageWrapperProps, type MessagingAgentIdentity, type MessagingAgents, type MessagingAi, type MessagingAiOptions, type MessagingEngine, type MessagingEngineOptions, MessagingError, type MessagingErrorCode, type MessagingHost, type MessagingIdentity, MessagingInbox, type MessagingInboxProps, MessagingProvider, type MessagingProviderProps, type MessagingRepository, type MessagingSnapshot, type MessagingStore, type MessagingSupabaseClient, type MessagingSupabaseInternal, type OrganizationId, type Outbox, type OutboxEntry, type OutboxOptions, type OutboxStorage, type Page, PaperclipIcon, type Participant, type ParticipantRole, PlusIcon, type PostgrestFilterLike, type PostgrestLikeResponse, type PostgrestTableLike, RPCS, type ReadCache, type ReadCacheOptions, ReferenceCard, type ReferenceRenderer, ReplyIcon, type RepositoryOptions, type SchemaLike, SearchIcon, SendIcon, type SessionResolver, SparklesIcon, type SupabaseLike, TABLES, type TextSegment, TypingDots, type UseComposerResult, type UseConversationResult, type UseConversationsResult, type UseMessageActionResult, type UseMessagingAiResult, type UseTypistsResult, type UserId, type UserSummary, UsersIcon, asClientMessageId, asConversationId, asMessageId, asOrganizationId, asUserId, composeFence, conversationTopic, createActionRegistry, createMemoryOutboxStorage, createMessagingAi, createMessagingEngine, createMessagingRepository, createMessagingStore, createOutbox, createReadCache, createWebOutboxStorage, effectiveActorKey, extractReferences, formatConversationTime, formatDateSeparator, formatLastSeen, formatMessageTime, formatTypists, groupMessages, inboxTopic, invalidResponse, isSameDay, messagingClientId, normalizeMessagingError, optimisticMessage, participantNames, projectConversationSummary, projectMessage, projectMessageAction, projectParticipantRole, projectUserSummary, resolveActor, splitText, summarizeText, unreadCutoff, useComposer, useConversation, useConversations, useMessageAction, useMessagingAi, useMessagingHost, useMessagingSnapshot, useOnlineUserIds, useRequiredMessagingHost, useTypists };
+export { type ActionChoice, type ActionContext, type ActionHandler, type ActionOutcome, type ActionReceipt, type ActionRegistry, type ActorPresentation, AgentTag, type AiCallArgs, type AiCapability, type AiResult, AlertIcon, type Attachment, Avatar, BotIcon, CheckIcon, ChevronLeftIcon, type ClientMessageId, ClockIcon, CloseIcon, Composer, type ComposerInputRenderProps, type Conversation, type ConversationCursor, type ConversationId, ConversationList, type ConversationListProps, type ConversationRowWrapperProps, ConversationSkeleton, type ConversationSummary, type ConversationThread, type ConversationType, ConversationView, type ConversationViewProps, DEFAULT_MESSAGING_ARCHIVE_FILTER, type DeliveryState, DeliveryTick, DoubleCheckIcon, type DraftMessage, EmptyState, type EngineDiagnostic, type IncomingMessageContext, type JsonObject, type JsonValue, LinkIcon, MESSAGING_EVENTS, MESSAGING_RPC_SCHEMA, MESSAGING_SCHEMA, type MatrxReference, type Message, type MessageAction, MessageActionChips, type MessageActionRenderProps, type MessageActionRenderer, MessageBubble, type MessageCursor, type MessageGroup, type MessageId, type MessageKind, type MessageWrapperProps, type MessagingAgentIdentity, type MessagingAgents, type MessagingAi, type MessagingAiOptions, type MessagingArchiveFilter, type MessagingEngine, type MessagingEngineOptions, MessagingError, type MessagingErrorCode, type MessagingHost, type MessagingIdentity, MessagingInbox, type MessagingInboxProps, MessagingProvider, type MessagingProviderProps, type MessagingRepository, type MessagingSnapshot, type MessagingStore, type MessagingSupabaseClient, type MessagingSupabaseInternal, type OrganizationId, type Outbox, type OutboxEntry, type OutboxOptions, type OutboxStorage, type Page, PaperclipIcon, type Participant, type ParticipantRole, PlusIcon, type PostgrestFilterLike, type PostgrestLikeResponse, type PostgrestTableLike, RPCS, type ReadCache, type ReadCacheOptions, ReferenceCard, type ReferenceRenderer, ReplyIcon, type RepositoryOptions, type SchemaLike, SearchIcon, SendIcon, type SessionResolver, SparklesIcon, type SupabaseLike, TABLES, type TextSegment, TypingDots, type UseComposerResult, type UseConversationResult, type UseConversationsResult, type UseMessageActionResult, type UseMessagingAiResult, type UseTypistsResult, type UserId, type UserSummary, UsersIcon, asClientMessageId, asConversationId, asMessageId, asOrganizationId, asUserId, composeFence, conversationTopic, createActionRegistry, createMemoryOutboxStorage, createMessagingAi, createMessagingEngine, createMessagingRepository, createMessagingStore, createOutbox, createReadCache, createWebOutboxStorage, effectiveActorKey, extractReferences, formatConversationTime, formatDateSeparator, formatLastSeen, formatMessageTime, formatTypists, groupMessages, inboxTopic, invalidResponse, isSameDay, messagingClientId, normalizeMessagingError, optimisticMessage, participantNames, projectConversationSummary, projectMessage, projectMessageAction, projectParticipantRole, projectUserSummary, resolveActor, splitText, summarizeText, toMessagingArchiveFilter, unreadCutoff, useComposer, useConversation, useConversations, useMessageAction, useMessagingAi, useMessagingHost, useMessagingSnapshot, useOnlineUserIds, useRequiredMessagingHost, useTypists };

package/dist/react.d.ts

@@ -138,6 +138,39 @@ interface Message {
     /** Set only while this message is in the outbox and its last send failed. */
     readonly failureReason?: string | undefined;
 }
+/**
+ * THE ARCHIVED-ITEMS LAW's three states (Arman, 2026-09-09 —
+ * `common-docs/policies/archived-items.md`):
+ *
+ * > "everything should have an archive filter, and the default should always
+ * >  hide archived, but seeing archived items should be one or two clicks
+ * >  away … this is a system wide decision for every single item everywhere in
+ * >  our system, for every single table and every single page."
+ *
+ * | value      | what the list shows      |
+ * |------------|--------------------------|
+ * | `active`   | only un-archived rows    |
+ * | `archived` | only archived rows       |
+ * | `all`      | every row                |
+ *
+ * The same three words the rest of the platform uses — `ArchivedFilter` in
+ * matrx-frontend's `lib/entity-list`, `p_archived` on the `agx_*`/`wfx_*` and
+ * DM list RPCs, `ArchiveFilter` in `@ai-matrx/design-system`. A person meets
+ * ONE control, not one per app.
+ *
+ * 🚨 Three states, never a boolean. A boolean cannot say "archived only",
+ * which is exactly the view someone looking for a conversation they archived
+ * last month needs.
+ */
+type MessagingArchiveFilter = "active" | "archived" | "all";
+/** The platform default: a list hides archived rows until asked. */
+declare const DEFAULT_MESSAGING_ARCHIVE_FILTER: MessagingArchiveFilter;
+/**
+ * Narrow an untrusted value (a stored preference, a URL param, a host knob) to
+ * the tri-state. Anything unrecognised falls back to the default rather than
+ * silently widening a list to archived conversations.
+ */
+declare function toMessagingArchiveFilter(value: unknown, fallback?: MessagingArchiveFilter): MessagingArchiveFilter;
 interface ConversationSummary {
     readonly conversation: Conversation;
     readonly participants: readonly UserSummary[];
@@ -667,7 +700,30 @@ interface MessagingRepository {
     listConversations(args?: {
         limit?: number;
         cursor?: ConversationCursor | null;
+        /**
+         * THE ARCHIVED-ITEMS LAW. Omitted means `active` — archived conversations
+         * are hidden until a caller asks for them. This is a REQUEST to the reader
+         * (the RPC's `p_archived`), never a client-side sieve, so `hasMore` and the
+         * cursor describe the rows the caller actually asked for.
+         */
+        archived?: MessagingArchiveFilter;
     }): Promise<Page<ConversationSummary, ConversationCursor>>;
+    /**
+     * How many ARCHIVED conversations the caller has — the number a reveal
+     * control prints ("Archived (12)").
+     *
+     * 🚨 It is capped, and it says so. A count is read by listing archived rows
+     * up to `limit`; if that many come back the result is `exact: false` and the
+     * UI must render "12+", never a confident "12". A screen never lies: a cap
+     * silently presented as a total is the same defect as a badge counting rows
+     * the list hides.
+     */
+    countArchivedConversations(args?: {
+        limit?: number;
+    }): Promise<{
+        count: number;
+        exact: boolean;
+    }>;
     getConversation(id: ConversationId): Promise<Conversation>;
     listMessages(conversationId: ConversationId, args?: {
         limit?: number;
@@ -754,11 +810,38 @@ interface MessagingSnapshot {
     readonly activeConversationId: ConversationId | null;
     /** Conversations WITH unread, not total unread messages (the origin's semantics). */
     readonly totalUnreadConversations: number;
+    /**
+     * THE ARCHIVED-ITEMS LAW's state for this inbox. `conversations` above is
+     * ALWAYS the rows this filter asked the server for — never a superset a
+     * surface is expected to sieve, so counts and pagination cannot disagree
+     * with what renders.
+     */
+    readonly archiveFilter: MessagingArchiveFilter;
+    /**
+     * How many archived conversations exist, for the reveal control's label, or
+     * `null` before the first count lands. `exact: false` means the count hit its
+     * cap and the label must read "N+" — a capped number shown as a total is the
+     * same lie as a badge counting hidden rows.
+     */
+    readonly archivedCount: {
+        readonly count: number;
+        readonly exact: boolean;
+    } | null;
 }
 interface MessagingStore {
     snapshot(): MessagingSnapshot;
     subscribe(listener: (snapshot: MessagingSnapshot) => void): () => void;
     setConversations(items: readonly ConversationSummary[], hasMore: boolean): 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
+     * page is in flight shows active conversations under an "Archived" heading.
+     */
+    setArchiveFilter(next: MessagingArchiveFilter): void;
+    setArchivedCount(value: {
+        count: number;
+        exact: boolean;
+    } | null): void;
     appendConversations(items: readonly ConversationSummary[], hasMore: boolean): void;
     upsertConversation(item: ConversationSummary): void;
     removeConversation(id: ConversationId): void;
@@ -833,6 +916,15 @@ interface MessagingEngineOptions {
     onIncoming?: ((message: Message) => void) | undefined;
     conversationPageSize?: number | undefined;
     messagePageSize?: number | undefined;
+    /**
+     * 🚨 OPINIONS BECOME KNOBS. THE ARCHIVED-ITEMS LAW's clause 6 says the
+     * filter's initial state is an org/user-configurable setting, not code
+     * taste. The PLATFORM default is `active` (hide archived) and a host that
+     * passes nothing gets exactly that; a host wires this to whatever its own
+     * setting resolves to. The person can always change it from the control on
+     * the list.
+     */
+    archiveFilter?: MessagingArchiveFilter | undefined;
 }
 interface MessagingEngine {
     readonly store: MessagingStore;
@@ -841,6 +933,14 @@ interface MessagingEngine {
     /** Load page one of the inbox and start the inbox channel. */
     start(): Promise<void>;
     loadMoreConversations(): Promise<void>;
+    /**
+     * THE ARCHIVED-ITEMS LAW's control. Re-reads page one under the new state
+     * (the filter is a REQUEST to the server, never a client-side sieve) and
+     * refreshes the archived count the reveal label prints.
+     */
+    setArchiveFilter(next: MessagingArchiveFilter): 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. */
     openConversation(id: ConversationId): Promise<void>;
     closeConversation(id: ConversationId): void;
@@ -1037,6 +1137,15 @@ interface MessagingProviderProps {
     resolveSession?: SessionResolver | undefined;
     /** Override outbox persistence. Defaults to localStorage, then memory. */
     outboxStorage?: OutboxStorage | undefined;
+    /**
+     * 🚨 OPINIONS BECOME KNOBS. THE ARCHIVED-ITEMS LAW (Arman, 2026-09-09 —
+     * `common-docs/policies/archived-items.md`) clause 6: the archive filter's
+     * initial state is an org/user setting, not code taste. The PLATFORM default
+     * is `active` — archived conversations hidden — and a host that passes
+     * nothing gets exactly that. Pass whatever your own setting resolves to; the
+     * person can still flip it from the control on the list.
+     */
+    archiveFilter?: MessagingArchiveFilter | undefined;
     children: ReactNode;
 }
 declare function MessagingProvider(props: MessagingProviderProps): ReactNode;
@@ -1061,6 +1170,22 @@ interface UseConversationsResult {
     select: (id: ConversationId) => void;
     activeConversationId: ConversationId | null;
     startDirect: (otherUserId: UserId) => Promise<ConversationId>;
+    /**
+     * THE ARCHIVED-ITEMS LAW's state. `conversations` above is ALWAYS the rows
+     * this filter asked the SERVER for — never a superset to sieve — so a count
+     * taken over it can never disagree with what renders.
+     */
+    archiveFilter: MessagingArchiveFilter;
+    setArchiveFilter: (next: MessagingArchiveFilter) => void;
+    /**
+     * How many archived conversations exist, for a reveal label, or `null`
+     * before the first count lands. `exact: false` means the count hit its cap
+     * and the label must read "N+".
+     */
+    archivedCount: {
+        count: number;
+        exact: boolean;
+    } | null;
 }
 declare function useConversations(): UseConversationsResult;
 interface UseConversationResult {
@@ -1538,4 +1663,4 @@ declare function summarizeText(content: string, maxLength?: number): string;
 /** Serialize picked references into a fence the platform's other readers accept. */
 declare function composeFence(references: readonly MatrxReference[]): string;
 
-export { type ActionChoice, type ActionContext, type ActionHandler, type ActionOutcome, type ActionReceipt, type ActionRegistry, type ActorPresentation, AgentTag, type AiCallArgs, type AiCapability, type AiResult, AlertIcon, type Attachment, Avatar, BotIcon, CheckIcon, ChevronLeftIcon, type ClientMessageId, ClockIcon, CloseIcon, Composer, type ComposerInputRenderProps, type Conversation, type ConversationCursor, type ConversationId, ConversationList, type ConversationListProps, type ConversationRowWrapperProps, ConversationSkeleton, type ConversationSummary, type ConversationThread, type ConversationType, ConversationView, type ConversationViewProps, type DeliveryState, DeliveryTick, DoubleCheckIcon, type DraftMessage, EmptyState, type EngineDiagnostic, type IncomingMessageContext, type JsonObject, type JsonValue, LinkIcon, MESSAGING_EVENTS, MESSAGING_RPC_SCHEMA, MESSAGING_SCHEMA, type MatrxReference, type Message, type MessageAction, MessageActionChips, type MessageActionRenderProps, type MessageActionRenderer, MessageBubble, type MessageCursor, type MessageGroup, type MessageId, type MessageKind, type MessageWrapperProps, type MessagingAgentIdentity, type MessagingAgents, type MessagingAi, type MessagingAiOptions, type MessagingEngine, type MessagingEngineOptions, MessagingError, type MessagingErrorCode, type MessagingHost, type MessagingIdentity, MessagingInbox, type MessagingInboxProps, MessagingProvider, type MessagingProviderProps, type MessagingRepository, type MessagingSnapshot, type MessagingStore, type MessagingSupabaseClient, type MessagingSupabaseInternal, type OrganizationId, type Outbox, type OutboxEntry, type OutboxOptions, type OutboxStorage, type Page, PaperclipIcon, type Participant, type ParticipantRole, PlusIcon, type PostgrestFilterLike, type PostgrestLikeResponse, type PostgrestTableLike, RPCS, type ReadCache, type ReadCacheOptions, ReferenceCard, type ReferenceRenderer, ReplyIcon, type RepositoryOptions, type SchemaLike, SearchIcon, SendIcon, type SessionResolver, SparklesIcon, type SupabaseLike, TABLES, type TextSegment, TypingDots, type UseComposerResult, type UseConversationResult, type UseConversationsResult, type UseMessageActionResult, type UseMessagingAiResult, type UseTypistsResult, type UserId, type UserSummary, UsersIcon, asClientMessageId, asConversationId, asMessageId, asOrganizationId, asUserId, composeFence, conversationTopic, createActionRegistry, createMemoryOutboxStorage, createMessagingAi, createMessagingEngine, createMessagingRepository, createMessagingStore, createOutbox, createReadCache, createWebOutboxStorage, effectiveActorKey, extractReferences, formatConversationTime, formatDateSeparator, formatLastSeen, formatMessageTime, formatTypists, groupMessages, inboxTopic, invalidResponse, isSameDay, messagingClientId, normalizeMessagingError, optimisticMessage, participantNames, projectConversationSummary, projectMessage, projectMessageAction, projectParticipantRole, projectUserSummary, resolveActor, splitText, summarizeText, unreadCutoff, useComposer, useConversation, useConversations, useMessageAction, useMessagingAi, useMessagingHost, useMessagingSnapshot, useOnlineUserIds, useRequiredMessagingHost, useTypists };
+export { type ActionChoice, type ActionContext, type ActionHandler, type ActionOutcome, type ActionReceipt, type ActionRegistry, type ActorPresentation, AgentTag, type AiCallArgs, type AiCapability, type AiResult, AlertIcon, type Attachment, Avatar, BotIcon, CheckIcon, ChevronLeftIcon, type ClientMessageId, ClockIcon, CloseIcon, Composer, type ComposerInputRenderProps, type Conversation, type ConversationCursor, type ConversationId, ConversationList, type ConversationListProps, type ConversationRowWrapperProps, ConversationSkeleton, type ConversationSummary, type ConversationThread, type ConversationType, ConversationView, type ConversationViewProps, DEFAULT_MESSAGING_ARCHIVE_FILTER, type DeliveryState, DeliveryTick, DoubleCheckIcon, type DraftMessage, EmptyState, type EngineDiagnostic, type IncomingMessageContext, type JsonObject, type JsonValue, LinkIcon, MESSAGING_EVENTS, MESSAGING_RPC_SCHEMA, MESSAGING_SCHEMA, type MatrxReference, type Message, type MessageAction, MessageActionChips, type MessageActionRenderProps, type MessageActionRenderer, MessageBubble, type MessageCursor, type MessageGroup, type MessageId, type MessageKind, type MessageWrapperProps, type MessagingAgentIdentity, type MessagingAgents, type MessagingAi, type MessagingAiOptions, type MessagingArchiveFilter, type MessagingEngine, type MessagingEngineOptions, MessagingError, type MessagingErrorCode, type MessagingHost, type MessagingIdentity, MessagingInbox, type MessagingInboxProps, MessagingProvider, type MessagingProviderProps, type MessagingRepository, type MessagingSnapshot, type MessagingStore, type MessagingSupabaseClient, type MessagingSupabaseInternal, type OrganizationId, type Outbox, type OutboxEntry, type OutboxOptions, type OutboxStorage, type Page, PaperclipIcon, type Participant, type ParticipantRole, PlusIcon, type PostgrestFilterLike, type PostgrestLikeResponse, type PostgrestTableLike, RPCS, type ReadCache, type ReadCacheOptions, ReferenceCard, type ReferenceRenderer, ReplyIcon, type RepositoryOptions, type SchemaLike, SearchIcon, SendIcon, type SessionResolver, SparklesIcon, type SupabaseLike, TABLES, type TextSegment, TypingDots, type UseComposerResult, type UseConversationResult, type UseConversationsResult, type UseMessageActionResult, type UseMessagingAiResult, type UseTypistsResult, type UserId, type UserSummary, UsersIcon, asClientMessageId, asConversationId, asMessageId, asOrganizationId, asUserId, composeFence, conversationTopic, createActionRegistry, createMemoryOutboxStorage, createMessagingAi, createMessagingEngine, createMessagingRepository, createMessagingStore, createOutbox, createReadCache, createWebOutboxStorage, effectiveActorKey, extractReferences, formatConversationTime, formatDateSeparator, formatLastSeen, formatMessageTime, formatTypists, groupMessages, inboxTopic, invalidResponse, isSameDay, messagingClientId, normalizeMessagingError, optimisticMessage, participantNames, projectConversationSummary, projectMessage, projectMessageAction, projectParticipantRole, projectUserSummary, resolveActor, splitText, summarizeText, toMessagingArchiveFilter, unreadCutoff, useComposer, useConversation, useConversations, useMessageAction, useMessagingAi, useMessagingHost, useMessagingSnapshot, useOnlineUserIds, useRequiredMessagingHost, useTypists };

package/dist/react.js

@@ -821,6 +821,17 @@ function projectConversationSummary(row, viewerId, fallbackOrganizationId) {
   };
 }
 
+// src/core/types.ts
+var asConversationId = (value) => value;
+var asMessageId = (value) => value;
+var asUserId = (value) => value;
+var asOrganizationId = (value) => value;
+var asClientMessageId = (value) => value;
+var DEFAULT_MESSAGING_ARCHIVE_FILTER = "active";
+function toMessagingArchiveFilter(value, fallback = DEFAULT_MESSAGING_ARCHIVE_FILTER) {
+  return value === "active" || value === "archived" || value === "all" ? value : fallback;
+}
+
 // src/core/store.ts
 function timeOf(message) {
   const stamp = message.editedAt ?? message.createdAt;
@@ -851,6 +862,8 @@ function createMessagingStore() {
   let conversations = [];
   let hasMoreConversations = false;
   let hasLoadedConversations = false;
+  let archiveFilter = DEFAULT_MESSAGING_ARCHIVE_FILTER;
+  let archivedCount = null;
   let threads = /* @__PURE__ */ new Map();
   let activeConversationId = null;
   const listeners = /* @__PURE__ */ new Set();
@@ -863,7 +876,9 @@ function createMessagingStore() {
       hasLoadedConversations,
       threads,
       activeConversationId,
-      totalUnreadConversations: conversations.filter((item) => item.unreadCount > 0).length
+      totalUnreadConversations: conversations.filter((item) => item.unreadCount > 0).length,
+      archiveFilter,
+      archivedCount
     };
     return cached;
   }
@@ -910,6 +925,18 @@ function createMessagingStore() {
       hasLoadedConversations = true;
       emit();
     },
+    setArchiveFilter(next) {
+      if (next === archiveFilter) return;
+      archiveFilter = next;
+      conversations = [];
+      hasMoreConversations = false;
+      hasLoadedConversations = false;
+      emit();
+    },
+    setArchivedCount(value) {
+      archivedCount = value;
+      emit();
+    },
     appendConversations(items, hasMore) {
       const byId = new Map(conversations.map((item) => [item.conversation.id, item]));
       items.forEach((item) => byId.set(item.conversation.id, item));
@@ -1116,11 +1143,20 @@ function createMessagingEngine(options) {
   }
   async function reloadInbox() {
     if (disposed) return;
-    const page = await repository.listConversations({ limit: conversationPageSize });
+    const page = await repository.listConversations({
+      limit: conversationPageSize,
+      archived: store.snapshot().archiveFilter
+    });
     if (disposed) return;
     conversationCursor = page.nextCursor;
     store.setConversations(page.items, page.hasMore);
   }
+  async function reloadArchivedCount() {
+    if (disposed) return;
+    const value = await repository.countArchivedConversations();
+    if (disposed) return;
+    store.setArchivedCount(value);
+  }
   async function backfillConversation(id) {
     const thread = store.snapshot().threads.get(id);
     const since = thread?.latestAt ?? null;
@@ -1147,7 +1183,13 @@ function createMessagingEngine(options) {
     outbox,
     identity,
     async start() {
+      if (options.archiveFilter !== void 0) {
+        store.setArchiveFilter(options.archiveFilter);
+      }
       await reloadInbox();
+      void reloadArchivedCount().catch(
+        (error) => reportError(error, "refreshArchivedCount")
+      );
       if (disposed || inboxChannel !== null) return;
       inboxChannel = manager.open({
         topic: inboxTopic(identity.userId),
@@ -1189,12 +1231,33 @@ function createMessagingEngine(options) {
         }
       });
     },
+    async setArchiveFilter(next) {
+      if (next === store.snapshot().archiveFilter) return;
+      store.setArchiveFilter(next);
+      conversationCursor = null;
+      try {
+        await reloadInbox();
+      } catch (error) {
+        reportError(error, "setArchiveFilter");
+      }
+      await reloadArchivedCount().catch(
+        (error) => reportError(error, "refreshArchivedCount")
+      );
+    },
+    async refreshArchivedCount() {
+      try {
+        await reloadArchivedCount();
+      } catch (error) {
+        reportError(error, "refreshArchivedCount");
+      }
+    },
     async loadMoreConversations() {
       if (conversationCursor === null) return;
       try {
         const page = await repository.listConversations({
           limit: conversationPageSize,
-          cursor: conversationCursor
+          cursor: conversationCursor,
+          archived: store.snapshot().archiveFilter
         });
         conversationCursor = page.nextCursor;
         store.appendConversations(page.items, page.hasMore);
@@ -1458,6 +1521,7 @@ function createMessagingRepository(options) {
     identity,
     async listConversations(args = {}) {
       const limit = args.limit ?? 30;
+      const archived = args.archived ?? DEFAULT_MESSAGING_ARCHIVE_FILTER;
       const operation = "listConversations";
       const rows = await withSessionRetry(
         operation,
@@ -1467,7 +1531,12 @@ function createMessagingRepository(options) {
             p_user_id: identity.userId,
             p_limit: limit + 1,
             p_before_sort_at: args.cursor?.beforeSortAt ?? null,
-            p_before_conversation_id: args.cursor?.beforeConversationId ?? null
+            p_before_conversation_id: args.cursor?.beforeConversationId ?? null,
+            // THE ARCHIVED-ITEMS LAW, SERVER-side. `get_dm_conversations_with_details`
+            // used to hardcode `is_archived IS FALSE` with no parameter at all,
+            // so an archived conversation was not hidden — it was unreachable.
+            // The RPC gained `p_archived` on 2026-09-09 (register row R1).
+            p_archived: archived
           },
           operation
         )
@@ -1487,6 +1556,29 @@ function createMessagingRepository(options) {
         nextCursor: hasMore && last !== void 0 ? { beforeSortAt: last.sortAt, beforeConversationId: last.conversation.id } : null
       };
     },
+    async countArchivedConversations(args = {}) {
+      const limit = args.limit ?? 100;
+      const operation = "countArchivedConversations";
+      const rows = await withSessionRetry(
+        operation,
+        () => rpc(
+          RPCS.conversationsWithDetails,
+          {
+            p_user_id: identity.userId,
+            p_limit: limit + 1,
+            p_before_sort_at: null,
+            p_before_conversation_id: null,
+            p_archived: "archived"
+          },
+          operation
+        )
+      );
+      if (rows !== null && !Array.isArray(rows)) {
+        throw invalidResponse(operation, `${RPCS.conversationsWithDetails} did not return rows`);
+      }
+      const found = (rows ?? []).length;
+      return found > limit ? { count: limit, exact: false } : { count: found, exact: true };
+    },
     async getConversation(id) {
       const operation = "getConversation";
       const { data, error } = await withSessionRetry(
@@ -1795,6 +1887,7 @@ function MessagingRuntime(props) {
         onFallback: (message) => report({ level: "warn", message })
       }),
       onDiagnostic: report,
+      ...props.archiveFilter !== void 0 ? { archiveFilter: props.archiveFilter } : {},
       onIncoming: (message) => {
         const snapshot = built?.store.snapshot();
         if (snapshot === void 0) return;
@@ -2025,6 +2118,11 @@ function useConversations() {
     },
     select,
     activeConversationId: snapshot?.activeConversationId ?? null,
+    archiveFilter: snapshot?.archiveFilter ?? DEFAULT_MESSAGING_ARCHIVE_FILTER,
+    setArchiveFilter: (next) => {
+      void host?.engine.setArchiveFilter(next);
+    },
+    archivedCount: snapshot?.archivedCount ?? null,
     startDirect: async (otherUserId) => {
       if (host === null) {
         throw new Error("[@ai-matrx/messaging] startDirect called before the host was ready.");
@@ -2601,9 +2699,37 @@ var AI_LABELS = {
   draftReply: "Draft a reply"
 };
 function ConversationList(props) {
-  const { conversations, hasMore, isInitialLoading, loadMore, select, activeConversationId } = useConversations();
+  const {
+    conversations,
+    hasMore,
+    isInitialLoading,
+    loadMore,
+    select,
+    activeConversationId,
+    archiveFilter,
+    setArchiveFilter,
+    archivedCount
+  } = useConversations();
   const RowChrome = useMessagingHost()?.wrapConversationRow ?? null;
   const [query, setQuery] = useState2("");
+  const showingArchive = archiveFilter === "archived";
+  const archiveReveal = useMemo3(() => {
+    if (showingArchive) {
+      return {
+        next: "active",
+        label: "\u2190 Back to active conversations",
+        ariaLabel: "Hide archived conversations"
+      };
+    }
+    if (archivedCount === null) return null;
+    if (archivedCount.count === 0) return null;
+    const printed = archivedCount.exact ? `${archivedCount.count}` : `${archivedCount.count}+`;
+    return {
+      next: "archived",
+      label: `Archived (${printed})`,
+      ariaLabel: "Show archived conversations"
+    };
+  }, [showingArchive, archivedCount]);
   const visible = useMemo3(() => {
     const needle = query.trim().toLowerCase();
     if (needle.length === 0) return conversations;
@@ -2636,12 +2762,22 @@ function ConversationList(props) {
         }
       ) : null
     ] }),
+    archiveReveal !== null ? /* @__PURE__ */ jsx4("div", { className: "mx-msg__list-archive", children: /* @__PURE__ */ jsx4(
+      "button",
+      {
+        type: "button",
+        className: "mx-msg__chip",
+        onClick: () => setArchiveFilter(archiveReveal.next),
+        "aria-label": archiveReveal.ariaLabel,
+        children: archiveReveal.label
+      }
+    ) }) : null,
     /* @__PURE__ */ jsxs2("div", { className: "mx-msg__scroll", children: [
       isInitialLoading ? /* @__PURE__ */ jsx4(ConversationSkeleton, {}) : visible.length === 0 ? /* @__PURE__ */ jsx4(
         EmptyState,
         {
-          title: query.length > 0 ? "No matches" : "No conversations yet",
-          body: query.length > 0 ? "Try a different name or word." : "Start one and it will appear here."
+          title: query.length > 0 ? "No matches" : showingArchive ? "No archived conversations" : "No conversations yet",
+          body: query.length > 0 ? "Try a different name or word." : showingArchive ? "Archiving a conversation moves it here." : "Start one and it will appear here."
         }
       ) : /* @__PURE__ */ jsx4("ul", { className: "mx-msg__rows", children: visible.map((item) => {
         const row = /* @__PURE__ */ jsx4(
@@ -3136,13 +3272,6 @@ function MessagingInbox(props) {
     }
   );
 }
-
-// src/core/types.ts
-var asConversationId = (value) => value;
-var asMessageId = (value) => value;
-var asUserId = (value) => value;
-var asOrganizationId = (value) => value;
-var asClientMessageId = (value) => value;
 export {
   AgentTag,
   AlertIcon,
@@ -3156,6 +3285,7 @@ export {
   ConversationList,
   ConversationSkeleton,
   ConversationView,
+  DEFAULT_MESSAGING_ARCHIVE_FILTER,
   DeliveryTick,
   DoubleCheckIcon,
   EmptyState,
@@ -3218,6 +3348,7 @@ export {
   resolveActor,
   splitText,
   summarizeText,
+  toMessagingArchiveFilter,
   unreadCutoff,
   useComposer,
   useConversation,