@remit/web-client 0.0.30 → 0.0.32

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/web-client",
-  "version": "0.0.30",
+  "version": "0.0.32",
   "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

@@ -174,7 +174,7 @@ export function DailyBrief({
 	onSelectMessage,
 	onSelectSearchResult,
 }: DailyBriefProps) {
-	const { searchQuery } = useMailContext();
+	const { searchQuery, resultFolderIndex } = useMailContext();
 	const tokenContext = useSearchTokenContext();
 	const isDesktop = useIsDesktop();
 
@@ -346,8 +346,8 @@ export function DailyBrief({
 					(selectedCategory === "all" || t.category === selectedCategory) &&
 					predicates.every((p) => p(t)),
 			)
-			.map(rowToSearchResult);
-	}, [filteredRows, selectedCategory, searchAttributes]);
+			.map((row) => rowToSearchResult(row, resultFolderIndex));
+	}, [filteredRows, selectedCategory, searchAttributes, resultFolderIndex]);
 
 	// "Related" (semantic) spans every account here — the brief is the
 	// cross-account view, so no mailbox scope. Dedupe against the literal "Top
@@ -362,8 +362,12 @@ export function DailyBrief({
 		const literalThreadIds = searchResults
 			.map((result) => threadByMessageId.get(result.id))
 			.filter((id): id is string => id != null);
-		return relatedSearchResults(semanticHits, literalThreadIds);
-	}, [semanticHits, searchResults, threadsData]);
+		return relatedSearchResults(
+			semanticHits,
+			literalThreadIds,
+			resultFolderIndex,
+		);
+	}, [semanticHits, searchResults, threadsData, resultFolderIndex]);
 
 	const searchFilterConfig = useMemo<Omit<FilterSheetProps, "children">>(() => {
 		const preset = briefFilterConfig(

package/src/components/mail/FlaggedList.tsx

@@ -50,7 +50,7 @@ export function FlaggedList({
 	selectedMessageId,
 	onSelectMessage,
 }: FlaggedListProps) {
-	const { searchQuery } = useMailContext();
+	const { searchQuery, resultFolderIndex } = useMailContext();
 	const tokenContext = useSearchTokenContext();
 	const isDesktop = useIsDesktop();
 
@@ -106,7 +106,10 @@ export function FlaggedList({
 
 	const preset = useMemo(() => flaggedFilterConfig(), []);
 
-	const searchResults = useMemo(() => rows.map(rowToSearchResult), [rows]);
+	const searchResults = useMemo(
+		() => rows.map((row) => rowToSearchResult(row, resultFolderIndex)),
+		[rows, resultFolderIndex],
+	);
 
 	const unreadCount = useMemo(
 		() => rows.filter((t) => !t.isRead).length,

package/src/components/mail/MailListHeader.tsx

@@ -21,6 +21,11 @@
  * drops out kit-side, so a semantic-only result still shows when the literal
  * search finds nothing. The hamburger opens the nav drawer via the enclosing
  * `AppShellSlotted`.
+ *
+ * This is also the one place the route's scope reaches the results list, so both
+ * tiers agree on it: a global search labels every row with the folder it came
+ * from and offers the spam it held out, and a scoped search does neither. See
+ * `resultsScopeForRoute` and `lib/spam-offer.ts`.
  */
 import {
 	FilterSheet,
@@ -30,18 +35,23 @@ import {
 	type SearchResult,
 	type SearchResultSection,
 	SearchResults,
+	type SearchScope,
 	useAppShellLayout,
 } from "@remit/ui";
+import { useNavigate, useRouterState } from "@tanstack/react-router";
 import { type ReactNode, useEffect, useRef, useState } from "react";
 import { isSinglePaneTier, useLayoutTier } from "@/hooks/useLayoutTier";
+import { useSearchScope } from "@/hooks/useSearchScope";
 import { useSearchTokenContext } from "@/hooks/useSearchTokenContext";
 import { useMailContext } from "@/lib/mail-context";
 import { loadRecentSearches, saveRecentSearch } from "@/lib/recent-searches";
+import { resultsScopeForRoute, routeMailboxId } from "@/lib/search-scope";
 import {
 	parseSearchTokens,
 	removeSearchToken,
 	searchTokenLabel,
 } from "@/lib/search-tokens";
+import { spamOfferForResults } from "@/lib/spam-offer";
 
 interface MailListHeaderProps {
 	title: string;
@@ -82,9 +92,17 @@ export function MailListHeader({
 	searchResultsLabel = "Top matches",
 	relatedResultsLabel = "Related",
 }: MailListHeaderProps) {
-	const { searchInput, onSearchChange, onSearchClear, searchViewKey } =
-		useMailContext();
+	const {
+		accounts,
+		resultFolderIndex,
+		searchQuery,
+		searchInput,
+		onSearchChange,
+		onSearchClear,
+		searchViewKey,
+	} = useMailContext();
 	const tokenContext = useSearchTokenContext();
+	const navigate = useNavigate();
 	const layout = useAppShellLayout();
 	const tier = useLayoutTier();
 	const [searchOpen, setSearchOpen] = useState(false);
@@ -130,6 +148,40 @@ export function MailListHeader({
 	const resultsLoading =
 		!hasAnyResult && (searchLoading === true || relatedLoading === true);
 
+	// The mailbox's appointed role is what lets a search scoped to Spam show its
+	// rows rather than drop them.
+	const { scope } = useSearchScope(accounts);
+	const matches = useRouterState({ select: (s) => s.matches });
+	const scopedMailboxId = routeMailboxId(matches);
+	const routeScope = resultsScopeForRoute(
+		matches,
+		scope,
+		scopedMailboxId ? resultFolderIndex.get(scopedMailboxId)?.role : undefined,
+	);
+
+	// The offer counts results for the *committed* query, so that is the query it
+	// carries into Spam. The count the banner states is the results list's own,
+	// over every row it held out; the app supplies only where "Go to Spam" goes.
+	const spamOffer =
+		routeScope.kind === "global"
+			? spamOfferForResults([...topMatches, ...related])
+			: undefined;
+	const resultsScope: SearchScope = spamOffer
+		? {
+				kind: "global",
+				onScopeToSpam: () =>
+					navigate({
+						to: "/mail/$mailboxId",
+						params: { mailboxId: spamOffer.mailboxId },
+						search: {
+							q: searchQuery || undefined,
+							selectedMessageId: undefined,
+							selectedThreadId: undefined,
+						},
+					}),
+			}
+		: routeScope;
+
 	if (tier === "phone" && searchOpen) {
 		const handleSelectResult = (result: SearchResult) => {
 			setRecentSearches(saveRecentSearch(searchInput));
@@ -152,6 +204,7 @@ export function MailListHeader({
 				loading={resultsLoading}
 				onSelectResult={handleSelectResult}
 				tokens={tokenChips}
+				scope={resultsScope}
 			/>
 		);
 	}
@@ -171,6 +224,7 @@ export function MailListHeader({
 			loading={resultsLoading}
 			onSelectResult={handleSelectInlineResult}
 			tokens={tokenChips}
+			scope={resultsScope}
 		/>
 	);
 	const body = !showInlineResults ? (

package/src/components/mail/MailboxPane.tsx

@@ -947,7 +947,8 @@ function MailboxList() {
 		onClearFilters,
 		searchPredicate,
 	} = useMailboxPane();
-	const { searchQuery, searchInput, accounts } = useMailContext();
+	const { searchQuery, searchInput, accounts, resultFolderIndex } =
+		useMailContext();
 	const tier = useLayoutTier();
 	const navigate = useNavigate();
 
@@ -955,8 +956,9 @@ function MailboxList() {
 	const preset = useMemo(() => inboxFilterConfig(), []);
 
 	const searchResults = useMemo(
-		() => threads.map(threadToSearchResult),
-		[threads],
+		() =>
+			threads.map((thread) => threadToSearchResult(thread, resultFolderIndex)),
+		[threads, resultFolderIndex],
 	);
 	// The route scopes this view and the top bar's chip says so, so every engine
 	// here respects it: the literal engine searches this mailbox, and the
@@ -972,8 +974,9 @@ function MailboxList() {
 			relatedSearchResults(
 				semanticHits,
 				threads.map((t) => t.threadId),
+				resultFolderIndex,
 			),
-		[semanticHits, threads],
+		[semanticHits, threads, resultFolderIndex],
 	);
 	const handleSelectSearchResult = useCallback(
 		(result: SearchResult) =>

package/src/components/mail/MessageList.tsx

@@ -244,6 +244,7 @@ export const MessageList = ({
 		setAnchor,
 		selectAll,
 		toggleAll,
+		intersectWith,
 	} = useSelection();
 
 	// Pending delete, awaiting confirmation. `null` means the dialog is closed.
@@ -829,28 +830,26 @@ export const MessageList = ({
 		[],
 	);
 
-	// Clear selection when threads change (e.g., after delete). Skipped while
-	// an escalated run is active: `selectedIds` there is a stale loaded-rows
-	// snapshot from the moment escalation started (the real selection is the
-	// predicate, D2), not something a background refetch reshuffling `threads`
-	// should be allowed to blow away out from under a count or a delete in
-	// progress — that would silently exit selection mode mid-run.
+	// Narrow the selection when threads change (e.g., after delete), dropping
+	// only the ids that left and keeping every survivor — K-9's
+	// `selected.intersect(uniqueIds)`, the reference behavior #92's D2 cites.
+	// Wiping the whole selection because one id left (#111) cost the other 49
+	// rows on an ordinary refresh, and could take the post-delete Retry
+	// selection with it: `processDeleteOutcome` materializes the failed ids as
+	// the new selection and resets this effect to live by returning escalation
+	// to idle, so the cache invalidation's refetch ran this same effect against
+	// the retry set — a clear here would have dropped the Retry notice
+	// (gated on `selectedCount > 0`) along with it.
+	// Skipped while an escalated run is active: `selectedIds` there is a stale
+	// loaded-rows snapshot from the moment escalation started (the real
+	// selection is the predicate, D2), not something a background refetch
+	// reshuffling `threads` should be allowed to narrow out from under a count
+	// or a delete in progress — that would silently exit selection mode
+	// mid-run.
 	useEffect(() => {
 		if (escalation.phase.kind !== "idle" || escalation.isDeleting) return;
-		const threadIds = new Set(threads.map((t) => t.messageId));
-		const hasOrphanedSelection = Array.from(selectedIds).some(
-			(id) => !threadIds.has(id),
-		);
-		if (hasOrphanedSelection) {
-			clearSelection();
-		}
-	}, [
-		threads,
-		selectedIds,
-		clearSelection,
-		escalation.phase,
-		escalation.isDeleting,
-	]);
+		intersectWith(threads.map((t) => t.messageId));
+	}, [threads, intersectWith, escalation.phase, escalation.isDeleting]);
 
 	// Load more when scrolling near the bottom
 	useEffect(() => {
@@ -1210,6 +1209,14 @@ export const MessageList = ({
 			: pendingDelete.total
 		: 0;
 
+	// The predicate case (#109): `pendingDelete.total` is `countMatches`'s
+	// frozen page-through, and the delete itself re-pages the same predicate a
+	// second, independent time. Mail arriving or leaving between the two can
+	// make them differ, so the dialog says "about" instead of promising an
+	// exact number it may not honour. A materialized (bounded) selection's
+	// count is exact — it's the delete's own input, not an estimate of it.
+	const pendingDeleteIsEstimate = pendingDelete?.source === "predicate";
+
 	return (
 		<>
 			{completionBanner && !isDesktop && (
@@ -1249,8 +1256,15 @@ export const MessageList = ({
 			/>
 			<ConfirmDialog
 				isOpen={pendingDelete !== null}
-				title={formatDeleteToTrashTitle(pendingDeleteCount)}
-				description="You can restore them from Trash later."
+				title={formatDeleteToTrashTitle(
+					pendingDeleteCount,
+					pendingDeleteIsEstimate,
+				)}
+				description={
+					pendingDeleteIsEstimate
+						? "This count is a snapshot — new mail arriving during the delete won't be included. You can restore what's deleted from Trash later."
+						: "You can restore them from Trash later."
+				}
 				confirmLabel="Move to Trash"
 				destructive
 				isBusy={isDeleting}

package/src/components/ui/ConfirmDialog.stories.tsx

@@ -34,6 +34,21 @@ export const OneMessage: Story = {
 	},
 };
 
+/**
+ * An escalated (search-predicate) delete: the count was paged once by
+ * `countMatches` and the delete re-pages the same predicate independently, so
+ * it is not provably the number that gets deleted (#109). "about" and the
+ * description say so up front rather than stating an exact number the run may
+ * not honour.
+ */
+export const EscalatedEstimate: Story = {
+	args: {
+		title: "Move about 3,412 messages to Trash?",
+		description:
+			"This count is a snapshot — new mail arriving during the delete won't be included. You can restore what's deleted from Trash later.",
+	},
+};
+
 /** The mutation is in flight: the confirm button disables rather than
  *  allowing a second concurrent delete request. */
 export const Busy: Story = {

package/src/hooks/useEscalatedDelete.ts

@@ -17,6 +17,7 @@ import {
 	countMatches,
 	type DeleteRunOutcome,
 	type FetchIdsPage,
+	honestProgress,
 	runChunkedDelete,
 	runPredicateDelete,
 } from "@/lib/bulk-delete";
@@ -190,8 +191,11 @@ export const useEscalatedDelete = ({
 		async (ids?: string[]): Promise<DeleteRunOutcome> => {
 			cancelRef.current = false;
 			setIsDeleting(true);
+			// `honestProgress` widens `total` if `done` overtakes it (#109) — the
+			// predicate can match more by the time the delete re-pages it than
+			// `countMatches` saw, and the bar must never show more done than out of.
 			const onProgress = (progress: BulkDeleteProgress) =>
-				setDeleteProgress(progress);
+				setDeleteProgress(honestProgress(progress));
 
 			const outcome =
 				ids !== undefined

package/src/hooks/useResultFolderIndex.ts

@@ -0,0 +1,54 @@
+/**
+ * Fans out the per-account mailbox-list query (the same one `MailSidebarAdapter`
+ * and `useMailboxNameIndex` run — cached forever, react-query dedupes the
+ * identical key across call sites) and reduces it to the mailboxId → folder map
+ * search results resolve their provenance against. See `lib/result-folder.ts`.
+ */
+import { mailboxOperationsListMailboxesOptions } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import type {
+	RemitImapAccountResponse,
+	RemitImapMailboxResponse,
+} from "@remit/api-http-client/types.gen.ts";
+import { useQueries } from "@tanstack/react-query";
+import { useMemo } from "react";
+import {
+	buildResultFolderIndex,
+	type ResultFolderIndex,
+} from "@/lib/result-folder";
+
+type MailboxItems = RemitImapMailboxResponse[];
+
+/**
+ * Hoisted, not inline: `useQueries` skips re-running `combine` when it is given
+ * the same function, so a stable reference is what makes this a memo rather than
+ * a per-render reduce. Without it the index — and every search-result memo keyed
+ * on it — rebuilds on every render.
+ */
+const combineMailboxItems = (
+	results: { data?: { items: MailboxItems } }[],
+): MailboxItems[] => results.map((result) => result.data?.items ?? []);
+
+export function useResultFolderIndex(
+	accounts: RemitImapAccountResponse[],
+): ResultFolderIndex {
+	const mailboxItems = useQueries({
+		queries: accounts.map((account) => ({
+			...mailboxOperationsListMailboxesOptions({
+				path: { accountId: account.accountId },
+			}),
+			staleTime: Infinity,
+		})),
+		combine: combineMailboxItems,
+	});
+
+	return useMemo(
+		() =>
+			buildResultFolderIndex(
+				accounts.map((account, i) => ({
+					folderAppointments: account.folderAppointments,
+					mailboxes: mailboxItems[i] ?? [],
+				})),
+			),
+		[accounts, mailboxItems],
+	);
+}

package/src/hooks/useSelection.test.ts

@@ -1,6 +1,10 @@
 import assert from "node:assert";
 import { describe, test } from "node:test";
-import { computeRange, nextFocusId } from "./useSelection.js";
+import {
+	computeRange,
+	intersectSelectedIds,
+	nextFocusId,
+} from "./useSelection.js";
 
 const ids = ["a", "b", "c", "d", "e"];
 
@@ -73,3 +77,60 @@ describe("nextFocusId", () => {
 		assert.strictEqual(nextFocusId([], "a", 1), undefined);
 	});
 });
+
+describe("intersectSelectedIds", () => {
+	test("a refresh that drops some selected ids and adds new rows keeps only the survivors (#111)", () => {
+		// Regression for #111: the effect used to clear the WHOLE selection the
+		// moment any single selected id left the list. Here "b" leaves (deleted
+		// elsewhere) while "f" arrives (new mail) — "a" and "c" must survive.
+		const selected = new Set(["a", "b", "c"]);
+		const refreshedThreadIds = ["a", "c", "d", "f"];
+		assert.deepStrictEqual(
+			intersectSelectedIds(selected, refreshedThreadIds),
+			new Set(["a", "c"]),
+		);
+	});
+
+	test("never adds an id that wasn't already selected", () => {
+		const selected = new Set(["a"]);
+		assert.deepStrictEqual(
+			intersectSelectedIds(selected, ["a", "b", "c"]),
+			new Set(["a"]),
+		);
+	});
+
+	test("every selected id surviving is a no-op (same members, not just same size)", () => {
+		const selected = new Set(["a", "b"]);
+		assert.deepStrictEqual(
+			intersectSelectedIds(selected, ["a", "b", "z"]),
+			new Set(["a", "b"]),
+		);
+	});
+
+	test("a post-delete retry selection survives a refetch that still contains it, minus what actually left", () => {
+		// Mirrors processDeleteOutcome materializing the failed ids as the new
+		// selection, then the cache-invalidation refetch running this same
+		// intersection against the freshly reloaded `threads`. One retry id
+		// ("fail-2") is momentarily missing from the refreshed page; the other
+		// two must stay selected so the Retry notice (gated on
+		// `selectedCount > 0`) doesn't disappear with it.
+		const retrySelection = new Set(["fail-1", "fail-2", "fail-3"]);
+		const refetchedThreadIds = ["fail-1", "fail-3", "unrelated-1"];
+		assert.deepStrictEqual(
+			intersectSelectedIds(retrySelection, refetchedThreadIds),
+			new Set(["fail-1", "fail-3"]),
+		);
+	});
+
+	test("everything in the selection leaving empties it, rather than leaving stale ids behind", () => {
+		const selected = new Set(["a", "b"]);
+		assert.deepStrictEqual(intersectSelectedIds(selected, ["z"]), new Set());
+	});
+
+	test("an empty selection stays empty", () => {
+		assert.deepStrictEqual(
+			intersectSelectedIds(new Set(), ["a", "b"]),
+			new Set(),
+		);
+	});
+});

package/src/hooks/useSelection.ts

@@ -52,6 +52,12 @@ interface UseSelectionReturn {
 	 * nothing has been selected yet.
 	 */
 	anchorId: string | undefined;
+	/**
+	 * Narrows the selection to whatever in it is still present in `currentIds`
+	 * — drops ids that left, keeps every survivor. Never adds anything, and
+	 * never clears the selection just because one id is gone (#111).
+	 */
+	intersectWith: (currentIds: readonly string[]) => void;
 }
 
 /**
@@ -79,6 +85,25 @@ export const computeRange = (
 	return orderedIds.slice(start, end + 1);
 };
 
+/**
+ * The ids from `selectedIds` that are still present in `currentIds` — the
+ * survivor set after a list refresh. Only ever narrows: an id absent from
+ * `selectedIds` is never added just because it's in `currentIds`. Pure so the
+ * "drop what left, keep the rest" behavior (K-9's `selected.intersect
+ * (uniqueIds)`, cited by #92 D2) can be unit-tested without a DOM.
+ */
+export const intersectSelectedIds = (
+	selectedIds: ReadonlySet<string>,
+	currentIds: readonly string[],
+): Set<string> => {
+	const present = new Set(currentIds);
+	const next = new Set<string>();
+	for (const id of selectedIds) {
+		if (present.has(id)) next.add(id);
+	}
+	return next;
+};
+
 /**
  * Compute the id one step from `focusId` in `orderedIds`, clamped at the ends.
  * Pure so the shift-arrow range-extend math can be unit-tested without a DOM.
@@ -174,6 +199,17 @@ export const useSelection = <T>(
 		setAnchorId(id);
 	}, []);
 
+	// Bails out to the same `prev` reference when nothing was dropped, so a
+	// caller can run this on every list refresh (e.g. an effect keyed on
+	// `threads`) without forcing a render each time.
+	const intersectWith = useCallback((currentIds: readonly string[]) => {
+		setSelectedIds((prev) => {
+			if (prev.size === 0) return prev;
+			const next = intersectSelectedIds(prev, currentIds);
+			return next.size === prev.size ? prev : next;
+		});
+	}, []);
+
 	const selectRange = useCallback(
 		(orderedIds: string[], targetId: string) => {
 			setSelectedIds((prev) => {
@@ -207,5 +243,6 @@ export const useSelection = <T>(
 		selectRange,
 		setAnchor,
 		anchorId,
+		intersectWith,
 	};
 };

package/src/lib/bulk-delete.test.ts

@@ -6,6 +6,7 @@ import {
 	countMatches,
 	type DeleteBatchResult,
 	type FetchIdsPageResult,
+	honestProgress,
 	resolveSelectionAfterDelete,
 	runChunkedDelete,
 	runPredicateDelete,
@@ -454,3 +455,36 @@ describe("resolveSelectionAfterDelete", () => {
 		);
 	});
 });
+
+describe("honestProgress", () => {
+	// Regression for #109: `countMatches` and `runPredicateDelete` page the
+	// same predicate independently, so the delete can outrun the frozen
+	// `total` it started with when the result set grows in between.
+	test("leaves an on-track progress reading untouched", () => {
+		assert.deepEqual(honestProgress({ done: 50, total: 100 }), {
+			done: 50,
+			total: 100,
+		});
+	});
+
+	test("widens total to match done once done overtakes it, instead of reading past 100%", () => {
+		assert.deepEqual(honestProgress({ done: 1340, total: 1284 }), {
+			done: 1340,
+			total: 1340,
+		});
+	});
+
+	test("done equal to total stays put", () => {
+		assert.deepEqual(honestProgress({ done: 100, total: 100 }), {
+			done: 100,
+			total: 100,
+		});
+	});
+
+	test("never reports a total below zero-progress done", () => {
+		assert.deepEqual(honestProgress({ done: 0, total: 0 }), {
+			done: 0,
+			total: 0,
+		});
+	});
+});

package/src/lib/bulk-delete.ts

@@ -177,6 +177,24 @@ export const runPredicateDelete = async (
 	return { done, failedIds, cancelled: false };
 };
 
+/**
+ * Corrects a progress reading so its `total` can never read as less than
+ * `done` (#109). `runPredicateDelete`'s `total` is `countMatches`'s frozen
+ * page-through, taken before the delete re-pages the same predicate a second,
+ * independent time; if more matches arrived in between, `done` can overtake
+ * it mid-run and a raw "Deleting 1,340 of 1,284" would follow. Widening the
+ * denominator to match keeps the bar's ratio sane (never past 100%) without
+ * claiming the original count was exact — the honest fix is admitting the
+ * estimate grew, not re-paging to reconcile it (the result set is live; a
+ * second count taken any later is no less stale than the first).
+ */
+export const honestProgress = (
+	progress: BulkDeleteProgress,
+): BulkDeleteProgress => ({
+	done: progress.done,
+	total: Math.max(progress.total, progress.done),
+});
+
 export interface CountMatchesResult {
 	total: number;
 	cancelled: boolean;

package/src/lib/format.test.ts

@@ -119,4 +119,31 @@ describe("formatDeleteToTrashTitle", () => {
 			"Move 3,412 messages to Trash?",
 		);
 	});
+
+	// #109: an escalated-predicate count is paged once by `countMatches` and
+	// re-paged independently by the delete itself — never provably the number
+	// that gets deleted. `isEstimate` says so instead of stating an exact
+	// number the run may not honour.
+	describe("isEstimate (#109 — an escalated-predicate count, not a materialized selection)", () => {
+		test("prefixes 'about' for a plural estimate", () => {
+			assert.strictEqual(
+				formatDeleteToTrashTitle(3412, true),
+				"Move about 3,412 messages to Trash?",
+			);
+		});
+
+		test("prefixes 'about' for a singular estimate", () => {
+			assert.strictEqual(
+				formatDeleteToTrashTitle(1, true),
+				"Move about 1 message to Trash?",
+			);
+		});
+
+		test("defaults to false — a bounded selection's count stays exact", () => {
+			assert.strictEqual(
+				formatDeleteToTrashTitle(3412),
+				formatDeleteToTrashTitle(3412, false),
+			);
+		});
+	});
 });

package/src/lib/format.ts

@@ -195,8 +195,19 @@ export const formatList = (
  * moves messages to Trash (not a permanent delete) and pluralizes on count.
  * Thousands-separated: at escalated-selection scale this is exactly the digit
  * count someone checks against what they meant to select.
+ *
+ * `isEstimate` marks an escalated-predicate count (#109): it was paged to a
+ * total once, and the delete itself re-pages the same predicate independently
+ * — mail arriving or leaving between the two can make them differ. "about"
+ * says so up front instead of stating a number the run may not honour; a
+ * materialized (bounded) selection's count is exact and never passes it.
  */
-export const formatDeleteToTrashTitle = (count: number): string =>
-	count === 1
-		? "Move 1 message to Trash?"
-		: `Move ${formatNumber(count)} messages to Trash?`;
+export const formatDeleteToTrashTitle = (
+	count: number,
+	isEstimate = false,
+): string => {
+	const quantity = count === 1 ? "1" : formatNumber(count);
+	const noun = count === 1 ? "message" : "messages";
+	const prefix = isEstimate ? "about " : "";
+	return `Move ${prefix}${quantity} ${noun} to Trash?`;
+};

package/src/lib/mail-context.ts

@@ -1,5 +1,9 @@
 import type { RemitImapAccountResponse } from "@remit/api-http-client/types.gen.ts";
 import { createContext, useContext } from "react";
+import {
+	EMPTY_RESULT_FOLDER_INDEX,
+	type ResultFolderIndex,
+} from "./result-folder.js";
 
 /**
  * Shared mail-layout context. Lives in `lib/` — NOT in `routes/mail.tsx` — on
@@ -22,6 +26,13 @@ export interface MailContextValue {
 	 */
 	mailboxNameIndex: ReadonlyMap<string, string>;
 	accountNameIndex: ReadonlyMap<string, string>;
+	/**
+	 * mailboxId → the folder a search result read from that mailbox came from.
+	 * Computed once here for the same reason as the name indexes: the row labels,
+	 * the spam hold-out and the scope chip must agree on which folder is which.
+	 * See `lib/result-folder.ts`.
+	 */
+	resultFolderIndex: ResultFolderIndex;
 	searchQuery: string;
 	/** Live (pre-debounce) search input — the search field binds this. */
 	searchInput: string;
@@ -57,6 +68,7 @@ export const useMailContext = (): MailContextValue => {
 			accounts: [],
 			mailboxNameIndex: new Map(),
 			accountNameIndex: new Map(),
+			resultFolderIndex: EMPTY_RESULT_FOLDER_INDEX,
 			searchQuery: "",
 			searchInput: "",
 			searchViewKey: "",

package/src/lib/result-folder.test.ts

@@ -0,0 +1,115 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import {
+	type AccountMailboxes,
+	buildResultFolderIndex,
+	resolveResultFolder,
+} from "./result-folder";
+
+const account = (
+	appointments: { role: string; mailboxId: string }[],
+	mailboxes: { mailboxId: string; fullPath: string }[],
+): AccountMailboxes =>
+	({
+		folderAppointments: appointments,
+		mailboxes,
+	}) as unknown as AccountMailboxes;
+
+describe("buildResultFolderIndex", () => {
+	it("maps a mailbox to its appointed role and provider path", () => {
+		const index = buildResultFolderIndex([
+			account(
+				[{ role: "Junk", mailboxId: "mb-junk" }],
+				[
+					{ mailboxId: "mb-junk", fullPath: "Bulk Mail" },
+					{ mailboxId: "mb-work", fullPath: "Projects/Bookkeeping" },
+				],
+			),
+		]);
+
+		assert.deepEqual(index.get("mb-junk"), {
+			role: "junk",
+			providerPath: "Bulk Mail",
+		});
+		assert.deepEqual(index.get("mb-work"), {
+			providerPath: "Projects/Bookkeeping",
+		});
+	});
+
+	it("keeps every account's mailboxes", () => {
+		const index = buildResultFolderIndex([
+			account(
+				[{ role: "Inbox", mailboxId: "a-inbox" }],
+				[{ mailboxId: "a-inbox", fullPath: "INBOX" }],
+			),
+			account(
+				[{ role: "Inbox", mailboxId: "b-inbox" }],
+				[{ mailboxId: "b-inbox", fullPath: "INBOX" }],
+			),
+		]);
+
+		assert.equal(index.get("a-inbox")?.role, "inbox");
+		assert.equal(index.get("b-inbox")?.role, "inbox");
+	});
+});
+
+describe("resolveResultFolder", () => {
+	const index = buildResultFolderIndex([
+		account(
+			[
+				{ role: "Inbox", mailboxId: "mb-inbox" },
+				{ role: "All", mailboxId: "mb-all" },
+				{ role: "Junk", mailboxId: "mb-junk" },
+			],
+			[
+				{ mailboxId: "mb-inbox", fullPath: "INBOX" },
+				{ mailboxId: "mb-all", fullPath: "[Gmail]/All Mail" },
+				{ mailboxId: "mb-junk", fullPath: "[Gmail]/Spam" },
+			],
+		),
+	]);
+
+	it("skips a virtual folder for one that names a real place", () => {
+		assert.deepEqual(resolveResultFolder(index, ["mb-all", "mb-inbox"]), {
+			mailboxId: "mb-inbox",
+			folder: { role: "inbox", providerPath: "INBOX" },
+		});
+	});
+
+	it("resolves Spam by its appointed role, not its path", () => {
+		assert.equal(resolveResultFolder(index, ["mb-junk"]).folder?.role, "junk");
+	});
+
+	it("falls back to the first id when none names a real place", () => {
+		assert.deepEqual(resolveResultFolder(index, ["mb-all"]), {
+			mailboxId: "mb-all",
+			folder: { role: "all", providerPath: "[Gmail]/All Mail" },
+		});
+	});
+
+	it("returns the id but no folder when the mailbox is unknown", () => {
+		assert.deepEqual(resolveResultFolder(index, ["mb-gone"]), {
+			mailboxId: "mb-gone",
+		});
+	});
+
+	it("returns nothing for a result with no mailboxes", () => {
+		assert.deepEqual(resolveResultFolder(index, []), {});
+	});
+
+	it("still names a mailbox before the index has loaded", () => {
+		assert.deepEqual(resolveResultFolder(undefined, ["mb-inbox"]), {
+			mailboxId: "mb-inbox",
+		});
+	});
+});
+
+describe("buildResultFolderIndex before the mailbox list arrives", () => {
+	it("still knows the appointed role, so spam is never let through", () => {
+		const index = buildResultFolderIndex([
+			account([{ role: "Junk", mailboxId: "mb-junk" }], []),
+		]);
+
+		assert.deepEqual(index.get("mb-junk"), { role: "junk" });
+	});
+});

package/src/lib/result-folder.ts

@@ -0,0 +1,90 @@
+/**
+ * Where a search result was read from.
+ *
+ * A global search returns rows from every folder of every account, so each row
+ * says where it came from and spam is held out of the list. Both questions are
+ * answered by joining the row's mailbox ids against the mailbox lists the
+ * sidebar already loads: the id → folder map here is the only thing either
+ * needs, so neither the search API nor the semantic index has to carry a folder.
+ *
+ * The role comes from the account's `folderAppointments` map (RFC 032), which
+ * the server resolves from the IMAP SPECIAL-USE attributes — so `junk` means the
+ * folder the account advertises as `\Junk`, whatever it is called. Names are
+ * never consulted.
+ */
+import type {
+	RemitImapFolderAppointment,
+	RemitImapMailboxResponse,
+} from "@remit/api-http-client/types.gen.ts";
+import { provenanceFolderLabel, type ResultFolder } from "@remit/ui";
+import { buildMailboxRoleMap } from "./folder-roles.js";
+
+export type ResultFolderIndex = ReadonlyMap<string, ResultFolder>;
+
+export const EMPTY_RESULT_FOLDER_INDEX: ResultFolderIndex = new Map();
+
+export interface AccountMailboxes {
+	folderAppointments: readonly RemitImapFolderAppointment[];
+	mailboxes: readonly Pick<
+		RemitImapMailboxResponse,
+		"mailboxId" | "fullPath"
+	>[];
+}
+
+/**
+ * The appointments and the mailbox list arrive from two different queries, so
+ * the roles are seeded first and the provider paths laid over them. A role on
+ * its own is enough to hold spam out of a global search, which means the list
+ * loading late cannot let a Spam row through into the results.
+ */
+export function buildResultFolderIndex(
+	accounts: readonly AccountMailboxes[],
+): ResultFolderIndex {
+	const index = new Map<string, ResultFolder>();
+	for (const account of accounts) {
+		const roles = buildMailboxRoleMap(account.folderAppointments);
+		for (const [mailboxId, role] of roles) index.set(mailboxId, { role });
+		for (const mailbox of account.mailboxes) {
+			const role = roles.get(mailbox.mailboxId);
+			index.set(mailbox.mailboxId, {
+				...(role ? { role } : {}),
+				providerPath: mailbox.fullPath,
+			});
+		}
+	}
+	return index;
+}
+
+export interface ResolvedResultFolder {
+	mailboxId?: string;
+	folder?: ResultFolder;
+}
+
+/**
+ * The mailbox a result should be attributed to, and its folder.
+ *
+ * A message can sit in several mailboxes at once — Gmail files a copy of most
+ * mail in All Mail — and the order the ids arrive in carries no meaning, so the
+ * first id that names a real place wins. `provenanceFolderLabel` is the test:
+ * it is undefined exactly for the folders that are views rather than places.
+ * With nothing resolvable the first id is still returned, because opening the
+ * result needs a mailbox even when labelling it does not.
+ */
+export function resolveResultFolder(
+	folders: ResultFolderIndex | undefined,
+	mailboxIds: readonly string[],
+): ResolvedResultFolder {
+	const first = mailboxIds[0];
+	if (!folders) return first ? { mailboxId: first } : {};
+
+	for (const mailboxId of mailboxIds) {
+		const folder = folders.get(mailboxId);
+		if (folder && provenanceFolderLabel(folder) !== undefined) {
+			return { mailboxId, folder };
+		}
+	}
+
+	if (!first) return {};
+	const folder = folders.get(first);
+	return { mailboxId: first, ...(folder ? { folder } : {}) };
+}

package/src/lib/search-result.ts

@@ -11,6 +11,10 @@ import type {
 } from "@remit/api-http-client/types.gen.ts";
 import type { SearchResult, ThreadRowData } from "@remit/ui";
 import { formatEmailDate } from "./format.js";
+import {
+	type ResultFolderIndex,
+	resolveResultFolder,
+} from "./result-folder.js";
 
 /**
  * Plain-language label for the `matched: …` chip, so the user understands why
@@ -34,7 +38,9 @@ export function matchedChunkLabel(
 
 export function threadToSearchResult(
 	thread: RemitImapThreadMessageResponse,
+	folders?: ResultFolderIndex,
 ): SearchResult {
+	const { folder } = resolveResultFolder(folders, [thread.mailboxId]);
 	return {
 		id: thread.messageId,
 		sender: thread.fromName ?? thread.fromEmail ?? "Unknown",
@@ -45,10 +51,18 @@ export function threadToSearchResult(
 		flagged: thread.hasStars === true,
 		threadId: thread.threadId,
 		mailboxId: thread.mailboxId,
+		...(folder ? { folder } : {}),
 	};
 }
 
-export function rowToSearchResult(row: ThreadRowData): SearchResult {
+export function rowToSearchResult(
+	row: ThreadRowData,
+	folders?: ResultFolderIndex,
+): SearchResult {
+	const { folder } = resolveResultFolder(
+		folders,
+		row.mailboxId ? [row.mailboxId] : [],
+	);
 	return {
 		id: row.id,
 		sender: row.fromName,
@@ -57,6 +71,8 @@ export function rowToSearchResult(row: ThreadRowData): SearchResult {
 		date: row.timeLabel,
 		unread: !row.isRead,
 		flagged: row.starred === true,
+		...(row.mailboxId ? { mailboxId: row.mailboxId } : {}),
+		...(folder ? { folder } : {}),
 	};
 }
 
@@ -68,7 +84,9 @@ export function rowToSearchResult(row: ThreadRowData): SearchResult {
  */
 export function semanticToSearchResult(
 	hit: RemitImapSemanticSearchResult,
+	folders?: ResultFolderIndex,
 ): SearchResult {
+	const { mailboxId, folder } = resolveResultFolder(folders, hit.mailboxIds);
 	return {
 		id: hit.messageId,
 		sender: hit.fromName ?? "Unknown",
@@ -78,7 +96,8 @@ export function semanticToSearchResult(
 		threadId: hit.threadId,
 		matchedChunkLabel: matchedChunkLabel(hit.matchedChunkType),
 		score: hit.score,
-		...(hit.mailboxIds[0] != null ? { mailboxId: hit.mailboxIds[0] } : {}),
+		...(mailboxId ? { mailboxId } : {}),
+		...(folder ? { folder } : {}),
 	};
 }
 
@@ -90,13 +109,14 @@ export function semanticToSearchResult(
 export function relatedSearchResults(
 	hits: RemitImapSemanticSearchResult[],
 	literalThreadIds: Iterable<string>,
+	folders?: ResultFolderIndex,
 ): SearchResult[] {
 	const seenThreadIds = new Set<string>(literalThreadIds);
 	const results: SearchResult[] = [];
 	for (const hit of [...hits].sort((a, b) => b.score - a.score)) {
 		if (seenThreadIds.has(hit.threadId)) continue;
 		seenThreadIds.add(hit.threadId);
-		results.push(semanticToSearchResult(hit));
+		results.push(semanticToSearchResult(hit, folders));
 	}
 	return results;
 }

package/src/lib/search-scope.test.ts

@@ -8,6 +8,7 @@ import {
 } from "./mail-route";
 import {
 	isScopedRoute,
+	resultsScopeForRoute,
 	SEARCH_SCOPE_CHIP_ID,
 	scopeLabelForMailboxName,
 	searchScopeForRoute,
@@ -195,3 +196,57 @@ describe("semanticMailboxScope — a chip binds every engine on the route", () =
 		}
 	});
 });
+
+describe("resultsScopeForRoute", () => {
+	it("passes the global search through as global", () => {
+		assert.deepEqual(
+			resultsScopeForRoute(matches(MAIL_BRIEF_ROUTE_ID), { kind: "global" }),
+			{
+				kind: "global",
+			},
+		);
+	});
+
+	it("treats a mailbox whose name has not loaded as a folder, not global", () => {
+		assert.deepEqual(
+			resultsScopeForRoute(matches(MAIL_MAILBOX_ROUTE_ID), { kind: "pending" }),
+			{
+				kind: "folder",
+			},
+		);
+	});
+
+	it("carries the mailbox's role so a Spam search shows its rows", () => {
+		assert.deepEqual(
+			resultsScopeForRoute(
+				matches(MAIL_MAILBOX_ROUTE_ID),
+				{
+					kind: "scoped",
+					chip: { id: SEARCH_SCOPE_CHIP_ID, label: "in:spam" },
+				},
+				"junk",
+			),
+			{ kind: "folder", role: "junk" },
+		);
+	});
+
+	it("calls starred a collection, so its spam is not dropped", () => {
+		assert.deepEqual(
+			resultsScopeForRoute(matches(MAIL_FLAGGED_ROUTE_ID), {
+				kind: "scoped",
+				chip: { id: SEARCH_SCOPE_CHIP_ID, label: "is:starred" },
+			}),
+			{ kind: "collection" },
+		);
+	});
+
+	it("keeps the outbox a folder — it is one queue, and never holds spam", () => {
+		assert.deepEqual(
+			resultsScopeForRoute(matches(MAIL_OUTBOX_ROUTE_ID), {
+				kind: "scoped",
+				chip: { id: SEARCH_SCOPE_CHIP_ID, label: "in:outbox" },
+			}),
+			{ kind: "folder" },
+		);
+	});
+});

package/src/lib/search-scope.ts

@@ -21,6 +21,7 @@
  *
  * Pure functions only. `useSearchScope` binds these to the router.
  */
+import type { FolderRole, SearchScope as ResultsScope } from "@remit/ui";
 import {
 	isBriefRoute,
 	isFlaggedRoute,
@@ -152,3 +153,30 @@ export function searchScopeForRoute(
 	}
 	return { kind: "global" };
 }
+
+/**
+ * The route's scope as the results list understands it.
+ *
+ * `is:starred` is a collection, not a folder: it spans every folder a star can
+ * be set in, so its rows carry provenance, and it is the user's own hand-picked
+ * mail, so a starred spam message is shown rather than held back. Only a search
+ * confined to a folder drops spam.
+ *
+ * The bar's third state, `pending`, is a mailbox route whose name has not
+ * loaded. It maps to `folder` with no role yet, because the list underneath is
+ * already one mailbox; calling it global for that one frame would flash folder
+ * labels and a spam offer and then retract them.
+ *
+ * `role` is the appointed role of the mailbox the route is on, which is what
+ * makes a search scoped to Spam show its rows instead of dropping them. A
+ * folder nobody appointed carries no role.
+ */
+export function resultsScopeForRoute(
+	matches: readonly MailRouteMatch[],
+	state: SearchScopeState,
+	role?: FolderRole,
+): ResultsScope {
+	if (state.kind === "global") return { kind: "global" };
+	if (isFlaggedRoute(matches)) return { kind: "collection" };
+	return { kind: "folder", ...(role ? { role } : {}) };
+}

package/src/lib/spam-offer.test.ts

@@ -0,0 +1,84 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import type { SearchResult } from "@remit/ui";
+import { spamOfferForResults } from "./spam-offer";
+
+const row = (
+	id: string,
+	mailboxId: string,
+	role?: "junk" | "inbox",
+): SearchResult => ({
+	id,
+	sender: "Someone",
+	subject: "Subject",
+	snippet: "",
+	date: "",
+	mailboxId,
+	...(role ? { folder: { role } } : {}),
+});
+
+describe("spamOfferForResults", () => {
+	it("makes no offer when nothing came from Spam", () => {
+		assert.equal(
+			spamOfferForResults([row("1", "mb-inbox", "inbox"), row("2", "mb-a")]),
+			undefined,
+		);
+	});
+
+	it("counts the spam rows and names their mailbox", () => {
+		assert.deepEqual(
+			spamOfferForResults([
+				row("1", "mb-inbox", "inbox"),
+				row("2", "mb-junk", "junk"),
+				row("3", "mb-junk", "junk"),
+			]),
+			{ mailboxId: "mb-junk", count: 2 },
+		);
+	});
+
+	it("targets the Spam folder with the most matches when accounts compete", () => {
+		assert.deepEqual(
+			spamOfferForResults([
+				row("1", "mb-junk-a", "junk"),
+				row("2", "mb-junk-b", "junk"),
+				row("3", "mb-junk-b", "junk"),
+			]),
+			{ mailboxId: "mb-junk-b", count: 2 },
+		);
+	});
+
+	it("breaks a tie on result order, so the offer does not flip", () => {
+		assert.deepEqual(
+			spamOfferForResults([
+				row("1", "mb-junk-a", "junk"),
+				row("2", "mb-junk-b", "junk"),
+			]),
+			{ mailboxId: "mb-junk-a", count: 1 },
+		);
+	});
+
+	it("picks a destination without claiming to have counted every account", () => {
+		// Three spam rows across two accounts: the destination is the bigger folder,
+		// and its share is 2 — deliberately not the total, which the results list
+		// states for itself so the banner cannot under-report.
+		const offer = spamOfferForResults([
+			row("1", "mb-junk-a", "junk"),
+			row("2", "mb-junk-b", "junk"),
+			row("3", "mb-junk-b", "junk"),
+		]);
+		assert.equal(offer?.mailboxId, "mb-junk-b");
+		assert.equal(offer?.count, 2);
+	});
+
+	it("ignores a spam row that carries no mailbox to navigate to", () => {
+		const orphan: SearchResult = {
+			id: "1",
+			sender: "Someone",
+			subject: "Subject",
+			snippet: "",
+			date: "",
+			folder: { role: "junk" },
+		};
+		assert.equal(spamOfferForResults([orphan]), undefined);
+	});
+});

package/src/lib/spam-offer.ts

@@ -0,0 +1,37 @@
+/**
+ * Where taking the Spam offer lands.
+ *
+ * Scoping is a route and a route names one mailbox, so the offer has to pick a
+ * single Spam folder even when several accounts matched; it picks the one
+ * holding the most matches. `count` is that folder's share, used only to choose
+ * between folders — the banner states the full number of rows held out, which
+ * the results list counts for itself.
+ */
+import { partitionSpamResults, type SearchResult } from "@remit/ui";
+
+export interface SpamOffer {
+	mailboxId: string;
+	count: number;
+}
+
+export function spamOfferForResults(
+	results: readonly SearchResult[],
+): SpamOffer | undefined {
+	const { spam } = partitionSpamResults([...results]);
+	const countByMailbox = new Map<string, number>();
+	for (const result of spam) {
+		if (!result.mailboxId) continue;
+		countByMailbox.set(
+			result.mailboxId,
+			(countByMailbox.get(result.mailboxId) ?? 0) + 1,
+		);
+	}
+
+	let offer: SpamOffer | undefined;
+	// Insertion order is result order, so the first-seen folder wins a tie and
+	// the offer does not flip between renders of the same results.
+	for (const [mailboxId, count] of countByMailbox) {
+		if (!offer || count > offer.count) offer = { mailboxId, count };
+	}
+	return offer;
+}

package/src/routes/mail.tsx

@@ -27,6 +27,7 @@ import { useDebouncedValue } from "@/hooks/useDebouncedValue";
 import { useKeyboardNavigation } from "@/hooks/useKeyboardNavigation";
 import { isSinglePaneTier, useLayoutTier } from "@/hooks/useLayoutTier";
 import { useMailboxNameIndex } from "@/hooks/useMailboxNameIndex";
+import { useResultFolderIndex } from "@/hooks/useResultFolderIndex";
 import { useStaleAccountSync } from "@/hooks/useStaleAccountSync";
 import { writeIntelligencePref } from "@/lib/intelligence-pref";
 import { MailContext } from "@/lib/mail-context";
@@ -232,6 +233,7 @@ function MailLayout() {
 
 	const accounts = config?.accounts ?? [];
 	const mailboxNameIndex = useMailboxNameIndex(accounts);
+	const resultFolderIndex = useResultFolderIndex(accounts);
 	const accountNameIndex = useMemo(
 		() => buildAccountNameIndex(accounts),
 		[accounts],
@@ -290,6 +292,7 @@ function MailLayout() {
 		accounts,
 		mailboxNameIndex,
 		accountNameIndex,
+		resultFolderIndex,
 		// The committed local value is the source of truth for search; it is
 		// mirrored to the URL for shareable links.
 		searchQuery: committedQuery,