@rapidmx/web-client 0.20.0 → 0.21.0

package/apps/shared/mail/useMailboxUpdateAccess.ts

@@ -1,60 +1,60 @@
-///////////////////////////////////////////////////////////////////////////////
-// Copyright (C) 2026 Jean-Philippe Steinmetz
-// SPDX-License-Identifier: MPL-2.0
-///////////////////////////////////////////////////////////////////////////////
-import { useEffect, useState } from "react";
-import type { Mailbox } from "@rapidmx/react-shared/mail/mailApi.js";
-import { getMyMailboxAccess } from "@rapidmx/react-shared/mail/mailboxAccessApi.js";
-
-/** What the server said about the caller's update access to a mailbox, remembered per mailbox for the page load. */
-const answers = new Map<string, Promise<boolean | undefined>>();
-
-/** Forgets every remembered answer - for the tests, and anything that changes the caller's access mid-session. */
-export function clearMailboxUpdateAccessCache(): void {
-    answers.clear();
-}
-
-/** Whether the caller may change things in `mailboxUid` (move, mark and flag its messages, add its filters): the server's own ACL check. Never rejects; `undefined` when it could not be asked (which is not cached). */
-function fetchUpdateAccess(mailboxUid: string): Promise<boolean | undefined> {
-    let answer = answers.get(mailboxUid);
-    if (!answer) {
-        answer = getMyMailboxAccess(mailboxUid).then(
-            (access) => access.canUpdate,
-            () => {
-                answers.delete(mailboxUid);
-                return undefined;
-            },
-        );
-        answers.set(mailboxUid, answer);
-    }
-    return answer;
-}
-
-/**
- * Whether the reader may change the messages of `mailbox`: `false` only for a mailbox shared with them (`accessRole: "delegate"`) that
- * the server says they may not update - a view-only share. Everything else is `true` from the first render: the reader's own mailbox
- * needs no request, and a mailbox that is unknown (the shell has not listed it), or whose access could not be read, is treated as
- * writable - the server still refuses what is not allowed, and hiding a usable action over a failed lookup is worse than offering one
- * that then says why it failed.
- */
-export function useMailboxUpdateAccess(mailbox: Mailbox | undefined): boolean {
-    const uid = mailbox?.uid;
-    const delegated = mailbox?.accessRole === "delegate";
-    const [writable, setWritable] = useState(true);
-    useEffect(() => {
-        setWritable(true);
-        if (!uid || !delegated) {
-            return;
-        }
-        let cancelled = false;
-        void fetchUpdateAccess(uid).then((canUpdate) => {
-            if (!cancelled && canUpdate === false) {
-                setWritable(false);
-            }
-        });
-        return () => {
-            cancelled = true;
-        };
-    }, [uid, delegated]);
-    return writable;
-}
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { useEffect, useState } from "react";
+import type { Mailbox } from "@rapidmx/react-shared/mail/mailApi.js";
+import { getMyMailboxAccess } from "@rapidmx/react-shared/mail/mailboxAccessApi.js";
+
+/** What the server said about the caller's update access to a mailbox, remembered per mailbox for the page load. */
+const answers = new Map<string, Promise<boolean | undefined>>();
+
+/** Forgets every remembered answer - for the tests, and anything that changes the caller's access mid-session. */
+export function clearMailboxUpdateAccessCache(): void {
+    answers.clear();
+}
+
+/** Whether the caller may change things in `mailboxUid` (move, mark and flag its messages, add its filters): the server's own ACL check. Never rejects; `undefined` when it could not be asked (which is not cached). */
+function fetchUpdateAccess(mailboxUid: string): Promise<boolean | undefined> {
+    let answer = answers.get(mailboxUid);
+    if (!answer) {
+        answer = getMyMailboxAccess(mailboxUid).then(
+            (access) => access.canUpdate,
+            () => {
+                answers.delete(mailboxUid);
+                return undefined;
+            },
+        );
+        answers.set(mailboxUid, answer);
+    }
+    return answer;
+}
+
+/**
+ * Whether the reader may change the messages of `mailbox`: `false` only for a mailbox shared with them (`accessRole: "delegate"`) that
+ * the server says they may not update - a view-only share. Everything else is `true` from the first render: the reader's own mailbox
+ * needs no request, and a mailbox that is unknown (the shell has not listed it), or whose access could not be read, is treated as
+ * writable - the server still refuses what is not allowed, and hiding a usable action over a failed lookup is worse than offering one
+ * that then says why it failed.
+ */
+export function useMailboxUpdateAccess(mailbox: Mailbox | undefined): boolean {
+    const uid = mailbox?.uid;
+    const delegated = mailbox?.accessRole === "delegate";
+    const [writable, setWritable] = useState(true);
+    useEffect(() => {
+        setWritable(true);
+        if (!uid || !delegated) {
+            return;
+        }
+        let cancelled = false;
+        void fetchUpdateAccess(uid).then((canUpdate) => {
+            if (!cancelled && canUpdate === false) {
+                setWritable(false);
+            }
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, [uid, delegated]);
+    return writable;
+}

package/apps/shared/mail/useMarkMessageRead.ts

@@ -1,47 +1,47 @@
-///////////////////////////////////////////////////////////////////////////////
-// Copyright (C) 2026 Jean-Philippe Steinmetz
-// SPDX-License-Identifier: MPL-2.0
-///////////////////////////////////////////////////////////////////////////////
-import { useEffect, useRef } from "react";
-import type { Message } from "@rapidmx/react-shared/mail/mailApi.js";
-import { useMailShell } from "../components/mail/layout/MailShell.js";
-import { setReadState } from "./messageReadState.js";
-
-/**
- * Marks a message read when it is opened in a reading pane, through `setReadState()`: the row and the folder badge change at
- * once. `onPatched` is handed each copy of the message as it changes (the optimistic one, then the server's, or the original
- * again if the server refused).
- *
- * Replaces `@rapidmx/react-shared`'s `useMarkMessageRead`, which waits for the server before telling anyone and drops that
- * answer if the message changes meanwhile - which the optimistic copy itself does. A message is asked for once each time it is
- * opened: one the reader then marks unread stays unread while it is open, and one whose request failed is not retried in a loop
- * (its own revert changes it again), only when it is opened again.
- */
-export function useMarkMessageRead(message: Message | null, onPatched: (updated: Message, previous?: Message) => void): void {
-    const { trackMessageChange } = useMailShell();
-    const openUidRef = useRef<string | undefined>(undefined);
-    const requestedRef = useRef<Set<string>>(new Set());
-    const latestRef = useRef({ onPatched, trackMessageChange });
-    latestRef.current = { onPatched, trackMessageChange };
-
-    useEffect(() => {
-        if (message?.uid !== openUidRef.current) {
-            // Another message (or none) is open now: whatever was asked about the last one is over.
-            openUidRef.current = message?.uid;
-            requestedRef.current.clear();
-        }
-        if (!message || requestedRef.current.has(message.uid)) {
-            return;
-        }
-        // Every opening is asked about once - a message that is already read included, so that marking it unread while it is open (the
-        // keyboard's Ctrl+U) doesn't make this run again and read it straight back.
-        requestedRef.current.add(message.uid);
-        if (message.flags.read === true) {
-            return;
-        }
-        void setReadState(message, true, {
-            patch: (updated, previous) => latestRef.current.onPatched(updated, previous),
-            track: (previous, next) => latestRef.current.trackMessageChange(previous, next),
-        });
-    }, [message]);
-}
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { useEffect, useRef } from "react";
+import type { Message } from "@rapidmx/react-shared/mail/mailApi.js";
+import { useMailShell } from "../components/mail/layout/MailShell.js";
+import { setReadState } from "./messageReadState.js";
+
+/**
+ * Marks a message read when it is opened in a reading pane, through `setReadState()`: the row and the folder badge change at
+ * once. `onPatched` is handed each copy of the message as it changes (the optimistic one, then the server's, or the original
+ * again if the server refused).
+ *
+ * Replaces `@rapidmx/react-shared`'s `useMarkMessageRead`, which waits for the server before telling anyone and drops that
+ * answer if the message changes meanwhile - which the optimistic copy itself does. A message is asked for once each time it is
+ * opened: one the reader then marks unread stays unread while it is open, and one whose request failed is not retried in a loop
+ * (its own revert changes it again), only when it is opened again.
+ */
+export function useMarkMessageRead(message: Message | null, onPatched: (updated: Message, previous?: Message) => void): void {
+    const { trackMessageChange } = useMailShell();
+    const openUidRef = useRef<string | undefined>(undefined);
+    const requestedRef = useRef<Set<string>>(new Set());
+    const latestRef = useRef({ onPatched, trackMessageChange });
+    latestRef.current = { onPatched, trackMessageChange };
+
+    useEffect(() => {
+        if (message?.uid !== openUidRef.current) {
+            // Another message (or none) is open now: whatever was asked about the last one is over.
+            openUidRef.current = message?.uid;
+            requestedRef.current.clear();
+        }
+        if (!message || requestedRef.current.has(message.uid)) {
+            return;
+        }
+        // Every opening is asked about once - a message that is already read included, so that marking it unread while it is open (the
+        // keyboard's Ctrl+U) doesn't make this run again and read it straight back.
+        requestedRef.current.add(message.uid);
+        if (message.flags.read === true) {
+            return;
+        }
+        void setReadState(message, true, {
+            patch: (updated, previous) => latestRef.current.onPatched(updated, previous),
+            track: (previous, next) => latestRef.current.trackMessageChange(previous, next),
+        });
+    }, [message]);
+}

package/apps/shared/mail/useNewMailNotifications.ts

@@ -1,178 +1,178 @@
-///////////////////////////////////////////////////////////////////////////////
-// Copyright (C) 2026 Jean-Philippe Steinmetz
-// SPDX-License-Identifier: MPL-2.0
-///////////////////////////////////////////////////////////////////////////////
-import { useCallback, useEffect, useMemo, useRef, useState } from "react";
-import type { Mailbox, Message } from "@rapidmx/react-shared/mail/mailApi.js";
-import type { MailboxFolders } from "../components/mail/layout/MailShell.js";
-import {
-    DesktopPermission,
-    NewMailNotice,
-    desktopPermission,
-    getDesktopOfferDismissed,
-    noticeFor,
-    noticeSender,
-    ownAddressesOf,
-    requestDesktopPermission,
-    setDesktopOfferDismissed,
-    shouldAnnounce,
-} from "./newMailNotifications.js";
-import { getNotificationsEnabled } from "../notifications/preferences.js";
-import { getNotificationsSnapshot, notify } from "../notifications/store.js";
-
-/** How long a new-mail pop-up stays before it goes by itself (while it is neither hovered nor focused, and the tab is in view). */
-export const TOAST_DURATION_MS = 8_000;
-
-/** At most this many desktop notifications in `DESKTOP_BURST_WINDOW_MS`: a flood of mail is a few notifications, not a hundred. */
-export const DESKTOP_BURST_LIMIT = 5;
-export const DESKTOP_BURST_WINDOW_MS = 30_000;
-
-/** How many announced message uids are remembered, so an event delivered twice is announced once. */
-const ANNOUNCED_LIMIT = 500;
-
-export interface NewMailNotifications {
-    /** Whether the next pop-up should also offer to turn on desktop notifications: the browser can, has not been asked,
-     * and the user has not said "Not now". */
-    offerDesktop: boolean;
-    /** The offer's "Turn on desktop notifications": asks the browser. Must be called from a click. */
-    enableDesktop(): Promise<void>;
-    /** The offer's "Not now": remembered, so it is not made again. */
-    declineDesktop(): void;
-    /** Announces a message that just arrived - if it is worth it (see `shouldAnnounce()`) and pop-ups are on. Stable. */
-    announce(message: Message): void;
-}
-
-/** Whether the user is not looking at this tab: it is hidden, or another window has the focus. */
-function tabIsInBackground(): boolean {
-    return document.visibilityState === "hidden" || !document.hasFocus();
-}
-
-export interface UseNewMailNotificationsOptions {
-    mailboxes: Mailbox[];
-    mailboxFolders: MailboxFolders[];
-    /** Opens a message from a desktop notification's click. Defaults to a plain navigation. */
-    open?: (href: string) => void;
-}
-
-function defaultOpen(href: string): void {
-    window.location.href = href;
-}
-
-/**
- * New-mail announcements: an in-app pop-up for each message that arrives (a `mail` notification - see `notifications/store.ts`, which owns the
- * stack, its limit of three and the clock), and - while the tab
- * is in the background and the user has allowed it - a desktop notification with the same content, one per message however
- * many events name it. `announce()` is what `useMailLiveUpdates()`'s `onMessageCreated` calls; nothing else feeds it, so a
- * page load, a list refetch and a reconnect never announce anything.
- *
- * Nothing is ever asked of the browser on load: permission is requested only by `enableDesktop()`, from the offer in the
- * first pop-up, or from Settings. What the user answered is remembered in `localStorage` (see `newMailNotifications.ts`).
- */
-export function useNewMailNotifications({ mailboxes, mailboxFolders, open = defaultOpen }: UseNewMailNotificationsOptions): NewMailNotifications {
-    const [permission, setPermission] = useState<DesktopPermission>("unsupported");
-    const [offerDismissed, setOfferDismissed] = useState(true);
-    const folders = useMemo(() => mailboxFolders.flatMap((entry) => entry.folders), [mailboxFolders]);
-    const ownAddresses = useMemo(() => ownAddressesOf(mailboxes), [mailboxes]);
-    const latestRef = useRef({ folders, ownAddresses, open });
-    latestRef.current = { folders, ownAddresses, open };
-    const announcedRef = useRef<Set<string>>(new Set());
-    const desktopShownRef = useRef<number[]>([]);
-
-    // The browser's own state is only read on the client, after hydration, so the server and first client render agree.
-    useEffect(() => {
-        setPermission(desktopPermission());
-        setOfferDismissed(getDesktopOfferDismissed());
-    }, []);
-
-    const showDesktop = useCallback((notice: NewMailNotice) => {
-        const now = Date.now();
-        desktopShownRef.current = desktopShownRef.current.filter((at) => now - at < DESKTOP_BURST_WINDOW_MS);
-        if (desktopShownRef.current.length >= DESKTOP_BURST_LIMIT) {
-            return;
-        }
-        try {
-            const notification = new Notification(noticeSender(notice), {
-                body: [notice.subject, notice.preview].filter(Boolean).join("\n"),
-                // One per message: a duplicate (another tab of this app, a re-delivered event) replaces instead of stacking.
-                tag: notice.uid,
-            });
-            desktopShownRef.current.push(now);
-            notification.onclick = () => {
-                window.focus();
-                notification.close();
-                latestRef.current.open(notice.href);
-            };
-        } catch {
-            // Some browsers refuse `new Notification()` outright (a mobile one wanting a service worker): the pop-up is enough.
-        }
-    }, []);
-
-    const enableDesktop = useCallback(async () => {
-        const answer = await requestDesktopPermission();
-        setPermission(answer);
-        // Answered either way, so the offer goes: on granted it has done its job, on denied it can't be made again.
-        setDesktopOfferDismissed(true);
-        setOfferDismissed(true);
-    }, []);
-
-    const declineDesktop = useCallback(() => {
-        setDesktopOfferDismissed(true);
-        setOfferDismissed(true);
-    }, []);
-
-    // The offer's current state and answers, for the stable `announce` below.
-    const offerDesktop = permission === "default" && !offerDismissed;
-    const offerRef = useRef({ offered: offerDesktop, enable: enableDesktop, decline: declineDesktop });
-    offerRef.current = { offered: offerDesktop, enable: enableDesktop, decline: declineDesktop };
-
-    const announce = useCallback(
-        (message: Message) => {
-            if (!getNotificationsEnabled() || announcedRef.current.has(message.uid)) {
-                return;
-            }
-            const { folders: knownFolders, ownAddresses: own } = latestRef.current;
-            if (!shouldAnnounce(message, { folders: knownFolders, ownAddresses: own })) {
-                return;
-            }
-            announcedRef.current.add(message.uid);
-            if (announcedRef.current.size > ANNOUNCED_LIMIT) {
-                announcedRef.current.delete(announcedRef.current.values().next().value!);
-            }
-            const notice = noticeFor(message);
-            const offer = offerRef.current;
-            notify({
-                id: `mail:${notice.uid}`,
-                kind: "mail",
-                title: notice.senderName || notice.senderAddress,
-                subtitle: notice.senderName ? `<${notice.senderAddress}>` : undefined,
-                message: notice.subject,
-                preview: notice.preview || undefined,
-                href: notice.href,
-                timeoutMs: TOAST_DURATION_MS,
-                // Actions make a notification sticky; a new-mail pop-up with the offer still goes by itself.
-                sticky: false,
-                // The offer is made once at a time: on a pop-up only while none of the pop-ups still showing carries it.
-                ...(offer.offered && !getNotificationsSnapshot().visible.some((item) => item.kind === "mail" && item.actions.length > 0)
-                    ? {
-                          hint: "Get a desktop notification when mail arrives while this tab is in the background.",
-                          actions: [
-                              { label: "Turn on desktop notifications", onClick: () => void offer.enable() },
-                              { label: "Not now", onClick: offer.decline },
-                          ],
-                      }
-                    : {}),
-            });
-            if (desktopPermission() === "granted" && tabIsInBackground()) {
-                showDesktop(notice);
-            }
-        },
-        [showDesktop],
-    );
-
-    return {
-        offerDesktop,
-        enableDesktop,
-        declineDesktop,
-        announce,
-    };
-}
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import type { Mailbox, Message } from "@rapidmx/react-shared/mail/mailApi.js";
+import type { MailboxFolders } from "../components/mail/layout/MailShell.js";
+import {
+    DesktopPermission,
+    NewMailNotice,
+    desktopPermission,
+    getDesktopOfferDismissed,
+    noticeFor,
+    noticeSender,
+    ownAddressesOf,
+    requestDesktopPermission,
+    setDesktopOfferDismissed,
+    shouldAnnounce,
+} from "./newMailNotifications.js";
+import { getNotificationsEnabled } from "../notifications/preferences.js";
+import { getNotificationsSnapshot, notify } from "../notifications/store.js";
+
+/** How long a new-mail pop-up stays before it goes by itself (while it is neither hovered nor focused, and the tab is in view). */
+export const TOAST_DURATION_MS = 8_000;
+
+/** At most this many desktop notifications in `DESKTOP_BURST_WINDOW_MS`: a flood of mail is a few notifications, not a hundred. */
+export const DESKTOP_BURST_LIMIT = 5;
+export const DESKTOP_BURST_WINDOW_MS = 30_000;
+
+/** How many announced message uids are remembered, so an event delivered twice is announced once. */
+const ANNOUNCED_LIMIT = 500;
+
+export interface NewMailNotifications {
+    /** Whether the next pop-up should also offer to turn on desktop notifications: the browser can, has not been asked,
+     * and the user has not said "Not now". */
+    offerDesktop: boolean;
+    /** The offer's "Turn on desktop notifications": asks the browser. Must be called from a click. */
+    enableDesktop(): Promise<void>;
+    /** The offer's "Not now": remembered, so it is not made again. */
+    declineDesktop(): void;
+    /** Announces a message that just arrived - if it is worth it (see `shouldAnnounce()`) and pop-ups are on. Stable. */
+    announce(message: Message): void;
+}
+
+/** Whether the user is not looking at this tab: it is hidden, or another window has the focus. */
+function tabIsInBackground(): boolean {
+    return document.visibilityState === "hidden" || !document.hasFocus();
+}
+
+export interface UseNewMailNotificationsOptions {
+    mailboxes: Mailbox[];
+    mailboxFolders: MailboxFolders[];
+    /** Opens a message from a desktop notification's click. Defaults to a plain navigation. */
+    open?: (href: string) => void;
+}
+
+function defaultOpen(href: string): void {
+    window.location.href = href;
+}
+
+/**
+ * New-mail announcements: an in-app pop-up for each message that arrives (a `mail` notification - see `notifications/store.ts`, which owns the
+ * stack, its limit of three and the clock), and - while the tab
+ * is in the background and the user has allowed it - a desktop notification with the same content, one per message however
+ * many events name it. `announce()` is what `useMailLiveUpdates()`'s `onMessageCreated` calls; nothing else feeds it, so a
+ * page load, a list refetch and a reconnect never announce anything.
+ *
+ * Nothing is ever asked of the browser on load: permission is requested only by `enableDesktop()`, from the offer in the
+ * first pop-up, or from Settings. What the user answered is remembered in `localStorage` (see `newMailNotifications.ts`).
+ */
+export function useNewMailNotifications({ mailboxes, mailboxFolders, open = defaultOpen }: UseNewMailNotificationsOptions): NewMailNotifications {
+    const [permission, setPermission] = useState<DesktopPermission>("unsupported");
+    const [offerDismissed, setOfferDismissed] = useState(true);
+    const folders = useMemo(() => mailboxFolders.flatMap((entry) => entry.folders), [mailboxFolders]);
+    const ownAddresses = useMemo(() => ownAddressesOf(mailboxes), [mailboxes]);
+    const latestRef = useRef({ folders, ownAddresses, open });
+    latestRef.current = { folders, ownAddresses, open };
+    const announcedRef = useRef<Set<string>>(new Set());
+    const desktopShownRef = useRef<number[]>([]);
+
+    // The browser's own state is only read on the client, after hydration, so the server and first client render agree.
+    useEffect(() => {
+        setPermission(desktopPermission());
+        setOfferDismissed(getDesktopOfferDismissed());
+    }, []);
+
+    const showDesktop = useCallback((notice: NewMailNotice) => {
+        const now = Date.now();
+        desktopShownRef.current = desktopShownRef.current.filter((at) => now - at < DESKTOP_BURST_WINDOW_MS);
+        if (desktopShownRef.current.length >= DESKTOP_BURST_LIMIT) {
+            return;
+        }
+        try {
+            const notification = new Notification(noticeSender(notice), {
+                body: [notice.subject, notice.preview].filter(Boolean).join("\n"),
+                // One per message: a duplicate (another tab of this app, a re-delivered event) replaces instead of stacking.
+                tag: notice.uid,
+            });
+            desktopShownRef.current.push(now);
+            notification.onclick = () => {
+                window.focus();
+                notification.close();
+                latestRef.current.open(notice.href);
+            };
+        } catch {
+            // Some browsers refuse `new Notification()` outright (a mobile one wanting a service worker): the pop-up is enough.
+        }
+    }, []);
+
+    const enableDesktop = useCallback(async () => {
+        const answer = await requestDesktopPermission();
+        setPermission(answer);
+        // Answered either way, so the offer goes: on granted it has done its job, on denied it can't be made again.
+        setDesktopOfferDismissed(true);
+        setOfferDismissed(true);
+    }, []);
+
+    const declineDesktop = useCallback(() => {
+        setDesktopOfferDismissed(true);
+        setOfferDismissed(true);
+    }, []);
+
+    // The offer's current state and answers, for the stable `announce` below.
+    const offerDesktop = permission === "default" && !offerDismissed;
+    const offerRef = useRef({ offered: offerDesktop, enable: enableDesktop, decline: declineDesktop });
+    offerRef.current = { offered: offerDesktop, enable: enableDesktop, decline: declineDesktop };
+
+    const announce = useCallback(
+        (message: Message) => {
+            if (!getNotificationsEnabled() || announcedRef.current.has(message.uid)) {
+                return;
+            }
+            const { folders: knownFolders, ownAddresses: own } = latestRef.current;
+            if (!shouldAnnounce(message, { folders: knownFolders, ownAddresses: own })) {
+                return;
+            }
+            announcedRef.current.add(message.uid);
+            if (announcedRef.current.size > ANNOUNCED_LIMIT) {
+                announcedRef.current.delete(announcedRef.current.values().next().value!);
+            }
+            const notice = noticeFor(message);
+            const offer = offerRef.current;
+            notify({
+                id: `mail:${notice.uid}`,
+                kind: "mail",
+                title: notice.senderName || notice.senderAddress,
+                subtitle: notice.senderName ? `<${notice.senderAddress}>` : undefined,
+                message: notice.subject,
+                preview: notice.preview || undefined,
+                href: notice.href,
+                timeoutMs: TOAST_DURATION_MS,
+                // Actions make a notification sticky; a new-mail pop-up with the offer still goes by itself.
+                sticky: false,
+                // The offer is made once at a time: on a pop-up only while none of the pop-ups still showing carries it.
+                ...(offer.offered && !getNotificationsSnapshot().visible.some((item) => item.kind === "mail" && item.actions.length > 0)
+                    ? {
+                          hint: "Get a desktop notification when mail arrives while this tab is in the background.",
+                          actions: [
+                              { label: "Turn on desktop notifications", onClick: () => void offer.enable() },
+                              { label: "Not now", onClick: offer.decline },
+                          ],
+                      }
+                    : {}),
+            });
+            if (desktopPermission() === "granted" && tabIsInBackground()) {
+                showDesktop(notice);
+            }
+        },
+        [showDesktop],
+    );
+
+    return {
+        offerDesktop,
+        enableDesktop,
+        declineDesktop,
+        announce,
+    };
+}