@rapidmx/web-client 0.9.0 → 0.11.0

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

@@ -0,0 +1,116 @@
+/**
+ * The sidebar's order of a mailbox's well-known folders; anything else (`user`) follows, alphabetically. Also the order push channels are asked
+ * for (`pushChannelsFor()`), so when the server's channel cap bites it is the folders lowest in this list that go without live updates.
+ */
+export const FOLDER_ORDER = ["inbox", "drafts", "outbox", "sent_items", "deleted_items", "junk", "archive"];
+/**
+ * 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 well-known folders the server creates lazily around a first send: what the sidebar shows a placeholder for while a message is on its way. */
+export const SEND_FOLDER_TYPES = ["outbox", "sent_items"];
+export function isMailFolder(folder) {
+    return MAIL_FOLDER_TYPES.has(folder.type);
+}
+function sortKey(type) {
+    const index = FOLDER_ORDER.indexOf(type);
+    return index === -1 ? FOLDER_ORDER.length : index;
+}
+/** Well-known folders in `FOLDER_ORDER`, then the rest by name. A new array; the input is left alone. */
+export function sortFolders(folders) {
+    return [...folders].sort((a, b) => sortKey(a.type) - sortKey(b.type) || a.name.localeCompare(b.name));
+}
+/**
+ * The rows of one mailbox's sidebar section, in order: every folder that exists, and - while `sending` messages are on their way and the
+ * server has not made the folder yet - a placeholder for each of the Outbox and Sent Items that is missing. The one place a folder that has not
+ * arrived is drawn, so it can never appear twice: the moment the real folder is in `folders` its placeholder is not built.
+ */
+export function folderRows(folders, sending) {
+    const rows = sortFolders(folders).map((folder) => ({ kind: "folder", folder }));
+    if (sending > 0) {
+        for (const type of SEND_FOLDER_TYPES) {
+            if (!folders.some((folder) => folder.type === type)) {
+                rows.push({ kind: "placeholder", type });
+            }
+        }
+        rows.sort((a, b) => sortKey(rowType(a)) - sortKey(rowType(b)));
+    }
+    return rows;
+}
+function rowType(row) {
+    return row.kind === "folder" ? row.folder.type : row.type;
+}
+const CHANGEABLE = ["name", "type", "parentFolderUid", "color"];
+/**
+ * Files `folder` in the tree: added under its mailbox when unknown (a type Mail does not list is ignored), else its name, type, parent and
+ * colour brought up to date (a folder that became a type Mail does not list leaves the tree). Returns `entries` itself - the same array - when
+ * nothing changed, because everything on screen that depends on the tree starts over when it is a new one.
+ */
+export function upsertFolder(entries, folder) {
+    let changed = false;
+    const next = entries.map((entry) => {
+        const existing = entry.folders.find((f) => f.uid === folder.uid);
+        if (!existing) {
+            // Only a whole folder can be added: an update for one that is not known has nothing to add it with (the refetch it causes will).
+            if (entry.mailbox.uid !== folder.mailboxUid || !isFullFolder(folder) || !isMailFolder(folder)) {
+                return entry;
+            }
+            // A well-known folder is one per mailbox - the server treats the oldest as the real one - so a second of the same type (made by a client that did
+            // not know it existed) is not a second row: the older of the two is the one shown.
+            const sameType = folder.type === "user" ? undefined : entry.folders.find((f) => f.type === folder.type);
+            if (sameType) {
+                if (!isOlder(folder, sameType)) {
+                    return entry;
+                }
+                changed = true;
+                return { ...entry, folders: entry.folders.map((f) => (f === sameType ? folder : f)) };
+            }
+            changed = true;
+            return { ...entry, folders: [...entry.folders, folder] };
+        }
+        const patch = {};
+        for (const key of CHANGEABLE) {
+            if (key in folder && folder[key] !== undefined && folder[key] !== existing[key]) {
+                patch[key] = folder[key];
+            }
+        }
+        if (Object.keys(patch).length === 0) {
+            return entry;
+        }
+        changed = true;
+        const updated = { ...existing, ...patch };
+        return { ...entry, folders: isMailFolder(updated) ? entry.folders.map((f) => (f === existing ? updated : f)) : entry.folders.filter((f) => f !== existing) };
+    });
+    return changed ? next : entries;
+}
+function isFullFolder(folder) {
+    return typeof folder.name === "string" && typeof folder.type === "string";
+}
+/** Whether `a` was created before `b`: only when both say when. */
+function isOlder(a, b) {
+    // (A folder from the network may lack the date: `Date.parse(undefined)` is NaN, which is "cannot tell".)
+    const first = Date.parse(a.dateCreated);
+    const second = Date.parse(b.dateCreated);
+    return Number.isFinite(first) && Number.isFinite(second) && first < second;
+}
+/** Takes a deleted folder out of the tree. The same array when it was not in it. */
+export function removeFolder(entries, folderUid) {
+    if (!entries.some((entry) => entry.folders.some((folder) => folder.uid === folderUid))) {
+        return entries;
+    }
+    return entries.map((entry) => (entry.folders.some((folder) => folder.uid === folderUid) ? { ...entry, folders: entry.folders.filter((folder) => folder.uid !== folderUid) } : entry));
+}
+/**
+ * Brings one mailbox's part of the tree up to date with a listing the server just gave (`listFolders()`): folders it has that the tree lacks
+ * are added, changed names and types are taken. Nothing is removed - a listing that began before a folder was created here would take it out
+ * again, and deletions arrive as events - and the counts are not touched (see `useFolderCounts()`). The same array when there is nothing to do.
+ */
+export function reconcileFolders(entries, listed) {
+    return listed.reduce((tree, folder) => upsertFolder(tree, folder), entries);
+}
+/** Every folder uid in the tree. */
+export function knownFolderUids(entries) {
+    return new Set(entries.flatMap((entry) => entry.folders.map((folder) => folder.uid)));
+}

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

@@ -0,0 +1,46 @@
+import type { ConversationSummary } from "@rapidmx/react-shared/mail/conversationsApi.js";
+import type { Message } from "@rapidmx/react-shared/mail/mailApi.js";
+/**
+ * A short-lived, in-memory copy of a folder's listing, so that switching to a folder that was shown a moment ago (or coming back
+ * to Mail from another app) shows its rows on the very frame of the click and revalidates behind them (stale-while-revalidate),
+ * instead of replacing the list with a loading state and waiting for the network. It is the client-side router's answer to
+ * "folder navigation takes seconds": the list of the folder being switched to is usually already known.
+ *
+ * Only a plain folder's listing is kept - a search's, an aggregate ("All Mailboxes") view's and a load-more page's rows are not -
+ * and what is kept is exactly what was on screen, including the rows "load more" added, the selection and the scroll position,
+ * so returning to a folder puts the reader where they left it. A snapshot only makes the first paint fast; the listing is always
+ * fetched again and folded in (`mergeFirstPage()`), so nothing shown from here is ever taken as current.
+ */
+export interface ListSnapshot {
+    messages: Message[];
+    conversations: ConversationSummary[];
+    hasMore: boolean;
+    /** The message that was selected (the reading pane's), if it is still in `messages` when the snapshot is shown. */
+    selectedUid: string | null;
+    /** The list's `scrollTop`, saved when the listing was left. */
+    scrollTop: number;
+    /** When it was last written. */
+    at: number;
+}
+/** How long a snapshot may be shown after it was last written. Longer than that the folder is shown as loading, as before. */
+export declare const LIST_SNAPSHOT_TTL_MS: number;
+/** How many folders are remembered; the least recently written is dropped first. */
+export declare const LIST_SNAPSHOT_MAX = 16;
+/** Everything that makes one listing different from another: which folder, as messages or conversations, and how it is
+ * filtered and sorted. */
+export declare function listSnapshotKey(parts: {
+    mailboxUid: string | undefined;
+    folderUid: string | undefined;
+    conversations: boolean;
+    filter: string;
+    labels: string;
+    sort: string;
+}): string;
+/** The snapshot for `key`, or `undefined` when there is none or it is older than `LIST_SNAPSHOT_TTL_MS`. */
+export declare function readListSnapshot(key: string, now?: number): ListSnapshot | undefined;
+/** Remembers a listing as it is on screen (keeping the scroll position saved for it, if any). */
+export declare function writeListSnapshot(key: string, listing: Omit<ListSnapshot, "scrollTop" | "at">, now?: number): void;
+/** Records how far `key`'s list was scrolled when it was left. A no-op for a listing that was never remembered. */
+export declare function saveListScroll(key: string, scrollTop: number): void;
+/** Forgets every snapshot (sign-out, and tests). */
+export declare function clearListSnapshots(): void;

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

@@ -0,0 +1,43 @@
+/** How long a snapshot may be shown after it was last written. Longer than that the folder is shown as loading, as before. */
+export const LIST_SNAPSHOT_TTL_MS = 5 * 60000;
+/** How many folders are remembered; the least recently written is dropped first. */
+export const LIST_SNAPSHOT_MAX = 16;
+const snapshots = new Map();
+/** Everything that makes one listing different from another: which folder, as messages or conversations, and how it is
+ * filtered and sorted. */
+export function listSnapshotKey(parts) {
+    return [parts.mailboxUid, parts.folderUid, parts.conversations ? "conversations" : "messages", parts.filter, parts.labels, parts.sort].join("|");
+}
+/** The snapshot for `key`, or `undefined` when there is none or it is older than `LIST_SNAPSHOT_TTL_MS`. */
+export function readListSnapshot(key, now = Date.now()) {
+    const snapshot = snapshots.get(key);
+    if (!snapshot) {
+        return undefined;
+    }
+    if (now - snapshot.at > LIST_SNAPSHOT_TTL_MS) {
+        snapshots.delete(key);
+        return undefined;
+    }
+    return snapshot;
+}
+/** Remembers a listing as it is on screen (keeping the scroll position saved for it, if any). */
+export function writeListSnapshot(key, listing, now = Date.now()) {
+    const previous = snapshots.get(key);
+    // Re-inserted so that the Map's order is least-recently-written first.
+    snapshots.delete(key);
+    snapshots.set(key, { ...listing, scrollTop: previous?.scrollTop ?? 0, at: now });
+    while (snapshots.size > LIST_SNAPSHOT_MAX) {
+        snapshots.delete(snapshots.keys().next().value);
+    }
+}
+/** Records how far `key`'s list was scrolled when it was left. A no-op for a listing that was never remembered. */
+export function saveListScroll(key, scrollTop) {
+    const snapshot = snapshots.get(key);
+    if (snapshot) {
+        snapshot.scrollTop = scrollTop;
+    }
+}
+/** Forgets every snapshot (sign-out, and tests). */
+export function clearListSnapshots() {
+    snapshots.clear();
+}

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

@@ -0,0 +1,32 @@
+import { Message } from "@rapidmx/react-shared/mail/mailApi.js";
+import type { CountTracker } from "./folderCounts.js";
+/**
+ * The one way a message's read state changes in the webmail, so that every place that shows it moves together: the row in
+ * the list (and the conversation row's unread count), the folder badge, and the unread styling.
+ *
+ * It is **optimistic**: the row and the badge change the moment the user acts, the server is asked, and if it refuses the
+ * change is taken back. What each place is handed to do that is a `ReadStateSink`.
+ */
+export interface ReadStateSink {
+    /**
+     * Shows a message wherever the caller lists it - the message list, the conversation list's child rows, the open thread.
+     * `previous` is given with the optimistic copy (and with the revert of it) and is the copy being replaced, so a
+     * conversation row can tell that its unread count went up or down; it is absent for the server's own copy, which
+     * differs only in its `version`.
+     */
+    patch(updated: Message, previous?: Message): void;
+    /** Applies the change to the folder badges: `MailShell`'s `trackMessageChange`. */
+    track(previous: Message, next: Message): CountTracker;
+}
+/**
+ * Marks one message read (`read: true`) or unread. Resolves the server's updated copy, or `undefined` when nothing needed
+ * doing (it already was that way) or the server refused - in which case everything has already been put back as it was.
+ * Never rejects: like the old mark-as-read, a failure must not get in the way of reading the message.
+ */
+export declare function setReadState(message: Message, read: boolean, sink: ReadStateSink): Promise<Message | undefined>;
+/**
+ * The same for a whole selection, in one request. Resolves the updated messages, in request order. Unlike `setReadState()`
+ * it rejects when the server refuses (after putting everything back), because a bulk update is not atomic - some of it may
+ * have landed - and the caller's own handling reloads the list and says so (see `bulkUpdateMessages()`).
+ */
+export declare function setReadStateMany(messages: Message[], read: boolean, sink: ReadStateSink): Promise<Message[]>;

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

@@ -0,0 +1,63 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { setMessageRead, setMessagesRead } from "@rapidmx/react-shared/mail/mailApi.js";
+function withRead(message, read) {
+    return { ...message, flags: { ...message.flags, read } };
+}
+/** Whether `message` is not yet in the state `read` asks for. A message with no `read` flag counts as unread. */
+function needsChange(message, read) {
+    return (message.flags.read === true) !== read;
+}
+/**
+ * Marks one message read (`read: true`) or unread. Resolves the server's updated copy, or `undefined` when nothing needed
+ * doing (it already was that way) or the server refused - in which case everything has already been put back as it was.
+ * Never rejects: like the old mark-as-read, a failure must not get in the way of reading the message.
+ */
+export async function setReadState(message, read, sink) {
+    if (!needsChange(message, read)) {
+        return undefined;
+    }
+    const optimistic = withRead(message, read);
+    sink.patch(optimistic, message);
+    const tracker = sink.track(message, optimistic);
+    try {
+        const updated = await setMessageRead(message, read);
+        sink.patch(updated);
+        tracker.settle();
+        return updated;
+    }
+    catch {
+        sink.patch(message, optimistic);
+        tracker.revert();
+        return undefined;
+    }
+}
+/**
+ * The same for a whole selection, in one request. Resolves the updated messages, in request order. Unlike `setReadState()`
+ * it rejects when the server refuses (after putting everything back), because a bulk update is not atomic - some of it may
+ * have landed - and the caller's own handling reloads the list and says so (see `bulkUpdateMessages()`).
+ */
+export async function setReadStateMany(messages, read, sink) {
+    const changes = messages.filter((message) => needsChange(message, read)).map((message) => ({ message, optimistic: withRead(message, read) }));
+    const trackers = changes.map(({ message, optimistic }) => {
+        sink.patch(optimistic, message);
+        return sink.track(message, optimistic);
+    });
+    try {
+        const updated = await setMessagesRead(messages, read);
+        for (const message of updated) {
+            sink.patch(message);
+        }
+        trackers.forEach((tracker) => tracker.settle());
+        return updated;
+    }
+    catch (err) {
+        changes.forEach(({ message, optimistic }, index) => {
+            sink.patch(message, optimistic);
+            trackers[index].revert();
+        });
+        throw err;
+    }
+}

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

@@ -0,0 +1,62 @@
+import type { Folder, Mailbox, Message } from "@rapidmx/react-shared/mail/mailApi.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 declare 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 declare const DESKTOP_OFFER_KEY = "rapidmx-desktop-notifications-offer";
+/** How much of the body an announcement quotes. */
+export declare 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 declare const MAX_NEW_AGE_MS: number;
+/** Whether new-mail pop-ups are on (the default). */
+export declare function getNewMailPopupsEnabled(): boolean;
+export declare function setNewMailPopupsEnabled(enabled: boolean): void;
+/** Whether the "turn on desktop notifications" offer has been put away with "Not now" (or answered). */
+export declare function getDesktopOfferDismissed(): boolean;
+export declare function setDesktopOfferDismissed(dismissed: boolean): void;
+/** The browser's notification permission, or `"unsupported"` where there is no Notifications API. */
+export type DesktopPermission = NotificationPermission | "unsupported";
+export declare function desktopPermission(): DesktopPermission;
+/** Asks the browser for permission - call it from a click. Resolves the answer; never rejects. */
+export declare function requestDesktopPermission(): Promise<DesktopPermission>;
+/** What an announcement shows. */
+export interface NewMailNotice {
+    /** The message's uid: the announcement's identity (and the desktop notification's `tag`). */
+    uid: string;
+    mailboxUid: string;
+    folderUid: string;
+    /** The sender's display name, `""` when there is none. */
+    senderName: string;
+    /** The sender's address - always shown, so a name can't stand in for who really sent it. */
+    senderAddress: string;
+    subject: string;
+    /** About `PREVIEW_MAX_LENGTH` characters of the body as plain text; `Encrypted message` for an encrypted one. */
+    preview: string;
+    /** Where opening it goes. */
+    href: string;
+}
+/** `text` with those characters replaced by spaces, whitespace folded, and cut to `max` characters (with an ellipsis). */
+export declare function cleanPreview(text: string, max?: number): string;
+/** The text of an announcement of `message`. */
+export declare function noticeFor(message: Message): NewMailNotice;
+/** Every address that is this user's own, lowercased - a message from one of them is not new mail worth announcing. */
+export declare function ownAddressesOf(mailboxes: Mailbox[]): Set<string>;
+/**
+ * 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 declare function shouldAnnounce(message: Message, context: {
+    folders: Folder[];
+    ownAddresses: Set<string>;
+    now?: number;
+}): boolean;
+/** `Name <address>`, or the address alone - the desktop notification's title. */
+export declare function noticeSender(notice: Pick<NewMailNotice, "senderName" | "senderAddress">): string;

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/outbox/UnlockBridge.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Lets code with no React context - a pop-up's "Unlock" action - open the app's one unlock prompt (`UnlockPromptProvider`). Renders nothing;
+ * mounted once, inside the provider it reaches.
+ */
+export default function UnlockBridge(): null;

package/dist/apps/shared/mail/outbox/UnlockBridge.js

@@ -0,0 +1,18 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { useEffect } from "react";
+import { useUnlockPrompt } from "../../components/layout/UnlockPromptProvider.js";
+import { registerUnlockOpener } from "./composeBridge.js";
+/**
+ * Lets code with no React context - a pop-up's "Unlock" action - open the app's one unlock prompt (`UnlockPromptProvider`). Renders nothing;
+ * mounted once, inside the provider it reaches.
+ */
+export default function UnlockBridge() {
+    const { requestUnlock } = useUnlockPrompt();
+    useEffect(() => registerUnlockOpener(async (mailboxUid, keys) => {
+        await requestUnlock(mailboxUid, keys);
+    }), [requestUnlock]);
+    return null;
+}

package/dist/apps/shared/mail/outbox/composeBridge.d.ts

@@ -0,0 +1,34 @@
+import type { Attachment, Message } from "@rapidmx/react-shared/mail/mailApi.js";
+import type { PublicKey } from "@rapidmx/react-shared/crypto/keyvaultApi.js";
+/**
+ * A compose window to re-open around a message that was already composed: a failed send's "Open draft". The message keeps its uid - the
+ * server draft it was assembled into - and everything the sender had typed comes back exactly as it was, including what could not have
+ * been read back from the server (the plain text of a message that was encrypted before it was stored).
+ */
+export interface ResumeCompose {
+    /** The server draft the window continues - it must be in Drafts (a message that is in Outbox is moved back first). */
+    draft: Message;
+    mailboxUid: string;
+    to: string;
+    cc: string;
+    bcc: string;
+    subject: string;
+    html: string;
+    attachments: Attachment[];
+    requestReceipt: boolean;
+    signEnabled: boolean;
+    encryptRequested: boolean;
+}
+/** What the app frame's compose provider offers to code that has no React context (a pop-up's action, a push-event handler). */
+export interface ComposeOpenerInput {
+    mailboxUid?: string;
+    resume?: ResumeCompose;
+}
+/** Registered by `ComposeProvider`; returns the function that unregisters it. */
+export declare function registerComposeOpener(open: (input: ComposeOpenerInput) => void): () => void;
+/** Opens a compose window from outside React. `false` when no compose provider is mounted (nothing was opened). */
+export declare function openComposeFromOutside(input: ComposeOpenerInput): boolean;
+/** Registered by the unlock prompt's owner; returns the function that unregisters it. */
+export declare function registerUnlockOpener(unlock: (mailboxUid: string, keys: PublicKey[]) => Promise<void>): () => void;
+/** Opens the existing unlock prompt from outside React. Resolves once the keys are unlocked; rejects when the user dismissed it (or there is no prompt). */
+export declare function requestUnlockFromOutside(mailboxUid: string, keys: PublicKey[]): Promise<void>;

package/dist/apps/shared/mail/outbox/composeBridge.js

@@ -0,0 +1,32 @@
+let opener;
+let unlocker;
+/** Registered by `ComposeProvider`; returns the function that unregisters it. */
+export function registerComposeOpener(open) {
+    opener = open;
+    return () => {
+        if (opener === open) {
+            opener = undefined;
+        }
+    };
+}
+/** Opens a compose window from outside React. `false` when no compose provider is mounted (nothing was opened). */
+export function openComposeFromOutside(input) {
+    if (!opener) {
+        return false;
+    }
+    opener(input);
+    return true;
+}
+/** Registered by the unlock prompt's owner; returns the function that unregisters it. */
+export function registerUnlockOpener(unlock) {
+    unlocker = unlock;
+    return () => {
+        if (unlocker === unlock) {
+            unlocker = undefined;
+        }
+    };
+}
+/** Opens the existing unlock prompt from outside React. Resolves once the keys are unlocked; rejects when the user dismissed it (or there is no prompt). */
+export function requestUnlockFromOutside(mailboxUid, keys) {
+    return unlocker ? unlocker(mailboxUid, keys) : Promise.reject(new Error("No unlock prompt is available."));
+}

package/dist/apps/shared/mail/outbox/outboxState.d.ts

@@ -0,0 +1,41 @@
+import type { Message } from "@rapidmx/react-shared/mail/mailApi.js";
+/**
+ * What a message in Outbox is doing, read from the fields the server keeps on it (`scheduledSend*`):
+ *
+ * These are the server's own definitions (`@rapidmx/restapi`'s background send):
+ *
+ * - `sending`: a lease (`scheduledSendLeaseExpiresAt`) is running, or a *due* `scheduledSendTime` with no failed attempts yet - a message
+ * queued for the server's worker (a background send is queued as an ordinary due message, `scheduledSendTime` = when it was queued);
+ * - `retrying`: `scheduledSendAttempts > 0` with a later `scheduledSendTime` (or a lease on one): a delivery attempt failed and the server
+ * will try again;
+ * - `failed`: `scheduledSendError` set and no `scheduledSendTime` - the server gave up; it stays in Outbox, waiting for the user to retry
+ * (the same send call again) or to open it (back to Drafts is allowed, it is not in flight);
+ * - `scheduled`: a send-later message whose time has not come.
+ *
+ * "Due" is judged against the message's own `dateModified` as well as the clock: a background send's `scheduledSendTime` is set by the server
+ * at the moment it queued the message, so a browser whose clock runs behind must not read it as a send scheduled for the future.
+ */
+export type OutboxItemState = "sending" | "retrying" | "failed" | "scheduled";
+export interface OutboxItemStatus {
+    state: OutboxItemState;
+    /** Failed delivery attempts so far (`retrying`). */
+    attempts: number;
+    /** Why it failed (`failed`). */
+    error?: string;
+    /** When it will be sent or tried again (`scheduled`, `retrying`), epoch ms. */
+    at?: number;
+}
+/** A `scheduledSendTime` this close to the message's last modification was set by the server as "now": a due message, not a scheduled one. */
+export declare const DUE_SLACK_MS = 2000;
+export declare function outboxItemStatus(message: Message, now?: number): OutboxItemStatus;
+/** How many messages of each kind an Outbox folder holds. */
+export interface OutboxFolderStatus {
+    sending: number;
+    retrying: number;
+    failed: number;
+    scheduled: number;
+}
+export declare const EMPTY_OUTBOX_STATUS: OutboxFolderStatus;
+export declare function summarizeOutbox(messages: Message[], now?: number): OutboxFolderStatus;
+/** The text a screen reader gets for an Outbox count, and the tooltip: "2 messages sending", "3 messages, 1 failed". */
+export declare function outboxLabel(total: number, status: OutboxFolderStatus | undefined, pendingHere: number): string;