@rapidmx/web-client 0.10.0 → 0.11.0

package/apps/shared/mail/outbox/useOutboxStatus.ts

@@ -0,0 +1,61 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { useEffect, useMemo, useState } from "react";
+import { listMessages } from "@rapidmx/react-shared/mail/mailApi.js";
+import type { MailboxFolders } from "../../components/mail/layout/MailShell.js";
+import { FolderCount, countOfFolder } from "../folderCounts.js";
+import { OutboxFolderStatus, summarizeOutbox } from "./outboxState.js";
+
+/** The most Outbox messages read to say what state they are in; beyond this the pill still shows the folder's own total. */
+export const OUTBOX_STATUS_LIMIT = 50;
+
+/**
+ * What the messages in each Outbox folder are doing (sending / retrying / failed / scheduled), by folder uid - the second line of the Outbox
+ * indicator, next to the folder's own count. A folder only costs a request while it holds something (its count is above zero) and is read again
+ * whenever that count or the live updates change, so an empty Outbox - almost always - is free. A failed read keeps what was known.
+ */
+export function useOutboxStatus(mailboxFolders: MailboxFolders[], counts: Record<string, FolderCount>, liveTick: number, enabled: boolean): Record<string, OutboxFolderStatus> {
+    const [statuses, setStatuses] = useState<Record<string, OutboxFolderStatus>>({});
+    const outboxes = useMemo(
+        () =>
+            mailboxFolders.flatMap((entry) => entry.folders.filter((folder) => folder.type === "outbox")).map((folder) => ({ uid: folder.uid, total: countOfFolder(folder, counts).total })),
+        [mailboxFolders, counts],
+    );
+    const key = outboxes.map((outbox) => `${outbox.uid}:${outbox.total}`).join("|");
+
+    useEffect(() => {
+        if (!enabled) {
+            return;
+        }
+        const occupied = outboxes.filter((outbox) => outbox.total > 0);
+        setStatuses((previous) => {
+            const emptied = Object.keys(previous).filter((uid) => !occupied.some((outbox) => outbox.uid === uid));
+            if (emptied.length === 0) {
+                return previous;
+            }
+            const next = { ...previous };
+            for (const uid of emptied) {
+                delete next[uid];
+            }
+            return next;
+        });
+        let cancelled = false;
+        for (const outbox of occupied) {
+            listMessages(outbox.uid, { limit: OUTBOX_STATUS_LIMIT }).then(
+                (messages) => {
+                    if (!cancelled) {
+                        setStatuses((previous) => ({ ...previous, [outbox.uid]: summarizeOutbox(messages) }));
+                    }
+                },
+                () => undefined,
+            );
+        }
+        return () => {
+            cancelled = true;
+        };
+    }, [enabled, key, liveTick]);
+
+    return statuses;
+}

package/apps/shared/mail/useMailConnection.ts

@@ -2,26 +2,25 @@
 // Copyright (C) 2026 Jean-Philippe Steinmetz
 // SPDX-License-Identifier: MPL-2.0
 ///////////////////////////////////////////////////////////////////////////////
-import { createContext, useCallback, useEffect, useState } from "react";
+import { createContext, useCallback, useEffect, useRef, useState } from "react";
 import { ApiRequestError } from "@rapidmx/react-shared/util/api.js";
-import { Folder, Mailbox, listFolders, listMailboxes } from "@rapidmx/react-shared/mail/mailApi.js";
+import { Folder, Mailbox, Message, listFolders, listMailboxes } from "@rapidmx/react-shared/mail/mailApi.js";
+import { FOLDER_ORDER, FolderChange, MAIL_FOLDER_TYPES, isMailFolder, knownFolderUids, reconcileFolders, removeFolder, upsertFolder } from "./folderTree.js";
 import type { MailboxFolders } from "../components/mail/layout/MailShell.js";
 import { LiveUpdates, useMailLiveUpdates } from "./useMailLiveUpdates.js";
-import type { FolderCounts } from "./folderCounts.js";
+import type { CountTracker, FolderCounts } from "./folderCounts.js";
 import { NewMailNotifications, useNewMailNotifications } from "./useNewMailNotifications.js";
+import { usePushConnectionNotice } from "../notifications/pushStatus.js";
+import { registerOutboxCounter } from "./outbox/sendJob.js";
+import { handleSendEvent } from "./outbox/sendOutcomes.js";
+import { OutboxFolderStatus } from "./outbox/outboxState.js";
+import { useOutboxStatus } from "./outbox/useOutboxStatus.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"]);
+// 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 };
 
 export type MailConnectionStatus = "checking" | "error" | "ready";
 
@@ -38,14 +37,22 @@ export interface MailConnection {
     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;
+    /** Says which folders some message the page has met lives in (a list's rows, a conversation's folders): one the sidebar does not know is asked for
+     * - its mailbox's folders are listed again, once, debounced - and files it. Each unknown uid is asked about once, so a folder Mail never lists
+     * (another app's) cannot make the page ask again and again. */
+    noteFolderUids: (folderUids: Iterable<string>) => 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 messages in each Outbox folder are doing, by folder uid (the Outbox indicator's state) - see `useOutboxStatus()`. */
+    outbox: Record<string, OutboxFolderStatus>;
 }
 
+const NO_TRACKER: CountTracker = { 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<MailConnection | null>(null);
 
@@ -103,7 +110,7 @@ export function useMailConnection({ userUid, enabled, open }: UseMailConnectionO
         void Promise.all(
             mailboxes.map((mailbox) =>
                 listFolders(mailbox.uid)
-                    .then((result): MailboxFolders => ({ mailbox, folders: result.filter((f) => MAIL_FOLDER_TYPES.has(f.type)) }))
+                    .then((result): MailboxFolders => ({ mailbox, folders: result.filter(isMailFolder) }))
                     .catch(
                         (err): MailboxFolders => ({
                             mailbox,
@@ -118,21 +125,19 @@ export function useMailConnection({ userUid, enabled, open }: UseMailConnectionO
     }, [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: 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,
-            ),
-        );
-    }, []);
+     * 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: Folder) => setMailboxFolders((prev) => upsertFolder(prev, folder)), []);
+    /** A folder was renamed or changed type elsewhere. */
+    const onFolderChanged = useCallback((change: FolderChange) => setMailboxFolders((prev) => upsertFolder(prev, change)), []);
+    const onFolderDeleted = useCallback((folderUid: string) => 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: Folder[]) => setMailboxFolders((prev) => reconcileFolders(prev, listed)), []);
 
+    const askedFolderUidsRef = useRef(new Set<string>());
+    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
@@ -143,8 +148,56 @@ export function useMailConnection({ userUid, enabled, open }: UseMailConnectionO
         mailboxes,
         mailboxFolders,
         onFolderCreated,
+        onFolderChanged,
+        onFolderDeleted,
+        onFoldersListed,
         onMessageCreated: notifications.announce,
+        onSendEvent: handleSendEvent,
     });
+    const noteFolderUids = useCallback(
+        (folderUids: Iterable<string>) => {
+            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 } } as Message) : 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, live, folderCounts, notifications };
+    return { status, error, mailboxes, mailboxFolders, foldersLoading, onFolderCreated, noteFolderUids, live, folderCounts, notifications, outbox };
 }

package/apps/shared/mail/useMailLiveUpdates.ts

@@ -5,9 +5,11 @@
 import { useEffect, useMemo, useRef, useState } from "react";
 import { Folder, Mailbox, Message } from "@rapidmx/react-shared/mail/mailApi.js";
 import { getPushClient, PushEvent } from "@rapidmx/react-shared/mail/pushClient.js";
+import { SendEvent, parseSendEvent } from "@rapidmx/react-shared/mail/sendEvents.js";
 import type { MailboxFolders } from "../components/mail/layout/MailShell.js";
 import { SIGN_OUT_CHANNEL } from "../search/localIndexRpcClient.js";
 import { FolderCounts, useFolderCounts } from "./folderCounts.js";
+import { FolderChange, 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). */
@@ -34,14 +36,15 @@ 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: MailboxFolders[], mailboxes: Mailbox[]): string[] {
     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: unknown): value is Folder {
@@ -49,6 +52,12 @@ function isFolder(value: unknown): value is Folder {
     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: unknown): value is FolderChange {
+    const change = value as Partial<FolderChange> | null;
+    return !!change && typeof change.uid === "string" && (typeof change.name === "string" || typeof change.type === "string");
+}
+
 function isMessage(value: unknown): value is Message {
     const message = value as Partial<Message> | null;
     return (
@@ -76,10 +85,20 @@ 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 {
@@ -101,13 +120,23 @@ export interface MailLiveUpdates {
  * 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, onMessageCreated }: UseMailLiveUpdatesOptions): MailLiveUpdates {
+export function useMailLiveUpdates({
+    userUid,
+    mailboxes,
+    mailboxFolders,
+    onFolderCreated,
+    onFolderChanged,
+    onFolderDeleted,
+    onFoldersListed,
+    onMessageCreated,
+    onSendEvent,
+}: UseMailLiveUpdatesOptions): MailLiveUpdates {
     const [live, setLive] = useState<LiveUpdates>(NO_LIVE_UPDATES);
     const folders = useMemo(() => mailboxFolders.flatMap((entry) => entry.folders), [mailboxFolders]);
-    const folderCounts = useFolderCounts(mailboxes, folders);
+    const folderCounts = useFolderCounts(mailboxes, folders, onFoldersListed);
     // The latest inputs, for the long-lived listeners below.
-    const latestRef = useRef({ mailboxes, mailboxFolders, onFolderCreated, onMessageCreated, folderCounts });
-    latestRef.current = { mailboxes, mailboxFolders, onFolderCreated, onMessageCreated, folderCounts };
+    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("|");
@@ -149,7 +178,12 @@ export function useMailLiveUpdates({ userUid, mailboxes, mailboxFolders, onFolde
         }
 
         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)) {
@@ -158,13 +192,24 @@ export function useMailLiveUpdates({ userUid, mailboxes, mailboxFolders, onFolde
                 }
                 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 as { uid?: unknown } | null | undefined)?.uid;
+                if (typeof uid === "string") {
+                    latestRef.current.onFolderDeleted?.(uid);
+                }
             }
         });
         // Anything published while the socket was down is gone for good, so every reconnect is followed by a refresh.

package/apps/shared/mail/useNewMailNotifications.ts

@@ -18,11 +18,9 @@ import {
     setDesktopOfferDismissed,
     shouldAnnounce,
 } from "./newMailNotifications.js";
+import { getNotificationsSnapshot, notify } from "../notifications/store.js";
 
-/** The most pop-ups on screen at once; a new one pushes the oldest off. */
-export 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). */
+/** 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 = 8_000;
 
 /** At most this many desktop notifications in `DESKTOP_BURST_WINDOW_MS`: a flood of mail is a few notifications, not a hundred. */
@@ -33,11 +31,7 @@ export const DESKTOP_BURST_WINDOW_MS = 30_000;
 const ANNOUNCED_LIMIT = 500;
 
 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,
+    /** 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. */
@@ -65,7 +59,8 @@ function defaultOpen(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
+ * 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.
@@ -74,7 +69,6 @@ function defaultOpen(href: string): void {
  * first pop-up, or from Settings. What the user answered is remembered in `localStorage` (see `newMailNotifications.ts`).
  */
 export function useNewMailNotifications({ mailboxes, mailboxFolders, open = defaultOpen }: UseNewMailNotificationsOptions): NewMailNotifications {
-    const [toasts, setToasts] = useState<NewMailNotice[]>([]);
     const [permission, setPermission] = useState<DesktopPermission>("unsupported");
     const [offerDismissed, setOfferDismissed] = useState(true);
     const folders = useMemo(() => mailboxFolders.flatMap((entry) => entry.folders), [mailboxFolders]);
@@ -90,10 +84,6 @@ export function useNewMailNotifications({ mailboxes, mailboxFolders, open = defa
         setOfferDismissed(getDesktopOfferDismissed());
     }, []);
 
-    const dismiss = useCallback((uid: string) => {
-        setToasts((previous) => previous.filter((toast) => toast.uid !== uid));
-    }, []);
-
     const showDesktop = useCallback((notice: NewMailNotice) => {
         const now = Date.now();
         desktopShownRef.current = desktopShownRef.current.filter((at) => now - at < DESKTOP_BURST_WINDOW_MS);
@@ -117,6 +107,24 @@ export function useNewMailNotifications({ mailboxes, mailboxFolders, open = defa
         }
     }, []);
 
+    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: Message) => {
             if (!getNewMailPopupsEnabled() || announcedRef.current.has(message.uid)) {
@@ -131,7 +139,29 @@ export function useNewMailNotifications({ mailboxes, mailboxFolders, open = defa
                 announcedRef.current.delete(announcedRef.current.values().next().value!);
             }
             const notice = noticeFor(message);
-            setToasts((previous) => [...previous.filter((toast) => toast.uid !== notice.uid), notice].slice(-MAX_TOASTS));
+            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);
             }
@@ -139,23 +169,8 @@ export function useNewMailNotifications({ mailboxes, mailboxFolders, open = defa
         [showDesktop],
     );
 
-    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);
-    }, []);
-
     return {
-        toasts,
-        dismiss,
-        offerDesktop: permission === "default" && !offerDismissed,
+        offerDesktop,
         enableDesktop,
         declineDesktop,
         announce,

package/apps/shared/navigation/AppRouter.tsx

@@ -71,8 +71,8 @@ export interface AppRouterProps {
 }
 
 function pickChromeProps(props: Record<string, any>): Omit<AppShellProps, "active"> {
-    const { userUid, authServerUrl, impersonating, impersonationBaseUrl, trusted, trustedRoles, pluginNav } = props;
-    return { userUid, authServerUrl, impersonating, impersonationBaseUrl, trusted, trustedRoles, pluginNav };
+    const { userUid, authServerUrl, impersonating, impersonationBaseUrl, trusted, trustedRoles, pluginNav, branding, appearance } = props;
+    return { userUid, authServerUrl, impersonating, impersonationBaseUrl, trusted, trustedRoles, pluginNav, branding, appearance };
 }
 
 /** The anchor a click/pointer event is on or in, if it is a link. */