@rapidmx/web-client 0.9.0 → 0.10.0

package/apps/shared/mail/useMailConnection.ts

@@ -0,0 +1,150 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { createContext, useCallback, useEffect, useState } from "react";
+import { ApiRequestError } from "@rapidmx/react-shared/util/api.js";
+import { Folder, Mailbox, listFolders, listMailboxes } from "@rapidmx/react-shared/mail/mailApi.js";
+import type { MailboxFolders } from "../components/mail/layout/MailShell.js";
+import { LiveUpdates, useMailLiveUpdates } from "./useMailLiveUpdates.js";
+import type { FolderCounts } from "./folderCounts.js";
+import { NewMailNotifications, useNewMailNotifications } from "./useNewMailNotifications.js";
+
+/** Page size of the one `listMailboxes()` call. */
+export const MAILBOX_LIST_LIMIT = 100;
+
+/** Well-known folders sort first in the sidebar, in Gmail/Outlook's conventional order; anything else (incl. `user`) sorts after, alphabetically. */
+export const FOLDER_ORDER = ["inbox", "drafts", "outbox", "sent_items", "junk", "archive", "deleted_items"];
+
+/**
+ * A mailbox's `calendar`/`contacts`/`tasks`/`notes` folders back their own dedicated apps (see `CalendarShell`/`ContactsShell`/`TasksShell`), not
+ * Mail - `listFolders()` returns every well-known folder for the mailbox regardless of which app owns it, so Mail's own folder tree filters down
+ * to just the mail ones itself, or those other apps' folders leak into its sidebar.
+ */
+export const MAIL_FOLDER_TYPES = new Set([...FOLDER_ORDER, "user"]);
+
+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;
+    /** 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 persistent app frame (`AppChrome`) offers to the Mail shell so that it doesn't open a second connection. `null` outside a frame. */
+export const MailConnectionContext = createContext<MailConnection | null>(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 function useMailConnection({ userUid, enabled, open }: UseMailConnectionOptions): MailConnection {
+    const [status, setStatus] = useState<MailConnectionStatus>("checking");
+    const [error, setError] = useState<string | null>(null);
+    const [mailboxes, setMailboxes] = useState<Mailbox[]>([]);
+    const [mailboxFolders, setMailboxFolders] = useState<MailboxFolders[]>([]);
+    const [foldersLoading, setFoldersLoading] = useState(true);
+
+    useEffect(() => {
+        if (!userUid || !enabled) {
+            return;
+        }
+        listMailboxes({ limit: MAILBOX_LIST_LIMIT })
+            .then((result) => {
+                setMailboxes(result);
+                setStatus("ready");
+            })
+            .catch((err) => {
+                setError(err instanceof ApiRequestError ? err.message : "Could not load your mailboxes.");
+                setStatus("error");
+            });
+    }, [userUid, enabled]);
+
+    // Fans out one listFolders() call per accessible mailbox in parallel - each call catches its own failure into a MailboxFolders.error
+    // rather than letting Promise.all reject, so one mailbox's fetch failure renders that section's own inline Alert instead of blanking out
+    // every other mailbox's folder tree.
+    useEffect(() => {
+        if (mailboxes.length === 0) {
+            // Deliberately leaves foldersLoading as-is: this also runs once before listMailboxes() has resolved, and clearing it here would
+            // briefly render an empty sidebar the moment mailboxes arrive, before their folders do. A genuinely mailbox-less caller gets
+            // MailboxProvisioning.
+            setMailboxFolders([]);
+            return;
+        }
+        setFoldersLoading(true);
+        void Promise.all(
+            mailboxes.map((mailbox) =>
+                listFolders(mailbox.uid)
+                    .then((result): MailboxFolders => ({ mailbox, folders: result.filter((f) => MAIL_FOLDER_TYPES.has(f.type)) }))
+                    .catch(
+                        (err): MailboxFolders => ({
+                            mailbox,
+                            folders: [],
+                            error: err instanceof ApiRequestError ? err.message : "Could not load folders.",
+                        }),
+                    ),
+            ),
+        )
+            .then(setMailboxFolders)
+            .finally(() => setFoldersLoading(false));
+    }, [mailboxes]);
+
+    /** Files a newly created folder under its own mailbox, leaving every other mailbox's list untouched - and ignoring a type the
+     * sidebar doesn't list at all, the same filter the fetch above applies. */
+    const onFolderCreated = useCallback((folder: Folder) => {
+        if (!MAIL_FOLDER_TYPES.has(folder.type)) {
+            return;
+        }
+        setMailboxFolders((prev) =>
+            prev.map((entry) =>
+                // Not one already there: another client's create event can arrive after (or twice, or alongside) our own.
+                entry.mailbox.uid === folder.mailboxUid && !entry.folders.some((existing) => existing.uid === folder.uid)
+                    ? { ...entry, folders: [...entry.folders, folder] }
+                    : entry,
+            ),
+        );
+    }, []);
+
+    // New mail without a reload: push events for every folder, plus a safety-net poll. Held in state beside `mailboxFolders` rather than
+    // written into it, so a refreshed unread count never looks like a change of folders to the list on screen (which reloads, and forgets its
+    // selection, whenever the folders do). A pop-up (and, in the background, a desktop notification) for each new message the connection
+    // announces.
+    const notifications = useNewMailNotifications({ mailboxes, mailboxFolders, open });
+    const { live, folderCounts } = useMailLiveUpdates({
+        userUid: enabled ? userUid : undefined,
+        mailboxes,
+        mailboxFolders,
+        onFolderCreated,
+        onMessageCreated: notifications.announce,
+    });
+
+    return { status, error, mailboxes, mailboxFolders, foldersLoading, onFolderCreated, live, folderCounts, notifications };
+}

package/apps/shared/mail/useMailLiveUpdates.ts

@@ -1,224 +1,232 @@
-///////////////////////////////////////////////////////////////////////////////
-// Copyright (C) 2026 Jean-Philippe Steinmetz
-// SPDX-License-Identifier: MPL-2.0
-///////////////////////////////////////////////////////////////////////////////
-import { useEffect, useMemo, useRef, useState } from "react";
-import { Folder, Mailbox, listFolders } from "@rapidmx/react-shared/mail/mailApi.js";
-import { getPushClient, PushEvent } from "@rapidmx/react-shared/mail/pushClient.js";
-import type { MailboxFolders } from "../components/mail/layout/MailShell.js";
-import { SIGN_OUT_CHANNEL } from "../search/localIndexRpcClient.js";
-
-/** How often the safety-net poll runs while the tab is visible. The push socket does the real work; this is for a network
- * that blocks or silently drops it, and for events published while it was reconnecting (Redis pub/sub is never replayed). */
-export const LIVE_POLL_INTERVAL_MS = 45_000;
-
-/** Events arriving this close together are answered with one refresh - a burst of new mail is one refetch, not one each. */
-export const LIVE_EVENT_DEBOUNCE_MS = 400;
-
-/** What changed, as far as a list on screen is concerned. */
-export interface LiveUpdates {
-    /** Bumped each time the list should quietly refetch its first page. `0` until the first bump. */
-    tick: number;
-    /** The folders the events behind the latest bump touched - `null` when that isn't known (a poll, a reconnect, the tab
-     * coming back to the front), meaning any folder may have changed. */
-    folderUids: ReadonlySet<string> | null;
-}
-
-export const NO_LIVE_UPDATES: LiveUpdates = { tick: 0, folderUids: null };
-
-/** The class names `NotificationUtils.sendMessage()` publishes are the model's (`MessageMongo`, `MessageSQL`, `FolderMongo`). */
-const MESSAGE_EVENT = /^Message/;
-const FOLDER_EVENT = /^Folder/;
-const MESSAGE_ACTIONS = new Set(["create", "update", "delete"]);
-
-/**
- * The channels to subscribe to, most important first (the push client keeps the first `PUSH_MAX_CHANNELS`): every
- * mailbox's Inbox - where mail lands - then each mailbox's other folders in the sidebar's own order, then the mailbox uids
- * themselves (which announce new folders). A folder is a channel of its own; subscribing to a mailbox does not deliver its
- * folders' events.
- */
-export function pushChannelsFor(mailboxFolders: MailboxFolders[], mailboxes: Mailbox[]): string[] {
-    const inboxes = mailboxFolders.flatMap((entry) => entry.folders.filter((folder) => folder.type === "inbox"));
-    const others = mailboxFolders.flatMap((entry) => entry.folders.filter((folder) => folder.type !== "inbox"));
-    return [...new Set([...inboxes, ...others].map((folder) => folder.uid).concat(mailboxes.map((mailbox) => mailbox.uid)))];
-}
-
-function isFolder(value: unknown): value is Folder {
-    const folder = value as Partial<Folder> | null;
-    return !!folder && typeof folder.uid === "string" && typeof folder.mailboxUid === "string" && typeof folder.type === "string";
-}
-
-/** The folder a message event is about: the message's own `folderUid`, else the channel it arrived on (when the server said). */
-function folderOfMessageEvent(event: PushEvent): string | undefined {
-    const data = event.data as { folderUid?: unknown } | null | undefined;
-    if (typeof data?.folderUid === "string") {
-        return data.folderUid;
-    }
-    return event.channel;
-}
-
-export interface UseMailLiveUpdatesOptions {
-    /** Nothing runs without a signed-in user. */
-    userUid?: string;
-    mailboxes: Mailbox[];
-    mailboxFolders: MailboxFolders[];
-    /** Called with a folder another client (or this one) created, so the sidebar shows it. Called only for one not already known. */
-    onFolderCreated: (folder: Folder) => void;
-}
-
-export interface MailLiveUpdates {
-    live: LiveUpdates;
-    /** The latest unread count of each folder that has been refreshed since load, by folder uid - what the sidebar's badges show
-     * instead of the count the folder list was loaded with. */
-    unreadCounts: Record<string, number>;
-}
-
-/**
- * Keeps Mail current without a page reload. One shared push connection per tab (`getPushClient()`) is subscribed to every
- * folder of every accessible mailbox; a message event for any of them, a reconnect, a poll of the safety net (every
- * `LIVE_POLL_INTERVAL_MS` while the tab is visible - and the only mechanism, silently, where the socket can't connect), the
- * tab coming back to the front or the browser coming back online, all end in the same debounced refresh: `live` is bumped
- * (the list on screen refetches its first page - see `mergeFirstPage()`) and every folder's unread count is re-read.
- *
- * Sign-out closes the socket for good: another tab's or this one's, heard on the same channel `AppShell` listens on.
- * Renders nothing and does nothing where there is no window (server-side rendering).
- */
-export function useMailLiveUpdates({ userUid, mailboxes, mailboxFolders, onFolderCreated }: UseMailLiveUpdatesOptions): MailLiveUpdates {
-    const [live, setLive] = useState<LiveUpdates>(NO_LIVE_UPDATES);
-    const [unreadCounts, setUnreadCounts] = useState<Record<string, number>>({});
-    // The latest inputs, for the long-lived listeners below.
-    const latestRef = useRef({ mailboxes, mailboxFolders, onFolderCreated });
-    latestRef.current = { mailboxes, mailboxFolders, onFolderCreated };
-
-    const channels = useMemo(() => pushChannelsFor(mailboxFolders, mailboxes), [mailboxFolders, mailboxes]);
-    const channelKey = channels.join("|");
-    const channelsRef = useRef(channels);
-    channelsRef.current = channels;
-
-    useEffect(() => {
-        if (!userUid) {
-            return;
-        }
-        const client = getPushClient();
-        let stopped = false;
-        let timer: ReturnType<typeof setTimeout> | undefined;
-        let pendingFolders = new Set<string>();
-        let pendingUnknown = false;
-        let countsRun = 0;
-        let everOpen = false;
-
-        async function refreshCounts() {
-            const run = ++countsRun;
-            const results = await Promise.all(latestRef.current.mailboxes.map((mailbox) => listFolders(mailbox.uid).catch(() => undefined)));
-            if (stopped || run !== countsRun) {
-                return;
-            }
-            const fresh: Record<string, number> = {};
-            for (const folders of results) {
-                for (const folder of folders ?? []) {
-                    fresh[folder.uid] = folder.unreadCount;
-                }
-            }
-            setUnreadCounts((previous) => {
-                const changed = Object.entries(fresh).some(([uid, count]) => previous[uid] !== count);
-                return changed ? { ...previous, ...fresh } : previous;
-            });
-        }
-
-        // Never runs once `stopped`: whatever sets it clears the timer first.
-        function flush() {
-            timer = undefined;
-            const folderUids = pendingUnknown ? null : new Set(pendingFolders);
-            pendingFolders = new Set();
-            pendingUnknown = false;
-            setLive((previous) => ({ tick: previous.tick + 1, folderUids }));
-            void refreshCounts();
-        }
-
-        /** Asks for a refresh: of the given folders, or (no argument) of whatever may have changed. */
-        function schedule(folderUid?: string) {
-            if (stopped) {
-                return;
-            }
-            if (folderUid) {
-                pendingFolders.add(folderUid);
-            } else {
-                pendingUnknown = true;
-            }
-            timer ??= setTimeout(flush, LIVE_EVENT_DEBOUNCE_MS);
-        }
-
-        const offEvent = client.onEvent((event) => {
-            if (MESSAGE_EVENT.test(event.type) && MESSAGE_ACTIONS.has(event.action ?? "")) {
-                schedule(folderOfMessageEvent(event));
-            } else if (FOLDER_EVENT.test(event.type) && event.action === "create" && isFolder(event.data)) {
-                const folder = event.data;
-                const known = latestRef.current.mailboxFolders.some((entry) => entry.folders.some((f) => f.uid === folder.uid));
-                if (!known) {
-                    latestRef.current.onFolderCreated(folder);
-                }
-            }
-        });
-        // Anything published while the socket was down is gone for good, so every reconnect is followed by a refresh.
-        const offStatus = client.onStatus((status) => {
-            if (status === "open") {
-                if (everOpen) {
-                    schedule();
-                }
-                everOpen = true;
-            }
-        });
-
-        const poll = setInterval(() => {
-            if (document.visibilityState === "visible") {
-                schedule();
-            }
-        }, LIVE_POLL_INTERVAL_MS);
-        function refreshNow() {
-            if (document.visibilityState === "visible") {
-                client.reconnectNow();
-                schedule();
-            }
-        }
-        function handleOnline() {
-            client.reconnectNow();
-            schedule();
-        }
-        document.addEventListener("visibilitychange", refreshNow);
-        window.addEventListener("focus", refreshNow);
-        window.addEventListener("online", handleOnline);
-
-        // A sign-out, in this tab or another, ended the session behind the socket: close it for good and stop refreshing.
-        const signOut = typeof BroadcastChannel === "undefined" ? undefined : new BroadcastChannel(SIGN_OUT_CHANNEL);
-        signOut?.addEventListener("message", (event: MessageEvent<{ type?: string }>) => {
-            if (event.data?.type === "sign-out") {
-                stopped = true;
-                clearTimeout(timer);
-                client.close();
-            }
-        });
-
-        client.setChannels(channelsRef.current);
-        client.start();
-
-        return () => {
-            stopped = true;
-            clearTimeout(timer);
-            clearInterval(poll);
-            offEvent();
-            offStatus();
-            document.removeEventListener("visibilitychange", refreshNow);
-            window.removeEventListener("focus", refreshNow);
-            window.removeEventListener("online", handleOnline);
-            signOut?.close();
-        };
-    }, [userUid]);
-
-    useEffect(() => {
-        if (userUid) {
-            getPushClient().setChannels(channels);
-        }
-    }, [userUid, channelKey]);
-
-    return { live, unreadCounts };
-}
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { useEffect, useMemo, useRef, useState } from "react";
+import { Folder, Mailbox, Message } from "@rapidmx/react-shared/mail/mailApi.js";
+import { getPushClient, PushEvent } from "@rapidmx/react-shared/mail/pushClient.js";
+import type { MailboxFolders } from "../components/mail/layout/MailShell.js";
+import { SIGN_OUT_CHANNEL } from "../search/localIndexRpcClient.js";
+import { FolderCounts, useFolderCounts } from "./folderCounts.js";
+
+/** How often the safety-net poll runs while the tab is visible. The push socket does the real work; this is for a network
+ * that blocks or silently drops it, and for events published while it was reconnecting (Redis pub/sub is never replayed). */
+export const LIVE_POLL_INTERVAL_MS = 45_000;
+
+/** Events arriving this close together are answered with one refresh - a burst of new mail is one refetch, not one each. */
+export const LIVE_EVENT_DEBOUNCE_MS = 400;
+
+/** What changed, as far as a list on screen is concerned. */
+export interface LiveUpdates {
+    /** Bumped each time the list should quietly refetch its first page. `0` until the first bump. */
+    tick: number;
+    /** The folders the events behind the latest bump touched - `null` when that isn't known (a poll, a reconnect, the tab
+     * coming back to the front), meaning any folder may have changed. */
+    folderUids: ReadonlySet<string> | null;
+}
+
+export const NO_LIVE_UPDATES: LiveUpdates = { tick: 0, folderUids: null };
+
+/** The class names `NotificationUtils.sendMessage()` publishes are the model's (`MessageMongo`, `MessageSQL`, `FolderMongo`). */
+const MESSAGE_EVENT = /^Message/;
+const FOLDER_EVENT = /^Folder/;
+const MESSAGE_ACTIONS = new Set(["create", "update", "delete"]);
+
+/**
+ * The channels to subscribe to, most important first (the push client keeps the first `PUSH_MAX_CHANNELS`): every
+ * mailbox's Inbox - where mail lands - then each mailbox's other folders in the sidebar's own order, then the mailbox uids
+ * themselves (which announce new folders). A folder is a channel of its own; subscribing to a mailbox does not deliver its
+ * folders' events.
+ */
+export function pushChannelsFor(mailboxFolders: MailboxFolders[], mailboxes: Mailbox[]): string[] {
+    const inboxes = mailboxFolders.flatMap((entry) => entry.folders.filter((folder) => folder.type === "inbox"));
+    const others = mailboxFolders.flatMap((entry) => entry.folders.filter((folder) => folder.type !== "inbox"));
+    return [...new Set([...inboxes, ...others].map((folder) => folder.uid).concat(mailboxes.map((mailbox) => mailbox.uid)))];
+}
+
+function isFolder(value: unknown): value is Folder {
+    const folder = value as Partial<Folder> | null;
+    return !!folder && typeof folder.uid === "string" && typeof folder.mailboxUid === "string" && typeof folder.type === "string";
+}
+
+function isMessage(value: unknown): value is Message {
+    const message = value as Partial<Message> | null;
+    return (
+        !!message &&
+        typeof message.uid === "string" &&
+        typeof message.folderUid === "string" &&
+        typeof message.flags === "object" &&
+        message.flags !== null
+    );
+}
+
+/** The folder a message event is about: the message's own `folderUid`, else the channel it arrived on (when the server said). */
+function folderOfMessageEvent(event: PushEvent): string | undefined {
+    const data = event.data as { folderUid?: unknown } | null | undefined;
+    if (typeof data?.folderUid === "string") {
+        return data.folderUid;
+    }
+    return event.channel;
+}
+
+export interface UseMailLiveUpdatesOptions {
+    /** Nothing runs without a signed-in user. */
+    userUid?: string;
+    mailboxes: Mailbox[];
+    mailboxFolders: MailboxFolders[];
+    /** Called with a folder another client (or this one) created, so the sidebar shows it. Called only for one not already known. */
+    onFolderCreated: (folder: Folder) => void;
+    /** Called with each new message the push connection announces (a `create` event) - once per message, never for a list
+     * refetch, the initial load or a reconnect (nothing published while the socket was down is replayed). The caller decides
+     * whether it is worth telling the user about. */
+    onMessageCreated?: (message: Message) => void;
+}
+
+export interface MailLiveUpdates {
+    live: LiveUpdates;
+    /** The folder badges' numbers and how to change them - see `useFolderCounts()`. Kept in an overlay of their own, **not** in
+     * `mailboxFolders`, because the list effect reloads - and forgets the selection - whenever `mailboxFolders` changes. */
+    folderCounts: FolderCounts;
+}
+
+/**
+ * Keeps Mail current without a page reload. One shared push connection per tab (`getPushClient()`) is subscribed to every
+ * folder of every accessible mailbox; a message event for any of them, a reconnect, a poll of the safety net (every
+ * `LIVE_POLL_INTERVAL_MS` while the tab is visible - and the only mechanism, silently, where the socket can't connect), the
+ * tab coming back to the front or the browser coming back online, all end in the same debounced refresh: `live` is bumped
+ * (the list on screen refetches its first page - see `mergeFirstPage()`) and every folder's counts are re-read. A new message
+ * also bumps its folder's badge at once and is announced to `onMessageCreated`, and the server's `Folder` update events (the
+ * folder's real counts) are applied to the badges - see `useFolderCounts()`.
+ *
+ * Sign-out closes the socket for good: another tab's or this one's, heard on the same channel `AppShell` listens on.
+ * Renders nothing and does nothing where there is no window (server-side rendering).
+ */
+export function useMailLiveUpdates({ userUid, mailboxes, mailboxFolders, onFolderCreated, onMessageCreated }: UseMailLiveUpdatesOptions): MailLiveUpdates {
+    const [live, setLive] = useState<LiveUpdates>(NO_LIVE_UPDATES);
+    const folders = useMemo(() => mailboxFolders.flatMap((entry) => entry.folders), [mailboxFolders]);
+    const folderCounts = useFolderCounts(mailboxes, folders);
+    // The latest inputs, for the long-lived listeners below.
+    const latestRef = useRef({ mailboxes, mailboxFolders, onFolderCreated, onMessageCreated, folderCounts });
+    latestRef.current = { mailboxes, mailboxFolders, onFolderCreated, onMessageCreated, folderCounts };
+
+    const channels = useMemo(() => pushChannelsFor(mailboxFolders, mailboxes), [mailboxFolders, mailboxes]);
+    const channelKey = channels.join("|");
+    const channelsRef = useRef(channels);
+    channelsRef.current = channels;
+
+    useEffect(() => {
+        if (!userUid) {
+            return;
+        }
+        const client = getPushClient();
+        let stopped = false;
+        let timer: ReturnType<typeof setTimeout> | undefined;
+        let pendingFolders = new Set<string>();
+        let pendingUnknown = false;
+        let everOpen = false;
+
+        // Never runs once `stopped`: whatever sets it clears the timer first.
+        function flush() {
+            timer = undefined;
+            const folderUids = pendingUnknown ? null : new Set(pendingFolders);
+            pendingFolders = new Set();
+            pendingUnknown = false;
+            setLive((previous) => ({ tick: previous.tick + 1, folderUids }));
+            latestRef.current.folderCounts.refresh(0);
+        }
+
+        /** Asks for a refresh: of the given folders, or (no argument) of whatever may have changed. */
+        function schedule(folderUid?: string) {
+            if (stopped) {
+                return;
+            }
+            if (folderUid) {
+                pendingFolders.add(folderUid);
+            } else {
+                pendingUnknown = true;
+            }
+            timer ??= setTimeout(flush, LIVE_EVENT_DEBOUNCE_MS);
+        }
+
+        const offEvent = client.onEvent((event) => {
+            if (MESSAGE_EVENT.test(event.type) && MESSAGE_ACTIONS.has(event.action ?? "")) {
+                if (event.action === "create" && isMessage(event.data)) {
+                    // Once per message, whatever else the event triggers: the badge first, then whoever announces it.
+                    if (latestRef.current.folderCounts.noteCreated(event.data)) {
+                        latestRef.current.onMessageCreated?.(event.data);
+                    }
+                }
+                schedule(folderOfMessageEvent(event));
+            } else if (FOLDER_EVENT.test(event.type) && event.action === "create" && isFolder(event.data)) {
+                const folder = event.data;
+                const known = latestRef.current.mailboxFolders.some((entry) => entry.folders.some((f) => f.uid === folder.uid));
+                if (!known) {
+                    latestRef.current.onFolderCreated(folder);
+                }
+            } else if (FOLDER_EVENT.test(event.type) && event.action === "update") {
+                latestRef.current.folderCounts.applyFolderEvent(event.data);
+            }
+        });
+        // Anything published while the socket was down is gone for good, so every reconnect is followed by a refresh.
+        const offStatus = client.onStatus((status) => {
+            if (status === "open") {
+                if (everOpen) {
+                    schedule();
+                }
+                everOpen = true;
+            }
+        });
+
+        const poll = setInterval(() => {
+            if (document.visibilityState === "visible") {
+                schedule();
+            }
+        }, LIVE_POLL_INTERVAL_MS);
+        function refreshNow() {
+            if (document.visibilityState === "visible") {
+                client.reconnectNow();
+                schedule();
+            }
+        }
+        function handleOnline() {
+            client.reconnectNow();
+            schedule();
+        }
+        document.addEventListener("visibilitychange", refreshNow);
+        window.addEventListener("focus", refreshNow);
+        window.addEventListener("online", handleOnline);
+
+        // A sign-out, in this tab or another, ended the session behind the socket: close it for good and stop refreshing.
+        const signOut = typeof BroadcastChannel === "undefined" ? undefined : new BroadcastChannel(SIGN_OUT_CHANNEL);
+        signOut?.addEventListener("message", (event: MessageEvent<{ type?: string }>) => {
+            if (event.data?.type === "sign-out") {
+                stopped = true;
+                clearTimeout(timer);
+                client.close();
+            }
+        });
+
+        client.setChannels(channelsRef.current);
+        client.start();
+
+        return () => {
+            stopped = true;
+            clearTimeout(timer);
+            clearInterval(poll);
+            offEvent();
+            offStatus();
+            document.removeEventListener("visibilitychange", refreshNow);
+            window.removeEventListener("focus", refreshNow);
+            window.removeEventListener("online", handleOnline);
+            signOut?.close();
+        };
+    }, [userUid]);
+
+    useEffect(() => {
+        if (userUid) {
+            getPushClient().setChannels(channels);
+        }
+    }, [userUid, channelKey]);
+
+    return { live, folderCounts };
+}