@remit/web-client 0.0.123 → 0.0.124

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/web-client",
-  "version": "0.0.123",
+  "version": "0.0.124",
   "type": "module",
   "description": "Remit web client, published as composable primitives — the app shell, auth shells, and runtime config. A distributor imports what it composes and bundles it.",
   "exports": {

package/src/components/layout/MailTopBar.tsx

@@ -7,13 +7,16 @@
  * what wording is not decided here.
  */
 import type { RemitImapAccountResponse } from "@remit/api-http-client/types.gen.ts";
-import { ShellTopBar, shortcutHintForAction } from "@remit/ui";
+import { RefreshButton, ShellTopBar, shortcutHintForAction } from "@remit/ui";
 import { useNavigate } from "@tanstack/react-router";
+import { useMemo } from "react";
 import { AccountMenu } from "@/auth/AccountMenu";
 import { useGlobalCompose } from "@/hooks/useComposeTarget";
+import { useRefreshControl } from "@/hooks/useRefreshControl";
 import { useSearchScope } from "@/hooks/useSearchScope";
 import { openBugReport } from "@/lib/bug-report";
 import { useMailContext } from "@/lib/mail-context";
+import { useMailFreshness } from "@/lib/mail-freshness";
 
 interface MailTopBarProps {
 	accounts: RemitImapAccountResponse[];
@@ -30,6 +33,19 @@ export function MailTopBar({ accounts }: MailTopBarProps) {
 			? [{ id: scope.chip.id, label: scope.chip.label, tone: "scope" as const }]
 			: undefined;
 
+	// Every connected account — the global refresh's whole point, distinct from
+	// the account-scoped controls on the inbox and brief headers.
+	const allAccountIds = useMemo(
+		() => accounts.map((account) => account.accountId),
+		[accounts],
+	);
+	const { hasNewMail } = useMailFreshness();
+	const {
+		state: refreshState,
+		errorMessage: refreshError,
+		refresh,
+	} = useRefreshControl(allAccountIds);
+
 	return (
 		<ShellTopBar
 			search={{
@@ -45,6 +61,15 @@ export function MailTopBar({ accounts }: MailTopBarProps) {
 			onReportBug={openBugReport}
 			onOpenSettings={() => navigate({ to: "/settings/accounts" })}
 			composeShortcut={shortcutHintForAction("compose")}
+			refreshControl={
+				<RefreshButton
+					state={refreshState}
+					onRefresh={refresh}
+					label="Refresh all accounts"
+					errorMessage={refreshError}
+					hasUpdate={hasNewMail(allAccountIds)}
+				/>
+			}
 			account={<AccountMenu />}
 		/>
 	);

package/src/components/mail/DailyBrief.tsx

@@ -46,6 +46,7 @@ import {
 	KeyboardHintBar,
 	matchesBriefFilters,
 	partitionSpamResults,
+	RefreshButton,
 	type SearchResult,
 	SelectionTopBar,
 	SpamResultsOffer,
@@ -69,6 +70,7 @@ import {
 } from "@/hooks/useInitialSyncProgress";
 import { useLabelList } from "@/hooks/useLabels";
 import { useIsDesktop } from "@/hooks/useMediaQuery";
+import { useRefreshControl } from "@/hooks/useRefreshControl";
 import { useSearchTokenContext } from "@/hooks/useSearchTokenContext";
 import { useSemanticSearch } from "@/hooks/useSemanticSearch";
 import type { TriageContextUpdate } from "@/hooks/useTriageLayer";
@@ -84,6 +86,7 @@ import {
 import { isServerError } from "@/lib/error-classifier";
 import type { ListHeaderChrome } from "@/lib/list-header-chrome";
 import { useMailContext } from "@/lib/mail-context";
+import { useMailFreshness } from "@/lib/mail-freshness";
 import { relatedSearchResults, rowToSearchResult } from "@/lib/search-result";
 import { parseSearchTokens } from "@/lib/search-tokens";
 import { spamOfferForResults } from "@/lib/spam-offer";
@@ -581,6 +584,35 @@ export function DailyBrief({
 		[unseenByAccount],
 	);
 
+	// Every non-muted account the brief aggregates — refreshing it means
+	// refreshing all of them, same as the accounts the "caught up" reading
+	// above already spans.
+	const refreshAccountIds = useMemo(
+		() => nonMuted.map((account) => account.accountId),
+		[nonMuted],
+	);
+	const { hasNewMail } = useMailFreshness();
+	const {
+		state: refreshState,
+		errorMessage: refreshError,
+		refresh: onRefreshBrief,
+	} = useRefreshControl(refreshAccountIds, { onSettled: () => refetch() });
+	// Memoized: this element is a dep of `MailListHeader`'s own `chrome` memo
+	// (via the `refreshControl` prop), so a fresh element identity every render
+	// would defeat that memo and re-render every chrome consumer with it.
+	const refreshControl = useMemo(
+		() => (
+			<RefreshButton
+				state={refreshState}
+				onRefresh={onRefreshBrief}
+				label="Refresh daily brief"
+				errorMessage={refreshError}
+				hasUpdate={hasNewMail(refreshAccountIds)}
+			/>
+		),
+		[refreshState, onRefreshBrief, refreshError, hasNewMail, refreshAccountIds],
+	);
+
 	// The phone search takeover renders the account/free-text-narrowed rows,
 	// further narrowed by the same category and attribute chips the list applies.
 	const searchResults = useMemo<SearchResult[]>(
@@ -791,6 +823,7 @@ export function DailyBrief({
 						// it is on the mailbox route (#212) — the two-engine panel stays for
 						// the typing/uncommitted state only.
 						searchResultsInBody: true,
+						refreshControl,
 					}}
 					rows={filteredRows}
 				>

package/src/components/mail/MailListHeader.tsx

@@ -139,6 +139,12 @@ export interface MailListHeaderProps {
 	 * leaves this unset and keeps the panel for every query.
 	 */
 	searchResultsInBody?: boolean;
+	/**
+	 * The refresh control for this view — the mailbox route and the brief pass
+	 * one, scoped to the account(s) they show; a view with nothing account-scoped
+	 * to refresh (Starred) leaves it unset.
+	 */
+	refreshControl?: ReactNode;
 }
 
 export function MailListHeader({
@@ -157,6 +163,7 @@ export function MailListHeader({
 	searchResultsLabel = "Top matches",
 	relatedResultsLabel = "Related",
 	searchResultsInBody = false,
+	refreshControl,
 }: MailListHeaderProps) {
 	const {
 		accounts,
@@ -441,6 +448,7 @@ export function MailListHeader({
 						{unreadCount.toLocaleString()} unread
 					</span>
 					<FilterToggle />
+					{refreshControl}
 				</>
 			),
 			searchSlot: ownsSearch && !searchExpanded && (
@@ -492,6 +500,7 @@ export function MailListHeader({
 			chromeResults,
 			makeFilterAction,
 			searchConversion,
+			refreshControl,
 		],
 	);
 

package/src/components/mail/MailViewChrome.tsx

@@ -59,6 +59,8 @@ interface MailViewChromeProps {
 	 * over its own already query-narrowed rows.
 	 */
 	searchResultsInBody?: boolean;
+	/** The view's own refresh control, scoped to the account it shows. */
+	refreshControl?: ReactNode;
 }
 
 export function MailViewChrome({
@@ -81,6 +83,7 @@ export function MailViewChrome({
 	searchResultsLabel,
 	relatedResultsLabel,
 	searchResultsInBody,
+	refreshControl,
 }: MailViewChromeProps) {
 	// A query owns the pane: the filter chrome and the search's own affordance
 	// narrow the same list from the same place, so the filter sheet stands down
@@ -116,6 +119,7 @@ export function MailViewChrome({
 				searchResultsLabel={searchResultsLabel}
 				relatedResultsLabel={relatedResultsLabel}
 				searchResultsInBody={searchResultsInBody}
+				refreshControl={refreshControl}
 			>
 				{/* One shell either way: the children's parent must not change when a
 				    query starts, or everything under it — including the header's own

package/src/components/mail/MailboxPane.tsx

@@ -30,6 +30,7 @@ import {
 	inboxFilterConfig,
 	type MessageListFilter,
 	ReadingPaneEmpty,
+	RefreshButton,
 	type RescueCandidate,
 	type SearchResult,
 	useAppShellLayout,
@@ -87,6 +88,7 @@ import { useLayoutTier } from "@/hooks/useLayoutTier";
 import { useMailboxAccount } from "@/hooks/useMailboxAccount";
 import { useToggleReadFor } from "@/hooks/useMarkAsRead";
 import { useMoveMessages } from "@/hooks/useMoveMessages";
+import { useRefreshControl } from "@/hooks/useRefreshControl";
 import { useRescueCandidates } from "@/hooks/useRescueCandidates";
 import { useSearchTokenContext } from "@/hooks/useSearchTokenContext";
 import { useSemanticSearch } from "@/hooks/useSemanticSearch";
@@ -110,6 +112,7 @@ import {
 } from "@/lib/inbox-filters";
 import { readIntelligencePref } from "@/lib/intelligence-pref";
 import { useMailContext } from "@/lib/mail-context";
+import { useMailFreshness } from "@/lib/mail-freshness";
 import { isRescueCandidate } from "@/lib/rescue-candidates";
 import { recordRescueSentToJunk } from "@/lib/rescue-telemetry";
 import {
@@ -953,6 +956,42 @@ function MailboxList() {
 	const listTitle = mailboxName ?? "Inbox";
 	const preset = useMemo(() => inboxFilterConfig(), []);
 
+	// The account owning this folder — undefined for the instant before
+	// `useMailboxAccount` resolves it, which simply means there is nothing to
+	// refresh yet.
+	const refreshAccountIds = useMemo(
+		() => (mailboxAccountId ? [mailboxAccountId] : []),
+		[mailboxAccountId],
+	);
+	const { hasNewMail } = useMailFreshness();
+	const {
+		state: refreshState,
+		errorMessage: refreshError,
+		refresh: onRefreshMailbox,
+	} = useRefreshControl(refreshAccountIds, { onSettled: onRetry });
+	// Memoized: this element is a dep of `MailListHeader`'s own `chrome` memo
+	// (via the `refreshControl` prop), so a fresh element identity every render
+	// would defeat that memo and re-render every chrome consumer with it.
+	const refreshControl = useMemo(
+		() => (
+			<RefreshButton
+				state={refreshState}
+				onRefresh={onRefreshMailbox}
+				label={`Refresh ${listTitle}`}
+				errorMessage={refreshError}
+				hasUpdate={hasNewMail(refreshAccountIds)}
+			/>
+		),
+		[
+			refreshState,
+			onRefreshMailbox,
+			listTitle,
+			refreshError,
+			hasNewMail,
+			refreshAccountIds,
+		],
+	);
+
 	const searchResults = useMemo(
 		() =>
 			threads.map((thread) => threadToSearchResult(thread, resultFolderIndex)),
@@ -1084,6 +1123,7 @@ function MailboxList() {
 			// the "Select all N matching" escalation are reachable on desktop (#212).
 			// The typing/uncommitted state still shows the two-engine panel.
 			searchResultsInBody
+			refreshControl={refreshControl}
 		>
 			{body}
 		</MailViewChrome>

package/src/hooks/useRefreshControl.ts

@@ -0,0 +1,279 @@
+import {
+	mailboxOperationsListMailboxesQueryKey,
+	syncOperationsGetSyncStatusOptions,
+} from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import { syncOperationsTriggerSync } from "@remit/api-http-client/sdk.gen.ts";
+import type { RemitImapMailboxSyncProgress } from "@remit/api-http-client/types.gen.ts";
+import type { RefreshControlState } from "@remit/ui";
+import { type QueryClient, useQueryClient } from "@tanstack/react-query";
+import { useCallback, useEffect, useRef, useState } from "react";
+import { isSyncingPhase } from "@/hooks/useInitialSyncProgress";
+import { shouldEscalate } from "@/lib/error-classifier";
+import { reportFatalError } from "@/lib/fatal-error";
+import { useMailFreshness } from "@/lib/mail-freshness";
+import { useTelemetry } from "@/lib/telemetry-context";
+
+export type { RefreshControlState };
+
+/** How often the wait polls an account's own sync status once a round is
+ * enqueued — fast enough to feel responsive, far below the once-a-minute
+ * background cadence, and bounded by {@link REFRESH_TIMEOUT_MS} either way. */
+export const REFRESH_POLL_MS = 2000;
+
+/** A refresh that gets no answer must terminate in a stated failure rather
+ * than spin forever — this is that bound. */
+export const REFRESH_TIMEOUT_MS = 45_000;
+
+const sleep = (ms: number): Promise<void> =>
+	new Promise((resolve) => setTimeout(resolve, ms));
+
+const messageFor = (error: unknown): string =>
+	error instanceof Error && error.message
+		? error.message
+		: "Something went wrong";
+
+const escalateIfFatal = (error: unknown): void => {
+	if (shouldEscalate(error, { softError: true })) reportFatalError(error);
+};
+
+const maxLastSynced = (
+	mailboxes: readonly RemitImapMailboxSyncProgress[],
+): number =>
+	mailboxes.reduce(
+		(max, mailbox) => Math.max(max, mailbox.lastSyncedAt ?? 0),
+		0,
+	);
+
+/**
+ * `getSyncStatus` for one account, always as a real network read: `staleTime:
+ * 0` means even a reading `MailFreshnessProvider` fetched a moment ago is
+ * treated as stale. Sharing the query key means every fetch here also lands
+ * in the same cache `MailFreshnessProvider` reads, so acknowledging a refresh
+ * (see `useMailFreshness().acknowledge`) re-baselines from data this wait
+ * itself just fetched — never a round-old cached reading.
+ *
+ * Routed through `queryClient.fetchQuery` rather than the raw SDK call, so a
+ * failure here already reaches the global `QueryCache` error sink
+ * (`main.tsx` wires `handleQueryCacheError`) on the same terms as every other
+ * query — a manual `escalateIfFatal` on top would double-report the same
+ * error. `syncOperationsTriggerSync` below is the one call in this file that
+ * genuinely needs it: it's a raw SDK call outside React Query, so nothing
+ * else escalates it.
+ */
+const fetchStatus = (queryClient: QueryClient, accountId: string) =>
+	queryClient.fetchQuery({
+		...syncOperationsGetSyncStatusOptions({ path: { accountId } }),
+		staleTime: 0,
+	});
+
+interface AccountOutcome {
+	accountId: string;
+	message?: string;
+}
+
+/**
+ * Poll one account's sync status until a round that started after
+ * `baselineMaxLastSynced` was captured has settled, or `deadline` passes.
+ *
+ * `POST /sync` only enqueues the round (the worker runs it later), so the
+ * very first status read after triggering can still show the *previous*
+ * round's phase — reading that as "settled" would report success, or a
+ * stale failed phase, before the new round ever ran (#582 review). This
+ * waits for positive evidence the triggered round actually happened: either
+ * the phase was observed mid-flight, or some mailbox's `lastSyncedAt`
+ * advanced past the baseline taken before the trigger.
+ *
+ * Read-only (`getSyncStatus`, no IMAP call, no queue write), so waiting costs
+ * a handful of cheap GETs — never a refetch of the account's own message
+ * list.
+ */
+const waitForSettled = async (
+	queryClient: QueryClient,
+	accountId: string,
+	baselineMaxLastSynced: number,
+	deadline: number,
+): Promise<AccountOutcome | undefined> => {
+	let observedInProgress = false;
+	for (;;) {
+		const outcome = await fetchStatus(queryClient, accountId)
+			.then((data) => ({ ok: true as const, data }))
+			.catch((error: unknown) => ({ ok: false as const, error }));
+		if (!outcome.ok) {
+			return { accountId, message: messageFor(outcome.error) };
+		}
+		const { syncPhase, mailboxes } = outcome.data;
+		if (isSyncingPhase(syncPhase)) {
+			observedInProgress = true;
+		} else {
+			const confirmed =
+				observedInProgress ||
+				maxLastSynced(mailboxes ?? []) > baselineMaxLastSynced;
+			if (confirmed) {
+				if (syncPhase === "error") {
+					return { accountId, message: "Sync failed for this account" };
+				}
+				return undefined;
+			}
+		}
+		if (Date.now() >= deadline) {
+			return { accountId, message: "Refresh is taking longer than usual" };
+		}
+		await sleep(REFRESH_POLL_MS);
+	}
+};
+
+interface AccountResult {
+	accountId: string;
+	/** The trigger itself was accepted — the mailbox-list invalidation and
+	 * `onSettled`/`acknowledge` calls run for every enqueued account,
+	 * independent of whether its own round then succeeded. */
+	enqueued: boolean;
+	ok: boolean;
+	message?: string;
+}
+
+const refreshOneAccount = async (
+	queryClient: QueryClient,
+	telemetry: { recordEvent: (name: string) => void },
+	accountId: string,
+	deadline: number,
+): Promise<AccountResult> => {
+	const baseline = await fetchStatus(queryClient, accountId)
+		.then((data) => ({
+			ok: true as const,
+			maxLastSynced: maxLastSynced(data.mailboxes ?? []),
+		}))
+		.catch((error: unknown) => ({ ok: false as const, error }));
+	if (!baseline.ok) {
+		return {
+			accountId,
+			enqueued: false,
+			ok: false,
+			message: messageFor(baseline.error),
+		};
+	}
+
+	const triggered = await syncOperationsTriggerSync({
+		path: { accountId },
+		throwOnError: true,
+	})
+		.then(() => ({ ok: true as const }))
+		.catch((error: unknown) => ({ ok: false as const, error }));
+	if (!triggered.ok) {
+		escalateIfFatal(triggered.error);
+		return {
+			accountId,
+			enqueued: false,
+			ok: false,
+			message: messageFor(triggered.error),
+		};
+	}
+	telemetry.recordEvent("sync.triggered");
+
+	const settled = await waitForSettled(
+		queryClient,
+		accountId,
+		baseline.maxLastSynced,
+		deadline,
+	);
+	if (settled)
+		return { accountId, enqueued: true, ok: false, message: settled.message };
+	return { accountId, enqueued: true, ok: true };
+};
+
+export interface UseRefreshControlOptions {
+	/** Called once every enqueued account's sync round has settled, alongside
+	 * the unconditional invalidation of each enqueued account's own
+	 * mailbox-list query — the caller's chance to invalidate whatever
+	 * view-specific query (a mailbox's thread list, the brief's unified list)
+	 * the sync may have changed. */
+	onSettled?: () => void;
+}
+
+export interface UseRefreshControlResult {
+	state: RefreshControlState;
+	errorMessage?: string;
+	refresh: () => void;
+}
+
+/**
+ * Drives the shared `RefreshButton` for one or more accounts: triggers a sync
+ * for each, waits for the server's own sync-status to settle — not just the
+ * enqueue ack — then invalidates the queries the caller names. A manual
+ * refresh is an explicit user action, so unlike the background poll it always
+ * shows the result; what it must never do is leave the button spinning with
+ * no answer.
+ */
+export const useRefreshControl = (
+	accountIds: readonly string[],
+	options: UseRefreshControlOptions = {},
+): UseRefreshControlResult => {
+	const queryClient = useQueryClient();
+	const telemetry = useTelemetry();
+	const { acknowledge } = useMailFreshness();
+	const [state, setState] = useState<RefreshControlState>("idle");
+	const [errorMessage, setErrorMessage] = useState<string>();
+	const runIdRef = useRef(0);
+	const accountIdsRef = useRef(accountIds);
+	accountIdsRef.current = accountIds;
+	const optionsRef = useRef(options);
+	optionsRef.current = options;
+
+	// A success confirmation is a beat, not a permanent state — it hands the
+	// button back to idle on its own so a stale checkmark never lingers.
+	useEffect(() => {
+		if (state !== "success") return;
+		const timer = setTimeout(() => setState("idle"), 2000);
+		return () => clearTimeout(timer);
+	}, [state]);
+
+	const refresh = useCallback(() => {
+		const ids = accountIdsRef.current;
+		if (ids.length === 0) {
+			// Reachable before the owning account resolves (a fresh mailbox
+			// route) or when every account is muted (the brief) — a click here
+			// must say why it did nothing, never sit as a dead button.
+			setState("error");
+			setErrorMessage("Nothing to refresh yet");
+			return;
+		}
+		const runId = ++runIdRef.current;
+		setState("refreshing");
+		setErrorMessage(undefined);
+
+		void (async () => {
+			const deadline = Date.now() + REFRESH_TIMEOUT_MS;
+			const results = await Promise.all(
+				ids.map((accountId) =>
+					refreshOneAccount(queryClient, telemetry, accountId, deadline),
+				),
+			);
+			if (runIdRef.current !== runId) return;
+
+			const enqueued = results
+				.filter((result) => result.enqueued)
+				.map((result) => result.accountId);
+			for (const accountId of enqueued) {
+				queryClient.invalidateQueries({
+					queryKey: mailboxOperationsListMailboxesQueryKey({
+						path: { accountId },
+					}),
+				});
+			}
+			if (enqueued.length > 0) {
+				optionsRef.current.onSettled?.();
+				acknowledge(enqueued);
+			}
+
+			const failures = results.filter((result) => !result.ok);
+			if (failures.length === 0) {
+				setState("success");
+			} else {
+				setState("error");
+				setErrorMessage(failures[0]?.message);
+			}
+		})();
+	}, [acknowledge, queryClient, telemetry]);
+
+	return { state, errorMessage, refresh };
+};

package/src/lib/mail-freshness.test.ts

@@ -0,0 +1,116 @@
+import assert from "node:assert/strict";
+import { describe, test } from "node:test";
+import type { RemitImapMailboxSyncProgress } from "@remit/api-http-client/types.gen.ts";
+import type { NavMailboxRole } from "@remit/ui";
+import type { ResultFolderIndex } from "@/lib/result-folder";
+import { hasGrown, totalsFrom } from "./mail-freshness.js";
+
+const mailbox = (
+	mailboxId: string,
+	messagesTotal: number,
+): RemitImapMailboxSyncProgress => ({
+	mailboxId,
+	fullPath: mailboxId,
+	phase: "complete",
+	messagesTotal,
+	messagesSynced: messagesTotal,
+});
+
+const roles = (
+	entries: Record<string, NavMailboxRole | undefined>,
+): ResultFolderIndex =>
+	new Map(
+		Object.entries(entries).map(([id, role]) => [id, role ? { role } : {}]),
+	);
+
+describe("hasGrown", () => {
+	test("false when nothing changed", () => {
+		const baseline = new Map([["mb-1", 10]]);
+		const current = new Map([["mb-1", 10]]);
+		assert.equal(hasGrown(baseline, current), false);
+	});
+
+	test("true when a mailbox's total increased", () => {
+		const baseline = new Map([["mb-1", 10]]);
+		const current = new Map([["mb-1", 11]]);
+		assert.equal(hasGrown(baseline, current), true);
+	});
+
+	test("false when a mailbox's total dropped (reads, deletes) — not an arrival", () => {
+		const baseline = new Map([["mb-1", 10]]);
+		const current = new Map([["mb-1", 9]]);
+		assert.equal(hasGrown(baseline, current), false);
+	});
+
+	test("a mailbox missing from the baseline counts from zero", () => {
+		const baseline = new Map<string, number>();
+		const current = new Map([["mb-1", 1]]);
+		assert.equal(hasGrown(baseline, current), true);
+	});
+
+	test("a mailbox with zero new messages is not growth", () => {
+		const baseline = new Map<string, number>();
+		const current = new Map([["mb-1", 0]]);
+		assert.equal(hasGrown(baseline, current), false);
+	});
+
+	test("one mailbox growing is enough even if others are unchanged", () => {
+		const baseline = new Map([
+			["mb-1", 10],
+			["mb-2", 5],
+		]);
+		const current = new Map([
+			["mb-1", 10],
+			["mb-2", 6],
+		]);
+		assert.equal(hasGrown(baseline, current), true);
+	});
+});
+
+describe("totalsFrom", () => {
+	test("keeps a mailbox with no resolved role (a custom folder)", () => {
+		const totals = totalsFrom([mailbox("mb-custom", 5)], roles({}));
+		assert.deepEqual([...totals], [["mb-custom", 5]]);
+	});
+
+	test("keeps Inbox and Junk — both are places new mail actually arrives", () => {
+		const totals = totalsFrom(
+			[mailbox("mb-inbox", 5), mailbox("mb-junk", 2)],
+			roles({ "mb-inbox": "inbox", "mb-junk": "junk" }),
+		);
+		assert.deepEqual(new Set(totals.keys()), new Set(["mb-inbox", "mb-junk"]));
+	});
+
+	for (const role of ["sent", "drafts", "trash", "archive"] as const) {
+		test(`drops ${role} — its own total growing is the user's doing, not an arrival`, () => {
+			const totals = totalsFrom([mailbox("mb-1", 5)], roles({ "mb-1": role }));
+			assert.equal(totals.has("mb-1"), false);
+		});
+	}
+
+	test("a delete (Inbox shrinks, Trash grows) never reads as growth once Trash is excluded", () => {
+		const folders = roles({ "mb-inbox": "inbox", "mb-trash": "trash" });
+		const baseline = totalsFrom(
+			[mailbox("mb-inbox", 10), mailbox("mb-trash", 3)],
+			folders,
+		);
+		const afterDelete = totalsFrom(
+			[mailbox("mb-inbox", 9), mailbox("mb-trash", 4)],
+			folders,
+		);
+		assert.equal(hasGrown(baseline, afterDelete), false);
+	});
+
+	test("real new mail in Inbox still reads as growth alongside an unrelated delete", () => {
+		const folders = roles({ "mb-inbox": "inbox", "mb-trash": "trash" });
+		const baseline = totalsFrom(
+			[mailbox("mb-inbox", 10), mailbox("mb-trash", 3)],
+			folders,
+		);
+		const afterArrivalAndDelete = totalsFrom(
+			[mailbox("mb-inbox", 11), mailbox("mb-trash", 4)],
+			folders,
+		);
+		assert.equal(hasGrown(baseline, afterArrivalAndDelete), true);
+	});
+});

package/src/lib/mail-freshness.tsx

@@ -0,0 +1,201 @@
+import { syncOperationsGetSyncStatusOptions } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import type { RemitImapMailboxSyncProgress } from "@remit/api-http-client/types.gen.ts";
+import type { NavMailboxRole } from "@remit/ui";
+import { useQueries, useQueryClient } from "@tanstack/react-query";
+import {
+	createContext,
+	type ReactNode,
+	useCallback,
+	useContext,
+	useEffect,
+	useMemo,
+	useRef,
+	useState,
+} from "react";
+import { useMailContext } from "@/lib/mail-context";
+import type { ResultFolderIndex } from "@/lib/result-folder";
+
+/**
+ * How often the background poll re-reads each open account's sync status.
+ * `getSyncStatus` is a DDB read with no IMAP call and no queue write (see
+ * typespec Sync Operations), so this is the cheap side of the refresh
+ * feature — the once-a-minute check that decides whether anything is worth
+ * surfacing, never a refetch of the mailbox or brief content itself.
+ */
+export const FRESHNESS_POLL_MS = 60_000;
+
+/**
+ * Roles whose own total growing is the user's doing, not an arrival: sending
+ * grows Sent, deleting or archiving grows Trash/Archive, and a Drafts count is
+ * autosaves. Counting any of these as "new mail" would light the dot on a
+ * message the user just moved themselves. Junk is kept in — spam is still an
+ * arrival, just an unwanted one — and a mailbox with no resolved role (a
+ * custom folder, or one a filter files mail into directly) is never excluded.
+ */
+const EXCLUDED_GROWTH_ROLES: ReadonlySet<NavMailboxRole> = new Set([
+	"sent",
+	"drafts",
+	"trash",
+	"archive",
+]);
+
+type MailboxTotals = ReadonlyMap<string, number>;
+
+export const totalsFrom = (
+	mailboxes: readonly RemitImapMailboxSyncProgress[],
+	resultFolderIndex: ResultFolderIndex,
+): MailboxTotals => {
+	const totals = new Map<string, number>();
+	for (const mailbox of mailboxes) {
+		const role = resultFolderIndex.get(mailbox.mailboxId)?.role;
+		if (role && EXCLUDED_GROWTH_ROLES.has(role)) continue;
+		totals.set(mailbox.mailboxId, mailbox.messagesTotal);
+	}
+	return totals;
+};
+
+/**
+ * Whether any mailbox's message total grew since the baseline. Pure so the
+ * "did mail arrive" call is unit-testable without a DOM or a QueryClient. A
+ * mailbox missing from the baseline (new folder, first-ever reading) counts
+ * from zero rather than being skipped, so mail landing in a folder created
+ * since the last look still counts as an arrival.
+ */
+export const hasGrown = (
+	baseline: MailboxTotals,
+	current: MailboxTotals,
+): boolean => {
+	for (const [mailboxId, total] of current) {
+		if (total > (baseline.get(mailboxId) ?? 0)) return true;
+	}
+	return false;
+};
+
+interface MailFreshnessContextValue {
+	/** True once any of these accounts has grown since it was last acknowledged. */
+	hasNewMail: (accountIds: readonly string[]) => boolean;
+	/** Clears the flag for these accounts and re-baselines them from whatever
+	 * is currently cached — called once a refresh has shown the user current
+	 * data for them. */
+	acknowledge: (accountIds: readonly string[]) => void;
+}
+
+const MailFreshnessContext = createContext<MailFreshnessContextValue | null>(
+	null,
+);
+
+export const useMailFreshness = (): MailFreshnessContextValue => {
+	const ctx = useContext(MailFreshnessContext);
+	if (!ctx) {
+		throw new Error(
+			"useMailFreshness must be used inside <MailFreshnessProvider>",
+		);
+	}
+	return ctx;
+};
+
+interface MailFreshnessProviderProps {
+	accountIds: readonly string[];
+	children: ReactNode;
+}
+
+/**
+ * Watches every open account's sync status once a minute and flags which
+ * accounts have grown since they were last shown to the user (#582 clause
+ * 4). The flag is sticky until acknowledged — a background tick never
+ * invalidates or reorders anything on its own, it only lights the dot on
+ * whichever `RefreshButton` reads this context, leaving the choice to load
+ * it with the user.
+ */
+export function MailFreshnessProvider({
+	accountIds,
+	children,
+}: MailFreshnessProviderProps) {
+	const queryClient = useQueryClient();
+	const { resultFolderIndex } = useMailContext();
+	const baselineRef = useRef(new Map<string, MailboxTotals>());
+	const seededRef = useRef(new Set<string>());
+	const [newMail, setNewMail] = useState<ReadonlySet<string>>(new Set());
+
+	const queries = useQueries({
+		queries: accountIds.map((accountId) => ({
+			...syncOperationsGetSyncStatusOptions({ path: { accountId } }),
+			refetchInterval: FRESHNESS_POLL_MS,
+			staleTime: FRESHNESS_POLL_MS,
+			meta: { softError: true },
+		})),
+	});
+	const updatedKey = queries.map((query) => query.dataUpdatedAt).join(",");
+	const accountIdsKey = accountIds.join(",");
+
+	// biome-ignore lint/correctness/useExhaustiveDependencies: updatedKey is the real trigger (each query's own dataUpdatedAt); queries and resultFolderIndex are read fresh each run, not values this effect reacts to on their own.
+	useEffect(() => {
+		let changed = false;
+		const next = new Set(newMail);
+		accountIds.forEach((accountId, index) => {
+			const data = queries[index]?.data;
+			if (!data) return;
+			const current = totalsFrom(data.mailboxes ?? [], resultFolderIndex);
+			if (!seededRef.current.has(accountId)) {
+				seededRef.current.add(accountId);
+				baselineRef.current.set(accountId, current);
+				return;
+			}
+			if (next.has(accountId)) return;
+			const baseline = baselineRef.current.get(accountId) ?? new Map();
+			if (hasGrown(baseline, current)) {
+				next.add(accountId);
+				changed = true;
+			}
+		});
+		if (changed) setNewMail(next);
+	}, [accountIdsKey, updatedKey]);
+
+	const hasNewMail = useCallback(
+		(ids: readonly string[]) => ids.some((id) => newMail.has(id)),
+		[newMail],
+	);
+
+	const acknowledge = useCallback(
+		(ids: readonly string[]) => {
+			setNewMail((prev) => {
+				if (ids.every((id) => !prev.has(id))) return prev;
+				const next = new Set(prev);
+				for (const id of ids) next.delete(id);
+				return next;
+			});
+			for (const accountId of ids) {
+				// `useRefreshControl` reads and writes this exact query key through
+				// `queryClient.fetchQuery` as its own wait settles, so this is the
+				// data that refresh just showed the user — never a round-old
+				// cached reading from this provider's own 60s interval.
+				const data = queryClient.getQueryData(
+					syncOperationsGetSyncStatusOptions({ path: { accountId } }).queryKey,
+				) as
+					| { mailboxes?: readonly RemitImapMailboxSyncProgress[] }
+					| undefined;
+				baselineRef.current.set(
+					accountId,
+					totalsFrom(data?.mailboxes ?? [], resultFolderIndex),
+				);
+				seededRef.current.add(accountId);
+			}
+		},
+		[queryClient, resultFolderIndex],
+	);
+
+	// The sync-status queries update on their own cadence (this poll's 60s, or
+	// every 3s while `useInitialSyncProgress` shares the same key during an
+	// initial sync) — memoized so a tick that changes nothing about the
+	// flag set does not re-render every consumer down the tree.
+	const value = useMemo(
+		() => ({ hasNewMail, acknowledge }),
+		[hasNewMail, acknowledge],
+	);
+
+	return (
+		<MailFreshnessContext.Provider value={value}>
+			{children}
+		</MailFreshnessContext.Provider>
+	);
+}

package/src/routes/mail.tsx

@@ -31,6 +31,7 @@ import { useResultFolderIndex } from "@/hooks/useResultFolderIndex";
 import { useStaleAccountSync } from "@/hooks/useStaleAccountSync";
 import { writeIntelligencePref } from "@/lib/intelligence-pref";
 import { MailContext } from "@/lib/mail-context";
+import { MailFreshnessProvider } from "@/lib/mail-freshness";
 import {
 	isBriefRoute,
 	isFlaggedRoute,
@@ -238,6 +239,10 @@ function MailLayout() {
 	}, []);
 
 	const accounts = config?.accounts ?? [];
+	const accountIds = useMemo(
+		() => accounts.map((account) => account.accountId),
+		[accounts],
+	);
 	const mailboxNameIndex = useMailboxNameIndex(accounts);
 	const resultFolderIndex = useResultFolderIndex(accounts);
 	const accountNameIndex = useMemo(
@@ -337,147 +342,149 @@ function MailLayout() {
 
 	return (
 		<MailContext.Provider value={mailContextValue}>
-			{isConfigError ? (
-				<div className="flex h-full items-center justify-center bg-canvas p-4">
-					<ErrorState
-						title="Couldn't load your account"
-						error={configError}
-						onRetry={() => {
-							refetchConfig();
-						}}
-					/>
-				</div>
-			) : onBriefRoute ? (
-				// Daily brief (/mail/) — no mailboxId param; same 3-pane layout as a
-				// mailbox: an open message has an intelligence rail here too (#52).
-				<BriefPane selectedMessageId={mobileSelectedMessageId}>
-					{isSinglePane ? (
-						<AppShellSlotted
-							nav={navContent}
-							list={<BriefPane.Phone />}
-							intelligenceOpen={intelligenceOpen}
-							overlay={overlayContent}
-							skeleton={<AppShellSkeleton />}
-							isLoading={isLoading || hasNoAccounts}
-							{...navSlideOver}
-						/>
-					) : (
-						<AppShellSlotted
-							nav={navContent}
-							topBar={topBar}
-							list={<BriefPane.List />}
-							reading={<BriefPane.Reading />}
-							intelligence={<BriefPane.Intelligence />}
-							intelligenceOpen={intelligenceOpen}
-							hasThread={Boolean(mobileSelectedMessageId)}
-							overlay={overlayContent}
-							skeleton={<AppShellSkeleton />}
-							isLoading={isLoading || hasNoAccounts}
-							{...navSlideOver}
-						/>
-					)}
-				</BriefPane>
-			) : onFlaggedRoute ? (
-				// Flagged virtual mailbox (/mail/flagged) — flat starred list across
-				// accounts; same slots as the brief, intelligence rail included.
-				<FlaggedPane selectedMessageId={mobileSelectedMessageId}>
-					{isSinglePane ? (
-						<AppShellSlotted
-							nav={navContent}
-							list={<FlaggedPane.Phone />}
-							intelligenceOpen={intelligenceOpen}
-							overlay={overlayContent}
-							skeleton={<AppShellSkeleton />}
-							isLoading={isLoading || hasNoAccounts}
-							{...navSlideOver}
-						/>
-					) : (
-						<AppShellSlotted
-							nav={navContent}
-							topBar={topBar}
-							list={<FlaggedPane.List />}
-							reading={<FlaggedPane.Reading />}
-							intelligence={<FlaggedPane.Intelligence />}
-							intelligenceOpen={intelligenceOpen}
-							hasThread={Boolean(mobileSelectedMessageId)}
-							overlay={overlayContent}
-							skeleton={<AppShellSkeleton />}
-							isLoading={isLoading || hasNoAccounts}
-							{...navSlideOver}
-						/>
-					)}
-				</FlaggedPane>
-			) : mobileMailboxId ? (
-				// Mailbox view (/mail/$mailboxId) — full 4-pane layout.
-				<MailboxPane
-					mailboxId={mobileMailboxId}
-					selectedMessageId={mobileSelectedMessageId}
-				>
-					{isSinglePane ? (
-						<AppShellSlotted
-							nav={navContent}
-							list={<MailboxPane.Phone />}
-							intelligenceOpen={intelligenceOpen}
-							overlay={overlayContent}
-							skeleton={<AppShellSkeleton />}
-							isLoading={isLoading || hasNoAccounts}
-							{...navSlideOver}
-						/>
-					) : (
-						<AppShellSlotted
-							nav={navContent}
-							topBar={topBar}
-							list={<MailboxPane.List />}
-							reading={<MailboxPane.Reading />}
-							intelligence={<MailboxPane.Intelligence />}
-							intelligenceOpen={intelligenceOpen}
-							hasThread={Boolean(mobileSelectedMessageId)}
-							overlay={overlayContent}
-							skeleton={<AppShellSkeleton />}
-							isLoading={isLoading || hasNoAccounts}
-							{...navSlideOver}
-						/>
-					)}
-				</MailboxPane>
-			) : onOutboxRoute ? (
-				// Outbox — 2-pane layout (list + reading, no intelligence).
-				<OutboxPane>
-					{isSinglePane ? (
-						<AppShellSlotted
-							nav={navContent}
-							list={<OutboxPane.Phone />}
-							intelligenceOpen={false}
-							overlay={overlayContent}
-							skeleton={<AppShellSkeleton />}
-							isLoading={isLoading || hasNoAccounts}
-							{...navSlideOver}
-						/>
-					) : (
-						<AppShellSlotted
-							nav={navContent}
-							topBar={topBar}
-							list={<OutboxPane.List />}
-							reading={<OutboxPane.Reading />}
-							intelligenceOpen={false}
-							overlay={overlayContent}
-							skeleton={<AppShellSkeleton />}
-							isLoading={isLoading || hasNoAccounts}
-							{...navSlideOver}
+			<MailFreshnessProvider accountIds={accountIds}>
+				{isConfigError ? (
+					<div className="flex h-full items-center justify-center bg-canvas p-4">
+						<ErrorState
+							title="Couldn't load your account"
+							error={configError}
+							onRetry={() => {
+								refetchConfig();
+							}}
 						/>
-					)}
-				</OutboxPane>
-			) : (
-				// Fallback: transitioning or unrecognized route — show skeleton.
-				<AppShellSkeleton />
-			)}
-			<KeyboardShortcutsModal
-				isOpen={showShortcuts}
-				onClose={() => setShowShortcuts(false)}
-			/>
-			{/* Outlet is required for TanStack Router to activate child routes.
+					</div>
+				) : onBriefRoute ? (
+					// Daily brief (/mail/) — no mailboxId param; same 3-pane layout as a
+					// mailbox: an open message has an intelligence rail here too (#52).
+					<BriefPane selectedMessageId={mobileSelectedMessageId}>
+						{isSinglePane ? (
+							<AppShellSlotted
+								nav={navContent}
+								list={<BriefPane.Phone />}
+								intelligenceOpen={intelligenceOpen}
+								overlay={overlayContent}
+								skeleton={<AppShellSkeleton />}
+								isLoading={isLoading || hasNoAccounts}
+								{...navSlideOver}
+							/>
+						) : (
+							<AppShellSlotted
+								nav={navContent}
+								topBar={topBar}
+								list={<BriefPane.List />}
+								reading={<BriefPane.Reading />}
+								intelligence={<BriefPane.Intelligence />}
+								intelligenceOpen={intelligenceOpen}
+								hasThread={Boolean(mobileSelectedMessageId)}
+								overlay={overlayContent}
+								skeleton={<AppShellSkeleton />}
+								isLoading={isLoading || hasNoAccounts}
+								{...navSlideOver}
+							/>
+						)}
+					</BriefPane>
+				) : onFlaggedRoute ? (
+					// Flagged virtual mailbox (/mail/flagged) — flat starred list across
+					// accounts; same slots as the brief, intelligence rail included.
+					<FlaggedPane selectedMessageId={mobileSelectedMessageId}>
+						{isSinglePane ? (
+							<AppShellSlotted
+								nav={navContent}
+								list={<FlaggedPane.Phone />}
+								intelligenceOpen={intelligenceOpen}
+								overlay={overlayContent}
+								skeleton={<AppShellSkeleton />}
+								isLoading={isLoading || hasNoAccounts}
+								{...navSlideOver}
+							/>
+						) : (
+							<AppShellSlotted
+								nav={navContent}
+								topBar={topBar}
+								list={<FlaggedPane.List />}
+								reading={<FlaggedPane.Reading />}
+								intelligence={<FlaggedPane.Intelligence />}
+								intelligenceOpen={intelligenceOpen}
+								hasThread={Boolean(mobileSelectedMessageId)}
+								overlay={overlayContent}
+								skeleton={<AppShellSkeleton />}
+								isLoading={isLoading || hasNoAccounts}
+								{...navSlideOver}
+							/>
+						)}
+					</FlaggedPane>
+				) : mobileMailboxId ? (
+					// Mailbox view (/mail/$mailboxId) — full 4-pane layout.
+					<MailboxPane
+						mailboxId={mobileMailboxId}
+						selectedMessageId={mobileSelectedMessageId}
+					>
+						{isSinglePane ? (
+							<AppShellSlotted
+								nav={navContent}
+								list={<MailboxPane.Phone />}
+								intelligenceOpen={intelligenceOpen}
+								overlay={overlayContent}
+								skeleton={<AppShellSkeleton />}
+								isLoading={isLoading || hasNoAccounts}
+								{...navSlideOver}
+							/>
+						) : (
+							<AppShellSlotted
+								nav={navContent}
+								topBar={topBar}
+								list={<MailboxPane.List />}
+								reading={<MailboxPane.Reading />}
+								intelligence={<MailboxPane.Intelligence />}
+								intelligenceOpen={intelligenceOpen}
+								hasThread={Boolean(mobileSelectedMessageId)}
+								overlay={overlayContent}
+								skeleton={<AppShellSkeleton />}
+								isLoading={isLoading || hasNoAccounts}
+								{...navSlideOver}
+							/>
+						)}
+					</MailboxPane>
+				) : onOutboxRoute ? (
+					// Outbox — 2-pane layout (list + reading, no intelligence).
+					<OutboxPane>
+						{isSinglePane ? (
+							<AppShellSlotted
+								nav={navContent}
+								list={<OutboxPane.Phone />}
+								intelligenceOpen={false}
+								overlay={overlayContent}
+								skeleton={<AppShellSkeleton />}
+								isLoading={isLoading || hasNoAccounts}
+								{...navSlideOver}
+							/>
+						) : (
+							<AppShellSlotted
+								nav={navContent}
+								topBar={topBar}
+								list={<OutboxPane.List />}
+								reading={<OutboxPane.Reading />}
+								intelligenceOpen={false}
+								overlay={overlayContent}
+								skeleton={<AppShellSkeleton />}
+								isLoading={isLoading || hasNoAccounts}
+								{...navSlideOver}
+							/>
+						)}
+					</OutboxPane>
+				) : (
+					// Fallback: transitioning or unrecognized route — show skeleton.
+					<AppShellSkeleton />
+				)}
+				<KeyboardShortcutsModal
+					isOpen={showShortcuts}
+					onClose={() => setShowShortcuts(false)}
+				/>
+				{/* Outlet is required for TanStack Router to activate child routes.
 			    Routes that manage their own rendering (brief, mailbox, outbox) return
 			    null from their component — the parent shell owns the layout. */}
-			<Outlet />
+				<Outlet />
+			</MailFreshnessProvider>
 		</MailContext.Provider>
 	);
 }