@rapidmx/web-client 0.9.0 → 0.11.0

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

@@ -0,0 +1,319 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { ApiRequestError } from "@rapidmx/react-shared/util/api.js";
+import { assembleDraft, assembleDraftRaw, getMailbox, getMessage, queueMessageSend, sendMessage, setMessageRequestReceipt, } from "@rapidmx/react-shared/mail/mailApi.js";
+import { describeSendFailure } from "@rapidmx/react-shared/mail/sendFailure.js";
+import { resolveRecipientEncryption } from "@rapidmx/react-shared/crypto/composeSecurity.js";
+import { getUnlockedKeys } from "@rapidmx/react-shared/crypto/keySession.js";
+import { findActivePublicKey, getEncryptionPolicy, lookupKeys } from "@rapidmx/react-shared/crypto/keyvaultApi.js";
+import { fromBase64 } from "@rapidmx/react-shared/crypto/encoding.js";
+import { policyCanAutoEncrypt } from "../../components/mail/compose/encryptionRequirement.js";
+import { dismiss, notify } from "../../notifications/store.js";
+import { INLINE_IMAGE_PATTERN, decideSend } from "./sendDecision.js";
+import { beginPendingSend, finishPendingSend, setPendingStage } from "./pendingSends.js";
+import { openComposeFromOutside, requestUnlockFromOutside } from "./composeBridge.js";
+import { sendState } from "./sendState.js";
+/** How long a background send waits for the mailbox / encryption policy it did not have, before it goes ahead treating them as unknown. Nobody waits for it. */
+export const CONTEXT_GRACE_MS = 4000;
+export function registerOutboxCounter(tracker, onQueued) {
+    sendState.countTracker = tracker;
+    sendState.queuedListener = onQueued;
+    return () => {
+        if (sendState.countTracker === tracker) {
+            sendState.countTracker = undefined;
+            sendState.queuedListener = undefined;
+        }
+    };
+}
+const RETAINED_LIMIT = 25;
+/** The request a message was queued from, while this tab still holds it: what lets "Open draft" and "Retry" work on a failure the server reports later. */
+export function retainedRequest(draftUid) {
+    return sendState.retained.get(draftUid);
+}
+export function forgetRetainedRequest(draftUid) {
+    sendState.retained.delete(draftUid);
+}
+function retain(request) {
+    sendState.retained.delete(request.draft.uid);
+    sendState.retained.set(request.draft.uid, request);
+    if (sendState.retained.size > RETAINED_LIMIT) {
+        sendState.retained.delete(sendState.retained.keys().next().value);
+    }
+}
+const UNSAFE_DISPLAY_NAME_PATTERN = /[@＠﹫\r\n]/;
+/** The sender's signing/encryption key state right now, read from the tab's key session (they can lock mid-send). */
+export function readSendKeys(mailboxUid, signEnabled, mailbox) {
+    const stored = getUnlockedKeys(mailboxUid);
+    const unlocked = stored?.destroyed ? undefined : stored;
+    return {
+        unlocked,
+        canSign: signEnabled && !!mailbox && !!unlocked?.signingPrivateKey && !!unlocked.signingCertDer,
+        canEncryptSelf: !!unlocked?.encryptionPrivateKey && !!unlocked.encryptionCertDer,
+    };
+}
+/** Whether this sender could encrypt at all: an encryption key unlocked here, enrolled on the mailbox, or offered earlier this session. */
+export function senderHasEncryptionKey(request, canEncryptSelf) {
+    return canEncryptSelf || request.offeredEncrypt || !!findActivePublicKey(request.mailbox?.keys ?? [], "encrypt");
+}
+/** The input `decideSend()` reads, from a request and what has been looked up. */
+export function sendDecisionInput(request, mailbox, policy, recipients, lookupsComplete) {
+    const keys = readSendKeys(request.mailboxUid, request.signEnabled, mailbox);
+    return {
+        forcePlaintext: request.forcePlaintext,
+        signEnabled: request.signEnabled,
+        offeredSign: request.offeredSign,
+        encryptRequested: request.encryptRequested,
+        policy,
+        mailboxLoaded: !!mailbox,
+        hasEncryptionKey: senderHasEncryptionKey({ mailbox, offeredEncrypt: request.offeredEncrypt }, keys.canEncryptSelf),
+        keys: { canSign: keys.canSign, canEncryptSelf: keys.canEncryptSelf, unlocked: !!keys.unlocked },
+        recipients,
+        lookupsComplete,
+        hasBcc: request.bcc.length > 0,
+        hasAttachments: request.attachments.length > 0,
+        hasInlineImages: INLINE_IMAGE_PATTERN.test(request.html),
+    };
+}
+const OPEN_POLICY = { encryptSameOrg: "optional", encryptFederated: "optional", encryptExternal: "optional" };
+/** The mailbox and policy this send is missing, loaded now: the sender is not waiting, so a slow answer costs nothing - but it is not waited on for ever. */
+async function completeContext(request) {
+    let mailbox = request.mailbox;
+    let policy = request.policy;
+    const keysNow = readSendKeys(request.mailboxUid, request.signEnabled, mailbox);
+    const loads = [];
+    if (!mailbox) {
+        loads.push(getMailbox(request.mailboxUid).then((loaded) => void (mailbox = loaded)));
+    }
+    if (!policy && (!mailbox || senderHasEncryptionKey({ mailbox, offeredEncrypt: request.offeredEncrypt }, keysNow.canEncryptSelf))) {
+        loads.push(getEncryptionPolicy().then((loaded) => void (policy = loaded)));
+    }
+    if (loads.length > 0) {
+        let timer;
+        const grace = new Promise((resolve) => {
+            timer = setTimeout(resolve, CONTEXT_GRACE_MS);
+        });
+        await Promise.race([Promise.allSettled(loads), grace]);
+        clearTimeout(timer);
+    }
+    return { mailbox, policy };
+}
+/** Builds the message's final content into the draft (plain, signed, or signed and encrypted in this browser) and returns the stored message. */
+async function assemble(request, mailbox, mode, statuses, withSignature) {
+    const { draft, to, cc, bcc, subject, html } = request;
+    if (mode === "plain") {
+        return assembleDraft(draft.uid, { to, cc, bcc, subject, html });
+    }
+    const keys = readSendKeys(request.mailboxUid, request.signEnabled, mailbox);
+    const own = mailbox;
+    const domain = own.primarySmtpAddress.split("@")[1] ?? "localhost";
+    const displayName = own.displayName && !UNSAFE_DISPLAY_NAME_PATTERN.test(own.displayName) ? own.displayName : "";
+    const protectedHeaders = {
+        from: displayName ? `"${displayName.replace(/"/g, '\\"')}" <${own.primarySmtpAddress}>` : own.primarySmtpAddress,
+        to: to.map((r) => r.address).join(", "),
+        cc: cc.length > 0 ? cc.map((r) => r.address).join(", ") : undefined,
+        date: new Date().toUTCString(),
+        subject,
+        messageId: `<${crypto.randomUUID()}@${domain}>`,
+    };
+    const bodyContentType = 'text/html; charset="utf-8"';
+    const signing = withSignature ? { certDer: keys.unlocked.signingCertDer, privateKey: keys.unlocked.signingPrivateKey } : undefined;
+    // The S/MIME code (PKI.js and the ASN.1/X.509 libraries, over half a megabyte) is only needed here, to sign or encrypt - a plain message
+    // never loads it, and it is kept out of the compose window's own chunk.
+    const { applyBaselineOuterHeaders, assembleOutboundMime, buildEncryptedMessage, buildSignedOnlyMessage } = await import("@rapidmx/react-shared/crypto/smimeMessage.js");
+    const encrypt = mode === "encrypt";
+    const outerHeaders = encrypt ? applyBaselineOuterHeaders(protectedHeaders) : protectedHeaders;
+    const mimePart = encrypt
+        ? await buildEncryptedMessage(bodyContentType, html, protectedHeaders, outerHeaders, [keys.unlocked.encryptionCertDer, ...statuses.map((status) => fromBase64(status.encryptCert.publicKey))], signing)
+        : await buildSignedOnlyMessage(bodyContentType, html, protectedHeaders, signing.certDer, signing.privateKey);
+    const rawMime = assembleOutboundMime(outerHeaders, mimePart);
+    return assembleDraftRaw(draft.uid, { to, cc, bcc, subject: outerHeaders.subject, rawMime });
+}
+function failureOf(err, fallback) {
+    const failure = describeSendFailure(err, fallback);
+    return { message: failure.message, details: failure.lines };
+}
+/** Whether the server already holds `request`'s message as accepted (out of Drafts, or leased) - the answer to "did that request that never returned actually land?". */
+async function alreadyAccepted(request) {
+    try {
+        const fresh = await getMessage(request.draft.uid);
+        return fresh.folderUid !== request.draft.folderUid || !!fresh.scheduledSendLeaseExpiresAt || !!fresh.scheduledSendRelayedAt;
+    }
+    catch {
+        return false;
+    }
+}
+/** The whole client-side path of one send: settle, decide, assemble, hand over. Never rejects. */
+async function attempt(request) {
+    try {
+        await request.saved?.catch(() => undefined);
+        const all = [...request.to, ...request.cc, ...request.bcc];
+        let mailbox = request.mailbox;
+        let policy = request.policy;
+        let statuses = all.map(() => undefined);
+        let lookupsComplete = false;
+        if (!request.forcePlaintext) {
+            ({ mailbox, policy } = await completeContext(request));
+            const keys = readSendKeys(request.mailboxUid, request.signEnabled, mailbox);
+            const hasKey = senderHasEncryptionKey({ mailbox, offeredEncrypt: request.offeredEncrypt }, keys.canEncryptSelf);
+            // Recipients' keys are only looked up when the answer can matter: encryption was asked for, or the loaded policy auto-applies.
+            if (mailbox && hasKey && (request.encryptRequested || (policy && policyCanAutoEncrypt(policy)))) {
+                const own = mailbox;
+                const ownPrefersMutual = own.encryptPreference?.preferEncrypt === "mutual";
+                const lookups = await Promise.all(all.map((recipient) => lookupKeys(request.mailboxUid, recipient.address).then((lookup) => ({ lookup }), () => null)));
+                statuses = all.map((recipient, index) => {
+                    const found = lookups[index];
+                    return found ? resolveRecipientEncryption(own.primarySmtpAddress, ownPrefersMutual, policy ?? OPEN_POLICY, recipient.address, found.lookup) : undefined;
+                });
+            }
+            lookupsComplete = true;
+        }
+        const decision = decideSend(sendDecisionInput(request, mailbox, policy, statuses, lookupsComplete));
+        if (decision.action === "blocked") {
+            return { kind: "failed", failure: { message: decision.block.message, details: [], block: decision.block } };
+        }
+        if (decision.action === "rejected") {
+            return { kind: "failed", failure: { message: decision.message, details: [] } };
+        }
+        const assembled = await assemble(request, mailbox, decision.action, statuses, decision.action === "sign" || (decision.action === "encrypt" && decision.sign));
+        const withReceipt = request.requestReceipt ? await setMessageRequestReceipt(assembled, true) : assembled;
+        setPendingStage(request.draft.uid, "queuing");
+        try {
+            if (request.scheduledSendTime) {
+                await sendMessage(withReceipt.uid, { scheduledSendTime: request.scheduledSendTime });
+                return { kind: "scheduled" };
+            }
+            const result = await queueMessageSend(withReceipt.uid);
+            return { kind: result.queued ? "queued" : "sent" };
+        }
+        catch (err) {
+            // A request that never came back may still have landed: never offer to send it twice if it did.
+            if (!(err instanceof ApiRequestError) && (await alreadyAccepted(request))) {
+                return { kind: request.scheduledSendTime ? "scheduled" : "queued" };
+            }
+            throw err;
+        }
+    }
+    catch (err) {
+        return { kind: "failed", failure: failureOf(err, request.scheduledSendTime ? "Could not schedule this message." : "Could not send this message.") };
+    }
+}
+function recipientSummary(request) {
+    const all = [...request.to, ...request.cc, ...request.bcc].map((recipient) => recipient.address);
+    return all.length <= 2 ? all.join(" and ") : `${all[0]} and ${all.length - 1} others`;
+}
+/** "Message to a@b.c and 2 others (\"Subject\")" - which message a pop-up is about. */
+export function describeMessage(subject, recipients) {
+    return `${recipients ? `To ${recipients}` : "Message"}${subject ? ` - "${subject}"` : ""}`;
+}
+/** Re-opens the compose window around a request's message, with everything as it was typed. */
+export function openDraftFromRequest(request) {
+    return openComposeFromOutside({
+        mailboxUid: request.mailboxUid,
+        resume: {
+            draft: request.draft,
+            mailboxUid: request.mailboxUid,
+            to: request.toText,
+            cc: request.ccText,
+            bcc: request.bccText,
+            subject: request.subject,
+            html: request.html,
+            attachments: request.attachments,
+            requestReceipt: request.requestReceipt,
+            signEnabled: request.signEnabled,
+            encryptRequested: request.encryptRequested,
+        },
+    });
+}
+function failureNotificationId(draftUid) {
+    return `send-failed:${draftUid}`;
+}
+/** The sticky "This message wasn't sent" pop-up for a send that failed on this side, with what can be done about it. */
+function notifyFailure(request, failure) {
+    const uid = request.draft.uid;
+    const actions = [];
+    const { block } = failure;
+    if (block?.keysLocked && request.mailbox?.keys?.length) {
+        actions.push({
+            label: "Unlock",
+            onClick: () => {
+                void requestUnlockFromOutside(request.mailboxUid, request.mailbox.keys).then(() => void retrySend(request), () => undefined);
+            },
+        });
+    }
+    if (block) {
+        actions.push({ label: block.overrideLabel, onClick: () => void retrySend({ ...request, forcePlaintext: true }) });
+    }
+    else {
+        actions.push({ label: "Retry", onClick: () => void retrySend(request) });
+    }
+    actions.push({ label: "Open draft", onClick: () => void openDraftFromRequest(request) });
+    notify({
+        id: failureNotificationId(uid),
+        kind: "error",
+        title: "This message wasn't sent",
+        message: `${describeMessage(request.subject, recipientSummary(request))}: ${failure.message}`,
+        details: failure.details,
+        actions,
+    });
+}
+const SENT_BURST_MS = 6000;
+/** The short "Message sent" confirmation - several sent close together are one pop-up counting up, never a stack of them. */
+export function notifySent(message = "Message sent") {
+    const now = Date.now();
+    const { sentBurst } = sendState;
+    sendState.sentBurst = { count: now - sentBurst.at > SENT_BURST_MS ? 1 : sentBurst.count + 1, at: now };
+    notify({ id: "message-sent", kind: "success", title: sendState.sentBurst.count > 1 ? `${sendState.sentBurst.count} messages sent` : message, timeoutMs: 4000 });
+}
+/**
+ * Sends `request`'s draft in the background and returns at once, `true` - or `false` (doing nothing) when a send of this draft is already
+ * under way here. The outcome is shown as pop-ups and the Outbox indicator, never as a window that waits: a failure at any stage (assembling,
+ * encrypting, the request) is a sticky "This message wasn't sent" with the reason, and Retry / Open draft; the server's own later outcome
+ * (`send-succeeded`, `send-failed`, `send-retrying`) is `handleSendEvent()`'s.
+ */
+export function startSend(request) {
+    const uid = request.draft.uid;
+    const recipients = [...request.to, ...request.cc, ...request.bcc].map((recipient) => recipient.address);
+    if (!beginPendingSend({ draftUid: uid, mailboxUid: request.mailboxUid, subject: request.subject, recipients, scheduled: !!request.scheduledSendTime })) {
+        return false;
+    }
+    // The failure of an earlier attempt is resolved by trying again.
+    dismiss(failureNotificationId(uid));
+    const tracker = sendState.countTracker?.(request.mailboxUid);
+    void attempt(request).then((outcome) => {
+        finishPendingSend(uid);
+        if (outcome.kind === "failed") {
+            tracker?.revert();
+            notifyFailure(request, outcome.failure);
+            return;
+        }
+        tracker?.settle();
+        if (outcome.kind === "queued") {
+            retain(request);
+            sendState.queuedListener?.(request.mailboxUid);
+        }
+        else if (outcome.kind === "sent") {
+            notifySent();
+        }
+        else {
+            notify({
+                id: `scheduled:${uid}`,
+                kind: "success",
+                title: "Message scheduled",
+                message: `It will be sent ${new Date(request.scheduledSendTime).toLocaleString()}.`,
+                timeoutMs: 5000,
+            });
+        }
+    });
+    return true;
+}
+/** Tries a failed send again - unless the server already has the message (an earlier request that seemed to fail did land), which it must not send twice. */
+export async function retrySend(request) {
+    if (await alreadyAccepted(request)) {
+        dismiss(failureNotificationId(request.draft.uid));
+        notify({ id: `already-sent:${request.draft.uid}`, kind: "info", title: "This message is already on its way", timeoutMs: 5000 });
+        return;
+    }
+    startSend({ ...request, saved: undefined });
+}

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

@@ -0,0 +1,3 @@
+import { SendEvent } from "@rapidmx/react-shared/mail/sendEvents.js";
+/** Shows what a send event means to the user. */
+export declare function handleSendEvent(event: SendEvent): void;

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

@@ -0,0 +1,141 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { cancelScheduledSend, getMessage, listAttachments, listFolders, queueMessageSend } from "@rapidmx/react-shared/mail/mailApi.js";
+import { describeSendEventError } from "@rapidmx/react-shared/mail/sendEvents.js";
+import { formatRecipient } from "../../components/mail/compose/recipients.js";
+import { loadOriginalMessage } from "../../components/mail/compose/quotedBody.js";
+import { notifyApiError } from "../../notifications/apiErrors.js";
+import { dismiss, notify } from "../../notifications/store.js";
+import { beginPendingSend, finishPendingSend, setPendingStage } from "./pendingSends.js";
+import { openComposeFromOutside } from "./composeBridge.js";
+import { describeMessage, forgetRetainedRequest, notifySent, openDraftFromRequest, retainedRequest } from "./sendJob.js";
+/**
+ * What the user is told when the server reports how a queued message went (`send-succeeded`, `send-failed`, `send-retrying` push events,
+ * see `@rapidmx/react-shared`'s `parseSendEvent()`): a quiet, single "Message sent" for a message this tab sent (several close together are
+ * one pop-up counting up), an info pop-up when a delivery is retried, and - only when it finally failed - the sticky "This message wasn't sent" with the
+ * server's reason, its technical details and what to do about it. The Outbox count, list and pill update themselves from the same events
+ * (`useMailLiveUpdates()` refreshes on them).
+ */
+const retryId = (uid) => `send-retry:${uid}`;
+const failedId = (uid) => `send-failed:${uid}`;
+function summary(recipients) {
+    return recipients.length <= 2 ? recipients.join(" and ") : `${recipients[0]} and ${recipients.length - 1} others`;
+}
+/** Moves a message the server failed to relay back into Drafts (the only place it can be edited or sent again), and returns it as it is there. */
+async function moveBackToDrafts(uid, mailboxUid) {
+    const message = await getMessage(uid);
+    const drafts = (await listFolders(mailboxUid)).find((folder) => folder.type === "drafts");
+    if (!drafts || message.folderUid === drafts.uid) {
+        return message;
+    }
+    return cancelScheduledSend(message, drafts.uid);
+}
+function escapeHtml(text) {
+    return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+/** "Open draft" for a message the server failed to relay: back into Drafts, and into a compose window with what was written. */
+async function openFailedDraft(event) {
+    try {
+        const moved = await moveBackToDrafts(event.uid, event.mailboxUid ?? "");
+        const request = retainedRequest(event.uid);
+        if (request) {
+            openDraftFromRequest({ ...request, draft: moved });
+            return;
+        }
+        if (moved.encrypted) {
+            notify({
+                id: `open-draft:${event.uid}`,
+                kind: "info",
+                title: "This message is encrypted",
+                message: "It was moved back to Drafts, but it can only be edited in the tab that wrote it. Open it from Drafts to send it again.",
+                timeoutMs: 8000,
+            });
+            return;
+        }
+        const original = await loadOriginalMessage(moved, null);
+        const attachments = await listAttachments(moved.folderUid, moved.uid).catch(() => []);
+        const byType = (type) => moved.recipients.filter((recipient) => recipient.type === type).map(formatRecipient).join(", ");
+        openComposeFromOutside({
+            mailboxUid: moved.mailboxUid,
+            resume: {
+                draft: moved,
+                mailboxUid: moved.mailboxUid,
+                to: byType("to"),
+                cc: byType("cc"),
+                bcc: byType("bcc"),
+                subject: moved.subject ?? event.subject,
+                html: original.body.html ?? (original.body.text ? `<p>${escapeHtml(original.body.text).replace(/\r?\n/g, "<br>")}</p>` : ""),
+                attachments,
+                requestReceipt: !!moved.requestReceipt,
+                signEnabled: true,
+                encryptRequested: false,
+            },
+        });
+    }
+    catch (err) {
+        notifyApiError(err, "Couldn't open this draft");
+    }
+}
+/** "Retry" for a message the server failed to relay: the same send call again - a failed message stays in Outbox and the server queues it afresh (with a new retry budget). */
+async function retryFailed(event) {
+    if (!beginPendingSend({ draftUid: event.uid, mailboxUid: event.mailboxUid ?? "", subject: event.subject, recipients: event.recipients, scheduled: false })) {
+        return;
+    }
+    dismiss(failedId(event.uid));
+    try {
+        setPendingStage(event.uid, "queuing");
+        const result = await queueMessageSend(event.uid);
+        if (!result.queued) {
+            notifySent();
+        }
+    }
+    catch (err) {
+        notifyApiError(err, "This message wasn't sent", { dedupeKey: failedId(event.uid) });
+    }
+    finally {
+        finishPendingSend(event.uid);
+    }
+}
+/** Shows what a send event means to the user. */
+export function handleSendEvent(event) {
+    if (event.action === "send-succeeded") {
+        dismiss(retryId(event.uid));
+        dismiss(failedId(event.uid));
+        // The server reports every message it relays, scheduled ones from long ago included: only a message this tab queued in the background is
+        // worth a confirmation (several are one pop-up counting up). Anything else - a send-later message going out, another tab's send - is quiet.
+        if (retainedRequest(event.uid)) {
+            forgetRetainedRequest(event.uid);
+            notifySent();
+        }
+        return;
+    }
+    const failure = describeSendEventError(event.error, event.action === "send-failed" ? "The server couldn't send this message." : "The server couldn't send this message yet.");
+    const what = describeMessage(event.subject, summary(event.recipients));
+    if (event.action === "send-retrying") {
+        const next = event.nextAttemptAt ? Date.parse(event.nextAttemptAt) : NaN;
+        notify({
+            id: retryId(event.uid),
+            kind: "info",
+            title: "Retrying to send",
+            message: `${what} (attempt ${event.attempt + 1}${Number.isNaN(next) ? "" : `, at ${new Date(next).toLocaleTimeString()}`}). ${failure.message}`,
+            details: failure.lines,
+            sticky: false,
+            timeoutMs: 8000,
+        });
+        return;
+    }
+    dismiss(retryId(event.uid));
+    notify({
+        id: failedId(event.uid),
+        kind: "error",
+        title: "This message wasn't sent",
+        message: `${what}: ${failure.message}`,
+        details: failure.lines,
+        actions: [
+            { label: "Retry", onClick: () => void retryFailed(event) },
+            { label: "Open draft", onClick: () => void openFailedDraft(event) },
+        ],
+    });
+}

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

@@ -0,0 +1,25 @@
+import type { SendRequest } from "./sendJob.js";
+/**
+ * The module-level state of the background send (`sendJob.ts`), kept in a module with no imports of its own: a test setup can reset it after each
+ * test without loading the send code (and everything that code imports) before a test file has had the chance to mock it.
+ */
+/** Registered by the frame: puts an optimistic +1 on the Outbox count for `mailboxUid`, at once, and says how to settle or take it back. */
+export interface OutboxCountTracker {
+    settle(): void;
+    revert(): void;
+}
+export declare const sendState: {
+    countTracker: ((mailboxUid: string) => OutboxCountTracker) | undefined;
+    /** Called after the server accepted a message into Outbox - the frame reads the folders back (the Outbox may not have existed before). */
+    queuedListener: ((mailboxUid: string) => void) | undefined;
+    /** What is kept of each message the server accepted, so a later failure reported by push event can offer "Open draft" and "Retry" with
+     * the content intact (a message that was encrypted before it was stored can't be read back from the server). Bounded; this tab's only. */
+    retained: Map<string, SendRequest>;
+    /** "Message sent" confirmations close together are one pop-up counting up. */
+    sentBurst: {
+        count: number;
+        at: number;
+    };
+};
+/** Forgets everything - for a test. */
+export declare function resetSendJobs(): void;

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

@@ -0,0 +1,8 @@
+export const sendState = { countTracker: undefined, queuedListener: undefined, retained: new Map(), sentBurst: { count: 0, at: 0 } };
+/** Forgets everything - for a test. */
+export function resetSendJobs() {
+    sendState.countTracker = undefined;
+    sendState.queuedListener = undefined;
+    sendState.retained.clear();
+    sendState.sentBurst = { count: 0, at: 0 };
+}

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

@@ -0,0 +1,11 @@
+import type { MailboxFolders } from "../../components/mail/layout/MailShell.js";
+import { FolderCount } from "../folderCounts.js";
+import { OutboxFolderStatus } 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 declare 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 declare function useOutboxStatus(mailboxFolders: MailboxFolders[], counts: Record<string, FolderCount>, liveTick: number, enabled: boolean): Record<string, OutboxFolderStatus>;

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

@@ -0,0 +1,49 @@
+///////////////////////////////////////////////////////////////////////////////
+// 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 { countOfFolder } from "../folderCounts.js";
+import { 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, counts, liveTick, enabled) {
+    const [statuses, setStatuses] = useState({});
+    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/dist/apps/shared/mail/useMailConnection.d.ts

@@ -0,0 +1,56 @@
+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;
+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 {
+    /** Where the one `listMailboxes()` call is. */
+    status: MailConnectionStatus;
+    /** Why `status` is `"error"`. */
+    error: string | null;
+    mailboxes: Mailbox[];
+    /** Every accessible mailbox's own mail folders, one entry per mailbox - see `MailboxFolders`. */
+    mailboxFolders: MailboxFolders[];
+    /** Their folder lists are still being fetched. */
+    foldersLoading: boolean;
+    /** Files a folder that was just created (by this client or another) under its mailbox, so the sidebar and every folder picker show it. */
+    onFolderCreated: (folder: Folder) => void;
+    /** 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>;
+export interface UseMailConnectionOptions {
+    /** Nothing is fetched, and no socket opened, without a signed-in user. */
+    userUid?: string;
+    /** Runs only while true. The frame turns it on; a Mail shell rendered outside a frame turns it on for itself; and the one that isn't
+     * the owner leaves it off - so exactly one connection exists, whichever of them the page is rendered by. */
+    enabled: boolean;
+    /** Opens a message from a desktop notification's click (the router's `useNavigate()`); defaults to a plain navigation. */
+    open?: (href: string) => void;
+}
+/**
+ * The user's mailboxes and their mail folders, plus the live connection that keeps them - and the badges, the list, the new-mail
+ * pop-ups - current. It is everything `MailShell` used to do on mount, gathered so that it can live in the persistent app frame instead: the
+ * push socket (the server allows ten per user), the safety-net poll, the folder counters and the pop-ups then belong to the signed-in session
+ * rather than to whichever page happens to be showing, and keep working in Calendar, Contacts, Tasks and Settings. `MailShell` reads the same
+ * state from `MailConnectionContext` when there is a frame, and runs this hook itself when there isn't (a page rendered outside the router).
+ */
+export declare function useMailConnection({ userUid, enabled, open }: UseMailConnectionOptions): MailConnection;