@rapidmx/web-client 0.10.0 → 0.12.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/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;

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

@@ -0,0 +1,42 @@
+/** 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 const DUE_SLACK_MS = 2000;
+export function outboxItemStatus(message, now = Date.now()) {
+    const attempts = message.scheduledSendAttempts ?? 0;
+    const lease = message.scheduledSendLeaseExpiresAt ? Date.parse(message.scheduledSendLeaseExpiresAt) : NaN;
+    const at = message.scheduledSendTime ? Date.parse(message.scheduledSendTime) : NaN;
+    if (message.scheduledSendError && !message.scheduledSendTime && !(lease > now)) {
+        return { state: "failed", attempts, error: message.scheduledSendError };
+    }
+    if (lease > now) {
+        return { state: attempts > 0 ? "retrying" : "sending", attempts };
+    }
+    if (attempts > 0) {
+        return { state: "retrying", attempts, at: Number.isNaN(at) ? undefined : at };
+    }
+    const modified = message.dateModified ? Date.parse(message.dateModified) : NaN;
+    const dueWhenModified = at - modified <= DUE_SLACK_MS;
+    if (at > now && !dueWhenModified) {
+        return { state: "scheduled", attempts, at };
+    }
+    return { state: "sending", attempts };
+}
+export const EMPTY_OUTBOX_STATUS = { sending: 0, retrying: 0, failed: 0, scheduled: 0 };
+export function summarizeOutbox(messages, now = Date.now()) {
+    const status = { ...EMPTY_OUTBOX_STATUS };
+    for (const message of messages) {
+        status[outboxItemStatus(message, now).state] += 1;
+    }
+    return status;
+}
+/** The text a screen reader gets for an Outbox count, and the tooltip: "2 messages sending", "3 messages, 1 failed". */
+export function outboxLabel(total, status, pendingHere) {
+    const noun = `${total} ${total === 1 ? "message" : "messages"}`;
+    if (status && status.failed > 0) {
+        return `${noun}, ${status.failed} failed`;
+    }
+    const inFlight = (status ? status.sending + status.retrying : 0) + pendingHere;
+    if (inFlight > 0) {
+        return `${noun} sending`;
+    }
+    return status && status.scheduled > 0 && status.scheduled === total ? `${noun} scheduled` : noun;
+}

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

@@ -0,0 +1,39 @@
+/**
+ * The messages this tab has been asked to send whose *client-side* work is not finished: assembling (and encrypting/signing, which takes
+ * a moment) and the request that hands them to the server. Once the server has answered `202 queued` a message is safe - the server
+ * owns it, and the Outbox folder's own count, list and push events say the rest - so it leaves this set.
+ *
+ * What this is for: the Outbox indicator counts these at once (before the server has heard of the message), a message in this set is
+ * why the tab asks "Leave site?" (`beforeunload`) and why Sign Out waits a moment before ending the session, and a second Send of the same
+ * draft is refused while it is here.
+ */
+export type PendingStage = "preparing" | "queuing";
+export interface PendingSend {
+    /** The draft's uid: one send per draft at a time. */
+    draftUid: string;
+    mailboxUid: string;
+    subject: string;
+    /** Every recipient's address. */
+    recipients: string[];
+    stage: PendingStage;
+    /** A send-later message: it goes to Outbox and waits for its time, rather than being relayed. */
+    scheduled: boolean;
+    startedAt: number;
+}
+/** Whether a send of this draft is under way in this tab. */
+export declare function isSendPending(draftUid: string): boolean;
+/** Starts tracking a send. `false` (and nothing tracked) when this draft is already being sent - the caller must not send it again. */
+export declare function beginPendingSend(entry: Omit<PendingSend, "stage" | "startedAt">): boolean;
+export declare function setPendingStage(draftUid: string, stage: PendingStage): void;
+/** The server has the message (or the attempt failed and is now the user's to resolve): it is no longer this tab's work. */
+export declare function finishPendingSend(draftUid: string): void;
+export declare function getPendingSends(): readonly PendingSend[];
+export declare function subscribePendingSends(listener: () => void): () => void;
+/** How many messages of `mailboxUid` are still being handed to the server: what the Outbox pill adds to its server count at once. */
+export declare function pendingCountFor(mailboxUid: string, sends?: readonly PendingSend[]): number;
+/** Resolves (to whether everything settled) when no send is pending, or after `timeoutMs`. */
+export declare function whenSettled(timeoutMs: number): Promise<boolean>;
+/** The messages being sent, for a component. */
+export declare function usePendingSends(): readonly PendingSend[];
+/** Forgets everything - for a test. */
+export declare function resetPendingSends(): void;

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

@@ -0,0 +1,109 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { useSyncExternalStore } from "react";
+import { registerComposeFlush } from "../../components/mail/compose/composeFlushRegistry.js";
+const NO_SENDS = [];
+let pending = [];
+let snapshot = pending;
+const listeners = new Set();
+let stopFlush;
+let waiters = [];
+function emit() {
+    snapshot = [...pending];
+    for (const listener of [...listeners]) {
+        listener();
+    }
+}
+/** `beforeunload`: leaving now would lose a message the server has not received. */
+function handleBeforeUnload(event) {
+    // Only installed while something is pending (see `syncGuards()`).
+    event.preventDefault();
+    event.returnValue = "";
+}
+/** Installs the `beforeunload` prompt and the sign-out wait while a send is pending, and takes them away when none is. Only ever called from a browser. */
+function syncGuards() {
+    if (pending.length > 0 && !stopFlush) {
+        window.addEventListener("beforeunload", handleBeforeUnload);
+        // Sign Out flushes compose windows before it ends the session; a message still being prepared is waited for there too.
+        stopFlush = registerComposeFlush(() => whenSettled(20000));
+    }
+    else if (pending.length === 0 && stopFlush) {
+        window.removeEventListener("beforeunload", handleBeforeUnload);
+        stopFlush();
+        stopFlush = undefined;
+    }
+    if (pending.length === 0) {
+        const done = waiters;
+        waiters = [];
+        for (const resolve of done) {
+            resolve();
+        }
+    }
+}
+/** Whether a send of this draft is under way in this tab. */
+export function isSendPending(draftUid) {
+    return pending.some((entry) => entry.draftUid === draftUid);
+}
+/** Starts tracking a send. `false` (and nothing tracked) when this draft is already being sent - the caller must not send it again. */
+export function beginPendingSend(entry) {
+    if (isSendPending(entry.draftUid)) {
+        return false;
+    }
+    pending.push({ ...entry, stage: "preparing", startedAt: Date.now() });
+    syncGuards();
+    emit();
+    return true;
+}
+export function setPendingStage(draftUid, stage) {
+    pending = pending.map((entry) => (entry.draftUid === draftUid ? { ...entry, stage } : entry));
+    emit();
+}
+/** The server has the message (or the attempt failed and is now the user's to resolve): it is no longer this tab's work. */
+export function finishPendingSend(draftUid) {
+    pending = pending.filter((entry) => entry.draftUid !== draftUid);
+    syncGuards();
+    emit();
+}
+export function getPendingSends() {
+    return snapshot;
+}
+export function subscribePendingSends(listener) {
+    listeners.add(listener);
+    return () => {
+        listeners.delete(listener);
+    };
+}
+/** How many messages of `mailboxUid` are still being handed to the server: what the Outbox pill adds to its server count at once. */
+export function pendingCountFor(mailboxUid, sends = snapshot) {
+    return sends.filter((entry) => entry.mailboxUid === mailboxUid).length;
+}
+/** Resolves (to whether everything settled) when no send is pending, or after `timeoutMs`. */
+export function whenSettled(timeoutMs) {
+    if (pending.length === 0) {
+        return Promise.resolve(true);
+    }
+    return new Promise((resolve) => {
+        const timer = setTimeout(() => {
+            waiters = waiters.filter((waiter) => waiter !== done);
+            resolve(false);
+        }, timeoutMs);
+        function done() {
+            clearTimeout(timer);
+            resolve(true);
+        }
+        waiters.push(done);
+    });
+}
+/** The messages being sent, for a component. */
+export function usePendingSends() {
+    return useSyncExternalStore(subscribePendingSends, getPendingSends, () => NO_SENDS);
+}
+/** Forgets everything - for a test. */
+export function resetPendingSends() {
+    pending = [];
+    waiters = [];
+    syncGuards();
+    emit();
+}

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

@@ -0,0 +1,80 @@
+import { RecipientEncryptionStatus } from "@rapidmx/react-shared/crypto/composeSecurity.js";
+import type { EncryptionPolicy } from "@rapidmx/react-shared/crypto/keyvaultApi.js";
+/** Signed/encrypted bodies are built client-side from the editor's HTML verbatim, so an inline image (an uploaded attachment previewed via
+ * its content URL, or a `cid:` reference) would never be carried - only `assembleDraft()`'s server-side plaintext path rewrites those into
+ * real MIME parts. */
+export declare const INLINE_IMAGE_PATTERN: RegExp;
+export declare const KEYS_LOCKED_SIGN_MESSAGE = "This message can't be signed right now - your signing key is locked or your mailbox details couldn't be loaded. Unlock and send again, or send it without signing.";
+export declare const KEYS_LOCKED_ENCRYPT_MESSAGE = "This message can't be encrypted right now - your encryption key is locked. Unlock and send again, or send it without encryption.";
+export declare const BCC_ENCRYPTED_MESSAGE = "Bcc recipients can't be used with encrypted messages. Remove Bcc recipients or turn off encryption.";
+export declare const LOOKUP_UNAVAILABLE_MESSAGE = "Your recipients' encryption keys couldn't be checked, so this message can't be encrypted right now. Try again, or send it without encryption.";
+/** The plain sentence for recipients an encrypted message can't reach (no key on file, or the policy prohibits it). */
+export declare function recipientsBlockedMessage(blocked: RecipientEncryptionStatus[]): string;
+export declare const MAILBOX_UNAVAILABLE_MESSAGE = "Your mailbox details couldn't be loaded, so this message can't be encrypted right now. Try again, or send it without encryption.";
+export declare const ATTACHMENTS_UNSUPPORTED_MESSAGE = "A signed or encrypted message cannot include file attachments yet - remove them before sending.";
+export declare const INLINE_IMAGES_UNSUPPORTED_MESSAGE = "A signed or encrypted message cannot include inline images yet - remove them before sending.";
+/** Why a send is refused *before* anything is sent: signing/encryption was asked for (or applies) but cannot happen right now. Never a silent
+ * downgrade to plaintext - the sender explicitly picks the override. */
+export interface SendBlock {
+    kind: "signing-locked" | "encryption-locked" | "lookup-failed" | "mailbox-unavailable" | "bcc" | "recipients";
+    message: string;
+    /** The button that sends it anyway, without encryption (and without signing when that is what was blocked). */
+    overrideLabel: string;
+    /** The cause is keys that are enrolled but not unlocked in this tab: an Unlock action helps. */
+    keysLocked: boolean;
+    /** `recipients`: who has no key (or is not allowed one). */
+    blockedRecipients?: RecipientEncryptionStatus[];
+}
+export type SendDecision = {
+    action: "plain";
+} | {
+    action: "sign";
+} | {
+    action: "encrypt";
+    sign: boolean;
+} | {
+    action: "blocked";
+    block: SendBlock;
+}
+/** Not sendable as composed, and no override helps: fix the message. */
+ | {
+    action: "rejected";
+    message: string;
+};
+export interface SendDecisionInput {
+    /** The sender's explicit choice to skip every encryption/signing check (an override button): it never encrypts, and still signs if it can. */
+    forcePlaintext: boolean;
+    /** The "sign" checkbox. */
+    signEnabled: boolean;
+    /** The signing option was shown at some point this compose session (the keys were unlocked): losing the keys then blocks, never silently unsigns. */
+    offeredSign: boolean;
+    encryptRequested: boolean;
+    policy: EncryptionPolicy | undefined;
+    mailboxLoaded: boolean;
+    hasEncryptionKey: boolean;
+    keys: {
+        /** Signing is possible now: enabled, mailbox loaded (for the protected headers), signing key unlocked. */
+        canSign: boolean;
+        /** The encryption key is unlocked. */
+        canEncryptSelf: boolean;
+        /** Any key material is unlocked in this tab. */
+        unlocked: boolean;
+    };
+    /** Every recipient (To, Cc and Bcc), resolved; `undefined` where the lookup failed - or, with `lookupsComplete: false`, was not made. */
+    recipients: (RecipientEncryptionStatus | undefined)[];
+    /** Whether the lookups were all *attempted*: `false` for the early check a compose window makes from what it already knows. */
+    lookupsComplete: boolean;
+    hasBcc: boolean;
+    hasAttachments: boolean;
+    hasInlineImages: boolean;
+}
+/**
+ * How a message may go out, decided from the facts alone (no requests, no React): plain, signed, encrypted, refused with an override the sender
+ * can choose, or rejected outright. Used twice with the same rules - by the compose window, from what it already knows, to catch a problem
+ * *before* it closes (`lookupsComplete: false`), and by the background send, once its recipient lookups are in.
+ *
+ * Encryption follows `evaluateEncryptionRequirement()` - fail open: only a message the user asked to encrypt, or one the loaded policy
+ * encrypts, is encrypted; everything unknown is plain and sends. The one place unknown blocks is a message the user *explicitly* asked to
+ * encrypt whose recipients' keys could not be looked up: they asked for encryption, and it cannot be delivered.
+ */
+export declare function decideSend(input: SendDecisionInput): SendDecision;

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

@@ -0,0 +1,94 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { decideMessageEncryption } from "@rapidmx/react-shared/crypto/composeSecurity.js";
+import { evaluateEncryptionRequirement } from "../../components/mail/compose/encryptionRequirement.js";
+/** Signed/encrypted bodies are built client-side from the editor's HTML verbatim, so an inline image (an uploaded attachment previewed via
+ * its content URL, or a `cid:` reference) would never be carried - only `assembleDraft()`'s server-side plaintext path rewrites those into
+ * real MIME parts. */
+export const INLINE_IMAGE_PATTERN = /<img\b[^>]*\bsrc\s*=\s*["']?(?:cid:|[^"'\s>]*\/mail\/attachments\/[^"'\s>]+\/content)/i;
+export const KEYS_LOCKED_SIGN_MESSAGE = "This message can't be signed right now - your signing key is locked or your mailbox details couldn't be loaded. Unlock and send again, or send it without signing.";
+export const KEYS_LOCKED_ENCRYPT_MESSAGE = "This message can't be encrypted right now - your encryption key is locked. Unlock and send again, or send it without encryption.";
+export const BCC_ENCRYPTED_MESSAGE = "Bcc recipients can't be used with encrypted messages. Remove Bcc recipients or turn off encryption.";
+export const LOOKUP_UNAVAILABLE_MESSAGE = "Your recipients' encryption keys couldn't be checked, so this message can't be encrypted right now. Try again, or send it without encryption.";
+/** The plain sentence for recipients an encrypted message can't reach (no key on file, or the policy prohibits it). */
+export function recipientsBlockedMessage(blocked) {
+    const reason = blocked[0]?.prohibitedReason ? ` — ${blocked[0].prohibitedReason}` : " has no encryption key on file";
+    return `This message can’t be encrypted for everyone: ${blocked.map((r) => r.address).join(", ")}${reason}. Remove ${blocked.length > 1 ? "these recipients" : "this recipient"} from To/Cc/Bcc, or send the whole message in plaintext.`;
+}
+export const MAILBOX_UNAVAILABLE_MESSAGE = "Your mailbox details couldn't be loaded, so this message can't be encrypted right now. Try again, or send it without encryption.";
+export const ATTACHMENTS_UNSUPPORTED_MESSAGE = "A signed or encrypted message cannot include file attachments yet - remove them before sending.";
+export const INLINE_IMAGES_UNSUPPORTED_MESSAGE = "A signed or encrypted message cannot include inline images yet - remove them before sending.";
+/**
+ * How a message may go out, decided from the facts alone (no requests, no React): plain, signed, encrypted, refused with an override the sender
+ * can choose, or rejected outright. Used twice with the same rules - by the compose window, from what it already knows, to catch a problem
+ * *before* it closes (`lookupsComplete: false`), and by the background send, once its recipient lookups are in.
+ *
+ * Encryption follows `evaluateEncryptionRequirement()` - fail open: only a message the user asked to encrypt, or one the loaded policy
+ * encrypts, is encrypted; everything unknown is plain and sends. The one place unknown blocks is a message the user *explicitly* asked to
+ * encrypt whose recipients' keys could not be looked up: they asked for encryption, and it cannot be delivered.
+ */
+export function decideSend(input) {
+    const { keys } = input;
+    const attachmentsAreAProblem = (encrypting) => (encrypting || keys.canSign) && input.hasAttachments;
+    const imagesAreAProblem = (encrypting) => (encrypting || keys.canSign) && input.hasInlineImages;
+    if (input.forcePlaintext) {
+        if (attachmentsAreAProblem(false)) {
+            return { action: "rejected", message: ATTACHMENTS_UNSUPPORTED_MESSAGE };
+        }
+        if (imagesAreAProblem(false)) {
+            return { action: "rejected", message: INLINE_IMAGES_UNSUPPORTED_MESSAGE };
+        }
+        return keys.canSign ? { action: "sign" } : { action: "plain" };
+    }
+    if (input.signEnabled && input.offeredSign && !keys.canSign) {
+        return {
+            action: "blocked",
+            block: { kind: "signing-locked", message: KEYS_LOCKED_SIGN_MESSAGE, overrideLabel: "Send without signing or encryption", keysLocked: !keys.unlocked },
+        };
+    }
+    if (input.encryptRequested && !input.mailboxLoaded) {
+        // Asked for explicitly, and there is nothing to encrypt with (the sender's address and keys come from the mailbox).
+        return { action: "blocked", block: { kind: "mailbox-unavailable", message: MAILBOX_UNAVAILABLE_MESSAGE, overrideLabel: "Send without encryption", keysLocked: false } };
+    }
+    const requirement = evaluateEncryptionRequirement({
+        encryptRequested: input.encryptRequested,
+        policy: input.policy,
+        mailboxLoaded: input.mailboxLoaded,
+        hasEncryptionKey: input.hasEncryptionKey,
+        recipients: input.recipients,
+    });
+    const encrypting = requirement.required;
+    if (encrypting) {
+        const statuses = input.recipients.filter((status) => !!status);
+        const allResolved = statuses.length === input.recipients.length;
+        if (!allResolved && input.lookupsComplete) {
+            // Only reachable for an explicit request (a policy requirement needs every status): the sender asked for encryption and the
+            // recipients' keys could not be checked.
+            return { action: "blocked", block: { kind: "lookup-failed", message: LOOKUP_UNAVAILABLE_MESSAGE, overrideLabel: "Send without encryption", keysLocked: false } };
+        }
+        if (!keys.canEncryptSelf) {
+            return { action: "blocked", block: { kind: "encryption-locked", message: KEYS_LOCKED_ENCRYPT_MESSAGE, overrideLabel: "Send without encryption", keysLocked: !keys.unlocked } };
+        }
+        if (allResolved) {
+            const decision = decideMessageEncryption(statuses);
+            if (!decision.canEncryptAll) {
+                return {
+                    action: "blocked",
+                    block: { kind: "recipients", message: recipientsBlockedMessage(decision.blockedRecipients), overrideLabel: "Send without encryption", keysLocked: false, blockedRecipients: decision.blockedRecipients },
+                };
+            }
+        }
+        if (input.hasBcc) {
+            return { action: "blocked", block: { kind: "bcc", message: BCC_ENCRYPTED_MESSAGE, overrideLabel: "Send without encryption", keysLocked: false } };
+        }
+    }
+    if (attachmentsAreAProblem(encrypting)) {
+        return { action: "rejected", message: ATTACHMENTS_UNSUPPORTED_MESSAGE };
+    }
+    if (imagesAreAProblem(encrypting)) {
+        return { action: "rejected", message: INLINE_IMAGES_UNSUPPORTED_MESSAGE };
+    }
+    return encrypting ? { action: "encrypt", sign: keys.canSign } : keys.canSign ? { action: "sign" } : { action: "plain" };
+}