@rapidmx/web-client 0.9.0 → 0.10.0

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

@@ -0,0 +1,138 @@
+import { formatMailAddress, splitMailAddress } from "@rapidmx/react-shared/mail/mailAddress.js";
+/**
+ * What decides whether a new message is announced, what the announcement says, and the two settings behind it (both per
+ * browser, in `localStorage`): whether new-mail pop-ups are on at all, and what the user told the "turn on desktop
+ * notifications" offer.
+ *
+ * The announcement is built only from what the push event carries - the whole `Message`, including `bodyPreview` - and only
+ * ever as text: React escapes it on screen and the Notifications API takes plain strings, so nothing here is HTML.
+ */
+/** `localStorage` key of the pop-ups switch. Absent means on; `"off"` means the user turned them off. */
+export const NEW_MAIL_POPUPS_KEY = "rapidmx-new-mail-popups";
+/** `localStorage` key of the answer to the desktop-notifications offer: `"later"` (not now) or `"asked"` (they were asked). */
+export const DESKTOP_OFFER_KEY = "rapidmx-desktop-notifications-offer";
+/** How much of the body an announcement quotes. */
+export const PREVIEW_MAX_LENGTH = 140;
+/** A message received longer ago than this is not "new": mail imported or migrated in bulk arrives as `create` events too. */
+export const MAX_NEW_AGE_MS = 6 * 60 * 60 * 1000;
+/** The subject the server stores for an encrypted message (the real one is inside the ciphertext). */
+const ENCRYPTED_SUBJECT_PLACEHOLDER = "[...]";
+function readStorage(key) {
+    try {
+        return localStorage.getItem(key);
+    }
+    catch {
+        return null;
+    }
+}
+function writeStorage(key, value) {
+    try {
+        if (value === null) {
+            localStorage.removeItem(key);
+        }
+        else {
+            localStorage.setItem(key, value);
+        }
+    }
+    catch {
+        // Storage blocked or full: the choice lasts until the page is reloaded, no longer.
+    }
+}
+/** Whether new-mail pop-ups are on (the default). */
+export function getNewMailPopupsEnabled() {
+    return readStorage(NEW_MAIL_POPUPS_KEY) !== "off";
+}
+export function setNewMailPopupsEnabled(enabled) {
+    writeStorage(NEW_MAIL_POPUPS_KEY, enabled ? null : "off");
+}
+/** Whether the "turn on desktop notifications" offer has been put away with "Not now" (or answered). */
+export function getDesktopOfferDismissed() {
+    return readStorage(DESKTOP_OFFER_KEY) !== null;
+}
+export function setDesktopOfferDismissed(dismissed) {
+    writeStorage(DESKTOP_OFFER_KEY, dismissed ? "later" : null);
+}
+export function desktopPermission() {
+    return typeof Notification === "undefined" ? "unsupported" : Notification.permission;
+}
+/** Asks the browser for permission - call it from a click. Resolves the answer; never rejects. */
+export async function requestDesktopPermission() {
+    if (typeof Notification === "undefined") {
+        return "unsupported";
+    }
+    try {
+        return await Notification.requestPermission();
+    }
+    catch {
+        return desktopPermission();
+    }
+}
+/** Control characters, and the invisible or bidirectional-override characters that can make text read as something else, as code point ranges. */
+const UNWANTED_RANGES = [
+    [0x0000, 0x001f],
+    [0x007f, 0x009f],
+    [0x200b, 0x200f],
+    [0x2028, 0x202e],
+    [0x2060, 0x2064],
+    [0x2066, 0x2069],
+    [0xfeff, 0xfeff],
+];
+const hex = (code) => "\\u" + code.toString(16).padStart(4, "0");
+const UNWANTED = new RegExp("[" + UNWANTED_RANGES.map(([from, to]) => hex(from) + "-" + hex(to)).join("") + "]+", "g");
+/** `text` with those characters replaced by spaces, whitespace folded, and cut to `max` characters (with an ellipsis). */
+export function cleanPreview(text, max = PREVIEW_MAX_LENGTH) {
+    const cleaned = text.replace(UNWANTED, " ").replace(/\s+/g, " ").trim();
+    return cleaned.length > max ? cleaned.slice(0, max - 1).trimEnd() + String.fromCharCode(0x2026) : cleaned;
+}
+/** The text of an announcement of `message`. */
+export function noticeFor(message) {
+    const { name, address } = splitMailAddress(message.from);
+    const encrypted = message.encrypted === true;
+    const rawSubject = cleanPreview(message.subject ?? "", 200);
+    const subject = !rawSubject || rawSubject === ENCRYPTED_SUBJECT_PLACEHOLDER ? (encrypted ? "(encrypted subject)" : "(no subject)") : rawSubject;
+    return {
+        uid: message.uid,
+        mailboxUid: message.mailboxUid,
+        folderUid: message.folderUid,
+        // `splitMailAddress()` has already taken control and bidirectional-override characters out of both.
+        senderName: name ?? "",
+        senderAddress: address,
+        subject,
+        preview: encrypted ? "Encrypted message" : cleanPreview(message.bodyPreview ?? ""),
+        href: `/messages/${encodeURIComponent(message.uid)}`,
+    };
+}
+/** Every address that is this user's own, lowercased - a message from one of them is not new mail worth announcing. */
+export function ownAddressesOf(mailboxes) {
+    const own = new Set();
+    for (const mailbox of mailboxes) {
+        for (const address of [mailbox.primarySmtpAddress, ...(mailbox.aliasAddresses ?? [])]) {
+            if (address) {
+                own.add(address.trim().toLowerCase());
+            }
+        }
+    }
+    return own;
+}
+/**
+ * Whether the arrival of `message` is worth announcing: unread mail in an Inbox (not Drafts, Sent Items, Outbox, Deleted Items,
+ * Junk Email or quarantine, which are other folders), that Focused Inbox did not put under Other, that its own user did not
+ * send, and that is not old (a bulk import).
+ */
+export function shouldAnnounce(message, context) {
+    if (context.folders.find((folder) => folder.uid === message.folderUid)?.type !== "inbox") {
+        return false;
+    }
+    if (message.flags.read === true || message.inferenceClassification === "other") {
+        return false;
+    }
+    if (context.ownAddresses.has((message.from?.address ?? "").trim().toLowerCase())) {
+        return false;
+    }
+    const received = Date.parse(message.receivedDate);
+    return Number.isNaN(received) || (context.now ?? Date.now()) - received < MAX_NEW_AGE_MS;
+}
+/** `Name <address>`, or the address alone - the desktop notification's title. */
+export function noticeSender(notice) {
+    return formatMailAddress({ address: notice.senderAddress, displayName: notice.senderName || undefined });
+}

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

@@ -0,0 +1,55 @@
+import { Folder, Mailbox } from "@rapidmx/react-shared/mail/mailApi.js";
+import type { MailboxFolders } from "../components/mail/layout/MailShell.js";
+import { LiveUpdates } from "./useMailLiveUpdates.js";
+import type { FolderCounts } from "./folderCounts.js";
+import { NewMailNotifications } from "./useNewMailNotifications.js";
+/** Page size of the one `listMailboxes()` call. */
+export declare const MAILBOX_LIST_LIMIT = 100;
+/** Well-known folders sort first in the sidebar, in Gmail/Outlook's conventional order; anything else (incl. `user`) sorts after, alphabetically. */
+export declare const FOLDER_ORDER: string[];
+/**
+ * A mailbox's `calendar`/`contacts`/`tasks`/`notes` folders back their own dedicated apps (see `CalendarShell`/`ContactsShell`/`TasksShell`), not
+ * Mail - `listFolders()` returns every well-known folder for the mailbox regardless of which app owns it, so Mail's own folder tree filters down
+ * to just the mail ones itself, or those other apps' folders leak into its sidebar.
+ */
+export declare const MAIL_FOLDER_TYPES: Set<string>;
+export type MailConnectionStatus = "checking" | "error" | "ready";
+/** Everything the mail apps share about the user's mailboxes, and the one live connection that keeps it current. */
+export interface MailConnection {
+    /** Where the one `listMailboxes()` call is. */
+    status: MailConnectionStatus;
+    /** Why `status` is `"error"`. */
+    error: string | null;
+    mailboxes: Mailbox[];
+    /** Every accessible mailbox's own mail folders, one entry per mailbox - see `MailboxFolders`. */
+    mailboxFolders: MailboxFolders[];
+    /** Their folder lists are still being fetched. */
+    foldersLoading: boolean;
+    /** Files a folder that was just created (by this client or another) under its mailbox, so the sidebar and every folder picker show it. */
+    onFolderCreated: (folder: Folder) => void;
+    /** Bumped whenever new mail may have arrived - see `useMailLiveUpdates()`. */
+    live: LiveUpdates;
+    /** The folder badges' numbers and how to change them. */
+    folderCounts: FolderCounts;
+    /** The new-mail pop-ups and desktop notifications, and what feeds them. */
+    notifications: NewMailNotifications;
+}
+/** 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 declare const MailConnectionContext: import("react").Context<MailConnection | null>;
+export interface UseMailConnectionOptions {
+    /** Nothing is fetched, and no socket opened, without a signed-in user. */
+    userUid?: string;
+    /** Runs only while true. The frame turns it on; a Mail shell rendered outside a frame turns it on for itself; and the one that isn't
+     * the owner leaves it off - so exactly one connection exists, whichever of them the page is rendered by. */
+    enabled: boolean;
+    /** Opens a message from a desktop notification's click (the router's `useNavigate()`); defaults to a plain navigation. */
+    open?: (href: string) => void;
+}
+/**
+ * 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 declare function useMailConnection({ userUid, enabled, open }: UseMailConnectionOptions): MailConnection;

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

@@ -0,0 +1,96 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { createContext, useCallback, useEffect, useState } from "react";
+import { ApiRequestError } from "@rapidmx/react-shared/util/api.js";
+import { listFolders, listMailboxes } from "@rapidmx/react-shared/mail/mailApi.js";
+import { useMailLiveUpdates } from "./useMailLiveUpdates.js";
+import { useNewMailNotifications } from "./useNewMailNotifications.js";
+/** Page size of the one `listMailboxes()` call. */
+export const MAILBOX_LIST_LIMIT = 100;
+/** Well-known folders sort first in the sidebar, in Gmail/Outlook's conventional order; anything else (incl. `user`) sorts after, alphabetically. */
+export const FOLDER_ORDER = ["inbox", "drafts", "outbox", "sent_items", "junk", "archive", "deleted_items"];
+/**
+ * A mailbox's `calendar`/`contacts`/`tasks`/`notes` folders back their own dedicated apps (see `CalendarShell`/`ContactsShell`/`TasksShell`), not
+ * Mail - `listFolders()` returns every well-known folder for the mailbox regardless of which app owns it, so Mail's own folder tree filters down
+ * to just the mail ones itself, or those other apps' folders leak into its sidebar.
+ */
+export const MAIL_FOLDER_TYPES = new Set([...FOLDER_ORDER, "user"]);
+/** 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((f) => MAIL_FOLDER_TYPES.has(f.type)) }))
+            .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. */
+    const onFolderCreated = useCallback((folder) => {
+        if (!MAIL_FOLDER_TYPES.has(folder.type)) {
+            return;
+        }
+        setMailboxFolders((prev) => prev.map((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). 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,
+        onMessageCreated: notifications.announce,
+    });
+    return { status, error, mailboxes, mailboxFolders, foldersLoading, onFolderCreated, live, folderCounts, notifications };
+}

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

@@ -1,5 +1,6 @@
-import { Folder, Mailbox } from "@rapidmx/react-shared/mail/mailApi.js";
+import { Folder, Mailbox, Message } from "@rapidmx/react-shared/mail/mailApi.js";
 import type { MailboxFolders } from "../components/mail/layout/MailShell.js";
+import { FolderCounts } from "./folderCounts.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;
@@ -28,21 +29,27 @@ 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 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;
 }
 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, onMessageCreated }: UseMailLiveUpdatesOptions): MailLiveUpdates;

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

@@ -3,9 +3,9 @@
 // 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 { SIGN_OUT_CHANNEL } from "../search/localIndexRpcClient.js";
+import { useFolderCounts } from "./folderCounts.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;
@@ -31,6 +31,14 @@ function isFolder(value) {
     const folder = value;
     return !!folder && typeof folder.uid === "string" && typeof folder.mailboxUid === "string" && typeof folder.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 +52,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, onMessageCreated }) {
     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);
     // 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, onMessageCreated, folderCounts });
+    latestRef.current = { mailboxes, mailboxFolders, onFolderCreated, onMessageCreated, folderCounts };
     const channels = useMemo(() => pushChannelsFor(mailboxFolders, mailboxes), [mailboxFolders, mailboxes]);
     const channelKey = channels.join("|");
     const channelsRef = useRef(channels);
@@ -68,25 +79,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 +87,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) {
@@ -111,6 +104,12 @@ export function useMailLiveUpdates({ userUid, mailboxes, mailboxFolders, onFolde
         }
         const offEvent = client.onEvent((event) => {
             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)) {
@@ -120,6 +119,9 @@ export function useMailLiveUpdates({ userUid, mailboxes, mailboxFolders, onFolde
                     latestRef.current.onFolderCreated(folder);
                 }
             }
+            else if (FOLDER_EVENT.test(event.type) && event.action === "update") {
+                latestRef.current.folderCounts.applyFolderEvent(event.data);
+            }
         });
         // Anything published while the socket was down is gone for good, so every reconnect is followed by a refresh.
         const offStatus = client.onStatus((status) => {
@@ -176,5 +178,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,41 @@
+import type { Mailbox, Message } from "@rapidmx/react-shared/mail/mailApi.js";
+import type { MailboxFolders } from "../components/mail/layout/MailShell.js";
+import { NewMailNotice } from "./newMailNotifications.js";
+/** The most pop-ups on screen at once; a new one pushes the oldest off. */
+export declare const MAX_TOASTS = 3;
+/** How long a 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 {
+    /** The pop-ups on screen, oldest first. */
+    toasts: NewMailNotice[];
+    /** Takes one off the screen. */
+    dismiss(uid: string): void;
+    /** Whether the first 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 (`MAX_TOASTS` at most on screen), 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;