@remit/web-client 0.0.248 → 0.0.250

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/web-client",
-  "version": "0.0.248",
+  "version": "0.0.250",
   "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/mail/DailyBrief.tsx

@@ -2,10 +2,23 @@
  * DailyBrief — unified cross-account message digest.
  *
  * Renders one section per message category (Personal / Transactional /
- * Newsletter / Marketing / Social / Automated) from the GET /threads endpoint.
- * Starred mail is not a section — Flagged is a virtual mailbox in the nav. The
- * brief defaults to the cross-account aggregate, and `MailListHeader` provides
- * the title, unread count, and search.
+ * Newsletter / Marketing / Social / Automated / Unclassified) from the GET
+ * /threads endpoint. Starred mail is not a section — Flagged is a virtual
+ * mailbox in the nav. The brief defaults to the cross-account aggregate, and
+ * `MailListHeader` provides the title, unread count, and search.
+ *
+ * The brief paginates by section, not as a whole. Each section is its own
+ * category-scoped request for its newest rows plus one count of the whole
+ * category, so a header states how much mail that category holds rather than how
+ * many of a shared 50-row window fell into it, and a category whose mail is all
+ * older than that window still has a section with rows in it (#312). "Show all"
+ * hands the reader to the brief's own filtered list for that category; nothing
+ * here loads a mailbox.
+ *
+ * Sections are the unsearched brief only. A search is one request and one flat
+ * list, newest first across every category: sectioning the matches would order
+ * them by category first and recency second, putting last spring's newsletter
+ * above a mail that arrived this morning.
  *
  * The list's filter surface is the kit `BriefSections`: categories, attribute
  * chips and the account source group, in a panel the list header's caret opens
@@ -21,21 +34,26 @@
  * `ThreadListInteraction` cursor and `useSelection` state, and the same
  * `SelectionTopBar` in place of the pane header. A shift-range spans the rendered rows in
  * document order, so it crosses category sections exactly as the eye reads
- * them and never picks up a row hidden behind "Show N more" or a collapsed
- * header. Folder-scoped verbs (Move, Apply label, Organize) resolve their
+ * them and never picks up a row behind a collapsed header or one the section's
+ * page did not reach. Folder-scoped verbs (Move, Apply label, Organize) resolve their
  * account and source folder from the selection — see
  * `resolveBriefSelectionScope`.
  *
- * Loading: skeleton rows on first paint, patch-in-place on refetch.
- * Error: per-section; the brief still renders other sections.
+ * Loading: skeleton rows on first paint, per-section from then on, and the rows
+ * already on screen stay put while the same predicate is re-fetched.
+ * Error: a section whose own request never got an answer says so in its own
+ * place and the rest of the brief stands. A 5xx is not that case — the API
+ * breaking escalates globally (`shouldEscalate`, #1059), and nothing here softens
+ * it.
  * Empty: "You're caught up", but only once the server confirms no sync is
  * running — while one is, the same empty list says it is still syncing.
  */
-import {
-	mailboxOperationsListMailboxesOptions,
-	unifiedThreadOperationsListAllThreadsOptions,
-} from "@remit/api-http-client/@tanstack/react-query.gen.ts";
-import type { RemitImapAccountResponse } from "@remit/api-http-client/types.gen.ts";
+import { mailboxOperationsListMailboxesOptions } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import type {
+	RemitImapAccountResponse,
+	RemitImapMessageCategory,
+	RemitImapThreadMessageResponse,
+} from "@remit/api-http-client/types.gen.ts";
 import {
 	type BriefCategoryFilter,
 	BriefEmpty,
@@ -49,10 +67,12 @@ import {
 	FilterPanelProvider,
 	type FilterSheetProps,
 	type FilterSheetSource,
+	isBriefCategory,
 	KeyboardHintBar,
 	matchesBriefFilters,
 	partitionSpamResults,
 	RefreshButton,
+	SECTION_ROW_CAP,
 	type SearchResult,
 	type SelectionRestriction,
 	SelectionTopBar,
@@ -62,7 +82,7 @@ import {
 	type ThreadSection,
 	toggleBriefFilterInQuery,
 } from "@remit/ui";
-import { useQueries, useQuery } from "@tanstack/react-query";
+import { useQueries } from "@tanstack/react-query";
 import { AlertCircle, RefreshCw } from "lucide-react";
 import {
 	type ReactNode,
@@ -72,6 +92,7 @@ import {
 	useState,
 } from "react";
 import { useJunkMailbox } from "@/hooks/useArchiveMailbox";
+import { useBriefSearchRows, useBriefSections } from "@/hooks/useBriefSections";
 import {
 	isSyncingPhase,
 	useInitialSyncProgress,
@@ -85,13 +106,15 @@ import { useSemanticSearch } from "@/hooks/useSemanticSearch";
 import type { TriageContextUpdate } from "@/hooks/useTriageLayer";
 import { sortAccountsByCreatedAt } from "@/lib/account-order";
 import {
+	BRIEF_CATEGORIES,
+	type BriefCategoryResult,
+	briefSections,
+	briefSectionTotal,
 	excludeMutedSenders,
-	groupBriefSections,
-	matchesBriefSearch,
 	matchesSearchTokens,
-	mergeSearchRows,
 	toThreadRowData,
 } from "@/lib/brief";
+import { briefCountsMatchRows, briefCriteria } from "@/lib/brief-criteria";
 import { isServerError } from "@/lib/error-classifier";
 import { junkDestination } from "@/lib/junk-destination";
 import type { ListHeaderChrome } from "@/lib/list-header-chrome";
@@ -102,6 +125,7 @@ import { showInlineSearchResults } from "@/lib/search-surface";
 import { parseSearchTokens } from "@/lib/search-tokens";
 import { resolveSelectionAccountScope } from "@/lib/selection-account-scope";
 import { spamOfferForResults } from "@/lib/spam-offer";
+import { dedupeByThread } from "@/lib/starred-rows";
 import { wizardSelectionFrom } from "@/lib/wizard-selection";
 import {
 	type OpenThreadTarget,
@@ -121,9 +145,17 @@ import {
 	useThreadListSelection,
 } from "./ThreadListInteraction";
 
-/* Page size for the unscoped cross-folder search. One page is what the takeover
-   and the "Top matches" list render; the server caps it at 500. */
-const UNSCOPED_SEARCH_PAGE_SIZE = 200;
+/* Rows one category's own list renders once the brief is narrowed to it — the
+   "show all" destination, which is a page of that category rather than the whole
+   of it. */
+const CATEGORY_PAGE_SIZE = 50;
+
+/* One page of matches for a searched brief. The server orders the whole match
+   set; this is how much of the front of it the list renders. */
+const SEARCH_PAGE_SIZE = 200;
+
+/* The brief asks for no sections while it is answering a search. */
+const NO_CATEGORIES: RemitImapMessageCategory[] = [];
 
 // ---------------------------------------------------------------------------
 // Skeleton
@@ -433,6 +465,15 @@ export function DailyBrief({
 
 	const searching = searchInput.trim().length > 0;
 
+	// The committed query, split into the free text the request carries and the
+	// tokens. Free text is what turns the brief from seven category sections into
+	// one ordered list of matches, so it is read before anything downstream of it.
+	const { freeText: sq, tokens: queryTokens } = parseSearchTokens(
+		searchQuery.trim().toLowerCase(),
+		tokenContext,
+	);
+	const underQuery = sq.length > 0;
+
 	// Under a query the chips and the query are one state: a chip writes its term
 	// into the query — `is:unread`, `has:attachment`, `category:newsletter` — and
 	// a term typed by hand ticks its chip. What narrows the rows is then legible
@@ -449,6 +490,21 @@ export function DailyBrief({
 		[searchInput, selectedCategory],
 	);
 
+	// The same two, read off the committed query rather than the field. The chips
+	// above tick as the reader types, which is what the panel is for; the requests
+	// must not. Half-typed `is:unre` would otherwise fire a fresh burst of section
+	// requests on the way to `is:unread`, and the whole point of counting on a
+	// deliberate act is that nothing here rides a keystroke.
+	const requestFilters = useMemo(
+		() => briefChipFilters({ query: searchQuery, ownFilters: activeFilters }),
+		[searchQuery, activeFilters],
+	);
+	const requestCategory = useMemo(
+		() =>
+			briefChipCategory({ query: searchQuery, ownCategory: selectedCategory }),
+		[searchQuery, selectedCategory],
+	);
+
 	const toggleChip = useCallback(
 		(id: BriefFilterId) => {
 			if (!searching || !briefFilterHasTerm(id)) {
@@ -472,6 +528,20 @@ export function DailyBrief({
 		[searching, searchInput, onSearchChange],
 	);
 
+	// The way to a section's whole category: the brief's own list, narrowed to
+	// that category, which is a request for it rather than more of a window
+	// already fetched. Offered only at the "all" scope — inside one category the
+	// list already is the destination.
+	const showAllSection = useMemo(
+		() =>
+			requestCategory === "all" && !underQuery
+				? (sectionId: string) => {
+						if (isBriefCategory(sectionId)) selectChipCategory(sectionId);
+					}
+				: undefined,
+		[requestCategory, underQuery, selectChipCategory],
+	);
+
 	const clearChips = useCallback(() => {
 		setSelectedCategory("all");
 		setSelectedAccountId("all");
@@ -479,17 +549,6 @@ export function DailyBrief({
 		if (searching) onSearchChange(clearBriefFiltersInQuery(searchInput));
 	}, [searching, searchInput, onSearchChange, clearFilters]);
 
-	// --- Unified threads query ---
-	const {
-		data: threadsData,
-		isLoading,
-		isError,
-		refetch,
-	} = useQuery({
-		...unifiedThreadOperationsListAllThreadsOptions(),
-		staleTime: 60_000,
-	});
-
 	// --- Per-account mailbox list for unread counts and error detection ---
 	const mailboxQueries = useQueries({
 		queries: nonMuted.map((account) => ({
@@ -534,77 +593,160 @@ export function DailyBrief({
 		});
 	}, [nonMuted, mailboxQueries]);
 
-	const { freeText: sq, tokens: queryTokens } = parseSearchTokens(
-		searchQuery.trim().toLowerCase(),
-		tokenContext,
+	// --- The brief's rows ---
+	// The chips and the tokens as request parameters. The category is not among
+	// them: each section is its own category-scoped request, and the category
+	// chip decides which sections are on screen rather than narrowing a shared
+	// one.
+	const { criteria: chipCriteria, residual: residualTokens } = useMemo(
+		() => briefCriteria(requestCategory, requestFilters, queryTokens),
+		[requestCategory, requestFilters, queryTokens],
 	);
-
-	// --- Unscoped search query ---
-	// The brief's list is the unified INBOX, so filtering it client-side can only
-	// ever find inbox mail. The same endpoint in search mode (`query`) widens to
-	// every non-muted folder of every account — Archive, Sent, Spam, custom
-	// folders — and matches subject/From in the query. Its rows are merged with
-	// the client-side pass below, which still contributes snippet matches the
-	// server does not index.
-	const { data: searchData, isFetching: searchFetching } = useQuery({
-		...unifiedThreadOperationsListAllThreadsOptions({
-			query: { query: sq, limit: UNSCOPED_SEARCH_PAGE_SIZE },
+	const shownCategories = useMemo<RemitImapMessageCategory[]>(
+		() =>
+			requestCategory === "all" ? [...BRIEF_CATEGORIES] : [requestCategory],
+		[requestCategory],
+	);
+	// Under a query the category is a parameter again rather than a section
+	// scope: there is one request, and the chip narrows it.
+	const searchCriteria = useMemo(
+		() => ({
+			...chipCriteria,
+			query: sq,
+			...(requestCategory === "all" ? {} : { category: [requestCategory] }),
 		}),
-		enabled: sq.length > 0,
-		staleTime: 30_000,
+		[chipCriteria, sq, requestCategory],
+	);
+	// The account pills and the tokens no parameter carries narrow the rows after
+	// they arrive, so while either is active the count is of a wider set than the
+	// list and the sections show no number at all.
+	const counted = briefCountsMatchRows({
+		residual: residualTokens,
+		attributes: requestFilters,
+		accountScoped: selectedAccountId !== "all",
 	});
 
-	// Convert API rows to ThreadRowData, narrowing only by the selected account
-	// and the free-text search plus any filter tokens (`from:`, `has:attachment`,
-	// `is:unread`, `before:`/`after:`, `in:`, `account:`) parsed out of the
-	// query. The category axis is applied further down, on the grouped sections,
-	// so the list body can flatten them when narrowed to one category.
-	const filteredRows = useMemo<ThreadRowData[]>(() => {
-		const briefRows = excludeMutedSenders(threadsData?.items ?? []).map(
-			toThreadRowData,
-		);
-		// No free text: the brief list as it comes, order untouched.
-		const rows = sq
-			? mergeSearchRows(
-					briefRows.filter((t) => matchesBriefSearch(t, sq)),
-					excludeMutedSenders(searchData?.items ?? []).map(toThreadRowData),
-				)
-			: briefRows;
-		return rows.filter(
-			(t) =>
-				(selectedAccountId === "all" || t.accountId === selectedAccountId) &&
-				matchesSearchTokens(t, queryTokens),
-		);
-	}, [threadsData, searchData, selectedAccountId, sq, queryTokens]);
-
-	// The unscoped search reaches every folder, Spam included (see `filteredRows`
-	// above), and the brief is the one global-scope view whose own rows now stand
-	// in for the read-only results panel once the query commits. The panel held
-	// Spam out and offered a way to it instead (`MailListHeader`'s `spamOffer`);
-	// the brief's own body has to do the same, or a committed search surfaces
-	// junk mail inline and drops the way back to it. A bare token query (e.g.
-	// `is:unread`) never reaches the widened endpoint, so there is nothing to
-	// hold out.
-	const { bodyRows, briefSpamOffer } = useMemo(() => {
-		if (!sq) return { bodyRows: filteredRows, briefSpamOffer: undefined };
+	const {
+		sections: sectionRows,
+		isLoading: sectionsLoading,
+		isError: sectionsError,
+		refetch: refetchSections,
+	} = useBriefSections({
+		categories: underQuery ? NO_CATEGORIES : shownCategories,
+		criteria: chipCriteria,
+		limit: requestCategory === "all" ? SECTION_ROW_CAP : CATEGORY_PAGE_SIZE,
+		counted,
+	});
+
+	// A search is answered by one request and rendered as one list. Splitting the
+	// matches into category sections orders them by category first and recency
+	// second, which puts a newsletter from last spring above a mail that arrived
+	// this morning — the reading the search is asked to give (#312).
+	const {
+		rows: searchRows,
+		isLoading: searchLoading,
+		isError: searchError,
+		refetch: refetchSearch,
+	} = useBriefSearchRows(searchCriteria, SEARCH_PAGE_SIZE, underQuery);
+
+	const isLoading = underQuery ? searchLoading : sectionsLoading;
+	const isError = underQuery ? searchError : sectionsError;
+	const refetch = useCallback(() => {
+		if (underQuery) {
+			refetchSearch();
+			return;
+		}
+		refetchSections();
+	}, [underQuery, refetchSearch, refetchSections]);
+
+	// What the request could not carry: muted senders, the account pill, and the
+	// residual tokens (`from:`, `subject:`, `before:`, `after:`, `in:`,
+	// `account:`) that `listAllThreads` has no parameter for. Everything else was
+	// answered over the whole scope by the request itself, and the order the rows
+	// arrived in is kept — narrowing never re-sorts.
+	const narrowRows = useCallback(
+		(rows: RemitImapThreadMessageResponse[]): ThreadRowData[] =>
+			// One row per conversation, because that is what the server counted:
+			// `count` is thread-distinct, and a list keying on messageId puts twelve
+			// rows under a header reading one. Collapsed before anything reads a
+			// length, so the rows and the number are the same unit.
+			dedupeByThread(excludeMutedSenders(rows))
+				.map(toThreadRowData)
+				.filter(
+					(t) =>
+						(selectedAccountId === "all" ||
+							t.accountId === selectedAccountId) &&
+						matchesSearchTokens(t, residualTokens),
+				),
+		[selectedAccountId, residualTokens],
+	);
+
+	const briefRows = useMemo<BriefCategoryResult[]>(
+		() =>
+			sectionRows.map((section) => ({
+				category: section.category,
+				total: briefSectionTotal(section.total, section.rows),
+				atCap: section.atCap,
+				loading: section.loading,
+				failed: section.failed,
+				rows: narrowRows(section.rows),
+			})),
+		[sectionRows, narrowRows],
+	);
+
+	const matchRows = useMemo<ThreadRowData[]>(
+		() => narrowRows(searchRows),
+		[searchRows, narrowRows],
+	);
+
+	// Each section answers for itself, so a retry is that section's own request.
+	const retrySection = useCallback(
+		(sectionId: string) => {
+			sectionRows.find((section) => section.category === sectionId)?.retry();
+		},
+		[sectionRows],
+	);
+
+	const filteredRows = useMemo<ThreadRowData[]>(
+		() =>
+			underQuery ? matchRows : briefRows.flatMap((section) => section.rows),
+		[underQuery, matchRows, briefRows],
+	);
+
+	// A search reaches every folder, Spam included, and the brief is the one
+	// global-scope view whose own rows stand in for the read-only results panel
+	// once the query commits. The panel held Spam out and offered a way to it
+	// instead (`MailListHeader`'s `spamOffer`); the brief's own body has to do the
+	// same, or a committed search surfaces junk mail inline and drops the way back
+	// to it. A bare token query (e.g. `is:unread`) never reaches search mode, so
+	// there is nothing to hold out.
+	const { spamIds, briefSpamOffer } = useMemo(() => {
+		const none = { spamIds: undefined, briefSpamOffer: undefined };
+		if (!sq) return none;
 		const asResults = filteredRows.map((row) =>
 			rowToSearchResult(row, resultFolderIndex),
 		);
 		const { spam } = partitionSpamResults(asResults);
-		if (spam.length === 0) {
-			return { bodyRows: filteredRows, briefSpamOffer: undefined };
-		}
-		const spamIds = new Set(spam.map((result) => result.id));
+		if (spam.length === 0) return none;
 		return {
-			bodyRows: filteredRows.filter((row) => !spamIds.has(row.id)),
+			spamIds: new Set(spam.map((result) => result.id)),
 			briefSpamOffer: spamOfferForResults(asResults),
 		};
 	}, [filteredRows, sq, resultFolderIndex]);
 
-	const sections = useMemo<ThreadSection[]>(
-		() => groupBriefSections(bodyRows),
-		[bodyRows],
-	);
+	const sections = useMemo<ThreadSection[]>(() => {
+		const keep = (rows: ThreadRowData[]): ThreadRowData[] =>
+			spamIds === undefined ? rows : rows.filter((row) => !spamIds.has(row.id));
+		// One unlabelled section under a query: the body renders it flat, so the
+		// matches stay in the single order the server put them in.
+		if (underQuery) return [{ id: "matches", threads: keep(matchRows) }];
+		return briefSections(
+			briefRows.map((section) => ({
+				...section,
+				rows: keep(section.rows),
+			})),
+		);
+	}, [underQuery, matchRows, briefRows, spamIds]);
 
 	// A committed query puts rows the widened cross-folder search found into the
 	// body, and those messages are in folders the brief itself never loads. They
@@ -704,10 +846,9 @@ export function DailyBrief({
 	// its thread via the raw threads.
 	const { hits: semanticHits, isLoading: relatedLoading } = useSemanticSearch();
 	const relatedResults = useMemo<SearchResult[]>(() => {
-		const threadByMessageId = new Map<string, string>();
-		for (const thread of threadsData?.items ?? []) {
-			threadByMessageId.set(thread.messageId, thread.threadId);
-		}
+		const threadByMessageId = new Map<string, string | undefined>(
+			filteredRows.map((row) => [row.id, row.threadId]),
+		);
 		const literalThreadIds = searchResults
 			.map((result) => threadByMessageId.get(result.id))
 			.filter((id): id is string => id != null);
@@ -716,7 +857,7 @@ export function DailyBrief({
 			literalThreadIds,
 			resultFolderIndex,
 		);
-	}, [semanticHits, searchResults, threadsData, resultFolderIndex]);
+	}, [semanticHits, searchResults, filteredRows, resultFolderIndex]);
 
 	const filterConfig = useMemo<Omit<FilterSheetProps, "children">>(() => {
 		const preset = briefFilterConfig(
@@ -823,6 +964,9 @@ export function DailyBrief({
 					Row={MessageRow}
 					selectedThreadId={selectedMessageId}
 					onSelectThread={openRow}
+					onShowAllSection={showAllSection}
+					onRetrySection={retrySection}
+					flat={underQuery}
 					onSelectBriefCategory={selectChipCategory}
 					sources={accountSources}
 					sourcesNote={mutedCount > 0 ? `+${mutedCount} muted` : undefined}
@@ -884,15 +1028,15 @@ export function DailyBrief({
 						footer: isDesktop ? <KeyboardHintBar /> : undefined,
 						searchFilter: filterConfig,
 						searchResults,
-						searchLoading: isLoading || searchFetching,
+						searchLoading: isLoading,
 						relatedResults,
 						relatedLoading,
 						onSelectSearchResult: openResult,
-						// The body already narrows to the committed query
-						// (`matchesBriefSearch` + `matchesSearchTokens` + the server `query`,
-						// above), so a committed search is a selectable list here exactly as
-						// it is on the mailbox route (#212) — the two-engine panel stays for
-						// the typing/uncommitted state only.
+						// The body already narrows to the committed query (the server
+						// `query` on every section request, plus `matchesSearchTokens` for
+						// the residue), so a committed search is a selectable list here
+						// exactly as it is on the mailbox route (#212) — the two-engine
+						// panel stays for the typing/uncommitted state only.
 						searchResultsInBody: true,
 						refreshControl,
 					}}

package/src/components/mail/MailboxPane.tsx

@@ -30,6 +30,7 @@ import {
 	ReadingPaneEmpty,
 	RefreshButton,
 	type RescueCandidate,
+	type ResultCount,
 	type SearchResult,
 } from "@remit/ui";
 import { useInfiniteQuery } from "@tanstack/react-query";
@@ -87,6 +88,7 @@ import { useToggleReadFor } from "@/hooks/useMarkAsRead";
 import { useMoveMessages } from "@/hooks/useMoveMessages";
 import { useRefreshControl } from "@/hooks/useRefreshControl";
 import { useRescueCandidates } from "@/hooks/useRescueCandidates";
+import { useResultCount } from "@/hooks/useResultCount";
 import { useSearchTokenContext } from "@/hooks/useSearchTokenContext";
 import { useSemanticSearch } from "@/hooks/useSemanticSearch";
 import { useThreadActions } from "@/hooks/useThreadActions";
@@ -111,6 +113,7 @@ 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 { shouldRequestResultCount } from "@/lib/result-count";
 import { normalizeSearchQuery } from "@/lib/search-query";
 import {
 	relatedSearchResults,
@@ -204,6 +207,8 @@ interface MailboxPaneContextValue {
 	 * header, not enough to reproduce the query server-side.
 	 */
 	searchPredicate: EscalationSearchQuery | undefined;
+	/** The server's count of the whole match set, for the result header. */
+	resultCount: ResultCount;
 	// List actions
 	onDeleteMessages: (ids: string[]) => void;
 	onMoveMessages: (ids: string[], dest: string) => void;
@@ -316,15 +321,21 @@ function MailboxPaneProvider({
 		searchTokens,
 		filterParams,
 	);
-	const searchThreadsQuery = {
+	// What the list is asking about, with nothing about paging in it. The count
+	// is a property of the criteria alone, so it keys on this and a page fetch
+	// can never trigger one.
+	const searchCriteria = {
 		order: "desc" as const,
-		// Explicit: an unspecified limit clamps to THREAD_SEARCH_MAX_LIMIT (500),
-		// so switching paths without it multiplies the page size by ten.
-		limit: THREADS_PAGE_SIZE,
 		...(freeText ? { query: freeText } : {}),
 		...tokenParams,
 		...filterParams,
 	};
+	const searchThreadsQuery = {
+		...searchCriteria,
+		// Explicit: an unspecified limit clamps to THREAD_SEARCH_MAX_LIMIT (500),
+		// so switching paths without it multiplies the page size by ten.
+		limit: THREADS_PAGE_SIZE,
+	};
 	// What the request actually narrows by, whoever set it. `placeholderData`
 	// keeps the previous rows only under the same predicate, and a token
 	// narrowing the list is as much that predicate as a chip is.
@@ -387,6 +398,16 @@ function MailboxPaneProvider({
 				: undefined,
 	});
 
+	const resultCount = useResultCount({
+		mailboxId,
+		criteria: searchCriteria,
+		enabled: shouldRequestResultCount({
+			hasSearchQuery,
+			freeText,
+			residualTokenCount: residualTokens.length,
+		}),
+	});
+
 	const { accountId: mailboxAccountId, isLoading: mailboxAccountLoading } =
 		useMailboxAccount(mailboxId);
 	const mailboxName = useCurrentMailboxName({ accounts });
@@ -790,6 +811,7 @@ function MailboxPaneProvider({
 			hasSearchQuery && residualTokens.length === 0
 				? searchThreadsQuery
 				: undefined,
+		resultCount,
 		onDeleteMessages: handleDeleteMessages,
 		onMoveMessages: handleMoveMessages,
 		isDeleting,
@@ -854,6 +876,7 @@ function MailboxList() {
 		onClearFilters,
 		listFilter,
 		searchPredicate,
+		resultCount,
 	} = useMailboxPane();
 	const { searchQuery, searchInput, accounts, resultFolderIndex } =
 		useMailContext();
@@ -978,6 +1001,7 @@ function MailboxList() {
 			onRetry={onRetry}
 			searchQuery={searchQuery}
 			searchPredicate={searchPredicate}
+			resultCount={resultCount}
 			onDeleteMessages={onDeleteMessages}
 			isDeleting={isDeleting}
 			isMoving={isMoving}

package/src/components/mail/MessageList.tsx

@@ -4,10 +4,12 @@ import {
 	cn,
 	type Density,
 	deriveIsMultiSelectMode,
+	ListResultHeader,
 	type MessageListFilter,
 	MessageListLoadingMore,
 	MessageListPane,
 	nextFocusId,
+	type ResultCount,
 	type SelectionModifiers,
 	SelectionTopBar,
 	useSelection,
@@ -15,7 +17,6 @@ import {
 } from "@remit/ui";
 import { useBlocker } from "@tanstack/react-router";
 import { useVirtualizer } from "@tanstack/react-virtual";
-import { Search } from "lucide-react";
 import type { RefObject } from "react";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { useErrorBanners } from "@/components/ui/ErrorBannerProvider";
@@ -113,6 +114,12 @@ interface MessageListProps {
 	 * only the display string.
 	 */
 	searchPredicate?: EscalationSearchQuery;
+	/**
+	 * How many messages the search matches, as the server counted them — the
+	 * whole match set, not the pages loaded. Omitted where the count was never
+	 * asked for, which renders the header without a number.
+	 */
+	resultCount?: ResultCount;
 	onDeleteMessages?: (messageIds: string[]) => void;
 	isDeleting?: boolean;
 	isMoving?: boolean;
@@ -188,21 +195,6 @@ const readStoredDensity = (): Density => {
 	return "comfortable";
 };
 
-/**
- * Names what the list is showing. No number: the only figure available here is
- * the length of the loaded pages, and a page length presented as a result total
- * contradicts the completeness the filtered empty state states in the same view
- * (#306). The exact count is #307's.
- */
-const SearchResultsHeader = ({ query }: { query: string }) => (
-	<div className="flex items-center gap-2 px-3 py-2 border-b border-line bg-surface-sunken/30">
-		<Search className="size-4 text-fg-muted" />
-		<span className="text-sm text-fg-muted">
-			Results for &ldquo;{query}&rdquo;
-		</span>
-	</div>
-);
-
 /**
  * Why Move is withheld from a selection, in the toolbar's own words. Rows from
  * a per-mailbox endpoint carry no account of their own, so the list's own
@@ -230,6 +222,7 @@ export const MessageList = ({
 	onRetry,
 	searchQuery,
 	searchPredicate,
+	resultCount = { kind: "unknown" },
 	onDeleteMessages,
 	isDeleting = false,
 	isMoving = false,
@@ -1227,7 +1220,7 @@ export const MessageList = ({
 	const virtualBody = (
 		<>
 			{isSearching && searchQuery && (
-				<SearchResultsHeader query={searchQuery} />
+				<ListResultHeader query={searchQuery} count={resultCount} />
 			)}
 			<div
 				ref={parentRef}