@rapidmx/web-client 0.10.0 → 0.12.0

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

@@ -1,18 +1,13 @@
 import { Folder, Mailbox } from "@rapidmx/react-shared/mail/mailApi.js";
+import { FOLDER_ORDER, MAIL_FOLDER_TYPES } from "./folderTree.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";
+import { OutboxFolderStatus } from "./outbox/outboxState.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 { FOLDER_ORDER, MAIL_FOLDER_TYPES };
 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 {
@@ -27,12 +22,18 @@ 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>;
 }
 /** 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>;

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

@@ -2,21 +2,21 @@
 // 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 { 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;
-/** 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 };
+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);
 /**
@@ -59,7 +59,7 @@ export function useMailConnection({ userUid, enabled, open }) {
         }
         setFoldersLoading(true);
         void Promise.all(mailboxes.map((mailbox) => listFolders(mailbox.uid)
-            .then((result) => ({ mailbox, folders: result.filter((f) => MAIL_FOLDER_TYPES.has(f.type)) }))
+            .then((result) => ({ mailbox, folders: result.filter(isMailFolder) }))
             .catch((err) => ({
             mailbox,
             folders: [],
@@ -69,17 +69,18 @@ export function useMailConnection({ userUid, enabled, open }) {
             .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));
-    }, []);
+     * 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
@@ -90,7 +91,48 @@ export function useMailConnection({ userUid, enabled, open }) {
         mailboxes,
         mailboxFolders,
         onFolderCreated,
+        onFolderChanged,
+        onFolderDeleted,
+        onFoldersListed,
         onMessageCreated: notifications.announce,
+        onSendEvent: handleSendEvent,
     });
-    return { status, error, mailboxes, mailboxFolders, foldersLoading, onFolderCreated, live, folderCounts, notifications };
+    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,6 +1,8 @@
 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;
@@ -17,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 {
@@ -29,10 +32,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 {
     live: LiveUpdates;
@@ -52,4 +65,4 @@ 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 declare function useMailLiveUpdates({ userUid, mailboxes, mailboxFolders, onFolderCreated, onMessageCreated }: UseMailLiveUpdatesOptions): MailLiveUpdates;
+export declare function useMailLiveUpdates({ userUid, mailboxes, mailboxFolders, onFolderCreated, onFolderChanged, onFolderDeleted, onFoldersListed, onMessageCreated, onSendEvent, }: UseMailLiveUpdatesOptions): MailLiveUpdates;

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

@@ -4,8 +4,10 @@
 ///////////////////////////////////////////////////////////////////////////////
 import { useEffect, useMemo, useRef, useState } from "react";
 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,25 @@ 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 &&
@@ -59,13 +67,13 @@ function folderOfMessageEvent(event) {
  * 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 }) {
+export function useMailLiveUpdates({ userUid, mailboxes, mailboxFolders, onFolderCreated, onFolderChanged, onFolderDeleted, onFoldersListed, onMessageCreated, onSendEvent, }) {
     const [live, setLive] = useState(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("|");
     const channelsRef = useRef(channels);
@@ -103,7 +111,13 @@ 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)) {
@@ -113,15 +127,27 @@ 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?.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.
         const offStatus = client.onStatus((status) => {

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

@@ -1,19 +1,12 @@
 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). */
+/** 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 {
-    /** 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. */
@@ -30,7 +23,8 @@ export interface UseNewMailNotificationsOptions {
     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
+ * 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.

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

@@ -4,9 +4,8 @@
 ///////////////////////////////////////////////////////////////////////////////
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { desktopPermission, getDesktopOfferDismissed, getNewMailPopupsEnabled, noticeFor, noticeSender, ownAddressesOf, requestDesktopPermission, setDesktopOfferDismissed, shouldAnnounce, } from "./newMailNotifications.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). */
+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;
@@ -21,7 +20,8 @@ function defaultOpen(href) {
     window.location.href = href;
 }
 /**
- * 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.
@@ -30,7 +30,6 @@ function defaultOpen(href) {
  * 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 [toasts, setToasts] = useState([]);
     const [permission, setPermission] = useState("unsupported");
     const [offerDismissed, setOfferDismissed] = useState(true);
     const folders = useMemo(() => mailboxFolders.flatMap((entry) => entry.folders), [mailboxFolders]);
@@ -44,9 +43,6 @@ export function useNewMailNotifications({ mailboxes, mailboxFolders, open = defa
         setPermission(desktopPermission());
         setOfferDismissed(getDesktopOfferDismissed());
     }, []);
-    const dismiss = useCallback((uid) => {
-        setToasts((previous) => previous.filter((toast) => toast.uid !== uid));
-    }, []);
     const showDesktop = useCallback((notice) => {
         const now = Date.now();
         desktopShownRef.current = desktopShownRef.current.filter((at) => now - at < DESKTOP_BURST_WINDOW_MS);
@@ -70,6 +66,21 @@ export function useNewMailNotifications({ mailboxes, mailboxFolders, open = defa
             // 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;
@@ -83,26 +94,35 @@ 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);
         }
     }, [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/dist/apps/shared/navigation/AppRouter.js

@@ -46,8 +46,8 @@ import { matchRoute } from "./routes.js";
 import { RouterContext, UNKNOWN_LOCATION, readWindowLocation } from "./routerContext.js";
 export { useLocation, useLocationSearch, useNavigate } from "./routerContext.js";
 function pickChromeProps(props) {
-    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. */
 function linkOf(event) {

package/dist/apps/shared/notifications/NotificationCenter.d.ts

@@ -0,0 +1,19 @@
+import React from "react";
+/**
+ * The pop-up stack, and the one place the app's notifications (see `store.ts`) are drawn. Mounted once, in the persistent app frame, so
+ * it survives page changes and covers every app.
+ *
+ * **Where it sits.** Top right, *below* the header row: the stack is anchored to a zero-height `sticky` line placed right after the
+ * frame's header, so it starts under the header (and so under the account menu button, whatever height a branded header has) and, as
+ * the page scrolls, sticks just below the header (`--rr-header-h`, published by the title bar / `FrameBrandingHeader` - see `headerOffset.ts`;
+ * never less than 2.5 rem, which clears a full-screen compose sheet's own title bar on a phone).
+ * On a desktop the compose windows are anchored at the bottom right, the far end of the screen from this; it never covers the account menu,
+ * the header's actions or a compose window's title bar and Send button unless the window is stretched over most of the screen height.
+ * It sits above the compose sheet (z-index 60 against 50), so a pop-up is never hidden behind it. Its height is capped and scrolls.
+ *
+ * **Live regions.** Two always-mounted containers with `aria-live` (a live region has to exist before its content changes to be announced):
+ * errors in an assertive one, everything else in a polite one, and each pop-up carries the matching role - `alert` for an error, `status`
+ * for the rest - so it is announced accordingly, and the empty containers add no `alert`/`status` of their own to the page.
+ * `prefers-reduced-motion` switches the entrance animation off (`.rr-toast-in`).
+ */
+export default function NotificationCenter(): React.JSX.Element;

package/dist/apps/shared/notifications/NotificationCenter.js

@@ -0,0 +1,90 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { useEffect } from "react";
+import { HiOutlineCheckCircle, HiOutlineEnvelope, HiOutlineExclamationCircle, HiOutlineExclamationTriangle, HiOutlineInformationCircle, HiOutlineXMark, } from "react-icons/hi2";
+import CopyButton from "@rapidmx/react-shared/components/buttons/CopyButton.js";
+import { dismiss, setAllPaused, setPaused } from "./store.js";
+import { useNotifications } from "./useNotifications.js";
+import { useSystemErrorNotifications } from "./systemErrors.js";
+const KIND_STYLE = {
+    mail: { border: "border-l-primary", icon: "text-primary-dark", Icon: HiOutlineEnvelope, label: "New message" },
+    info: { border: "border-l-primary", icon: "text-primary-dark", Icon: HiOutlineInformationCircle, label: "Information" },
+    success: { border: "border-l-success", icon: "text-success", Icon: HiOutlineCheckCircle, label: "Success" },
+    warning: { border: "border-l-warning", icon: "text-warning", Icon: HiOutlineExclamationTriangle, label: "Warning" },
+    error: { border: "border-l-danger", icon: "text-danger", Icon: HiOutlineExclamationCircle, label: "Error" },
+};
+const ACTION_CLASS = "rounded-sm px-2.5 py-1 text-xs font-semibold text-primary-dark hover:bg-surface-alt focus-visible:outline-2 focus-visible:outline-primary";
+/** Stops every clock while the tab is out of view: nobody could have read what is on screen, and it is still there when they come back. */
+function usePauseWhileHidden() {
+    useEffect(() => {
+        const update = () => setAllPaused(document.visibilityState === "hidden");
+        update();
+        document.addEventListener("visibilitychange", update);
+        return () => {
+            document.removeEventListener("visibilitychange", update);
+            setAllPaused(false);
+        };
+    }, []);
+}
+function ActionButton({ action, id }) {
+    function run() {
+        action.onClick?.();
+        if (!action.keepOpen) {
+            dismiss(id);
+        }
+    }
+    return action.href ? (_jsx("a", { href: action.href, onClick: run, className: ACTION_CLASS, children: action.label })) : (_jsx("button", { type: "button", onClick: run, className: ACTION_CLASS, children: action.label }));
+}
+/** The expandable, copyable technical lines behind a notification. */
+function Details({ lines }) {
+    return (_jsxs("details", { className: "mt-1.5", children: [_jsx("summary", { className: "cursor-pointer text-xs font-semibold text-text-muted", children: "Technical details" }), _jsx("ul", { "aria-label": "Technical details", className: "mt-1.5 max-h-40 overflow-auto rounded-sm border border-border bg-surface-alt p-2 font-mono text-xs text-text select-text", children: lines.map((line, index) => (_jsx("li", { className: "whitespace-pre-wrap break-words", children: line }, index))) }), _jsx("div", { className: "mt-1.5", children: _jsx(CopyButton, { value: lines.join("\n"), label: "Copy technical details" }) })] }));
+}
+/** One pop-up. Its clock (kept by the store) stops while it is hovered or holds the keyboard focus; Escape dismisses it. */
+function NotificationItem({ notification }) {
+    const { id, kind, title, subtitle, message, preview, hint, details, actions, href, count } = notification;
+    const style = KIND_STYLE[kind];
+    const body = (_jsxs(_Fragment, { children: [kind === "mail" && _jsx("span", { className: "block text-xs font-semibold uppercase tracking-wide text-primary-dark", children: style.label }), _jsxs("span", { className: "flex min-w-0 items-baseline gap-1.5 text-sm", children: [_jsx("span", { className: ["truncate font-bold", kind === "error" ? "text-danger" : ""].join(" "), children: title }), count > 1 && (_jsxs("span", { className: "shrink-0 rounded-pill bg-surface-alt px-1.5 text-xs font-semibold text-text-muted", children: [_jsxs("span", { "aria-hidden": "true", children: ["\u00D7", count] }), _jsxs("span", { className: "sr-only", children: [" (", count, " times)"] })] })), subtitle && _jsx("span", { className: "truncate text-xs text-text-muted", children: subtitle })] }), message && _jsx("span", { className: ["mt-0.5 block text-sm [overflow-wrap:anywhere]", kind === "mail" ? "truncate font-semibold" : ""].join(" "), children: message }), preview && _jsx("span", { className: "mt-0.5 block text-xs text-text-muted [overflow-wrap:anywhere]", children: preview })] }));
+    return (_jsxs("div", { "data-testid": "notification", role: kind === "error" ? "alert" : "status", "data-kind": kind, "data-notification-id": id, onMouseEnter: () => setPaused(id, true), onMouseLeave: () => setPaused(id, false), onFocus: () => setPaused(id, true), onBlur: (event) => {
+            // Focus moving between this pop-up's own controls is not leaving it.
+            if (!event.currentTarget.contains(event.relatedTarget)) {
+                setPaused(id, false);
+            }
+        }, onKeyDown: (event) => {
+            if (event.key === "Escape") {
+                event.preventDefault();
+                dismiss(id);
+            }
+        }, className: `rr-toast-in pointer-events-auto relative rounded-md border border-border border-l-4 ${style.border} bg-surface text-text shadow-lg`, children: [_jsxs("div", { className: "flex items-start gap-2 p-3 pr-10", children: [kind !== "mail" && _jsx(style.Icon, { size: 18, "aria-hidden": "true", className: `mt-0.5 shrink-0 ${style.icon}` }), _jsxs("div", { className: "min-w-0 flex-1", children: [href ? (_jsx("a", { href: href, onClick: () => dismiss(id), className: "-m-1 block rounded-md p-1 hover:bg-surface-alt focus-visible:outline-2 focus-visible:outline-primary", children: body })) : (body), hint && _jsx("p", { className: "mt-1.5 text-xs text-text-muted", children: hint }), details.length > 0 && _jsx(Details, { lines: details }), actions.length > 0 && (_jsx("div", { className: "-ml-2.5 mt-1.5 flex flex-wrap items-center gap-1", children: actions.map((action, index) => (_jsx(ActionButton, { action: action, id: id }, index))) }))] })] }), _jsx("button", { type: "button", onClick: () => dismiss(id), "aria-label": `Dismiss notification: ${title}`, className: "absolute right-1.5 top-1.5 flex h-7 w-7 items-center justify-center rounded-sm text-text-muted hover:bg-surface-alt hover:text-text focus-visible:outline-2 focus-visible:outline-primary", children: _jsx(HiOutlineXMark, { size: 16, "aria-hidden": "true" }) })] }));
+}
+/**
+ * The pop-up stack, and the one place the app's notifications (see `store.ts`) are drawn. Mounted once, in the persistent app frame, so
+ * it survives page changes and covers every app.
+ *
+ * **Where it sits.** Top right, *below* the header row: the stack is anchored to a zero-height `sticky` line placed right after the
+ * frame's header, so it starts under the header (and so under the account menu button, whatever height a branded header has) and, as
+ * the page scrolls, sticks just below the header (`--rr-header-h`, published by the title bar / `FrameBrandingHeader` - see `headerOffset.ts`;
+ * never less than 2.5 rem, which clears a full-screen compose sheet's own title bar on a phone).
+ * On a desktop the compose windows are anchored at the bottom right, the far end of the screen from this; it never covers the account menu,
+ * the header's actions or a compose window's title bar and Send button unless the window is stretched over most of the screen height.
+ * It sits above the compose sheet (z-index 60 against 50), so a pop-up is never hidden behind it. Its height is capped and scrolls.
+ *
+ * **Live regions.** Two always-mounted containers with `aria-live` (a live region has to exist before its content changes to be announced):
+ * errors in an assertive one, everything else in a polite one, and each pop-up carries the matching role - `alert` for an error, `status`
+ * for the rest - so it is announced accordingly, and the empty containers add no `alert`/`status` of their own to the page.
+ * `prefers-reduced-motion` switches the entrance animation off (`.rr-toast-in`).
+ */
+export default function NotificationCenter() {
+    const { visible, queued } = useNotifications();
+    usePauseWhileHidden();
+    useSystemErrorNotifications();
+    const errors = visible.filter((notification) => notification.kind === "error");
+    const others = visible.filter((notification) => notification.kind !== "error");
+    return (_jsx("div", { "data-testid": "notification-anchor", className: "sticky top-[max(var(--rr-header-h,0px),2.5rem)] z-[60] h-0 w-full", children: _jsxs("div", { "data-testid": "notification-stack", 
+            // Never taller than the room above the open compose windows (`ComposeProvider` publishes their top edge as `--rr-compose-top`), so
+            // a stack of pop-ups scrolls inside its own box rather than covering a compose window's title bar and buttons.
+            // (The padding is room for the pop-ups' shadow, which the scroll box would otherwise cut off in a visible edge.)
+            className: "pointer-events-none absolute right-0 -top-1 flex max-h-[max(8rem,calc(var(--rr-compose-top,100vh)-max(var(--rr-header-h,0px),2.5rem)-2rem))] w-[25rem] max-w-[calc(100vw-0.5rem)] flex-col overflow-y-auto p-4", children: [_jsx("div", { "data-testid": "notification-errors", "aria-live": "assertive", className: "flex flex-col gap-2 [&:not(:empty)]:mb-2", children: errors.map((notification) => (_jsx(NotificationItem, { notification: notification }, notification.id))) }), _jsxs("div", { "data-testid": "notification-others", "aria-live": "polite", className: "flex flex-col gap-2", children: [others.map((notification) => (_jsx(NotificationItem, { notification: notification }, notification.id))), queued > 0 && (_jsxs("p", { className: "rr-solid pointer-events-auto self-end rounded-pill bg-surface px-2.5 py-0.5 text-xs text-text-muted shadow-md", children: [queued, " more waiting"] }))] })] }) }));
+}

package/dist/apps/shared/notifications/NotificationHistoryDialog.d.ts

@@ -0,0 +1,10 @@
+import React from "react";
+export interface NotificationHistoryDialogProps {
+    open: boolean;
+    onClose: () => void;
+}
+/**
+ * "Recent notifications": the last few pop-ups, newest first, so nothing is lost when one expires. Opening it counts as having seen
+ * them (the unseen-error count on the account menu goes), but the errors that were unseen when it opened stay highlighted until it closes.
+ */
+export default function NotificationHistoryDialog({ open, onClose }: NotificationHistoryDialogProps): React.JSX.Element;