@rapidmx/web-client 0.8.0 → 0.9.0

package/apps/shared/components/mail/ConversationList.tsx

@@ -6,6 +6,8 @@ import React, { useState } from "react";
 import { HiChevronDown, HiChevronRight, HiOutlineFlag, HiOutlinePaperClip } from "react-icons/hi2";
 import { ApiRequestError } from "@rapidmx/react-shared/util/api.js";
 import { Message } from "@rapidmx/react-shared/mail/mailApi.js";
+import { formatMailAddress } from "@rapidmx/react-shared/mail/mailAddress.js";
+import MailAddress from "./MailAddress.js";
 import { ConversationSummary, listConversationMessages } from "@rapidmx/react-shared/mail/conversationsApi.js";
 
 export interface ConversationListProps {
@@ -39,8 +41,9 @@ export interface ConversationListProps {
     newestFirst?: boolean;
 }
 
-function participantNames(conversation: ConversationSummary): string {
-    return conversation.participants.map((participant) => participant.displayName || participant.address).join(", ");
+/** Every participant as `Name <address>`, for the tooltip and the accessible text of the "+N" a crowded row folds them into. */
+function participantList(conversation: ConversationSummary): string {
+    return conversation.participants.map((participant) => formatMailAddress(participant)).join(", ");
 }
 
 /**
@@ -168,7 +171,15 @@ export default function ConversationList({
                                 )}
                             >
                                 <div className="flex items-center justify-between gap-2 text-sm">
-                                    <span className="truncate">{participantNames(conversation)}</span>
+                                    {/* The first participant in full - name and address - and the rest as a count, with everyone's
+                                        address in its tooltip; the latest sender when the summary lists none. */}
+                                    <MailAddress recipient={conversation.participants[0] ?? conversation.latestFrom} className="flex-1" />
+                                    {conversation.participants.length > 1 && (
+                                        <span className="text-xs text-text-muted shrink-0 font-normal" title={participantList(conversation)}>
+                                            +{conversation.participants.length - 1}
+                                            <span className="sr-only"> more: {participantList(conversation)}</span>
+                                        </span>
+                                    )}
                                     <span className="text-xs text-text-muted shrink-0">
                                         {new Date(conversation.latestDate).toLocaleDateString()}
                                     </span>
@@ -220,9 +231,7 @@ export default function ConversationList({
                                             ].join(" ")}
                                         >
                                             <div className="flex items-center justify-between gap-2 text-sm">
-                                                <span className="truncate">
-                                                    {message.from.displayName || message.from.address}
-                                                </span>
+                                                <MailAddress recipient={message.from} />
                                                 <span className="text-xs text-text-muted shrink-0">
                                                     {new Date(message.receivedDate).toLocaleDateString()}
                                                 </span>

package/apps/shared/components/mail/ConversationThreadPane.tsx

@@ -8,6 +8,7 @@ import { Attachment, Folder, Message, listAttachments, setMessageRead } from "@r
 import { ConversationSummary, listConversationMessages } from "@rapidmx/react-shared/mail/conversationsApi.js";
 import { Label } from "@rapidmx/react-shared/mail/labelsApi.js";
 import Alert from "@rapidmx/react-shared/components/feedback/Alert.js";
+import MailAddress from "./MailAddress.js";
 import MessageDetailPane from "./MessageDetailPane.js";
 
 /** One request's worth of the thread. The server's own default for `listConversationMessages()`. */
@@ -362,7 +363,6 @@ export default function ConversationThreadPane({
                     const uid = message.uid;
                     const expanded = expandedUids.has(uid);
                     const bodyId = `thread-message-${uid}`;
-                    const sender = message.from.displayName || message.from.address;
                     return (
                         <li
                             key={uid}
@@ -391,7 +391,7 @@ export default function ConversationThreadPane({
                                     ].join(" ")}
                                 >
                                     <span className="flex items-center justify-between gap-2 text-sm">
-                                        <span className="truncate">{sender}</span>
+                                        <MailAddress recipient={message.from} />
                                         <span className="text-xs text-text-muted shrink-0">
                                             {new Date(message.receivedDate).toLocaleString()}
                                         </span>

package/apps/shared/components/mail/MailAddress.tsx

@@ -0,0 +1,88 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import React, { useState } from "react";
+import { MailAddressLike, formatMailAddress, splitMailAddress } from "@rapidmx/react-shared/mail/mailAddress.js";
+
+export interface MailAddressProps {
+    /** A message's `from`, a recipient, a conversation participant. */
+    recipient: MailAddressLike;
+    className?: string;
+}
+
+/**
+ * A sender or recipient as one compact line for a dense row: the name, when there is one, with the real address in muted
+ * type after it - `Jean-Philippe  <jp@example.com>` - or the bare address without a name. The address is never left out,
+ * and when the row is too narrow for both the name gives way first (it shrinks a thousand times faster), then the
+ * address's own local part - the `@domain`, which is what says who really sent it, keeps its room to the end. The full
+ * `Name <address>` is the tooltip and, once, the accessible text (the two visible halves are hidden from assistive
+ * technology), so a screen reader hears one address, not fragments.
+ */
+export default function MailAddress({ recipient, className }: MailAddressProps) {
+    const { name, address } = splitMailAddress(recipient);
+    const full = formatMailAddress(recipient);
+    const at = address.lastIndexOf("@");
+    const local = at > 0 ? address.slice(0, at) : address;
+    const domain = at > 0 ? address.slice(at) : "";
+    return (
+        <span className={["flex min-w-0 items-baseline gap-1.5", className].filter(Boolean).join(" ")} title={full}>
+            <span className="sr-only">{full}</span>
+            {name && (
+                <span aria-hidden="true" className="truncate min-w-0" style={{ flexShrink: 1000 }}>
+                    {name}
+                </span>
+            )}
+            <span
+                aria-hidden="true"
+                className={["flex min-w-0 items-baseline", name ? "text-xs font-normal text-text-muted" : ""].filter(Boolean).join(" ")}
+            >
+                {name && <span>&lt;</span>}
+                <span className="truncate min-w-0">{local}</span>
+                {domain && <span className="shrink-0">{domain}</span>}
+                {name && <span>&gt;</span>}
+            </span>
+        </span>
+    );
+}
+
+/** How many recipients a `RecipientLine` shows before folding the rest behind "and N more". */
+export const RECIPIENT_LINE_LIMIT = 3;
+
+/**
+ * A `To`/`Cc` line of a message header: every recipient as `Name <address>` in the text itself (never hover-only), wrapping
+ * onto more lines as needed. A long list shows its first `RECIPIENT_LINE_LIMIT` and folds the rest behind a button -
+ * "and 12 more" / "Show fewer" - so a message to a hundred people doesn't take the whole header. Nothing when empty.
+ */
+export function RecipientLine({ label, recipients }: { label: string; recipients: MailAddressLike[] }) {
+    const [expanded, setExpanded] = useState(false);
+    if (recipients.length === 0) {
+        return null;
+    }
+    const folded = recipients.length > RECIPIENT_LINE_LIMIT;
+    const shown = folded && !expanded ? recipients.slice(0, RECIPIENT_LINE_LIMIT) : recipients;
+    return (
+        <p className="text-sm text-text-muted break-words">
+            <span>{label}</span>{" "}
+            {shown.map((recipient, index) => (
+                <React.Fragment key={index}>
+                    {index > 0 && ", "}
+                    <span>{formatMailAddress(recipient)}</span>
+                </React.Fragment>
+            ))}
+            {folded && (
+                <>
+                    {" "}
+                    <button
+                        type="button"
+                        aria-expanded={expanded}
+                        onClick={() => setExpanded((open) => !open)}
+                        className="text-xs font-semibold text-primary-dark underline hover:no-underline"
+                    >
+                        {expanded ? "Show fewer" : `and ${recipients.length - RECIPIENT_LINE_LIMIT} more`}
+                    </button>
+                </>
+            )}
+        </p>
+    );
+}

package/apps/shared/components/mail/MessageDetailPane.tsx

@@ -60,6 +60,8 @@ import { KEY_CHANGE_STALE_MESSAGE, sameFingerprint } from "../contacts/contactKe
 import { useCompose } from "./compose/ComposeContext.js";
 import { loadOriginalMessage } from "./compose/quotedBody.js";
 import { formatRecipient } from "./compose/recipients.js";
+import { formatMailAddress } from "@rapidmx/react-shared/mail/mailAddress.js";
+import { RecipientLine } from "./MailAddress.js";
 import { useMailShell } from "./layout/MailShell.js";
 import { useUnlockPrompt } from "../layout/UnlockPromptProvider.js";
 import { moveLocalEntity } from "../../search/localIndexRpcClient.js";
@@ -834,8 +836,8 @@ function MessageDetailContent({
     const senderAddress = (signatureShown ? extractAddresses(security.protectedHeaders?.from)[0] : undefined) ?? message.from.address;
     const senderName = message.from.displayName;
     const senderNameCheck = checkSenderName(senderName, senderAddress);
-    const showSenderAddress = !!senderName && (signatureShown || senderNameCheck.looksLikeAddress);
-    const senderLabel = showSenderAddress ? `${senderName} <${senderAddress}>` : senderName || senderAddress;
+    // Always `Name <address>` (or the bare address): a name alone hides who a message is really from.
+    const senderLabel = formatMailAddress({ displayName: senderName, address: senderAddress });
     // Offered only for a valid signature from a certificate nobody pinned for this sender - never to replace a pin.
     // A recorded signing-key conflict for this sender is resolved from the contact, never by trusting another key.
     const pendingConflict = senderUnpinned && senderKeyState?.conflict !== undefined;
@@ -1082,8 +1084,9 @@ function MessageDetailContent({
                         been forwarded or re-sent to you unchanged, or you were Bcc&rsquo;d.
                     </p>
                 )}
-                <p className="text-sm text-text-muted mt-1">
-                    From {senderLabel} &middot; {new Date(message.receivedDate).toLocaleString()}
+                <p className="text-sm text-text-muted mt-1 break-words">
+                    From <span className="font-medium text-text">{senderLabel}</span> &middot;{" "}
+                    {new Date(message.receivedDate).toLocaleString()}
                 </p>
                 {senderNameCheck.misleading && (
                     <p role="status" className="mt-2 py-2 px-3 rounded-sm text-sm bg-warning/15 text-text">
@@ -1091,9 +1094,10 @@ function MessageDetailContent({
                         sent from <span className="font-medium">{senderAddress}</span>. Don&rsquo;t trust it based on the name.
                     </p>
                 )}
-                <p className="text-sm text-text-muted">
-                    To {message.recipients.map((r) => r.displayName || r.address).join(", ")}
-                </p>
+                {/* Every recipient with their address, grouped as the sender addressed them; a long list folds. */}
+                <RecipientLine label="To" recipients={message.recipients.filter((r) => r.type !== "cc" && r.type !== "bcc")} />
+                <RecipientLine label="Cc" recipients={message.recipients.filter((r) => r.type === "cc")} />
+                <RecipientLine label="Bcc" recipients={message.recipients.filter((r) => r.type === "bcc")} />
                 {/* Wraps: in a thread the pane can be as narrow as the reading pane gets (the list takes
                     384px of it), and these are six controls. */}
                 <div className="flex flex-wrap gap-1 mt-3">

package/apps/shared/components/mail/compose/ComposeWindow.tsx

@@ -33,6 +33,7 @@ import {
     uploadAttachment,
 } from "@rapidmx/react-shared/mail/mailApi.js";
 import { listMailSignatures } from "@rapidmx/react-shared/mail/mailSignaturesApi.js";
+import { describeSendFailure } from "@rapidmx/react-shared/mail/sendFailure.js";
 import { buildComposeBodyHtml } from "@rapidmx/react-shared/mail/compose/composeQuoting.js";
 import { peekMailboxWritability, useMailboxWritability } from "../writableMailboxes.js";
 import { decideMessageEncryption, resolveRecipientEncryption, RecipientEncryptionStatus } from "@rapidmx/react-shared/crypto/composeSecurity.js";
@@ -48,6 +49,7 @@ import RecipientInput from "./RecipientInput.js";
 import { parseRecipientList } from "./recipients.js";
 import RichTextEditor from "./RichTextEditor.js";
 import ScheduleSendPicker from "./ScheduleSendPicker.js";
+import SendFailureAlert from "./SendFailureAlert.js";
 import Alert from "@rapidmx/react-shared/components/feedback/Alert.js";
 import Button from "@rapidmx/react-shared/components/buttons/Button.js";
 import Modal from "@rapidmx/react-shared/components/overlays/Modal.js";
@@ -119,12 +121,19 @@ const CRYPTO_UNAVAILABLE_MESSAGE =
 const NO_RECIPIENTS_CLOSE_MESSAGE =
     "This message may be encrypted once its recipients are known, so it isn't saved as a draft until you add them. Add a recipient and close again, or discard it.";
 
+const SEND_FAILED_TITLE = "This message wasn't sent";
+function sendFailedCloseMessage(reason: string): string {
+    return `Sending it failed (${reason.replace(/\.$/, "")}). Closing keeps it as a draft, unsent. Keep editing to try again, or discard it.`;
+}
+
 /** The confirmation shown before a Close/Discard throws content away (or when a Close couldn't save it). */
 interface ClosePrompt {
     title: string;
     message: string;
     /** Also offer "Retry" for loading the encryption settings. */
     retry?: boolean;
+    /** Also offer "Close, keep draft": a failed send's close prompt, where closing keeps the unsent draft as it is. */
+    closeAnyway?: boolean;
 }
 
 interface SecurityBlock {
@@ -240,6 +249,8 @@ export default function ComposeWindow({
     const [attachments, setAttachments] = useState<Attachment[]>([]);
     const [attachError, setAttachError] = useState<string | null>(null);
     const [sendError, setSendError] = useState<string | null>(null);
+    // The technical facts behind `sendError` (per-recipient SMTP results, a transport error), when the server gave any.
+    const [sendDetails, setSendDetails] = useState<string[]>([]);
     const [sending, setSending] = useState(false);
     const [requestReceipt, setRequestReceipt] = useState(false);
     const [schedulePickerOpen, setSchedulePickerOpen] = useState(false);
@@ -909,6 +920,7 @@ export default function ComposeWindow({
         setSending(true);
         sendingRef.current = true;
         setSendError(null);
+        setSendDetails([]);
         setSecurityBlock(null);
         setEncryptionBlocked(null);
         pendingSaveRef.current = false;
@@ -928,8 +940,13 @@ export default function ComposeWindow({
             finishedRef.current = true;
             onClose();
         } catch (err) {
-            const fallback = scheduledSendTimeIso ? "Could not schedule this message." : "Could not send this message.";
-            setSendError(err instanceof ApiRequestError ? err.message : fallback);
+            // The window stays open with the draft exactly as it was; nothing here closes, discards or saves over it.
+            const failure = describeSendFailure(
+                err,
+                scheduledSendTimeIso ? "Could not schedule this message." : "Could not send this message.",
+            );
+            setSendError(failure.message);
+            setSendDetails(failure.lines);
         } finally {
             sendingRef.current = false;
             setSending(false);
@@ -1096,11 +1113,16 @@ export default function ComposeWindow({
      * the same confirmation as a discard. A failed save keeps the window open with Discard / Keep editing.
      * Close and Discard are both disabled while a send is in progress: deleting the draft, or saving a
      * plaintext copy over the message the send just assembled, mid-send would lose or leak it. */
-    async function handleClose() {
+    async function handleClose(sendFailureAcknowledged = false) {
         if (!hasUserContent) {
             void discardNow();
             return;
         }
+        if (sendError && !sendFailureAcknowledged) {
+            // Closing would keep the draft and say nothing, which reads as if it had been sent.
+            setClosePrompt({ title: SEND_FAILED_TITLE, message: sendFailedCloseMessage(sendError), closeAnyway: true });
+            return;
+        }
         if (encryptionDecided) {
             setClosePrompt({ title: DISCARD_TITLE, message: ENCRYPTED_CLOSE_MESSAGE });
             return;
@@ -1330,6 +1352,19 @@ export default function ComposeWindow({
                         Retry
                     </Button>
                 )}
+                {closePrompt?.closeAnyway && (
+                    <Button
+                        type="button"
+                        onClick={() => {
+                            setClosePrompt(null);
+                            void handleClose(true);
+                        }}
+                        disabled={sending || closing}
+                        className="!w-auto"
+                    >
+                        Close, keep draft
+                    </Button>
+                )}
                 <Button type="button" onClick={() => void discardNow()} disabled={sending || closing} className="!w-auto">
                     Discard
                 </Button>
@@ -1349,6 +1384,7 @@ export default function ComposeWindow({
                     onClick={onToggleMinimize}
                 >
                     <span className="text-sm font-medium truncate">{title}</span>
+                    {sendError && <span className="shrink-0 text-xs font-bold uppercase tracking-wide">Not sent</span>}
                     <div className="flex items-center gap-0.5" onClick={(e) => e.stopPropagation()}>
                         <HeaderButton label="Restore" onClick={onToggleMinimize} icon={HiOutlineArrowsPointingOut} />
                         <HeaderButton label="Discard draft" onClick={handleDiscard} icon={HiOutlineXMark} disabled={sending || closing} />
@@ -1420,7 +1456,7 @@ export default function ComposeWindow({
                     <div className="px-3 pt-2">
                         {folderError && <Alert>{folderError}</Alert>}
                         {draftError && <Alert>{draftError}</Alert>}
-                        {sendError && <Alert>{sendError}</Alert>}
+                        {sendError && <SendFailureAlert message={sendError} lines={sendDetails} />}
                         {attachError && <Alert>{attachError}</Alert>}
                         {discardError && <Alert>{discardError}</Alert>}
                     </div>

package/apps/shared/components/mail/compose/SendFailureAlert.tsx

@@ -0,0 +1,48 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import React from "react";
+import Alert from "@rapidmx/react-shared/components/feedback/Alert.js";
+import CopyButton from "@rapidmx/react-shared/components/buttons/CopyButton.js";
+
+export interface SendFailureAlertProps {
+    /** The plain, human message - always shown. */
+    message: string;
+    /** The technical facts behind it (`describeSendFailure().lines`): per-recipient SMTP results, a transport error.
+     * With none, only the message is shown. */
+    lines: string[];
+}
+
+/**
+ * The banner a compose window shows when a send (or scheduled send) fails: the plain message, prominent, and - when the
+ * server said more - a collapsed "Technical details" block of monospace lines, one per fact, that can be selected or
+ * copied in one go to send to whoever runs the server. Collapsed, because most people only need the message.
+ */
+export default function SendFailureAlert({ message, lines }: SendFailureAlertProps) {
+    return (
+        <Alert>
+            <div className="flex-1 min-w-0">
+                <p className="font-semibold break-words">{message}</p>
+                {lines.length > 0 && (
+                    <details className="mt-2">
+                        <summary className="cursor-pointer text-xs font-semibold">Technical details</summary>
+                        <ul
+                            aria-label="Technical details"
+                            className="mt-2 max-h-40 overflow-auto rounded-sm border border-border bg-surface p-2 text-xs font-mono text-text select-text"
+                        >
+                            {lines.map((line, index) => (
+                                <li key={index} className="whitespace-pre-wrap break-words">
+                                    {line}
+                                </li>
+                            ))}
+                        </ul>
+                        <div className="mt-2">
+                            <CopyButton value={lines.join("\n")} label="Copy technical details" />
+                        </div>
+                    </details>
+                )}
+            </div>
+        </Alert>
+    );
+}

package/apps/shared/components/mail/layout/MailShell.tsx

@@ -14,6 +14,7 @@ import KeyEnrollmentGate from "../../layout/KeyEnrollmentGate.js";
 import MailboxProvisioning from "../../layout/MailboxProvisioning.js";
 import { useCompose } from "../compose/ComposeContext.js";
 import LocalIndexLifecycle from "../../../search/LocalIndexLifecycle.js";
+import { LiveUpdates, NO_LIVE_UPDATES, useMailLiveUpdates } from "../../../mail/useMailLiveUpdates.js";
 
 export type MailShellProps = Omit<AppShellProps, "active">;
 
@@ -62,12 +63,19 @@ export interface MailShellContextValue {
      * A no-op on the default context value, which is only ever read outside a real shell.
      */
     onFolderCreated: (folder: Folder) => void;
+    /**
+     * Bumped whenever new mail (or another change to a message) may have arrived - a push event, a reconnect or the safety-net
+     * poll - so the list on screen can quietly refetch its first page. See `useMailLiveUpdates()`. Never changes on the default
+     * context value, which is only ever read outside a real shell.
+     */
+    live: LiveUpdates;
 }
 
 const MailShellContext = createContext<MailShellContextValue>({
     mailboxes: [],
     mailboxFolders: [],
     onFolderCreated: () => undefined,
+    live: NO_LIVE_UPDATES,
 });
 
 /** Reads the mailbox/folder a page is currently showing, as resolved by the enclosing `MailShell`. */
@@ -105,8 +113,16 @@ function sortedFoldersOf(folders: Folder[]): Folder[] {
     return [...folders].sort((a, b) => folderSortKey(a) - folderSortKey(b) || a.name.localeCompare(b.name));
 }
 
-function aggregateUnreadCount(mailboxFolders: MailboxFolders[], type: AggregateFolderType): number {
-    return mailboxFolders.reduce((total, mf) => total + (mf.folders.find((f) => f.type === type)?.unreadCount ?? 0), 0);
+/** A folder's unread count: the refreshed one when live updates have read it since load, else the one it was listed with. */
+function unreadOf(folder: Folder, unreadCounts: Record<string, number>): number {
+    return unreadCounts[folder.uid] ?? folder.unreadCount;
+}
+
+function aggregateUnreadCount(mailboxFolders: MailboxFolders[], type: AggregateFolderType, unreadCounts: Record<string, number>): number {
+    return mailboxFolders.reduce((total, mf) => {
+        const folder = mf.folders.find((f) => f.type === type);
+        return total + (folder ? unreadOf(folder, unreadCounts) : 0);
+    }, 0);
 }
 
 type Status = "checking" | "error" | "ready";
@@ -256,14 +272,22 @@ export default function MailShell({
         }
         setMailboxFolders((prev) =>
             prev.map((entry) =>
-                entry.mailbox.uid === folder.mailboxUid ? { ...entry, folders: [...entry.folders, folder] } : entry,
+                // Not one already there: another client's create event can arrive after (or twice, or alongside) our own.
+                entry.mailbox.uid === folder.mailboxUid && !entry.folders.some((existing) => existing.uid === folder.uid)
+                    ? { ...entry, folders: [...entry.folders, folder] }
+                    : entry,
             ),
         );
     }, []);
 
+    // New mail without a reload: push events for every folder, plus a safety-net poll. Held in state beside `mailboxFolders`
+    // rather than written into it, so a refreshed unread count never looks like a change of folders to the list on screen
+    // (which reloads, and forgets its selection, whenever the folders do).
+    const { live, unreadCounts } = useMailLiveUpdates({ userUid, mailboxes, mailboxFolders, onFolderCreated });
+
     const contextValue = useMemo<MailShellContextValue>(
-        () => ({ mailboxUid, folderUid, aggregateFolderType, mailboxes, mailboxFolders, onFolderCreated }),
-        [mailboxUid, folderUid, aggregateFolderType, mailboxes, mailboxFolders, onFolderCreated],
+        () => ({ mailboxUid, folderUid, aggregateFolderType, mailboxes, mailboxFolders, onFolderCreated, live }),
+        [mailboxUid, folderUid, aggregateFolderType, mailboxes, mailboxFolders, onFolderCreated, live],
     );
 
     // A full-screen takeover, not nested inside the rest of the app's chrome — there's nothing else for a
@@ -314,7 +338,7 @@ export default function MailShell({
                                 </div>
                                 <div className="flex flex-col gap-0.5">
                                     {AGGREGATE_FOLDER_TYPES.map((type) => {
-                                        const unread = aggregateUnreadCount(mailboxFolders, type);
+                                        const unread = aggregateUnreadCount(mailboxFolders, type, unreadCounts);
                                         return (
                                             <a
                                                 key={type}
@@ -350,7 +374,9 @@ export default function MailShell({
                                     </div>
                                 )}
                                 <div className="flex flex-col gap-0.5">
-                                    {sortedFoldersOf(folders).map((folder) => (
+                                    {sortedFoldersOf(folders).map((folder) => {
+                                        const unread = unreadOf(folder, unreadCounts);
+                                        return (
                                         <a
                                             key={folder.uid}
                                             href={`/?mailboxUid=${encodeURIComponent(mailbox.uid)}&folderUid=${encodeURIComponent(folder.uid)}`}
@@ -362,13 +388,14 @@ export default function MailShell({
                                             ].join(" ")}
                                         >
                                             <span>{FOLDER_LABELS[folder.type] ?? folder.name}</span>
-                                            {folder.unreadCount > 0 && (
+                                            {unread > 0 && (
                                                 <span className="text-xs font-bold rounded-pill py-0.5 px-1.5 bg-surface-alt text-text-muted">
-                                                    {folder.unreadCount}
+                                                    {unread}
                                                 </span>
                                             )}
                                         </a>
-                                    ))}
+                                        );
+                                    })}
                                 </div>
                             </div>
                         ))}

package/apps/shared/mail/mergeFirstPage.ts

@@ -0,0 +1,47 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+
+/** What `mergeFirstPage()` made of a fresh first page and the rows already on screen. */
+export interface MergedPage<T> {
+    /** The rows to show. */
+    rows: T[];
+    /** How many of the fresh page's rows were not on screen yet - the mail that arrived since. */
+    added: number;
+    /** `true` when `rows` is exactly the fresh page, because the whole listing fits on it. */
+    complete: boolean;
+}
+
+/**
+ * Folds a freshly fetched first page of a list into the rows already loaded (the first page plus whatever "load more"
+ * added), for the quiet refresh that follows a push event or a poll - so new mail appears without the list being reset,
+ * re-scrolled or re-selected the way a full reload would.
+ *
+ * - A page shorter than `pageSize` is the whole listing, so it simply replaces what is shown - which also drops what was
+ * deleted or moved elsewhere.
+ * - A full page is only the top of a longer listing. Its rows go first, in the server's order, followed by the loaded rows
+ * it did not repeat (older ones the reader has scrolled to). What was removed elsewhere from a long, partly loaded list
+ * stays until the next real load; nothing here can tell it from a row that merely slid off the first page.
+ * - A row in both keeps whichever copy `pick` prefers - by default the fresh one - so, for messages, a row the reader has
+ * just changed (a higher `version`) is not put back by a fetch that started before the change landed.
+ */
+export function mergeFirstPage<T>(
+    current: T[],
+    fresh: T[],
+    idOf: (row: T) => string,
+    pageSize: number,
+    pick: (current: T, fresh: T) => T = (_current, next) => next,
+): MergedPage<T> {
+    const currentById = new Map(current.map((row) => [idOf(row), row]));
+    const added = fresh.filter((row) => !currentById.has(idOf(row))).length;
+    const rows = fresh.map((row) => {
+        const existing = currentById.get(idOf(row));
+        return existing ? pick(existing, row) : row;
+    });
+    if (fresh.length < pageSize) {
+        return { rows, added, complete: true };
+    }
+    const freshIds = new Set(fresh.map(idOf));
+    return { rows: [...rows, ...current.filter((row) => !freshIds.has(idOf(row)))], added, complete: false };
+}