@rapidmx/web-client 0.9.0 → 0.11.0

package/dist/apps/shared/mail/useMailConnection.js

@@ -0,0 +1,138 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { createContext, useCallback, useEffect, useRef, useState } from "react";
+import { ApiRequestError } from "@rapidmx/react-shared/util/api.js";
+import { listFolders, listMailboxes } from "@rapidmx/react-shared/mail/mailApi.js";
+import { FOLDER_ORDER, MAIL_FOLDER_TYPES, isMailFolder, knownFolderUids, reconcileFolders, removeFolder, upsertFolder } from "./folderTree.js";
+import { useMailLiveUpdates } from "./useMailLiveUpdates.js";
+import { useNewMailNotifications } from "./useNewMailNotifications.js";
+import { usePushConnectionNotice } from "../notifications/pushStatus.js";
+import { registerOutboxCounter } from "./outbox/sendJob.js";
+import { handleSendEvent } from "./outbox/sendOutcomes.js";
+import { useOutboxStatus } from "./outbox/useOutboxStatus.js";
+/** Page size of the one `listMailboxes()` call. */
+export const MAILBOX_LIST_LIMIT = 100;
+// The sidebar's order and the folders Mail lists live in `folderTree.ts`; re-exported for what already imports them from here.
+export { FOLDER_ORDER, MAIL_FOLDER_TYPES };
+const NO_TRACKER = { settle: () => undefined, revert: () => undefined };
+/** What the persistent app frame (`AppChrome`) offers to the Mail shell so that it doesn't open a second connection. `null` outside a frame. */
+export const MailConnectionContext = createContext(null);
+/**
+ * The user's mailboxes and their mail folders, plus the live connection that keeps them - and the badges, the list, the new-mail
+ * pop-ups - current. It is everything `MailShell` used to do on mount, gathered so that it can live in the persistent app frame instead: the
+ * push socket (the server allows ten per user), the safety-net poll, the folder counters and the pop-ups then belong to the signed-in session
+ * rather than to whichever page happens to be showing, and keep working in Calendar, Contacts, Tasks and Settings. `MailShell` reads the same
+ * state from `MailConnectionContext` when there is a frame, and runs this hook itself when there isn't (a page rendered outside the router).
+ */
+export function useMailConnection({ userUid, enabled, open }) {
+    const [status, setStatus] = useState("checking");
+    const [error, setError] = useState(null);
+    const [mailboxes, setMailboxes] = useState([]);
+    const [mailboxFolders, setMailboxFolders] = useState([]);
+    const [foldersLoading, setFoldersLoading] = useState(true);
+    useEffect(() => {
+        if (!userUid || !enabled) {
+            return;
+        }
+        listMailboxes({ limit: MAILBOX_LIST_LIMIT })
+            .then((result) => {
+            setMailboxes(result);
+            setStatus("ready");
+        })
+            .catch((err) => {
+            setError(err instanceof ApiRequestError ? err.message : "Could not load your mailboxes.");
+            setStatus("error");
+        });
+    }, [userUid, enabled]);
+    // Fans out one listFolders() call per accessible mailbox in parallel - each call catches its own failure into a MailboxFolders.error
+    // rather than letting Promise.all reject, so one mailbox's fetch failure renders that section's own inline Alert instead of blanking out
+    // every other mailbox's folder tree.
+    useEffect(() => {
+        if (mailboxes.length === 0) {
+            // Deliberately leaves foldersLoading as-is: this also runs once before listMailboxes() has resolved, and clearing it here would
+            // briefly render an empty sidebar the moment mailboxes arrive, before their folders do. A genuinely mailbox-less caller gets
+            // MailboxProvisioning.
+            setMailboxFolders([]);
+            return;
+        }
+        setFoldersLoading(true);
+        void Promise.all(mailboxes.map((mailbox) => listFolders(mailbox.uid)
+            .then((result) => ({ mailbox, folders: result.filter(isMailFolder) }))
+            .catch((err) => ({
+            mailbox,
+            folders: [],
+            error: err instanceof ApiRequestError ? err.message : "Could not load folders.",
+        }))))
+            .then(setMailboxFolders)
+            .finally(() => setFoldersLoading(false));
+    }, [mailboxes]);
+    /** Files a newly created folder under its own mailbox, leaving every other mailbox's list untouched - and ignoring a type the
+     * sidebar doesn't list at all, the same filter the fetch above applies. One already there (another client's create event can arrive
+     * after, or twice, or alongside our own) is not added again - see `upsertFolder()`. */
+    const onFolderCreated = useCallback((folder) => setMailboxFolders((prev) => upsertFolder(prev, folder)), []);
+    /** A folder was renamed or changed type elsewhere. */
+    const onFolderChanged = useCallback((change) => setMailboxFolders((prev) => upsertFolder(prev, change)), []);
+    const onFolderDeleted = useCallback((folderUid) => setMailboxFolders((prev) => removeFolder(prev, folderUid)), []);
+    /** A mailbox's folders as the server just listed them (every count refresh does): folders the tree lacks - one created lazily on the
+     * first send, or by another client whose event never arrived - are added. */
+    const onFoldersListed = useCallback((listed) => setMailboxFolders((prev) => reconcileFolders(prev, listed)), []);
+    const askedFolderUidsRef = useRef(new Set());
+    const foldersRef = useRef(mailboxFolders);
+    foldersRef.current = mailboxFolders;
+    // 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). A pop-up (and, in the background, a desktop notification) for each new message the connection
+    // announces.
+    const notifications = useNewMailNotifications({ mailboxes, mailboxFolders, open });
+    const { live, folderCounts } = useMailLiveUpdates({
+        userUid: enabled ? userUid : undefined,
+        mailboxes,
+        mailboxFolders,
+        onFolderCreated,
+        onFolderChanged,
+        onFolderDeleted,
+        onFoldersListed,
+        onMessageCreated: notifications.announce,
+        onSendEvent: handleSendEvent,
+    });
+    const noteFolderUids = useCallback((folderUids) => {
+        const known = knownFolderUids(foldersRef.current);
+        const asked = askedFolderUidsRef.current;
+        let unknown = false;
+        for (const uid of folderUids) {
+            if (uid && !known.has(uid) && !asked.has(uid)) {
+                asked.add(uid);
+                unknown = true;
+            }
+        }
+        if (unknown) {
+            // The counts' read-back lists every mailbox's folders and files the new ones; a burst is one refresh.
+            folderCounts.refresh();
+        }
+    }, [folderCounts.refresh]);
+    // "Connection lost" for more than a few seconds is a subtle pop-up that goes when it is back.
+    usePushConnectionNotice(!!userUid && enabled);
+    // The Outbox indicator: a message being sent from this tab counts at once (before the server has heard of it), settled - or taken back - when
+    // the server answers (see `sendJob.ts`); once it accepted one, the folders are read again, since the Outbox may not have existed yet.
+    const latestRef = useRef({ mailboxFolders, folderCounts });
+    latestRef.current = { mailboxFolders, folderCounts };
+    useEffect(() => {
+        if (!userUid || !enabled) {
+            return;
+        }
+        return registerOutboxCounter((mailboxUid) => {
+            const { mailboxFolders: known, folderCounts: counts } = latestRef.current;
+            const outbox = known.find((entry) => entry.mailbox.uid === mailboxUid)?.folders.find((folder) => folder.type === "outbox");
+            return outbox ? counts.track(null, { folderUid: outbox.uid, flags: { read: true } }) : NO_TRACKER;
+        }, (mailboxUid) => {
+            // The server accepted a message: the Outbox (and, on an older server, Sent Items) may just have been made. The counts' read-back lists
+            // every mailbox's folders and files the new ones (`onFoldersListed`); this reads the one mailbox at once.
+            latestRef.current.folderCounts.refresh(0);
+            listFolders(mailboxUid).then(onFoldersListed, () => undefined);
+        });
+    }, [userUid, enabled, onFoldersListed]);
+    const outbox = useOutboxStatus(mailboxFolders, folderCounts.counts, live.tick, !!userUid && enabled);
+    return { status, error, mailboxes, mailboxFolders, foldersLoading, onFolderCreated, noteFolderUids, live, folderCounts, notifications, outbox };
+}

package/dist/apps/shared/mail/useMailLiveUpdates.d.ts

@@ -1,5 +1,8 @@
-import { Folder, Mailbox } from "@rapidmx/react-shared/mail/mailApi.js";
+import { Folder, Mailbox, Message } from "@rapidmx/react-shared/mail/mailApi.js";
+import { SendEvent } from "@rapidmx/react-shared/mail/sendEvents.js";
 import type { MailboxFolders } from "../components/mail/layout/MailShell.js";
+import { FolderCounts } from "./folderCounts.js";
+import { FolderChange } from "./folderTree.js";
 /** How often the safety-net poll runs while the tab is visible. The push socket does the real work; this is for a network
  * that blocks or silently drops it, and for events published while it was reconnecting (Redis pub/sub is never replayed). */
 export declare const LIVE_POLL_INTERVAL_MS = 45000;
@@ -16,9 +19,10 @@ export interface LiveUpdates {
 export declare const NO_LIVE_UPDATES: LiveUpdates;
 /**
  * The channels to subscribe to, most important first (the push client keeps the first `PUSH_MAX_CHANNELS`): every
- * mailbox's Inbox - where mail lands - then each mailbox's other folders in the sidebar's own order, then the mailbox uids
- * themselves (which announce new folders). A folder is a channel of its own; subscribing to a mailbox does not deliver its
- * folders' events.
+ * mailbox's Inbox - where mail lands - then the mailbox uids themselves (which announce new, renamed and deleted folders, so
+ * they must outrank any folder's own mail), then each mailbox's other folders in the sidebar's own order - a folder that has
+ * just appeared is filed by its type like any other, so when the server's cap bites it is the last of them that go without live
+ * updates. A folder is a channel of its own; subscribing to a mailbox does not deliver its folders' events.
  */
 export declare function pushChannelsFor(mailboxFolders: MailboxFolders[], mailboxes: Mailbox[]): string[];
 export interface UseMailLiveUpdatesOptions {
@@ -28,21 +32,37 @@ export interface UseMailLiveUpdatesOptions {
     mailboxFolders: MailboxFolders[];
     /** Called with a folder another client (or this one) created, so the sidebar shows it. Called only for one not already known. */
     onFolderCreated: (folder: Folder) => void;
+    /** Called when a folder's name or type was changed elsewhere (a `Folder` update event that says so - one that only carries counts is not this). */
+    onFolderChanged?: (change: FolderChange) => void;
+    /** Called with the uid of a folder that was deleted elsewhere. */
+    onFolderDeleted?: (folderUid: string) => void;
+    /** Called with a mailbox's folders as the server just listed them - on every refresh (a message event, the poll, a reconnect, the tab
+     * coming back, a send) - so a folder the tree does not know is found whichever way it appeared. */
+    onFoldersListed?: (folders: Folder[]) => void;
+    /** Called with each new message the push connection announces (a `create` event) - once per message, never for a list
+     * refetch, the initial load or a reconnect (nothing published while the socket was down is replayed). The caller decides
+     * whether it is worth telling the user about. */
+    onMessageCreated?: (message: Message) => void;
+    /** Called with the outcome of a message sent in the background (`send-succeeded`, `send-failed`, `send-retrying`). Every one also
+     * refreshes what is on screen (the Outbox and Sent Items lists and counts change with it). */
+    onSendEvent?: (event: SendEvent) => void;
 }
 export interface MailLiveUpdates {
     live: LiveUpdates;
-    /** The latest unread count of each folder that has been refreshed since load, by folder uid - what the sidebar's badges show
-     * instead of the count the folder list was loaded with. */
-    unreadCounts: Record<string, number>;
+    /** The folder badges' numbers and how to change them - see `useFolderCounts()`. Kept in an overlay of their own, **not** in
+     * `mailboxFolders`, because the list effect reloads - and forgets the selection - whenever `mailboxFolders` changes. */
+    folderCounts: FolderCounts;
 }
 /**
  * Keeps Mail current without a page reload. One shared push connection per tab (`getPushClient()`) is subscribed to every
  * folder of every accessible mailbox; a message event for any of them, a reconnect, a poll of the safety net (every
  * `LIVE_POLL_INTERVAL_MS` while the tab is visible - and the only mechanism, silently, where the socket can't connect), the
  * tab coming back to the front or the browser coming back online, all end in the same debounced refresh: `live` is bumped
- * (the list on screen refetches its first page - see `mergeFirstPage()`) and every folder's unread count is re-read.
+ * (the list on screen refetches its first page - see `mergeFirstPage()`) and every folder's counts are re-read. A new message
+ * also bumps its folder's badge at once and is announced to `onMessageCreated`, and the server's `Folder` update events (the
+ * folder's real counts) are applied to the badges - see `useFolderCounts()`.
  *
  * Sign-out closes the socket for good: another tab's or this one's, heard on the same channel `AppShell` listens on.
  * Renders nothing and does nothing where there is no window (server-side rendering).
  */
-export declare function useMailLiveUpdates({ userUid, mailboxes, mailboxFolders, onFolderCreated }: UseMailLiveUpdatesOptions): MailLiveUpdates;
+export declare function useMailLiveUpdates({ userUid, mailboxes, mailboxFolders, onFolderCreated, onFolderChanged, onFolderDeleted, onFoldersListed, onMessageCreated, onSendEvent, }: UseMailLiveUpdatesOptions): MailLiveUpdates;

package/dist/apps/shared/mail/useMailLiveUpdates.js

@@ -3,9 +3,11 @@
 // SPDX-License-Identifier: MPL-2.0
 ///////////////////////////////////////////////////////////////////////////////
 import { useEffect, useMemo, useRef, useState } from "react";
-import { listFolders } from "@rapidmx/react-shared/mail/mailApi.js";
 import { getPushClient } from "@rapidmx/react-shared/mail/pushClient.js";
+import { parseSendEvent } from "@rapidmx/react-shared/mail/sendEvents.js";
 import { SIGN_OUT_CHANNEL } from "../search/localIndexRpcClient.js";
+import { useFolderCounts } from "./folderCounts.js";
+import { sortFolders } from "./folderTree.js";
 /** How often the safety-net poll runs while the tab is visible. The push socket does the real work; this is for a network
  * that blocks or silently drops it, and for events published while it was reconnecting (Redis pub/sub is never replayed). */
 export const LIVE_POLL_INTERVAL_MS = 45000;
@@ -18,19 +20,33 @@ const FOLDER_EVENT = /^Folder/;
 const MESSAGE_ACTIONS = new Set(["create", "update", "delete"]);
 /**
  * The channels to subscribe to, most important first (the push client keeps the first `PUSH_MAX_CHANNELS`): every
- * mailbox's Inbox - where mail lands - then each mailbox's other folders in the sidebar's own order, then the mailbox uids
- * themselves (which announce new folders). A folder is a channel of its own; subscribing to a mailbox does not deliver its
- * folders' events.
+ * mailbox's Inbox - where mail lands - then the mailbox uids themselves (which announce new, renamed and deleted folders, so
+ * they must outrank any folder's own mail), then each mailbox's other folders in the sidebar's own order - a folder that has
+ * just appeared is filed by its type like any other, so when the server's cap bites it is the last of them that go without live
+ * updates. A folder is a channel of its own; subscribing to a mailbox does not deliver its folders' events.
  */
 export function pushChannelsFor(mailboxFolders, mailboxes) {
     const inboxes = mailboxFolders.flatMap((entry) => entry.folders.filter((folder) => folder.type === "inbox"));
-    const others = mailboxFolders.flatMap((entry) => entry.folders.filter((folder) => folder.type !== "inbox"));
-    return [...new Set([...inboxes, ...others].map((folder) => folder.uid).concat(mailboxes.map((mailbox) => mailbox.uid)))];
+    const others = mailboxFolders.flatMap((entry) => sortFolders(entry.folders.filter((folder) => folder.type !== "inbox")));
+    return [...new Set([...inboxes.map((folder) => folder.uid), ...mailboxes.map((mailbox) => mailbox.uid), ...others.map((folder) => folder.uid)])];
 }
 function isFolder(value) {
     const folder = value;
     return !!folder && typeof folder.uid === "string" && typeof folder.mailboxUid === "string" && typeof folder.type === "string";
 }
+/** A `Folder` update event that says the folder's name or type changed (and names the folder): the counts-only ones the server publishes after every message change do not. */
+function isFolderChange(value) {
+    const change = value;
+    return !!change && typeof change.uid === "string" && (typeof change.name === "string" || typeof change.type === "string");
+}
+function isMessage(value) {
+    const message = value;
+    return (!!message &&
+        typeof message.uid === "string" &&
+        typeof message.folderUid === "string" &&
+        typeof message.flags === "object" &&
+        message.flags !== null);
+}
 /** The folder a message event is about: the message's own `folderUid`, else the channel it arrived on (when the server said). */
 function folderOfMessageEvent(event) {
     const data = event.data;
@@ -44,17 +60,20 @@ function folderOfMessageEvent(event) {
  * folder of every accessible mailbox; a message event for any of them, a reconnect, a poll of the safety net (every
  * `LIVE_POLL_INTERVAL_MS` while the tab is visible - and the only mechanism, silently, where the socket can't connect), the
  * tab coming back to the front or the browser coming back online, all end in the same debounced refresh: `live` is bumped
- * (the list on screen refetches its first page - see `mergeFirstPage()`) and every folder's unread count is re-read.
+ * (the list on screen refetches its first page - see `mergeFirstPage()`) and every folder's counts are re-read. A new message
+ * also bumps its folder's badge at once and is announced to `onMessageCreated`, and the server's `Folder` update events (the
+ * folder's real counts) are applied to the badges - see `useFolderCounts()`.
  *
  * Sign-out closes the socket for good: another tab's or this one's, heard on the same channel `AppShell` listens on.
  * Renders nothing and does nothing where there is no window (server-side rendering).
  */
-export function useMailLiveUpdates({ userUid, mailboxes, mailboxFolders, onFolderCreated }) {
+export function useMailLiveUpdates({ userUid, mailboxes, mailboxFolders, onFolderCreated, onFolderChanged, onFolderDeleted, onFoldersListed, onMessageCreated, onSendEvent, }) {
     const [live, setLive] = useState(NO_LIVE_UPDATES);
-    const [unreadCounts, setUnreadCounts] = useState({});
+    const folders = useMemo(() => mailboxFolders.flatMap((entry) => entry.folders), [mailboxFolders]);
+    const folderCounts = useFolderCounts(mailboxes, folders, onFoldersListed);
     // The latest inputs, for the long-lived listeners below.
-    const latestRef = useRef({ mailboxes, mailboxFolders, onFolderCreated });
-    latestRef.current = { mailboxes, mailboxFolders, onFolderCreated };
+    const latestRef = useRef({ mailboxes, mailboxFolders, onFolderCreated, onFolderChanged, onFolderDeleted, onMessageCreated, onSendEvent, folderCounts });
+    latestRef.current = { mailboxes, mailboxFolders, onFolderCreated, onFolderChanged, onFolderDeleted, onMessageCreated, onSendEvent, folderCounts };
     const channels = useMemo(() => pushChannelsFor(mailboxFolders, mailboxes), [mailboxFolders, mailboxes]);
     const channelKey = channels.join("|");
     const channelsRef = useRef(channels);
@@ -68,25 +87,7 @@ export function useMailLiveUpdates({ userUid, mailboxes, mailboxFolders, onFolde
         let timer;
         let pendingFolders = new Set();
         let pendingUnknown = false;
-        let countsRun = 0;
         let everOpen = false;
-        async function refreshCounts() {
-            const run = ++countsRun;
-            const results = await Promise.all(latestRef.current.mailboxes.map((mailbox) => listFolders(mailbox.uid).catch(() => undefined)));
-            if (stopped || run !== countsRun) {
-                return;
-            }
-            const fresh = {};
-            for (const folders of results) {
-                for (const folder of folders ?? []) {
-                    fresh[folder.uid] = folder.unreadCount;
-                }
-            }
-            setUnreadCounts((previous) => {
-                const changed = Object.entries(fresh).some(([uid, count]) => previous[uid] !== count);
-                return changed ? { ...previous, ...fresh } : previous;
-            });
-        }
         // Never runs once `stopped`: whatever sets it clears the timer first.
         function flush() {
             timer = undefined;
@@ -94,7 +95,7 @@ export function useMailLiveUpdates({ userUid, mailboxes, mailboxFolders, onFolde
             pendingFolders = new Set();
             pendingUnknown = false;
             setLive((previous) => ({ tick: previous.tick + 1, folderUids }));
-            void refreshCounts();
+            latestRef.current.folderCounts.refresh(0);
         }
         /** Asks for a refresh: of the given folders, or (no argument) of whatever may have changed. */
         function schedule(folderUid) {
@@ -110,14 +111,41 @@ export function useMailLiveUpdates({ userUid, mailboxes, mailboxFolders, onFolde
             timer ?? (timer = setTimeout(flush, LIVE_EVENT_DEBOUNCE_MS));
         }
         const offEvent = client.onEvent((event) => {
-            if (MESSAGE_EVENT.test(event.type) && MESSAGE_ACTIONS.has(event.action ?? "")) {
+            const sendEvent = parseSendEvent(event);
+            if (sendEvent) {
+                // A queued message was relayed (or failed to be): it left Outbox for Sent Items, or stayed there failed - every list and count may have changed.
+                latestRef.current.onSendEvent?.(sendEvent);
+                schedule();
+            }
+            else if (MESSAGE_EVENT.test(event.type) && MESSAGE_ACTIONS.has(event.action ?? "")) {
+                if (event.action === "create" && isMessage(event.data)) {
+                    // Once per message, whatever else the event triggers: the badge first, then whoever announces it.
+                    if (latestRef.current.folderCounts.noteCreated(event.data)) {
+                        latestRef.current.onMessageCreated?.(event.data);
+                    }
+                }
                 schedule(folderOfMessageEvent(event));
             }
             else if (FOLDER_EVENT.test(event.type) && event.action === "create" && isFolder(event.data)) {
+                // A folder made by the server (on first use, or by another client) or by this one: filed in the sidebar and subscribed to at once (the
+                // channel list follows the tree), and its real counts read - all without a reload.
                 const folder = event.data;
                 const known = latestRef.current.mailboxFolders.some((entry) => entry.folders.some((f) => f.uid === folder.uid));
                 if (!known) {
                     latestRef.current.onFolderCreated(folder);
+                    latestRef.current.folderCounts.refresh(0);
+                }
+            }
+            else if (FOLDER_EVENT.test(event.type) && event.action === "update") {
+                if (isFolderChange(event.data)) {
+                    latestRef.current.onFolderChanged?.(event.data);
+                }
+                latestRef.current.folderCounts.applyFolderEvent(event.data);
+            }
+            else if (FOLDER_EVENT.test(event.type) && event.action === "delete") {
+                const uid = event.data?.uid;
+                if (typeof uid === "string") {
+                    latestRef.current.onFolderDeleted?.(uid);
                 }
             }
         });
@@ -176,5 +204,5 @@ export function useMailLiveUpdates({ userUid, mailboxes, mailboxFolders, onFolde
             getPushClient().setChannels(channels);
         }
     }, [userUid, channelKey]);
-    return { live, unreadCounts };
+    return { live, folderCounts };
 }

package/dist/apps/shared/mail/useMarkMessageRead.d.ts

@@ -0,0 +1,12 @@
+import type { Message } from "@rapidmx/react-shared/mail/mailApi.js";
+/**
+ * Marks a message read when it is opened in a reading pane, through `setReadState()`: the row and the folder badge change at
+ * once. `onPatched` is handed each copy of the message as it changes (the optimistic one, then the server's, or the original
+ * again if the server refused).
+ *
+ * Replaces `@rapidmx/react-shared`'s `useMarkMessageRead`, which waits for the server before telling anyone and drops that
+ * answer if the message changes meanwhile - which the optimistic copy itself does. A message is asked for once each time it is
+ * opened: one the reader then marks unread stays unread while it is open, and one whose request failed is not retried in a loop
+ * (its own revert changes it again), only when it is opened again.
+ */
+export declare function useMarkMessageRead(message: Message | null, onPatched: (updated: Message, previous?: Message) => void): void;

package/dist/apps/shared/mail/useMarkMessageRead.js

@@ -0,0 +1,44 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { useEffect, useRef } from "react";
+import { useMailShell } from "../components/mail/layout/MailShell.js";
+import { setReadState } from "./messageReadState.js";
+/**
+ * Marks a message read when it is opened in a reading pane, through `setReadState()`: the row and the folder badge change at
+ * once. `onPatched` is handed each copy of the message as it changes (the optimistic one, then the server's, or the original
+ * again if the server refused).
+ *
+ * Replaces `@rapidmx/react-shared`'s `useMarkMessageRead`, which waits for the server before telling anyone and drops that
+ * answer if the message changes meanwhile - which the optimistic copy itself does. A message is asked for once each time it is
+ * opened: one the reader then marks unread stays unread while it is open, and one whose request failed is not retried in a loop
+ * (its own revert changes it again), only when it is opened again.
+ */
+export function useMarkMessageRead(message, onPatched) {
+    const { trackMessageChange } = useMailShell();
+    const openUidRef = useRef(undefined);
+    const requestedRef = useRef(new Set());
+    const latestRef = useRef({ onPatched, trackMessageChange });
+    latestRef.current = { onPatched, trackMessageChange };
+    useEffect(() => {
+        if (message?.uid !== openUidRef.current) {
+            // Another message (or none) is open now: whatever was asked about the last one is over.
+            openUidRef.current = message?.uid;
+            requestedRef.current.clear();
+        }
+        if (!message || requestedRef.current.has(message.uid)) {
+            return;
+        }
+        // Every opening is asked about once - a message that is already read included, so that marking it unread while it is open (the
+        // keyboard's Ctrl+U) doesn't make this run again and read it straight back.
+        requestedRef.current.add(message.uid);
+        if (message.flags.read === true) {
+            return;
+        }
+        void setReadState(message, true, {
+            patch: (updated, previous) => latestRef.current.onPatched(updated, previous),
+            track: (previous, next) => latestRef.current.trackMessageChange(previous, next),
+        });
+    }, [message]);
+}

package/dist/apps/shared/mail/useNewMailNotifications.d.ts

@@ -0,0 +1,35 @@
+import type { Mailbox, Message } from "@rapidmx/react-shared/mail/mailApi.js";
+import type { MailboxFolders } from "../components/mail/layout/MailShell.js";
+/** How long a new-mail pop-up stays before it goes by itself (while it is neither hovered nor focused, and the tab is in view). */
+export declare const TOAST_DURATION_MS = 8000;
+/** At most this many desktop notifications in `DESKTOP_BURST_WINDOW_MS`: a flood of mail is a few notifications, not a hundred. */
+export declare const DESKTOP_BURST_LIMIT = 5;
+export declare const DESKTOP_BURST_WINDOW_MS = 30000;
+export interface NewMailNotifications {
+    /** Whether the next pop-up should also offer to turn on desktop notifications: the browser can, has not been asked,
+     * and the user has not said "Not now". */
+    offerDesktop: boolean;
+    /** The offer's "Turn on desktop notifications": asks the browser. Must be called from a click. */
+    enableDesktop(): Promise<void>;
+    /** The offer's "Not now": remembered, so it is not made again. */
+    declineDesktop(): void;
+    /** Announces a message that just arrived - if it is worth it (see `shouldAnnounce()`) and pop-ups are on. Stable. */
+    announce(message: Message): void;
+}
+export interface UseNewMailNotificationsOptions {
+    mailboxes: Mailbox[];
+    mailboxFolders: MailboxFolders[];
+    /** Opens a message from a desktop notification's click. Defaults to a plain navigation. */
+    open?: (href: string) => void;
+}
+/**
+ * New-mail announcements: an in-app pop-up for each message that arrives (a `mail` notification - see `notifications/store.ts`, which owns the
+ * stack, its limit of three and the clock), and - while the tab
+ * is in the background and the user has allowed it - a desktop notification with the same content, one per message however
+ * many events name it. `announce()` is what `useMailLiveUpdates()`'s `onMessageCreated` calls; nothing else feeds it, so a
+ * page load, a list refetch and a reconnect never announce anything.
+ *
+ * Nothing is ever asked of the browser on load: permission is requested only by `enableDesktop()`, from the offer in the
+ * first pop-up, or from Settings. What the user answered is remembered in `localStorage` (see `newMailNotifications.ts`).
+ */
+export declare function useNewMailNotifications({ mailboxes, mailboxFolders, open }: UseNewMailNotificationsOptions): NewMailNotifications;

package/dist/apps/shared/mail/useNewMailNotifications.js

@@ -0,0 +1,130 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { desktopPermission, getDesktopOfferDismissed, getNewMailPopupsEnabled, noticeFor, noticeSender, ownAddressesOf, requestDesktopPermission, setDesktopOfferDismissed, shouldAnnounce, } from "./newMailNotifications.js";
+import { getNotificationsSnapshot, notify } from "../notifications/store.js";
+/** How long a new-mail pop-up stays before it goes by itself (while it is neither hovered nor focused, and the tab is in view). */
+export const TOAST_DURATION_MS = 8000;
+/** At most this many desktop notifications in `DESKTOP_BURST_WINDOW_MS`: a flood of mail is a few notifications, not a hundred. */
+export const DESKTOP_BURST_LIMIT = 5;
+export const DESKTOP_BURST_WINDOW_MS = 30000;
+/** How many announced message uids are remembered, so an event delivered twice is announced once. */
+const ANNOUNCED_LIMIT = 500;
+/** Whether the user is not looking at this tab: it is hidden, or another window has the focus. */
+function tabIsInBackground() {
+    return document.visibilityState === "hidden" || !document.hasFocus();
+}
+function defaultOpen(href) {
+    window.location.href = href;
+}
+/**
+ * New-mail announcements: an in-app pop-up for each message that arrives (a `mail` notification - see `notifications/store.ts`, which owns the
+ * stack, its limit of three and the clock), and - while the tab
+ * is in the background and the user has allowed it - a desktop notification with the same content, one per message however
+ * many events name it. `announce()` is what `useMailLiveUpdates()`'s `onMessageCreated` calls; nothing else feeds it, so a
+ * page load, a list refetch and a reconnect never announce anything.
+ *
+ * Nothing is ever asked of the browser on load: permission is requested only by `enableDesktop()`, from the offer in the
+ * first pop-up, or from Settings. What the user answered is remembered in `localStorage` (see `newMailNotifications.ts`).
+ */
+export function useNewMailNotifications({ mailboxes, mailboxFolders, open = defaultOpen }) {
+    const [permission, setPermission] = useState("unsupported");
+    const [offerDismissed, setOfferDismissed] = useState(true);
+    const folders = useMemo(() => mailboxFolders.flatMap((entry) => entry.folders), [mailboxFolders]);
+    const ownAddresses = useMemo(() => ownAddressesOf(mailboxes), [mailboxes]);
+    const latestRef = useRef({ folders, ownAddresses, open });
+    latestRef.current = { folders, ownAddresses, open };
+    const announcedRef = useRef(new Set());
+    const desktopShownRef = useRef([]);
+    // The browser's own state is only read on the client, after hydration, so the server and first client render agree.
+    useEffect(() => {
+        setPermission(desktopPermission());
+        setOfferDismissed(getDesktopOfferDismissed());
+    }, []);
+    const showDesktop = useCallback((notice) => {
+        const now = Date.now();
+        desktopShownRef.current = desktopShownRef.current.filter((at) => now - at < DESKTOP_BURST_WINDOW_MS);
+        if (desktopShownRef.current.length >= DESKTOP_BURST_LIMIT) {
+            return;
+        }
+        try {
+            const notification = new Notification(noticeSender(notice), {
+                body: [notice.subject, notice.preview].filter(Boolean).join("\n"),
+                // One per message: a duplicate (another tab of this app, a re-delivered event) replaces instead of stacking.
+                tag: notice.uid,
+            });
+            desktopShownRef.current.push(now);
+            notification.onclick = () => {
+                window.focus();
+                notification.close();
+                latestRef.current.open(notice.href);
+            };
+        }
+        catch {
+            // Some browsers refuse `new Notification()` outright (a mobile one wanting a service worker): the pop-up is enough.
+        }
+    }, []);
+    const enableDesktop = useCallback(async () => {
+        const answer = await requestDesktopPermission();
+        setPermission(answer);
+        // Answered either way, so the offer goes: on granted it has done its job, on denied it can't be made again.
+        setDesktopOfferDismissed(true);
+        setOfferDismissed(true);
+    }, []);
+    const declineDesktop = useCallback(() => {
+        setDesktopOfferDismissed(true);
+        setOfferDismissed(true);
+    }, []);
+    // The offer's current state and answers, for the stable `announce` below.
+    const offerDesktop = permission === "default" && !offerDismissed;
+    const offerRef = useRef({ offered: offerDesktop, enable: enableDesktop, decline: declineDesktop });
+    offerRef.current = { offered: offerDesktop, enable: enableDesktop, decline: declineDesktop };
+    const announce = useCallback((message) => {
+        if (!getNewMailPopupsEnabled() || announcedRef.current.has(message.uid)) {
+            return;
+        }
+        const { folders: knownFolders, ownAddresses: own } = latestRef.current;
+        if (!shouldAnnounce(message, { folders: knownFolders, ownAddresses: own })) {
+            return;
+        }
+        announcedRef.current.add(message.uid);
+        if (announcedRef.current.size > ANNOUNCED_LIMIT) {
+            announcedRef.current.delete(announcedRef.current.values().next().value);
+        }
+        const notice = noticeFor(message);
+        const offer = offerRef.current;
+        notify({
+            id: `mail:${notice.uid}`,
+            kind: "mail",
+            title: notice.senderName || notice.senderAddress,
+            subtitle: notice.senderName ? `<${notice.senderAddress}>` : undefined,
+            message: notice.subject,
+            preview: notice.preview || undefined,
+            href: notice.href,
+            timeoutMs: TOAST_DURATION_MS,
+            // Actions make a notification sticky; a new-mail pop-up with the offer still goes by itself.
+            sticky: false,
+            // The offer is made once at a time: on a pop-up only while none of the pop-ups still showing carries it.
+            ...(offer.offered && !getNotificationsSnapshot().visible.some((item) => item.kind === "mail" && item.actions.length > 0)
+                ? {
+                    hint: "Get a desktop notification when mail arrives while this tab is in the background.",
+                    actions: [
+                        { label: "Turn on desktop notifications", onClick: () => void offer.enable() },
+                        { label: "Not now", onClick: offer.decline },
+                    ],
+                }
+                : {}),
+        });
+        if (desktopPermission() === "granted" && tabIsInBackground()) {
+            showDesktop(notice);
+        }
+    }, [showDesktop]);
+    return {
+        offerDesktop,
+        enableDesktop,
+        declineDesktop,
+        announce,
+    };
+}

package/dist/apps/shared/mail/useUnreadTitle.d.ts

@@ -0,0 +1,18 @@
+/** `title` with `count` unread in front - `(3) Acme: Mail` - or as it is when there are none. */
+export declare function titleWithUnread(title: string, count: number): string;
+export interface UseUnreadTitleOptions {
+    /** Does nothing while false - for the one of two owners that isn't. Default true. */
+    enabled?: boolean;
+    /** Changes whenever something else has rewritten the title (the app frame sets it on every page change), so the count is put in front of
+     * the new one. */
+    resetKey?: unknown;
+}
+/**
+ * Keeps the browser tab's title in step with the unread count, as Outlook on the web does - `(3) Acme: Mail` - so mail that
+ * arrives while the tab is in the background can be seen from the tab strip. The count is put in front of whatever the title is
+ * (the page sets its own, from the branding) and taken off again when it drops to zero or the component goes away.
+ *
+ * Order matters when the same component also sets the title: declare this hook after the effect that does, so that on a change of `resetKey`
+ * the count is taken off the old title, the new title is written, and the count goes back in front of it.
+ */
+export declare function useUnreadTitle(count: number, { enabled, resetKey }?: UseUnreadTitleOptions): void;