@remit/web-client 0.0.29 → 0.0.31

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/web-client",
-  "version": "0.0.29",
+  "version": "0.0.31",
   "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/auth/auth-interceptor.test.ts

@@ -1,5 +1,6 @@
 import assert from "node:assert";
 import { describe, test } from "node:test";
+import { AuthTokenError } from "./better-auth-config";
 import { type AuthProvider, noneAuthProvider } from "./provider";
 
 type RequestFn = (req: Request) => Promise<Request>;
@@ -47,7 +48,28 @@ describe("installAuthInterceptor", () => {
 		assert.equal(out.headers.get("Authorization"), "Bearer ID-TOKEN-123");
 	});
 
-	test("omits Authorization header when the provider returns no token", async () => {
+	test("abandons the request when the token cannot be minted — never sends it unauthenticated", async () => {
+		const mod = await loadInterceptor();
+		mod.installAuthInterceptor(
+			providerWithToken(async () => {
+				throw new AuthTokenError("Could not mint a session token: 429", 429);
+			}),
+		);
+		const fn = globalThis.__REMIT_CLIENT_MOCKS__?.requestFns[0];
+		assert.ok(fn);
+		const req = new Request("https://api.example.com/thing");
+		await assert.rejects(
+			() => fn(req),
+			(error: unknown) => {
+				assert.ok(error instanceof AuthTokenError);
+				assert.equal(error.status, 429);
+				return true;
+			},
+		);
+		assert.equal(req.headers.get("Authorization"), null);
+	});
+
+	test("omits Authorization header when the deployment presents no identity", async () => {
 		const mod = await loadInterceptor();
 		mod.installAuthInterceptor(providerWithToken(async () => null));
 		const fn = globalThis.__REMIT_CLIENT_MOCKS__?.requestFns[0];

package/src/auth/auth-interceptor.ts

@@ -7,6 +7,11 @@ let installed = false;
  * Attach the composed provider's bearer token to every API request. Called once
  * from `mountApp` with the app's chosen provider, so the token source is the
  * same `AuthProvider` the shell and screens read — no separate seam.
+ *
+ * A provider that cannot produce a token throws, and that throw is left to
+ * propagate: the request is abandoned rather than sent without an Authorization
+ * header. Only the deployments that present no identity at all resolve to null,
+ * and for those an unauthenticated request is the intended one.
  */
 export const installAuthInterceptor = (authProvider: AuthProvider): void => {
 	if (installed) return;

package/src/auth/better-auth-config.ts

@@ -51,11 +51,32 @@ const decodeExp = (token: string): number => {
 	}
 };
 
-const requestToken = async (): Promise<string | null> => {
+/**
+ * A session exists but no bearer token could be produced for it. Distinct from
+ * "signed out": there is nothing to fall back to, so the request that needed the
+ * token must not be sent. Carries the mint's HTTP status where there was one, so
+ * the shared classifier reads it like any other API failure.
+ */
+export class AuthTokenError extends Error {
+	readonly status: number | undefined;
+
+	constructor(message: string, status?: number) {
+		super(message);
+		this.name = "AuthTokenError";
+		this.status = status;
+	}
+}
+
+const requestToken = async (): Promise<string> => {
 	const res = await taggedFetch("/api/auth/token", {
 		credentials: "include",
 	});
-	if (!res.ok) return null;
+	if (!res.ok) {
+		throw new AuthTokenError(
+			`Could not mint a session token: ${res.status} ${res.statusText}`,
+			res.status,
+		);
+	}
 	const body: unknown = await res.json();
 	if (
 		body &&
@@ -65,7 +86,29 @@ const requestToken = async (): Promise<string | null> => {
 	) {
 		return (body as { token: string }).token;
 	}
-	return null;
+	throw new AuthTokenError("The token endpoint returned no token");
+};
+
+let inFlight: Promise<string> | null = null;
+
+/**
+ * One mint at a time. A cold load renders many screens at once and each of their
+ * requests needs the same token; without this every one of them mints its own,
+ * and the burst is large enough to spend the auth tier's rate-limit budget. The
+ * slot is released once the mint settles, so a failure is not replayed to later
+ * callers — they mint again.
+ */
+const mint = (): Promise<string> => {
+	if (inFlight) return inFlight;
+	inFlight = requestToken()
+		.then((token) => {
+			cached = { value: token, expiresAt: decodeExp(token) };
+			return token;
+		})
+		.finally(() => {
+			inFlight = null;
+		});
+	return inFlight;
 };
 
 /**
@@ -73,14 +116,16 @@ const requestToken = async (): Promise<string | null> => {
  * when the cached token is missing or within the skew window of expiry. The API
  * interceptor attaches it as a Bearer token; the backend verifies it against the
  * JWKS.
+ *
+ * Never resolves to null: a failed mint throws. Returning null would put the
+ * request on the wire without an Authorization header, and the backend answers
+ * that with a 401 that names a missing token rather than the mint that failed.
  */
-export const fetchBetterAuthToken = async (): Promise<string | null> => {
+export const fetchBetterAuthToken = async (): Promise<string> => {
 	if (cached && cached.expiresAt - EXPIRY_SKEW_SECONDS > nowSeconds()) {
 		return cached.value;
 	}
-	const token = await requestToken();
-	cached = token ? { value: token, expiresAt: decodeExp(token) } : null;
-	return token;
+	return mint();
 };
 
 export const resetBetterAuthTokenCache = (): void => {

package/src/auth/better-auth-token.test.ts

@@ -0,0 +1,152 @@
+import assert from "node:assert";
+import { afterEach, describe, test } from "node:test";
+import {
+	AuthTokenError,
+	fetchBetterAuthToken,
+	resetBetterAuthTokenCache,
+} from "./better-auth-config";
+
+const base64url = (value: string): string =>
+	Buffer.from(value, "utf8")
+		.toString("base64")
+		.replace(/\+/g, "-")
+		.replace(/\//g, "_")
+		.replace(/=+$/, "");
+
+/** A token shaped like the one better-auth mints, valid for an hour. */
+const jwt = (label: string): string =>
+	`header.${base64url(
+		JSON.stringify({ exp: Math.floor(Date.now() / 1000) + 3600, label }),
+	)}.signature`;
+
+const realFetch = globalThis.fetch;
+
+interface Stub {
+	calls: number;
+	release: () => void;
+}
+
+/** Stand in for the token endpoint, holding every request open until released. */
+const stubTokenEndpoint = (respond: (call: number) => Response): Stub => {
+	let open: () => void = () => {};
+	const gate = new Promise<void>((resolve) => {
+		open = resolve;
+	});
+	const stub: Stub = { calls: 0, release: () => open() };
+	globalThis.fetch = (async (input: RequestInfo | URL) => {
+		assert.match(String(input), /\/api\/auth\/token$/);
+		stub.calls += 1;
+		const call = stub.calls;
+		await gate;
+		return respond(call);
+	}) as typeof fetch;
+	return stub;
+};
+
+const tokenResponse = (token: string): Response =>
+	new Response(JSON.stringify({ token }), {
+		status: 200,
+		headers: { "Content-Type": "application/json" },
+	});
+
+afterEach(() => {
+	globalThis.fetch = realFetch;
+	resetBetterAuthTokenCache();
+});
+
+describe("fetchBetterAuthToken", () => {
+	test("concurrent callers share one mint instead of each firing their own", async () => {
+		const stub = stubTokenEndpoint((call) => tokenResponse(jwt(`t${call}`)));
+
+		const pending = Array.from({ length: 12 }, () => fetchBetterAuthToken());
+		stub.release();
+		const tokens = await Promise.all(pending);
+
+		assert.equal(stub.calls, 1);
+		assert.equal(new Set(tokens).size, 1);
+	});
+
+	test("a token minted once is reused from cache, without a second request", async () => {
+		const stub = stubTokenEndpoint(() => tokenResponse(jwt("cached")));
+		stub.release();
+
+		const first = await fetchBetterAuthToken();
+		const second = await fetchBetterAuthToken();
+
+		assert.equal(stub.calls, 1);
+		assert.equal(second, first);
+	});
+
+	test("a rejected mint throws with its status rather than resolving to null", async () => {
+		const stub = stubTokenEndpoint(
+			() => new Response("", { status: 429, statusText: "Too Many Requests" }),
+		);
+		stub.release();
+
+		await assert.rejects(
+			() => fetchBetterAuthToken(),
+			(error: unknown) => {
+				assert.ok(error instanceof AuthTokenError);
+				assert.equal(error.status, 429);
+				return true;
+			},
+		);
+	});
+
+	test("a response carrying no token throws rather than resolving to null", async () => {
+		const stub = stubTokenEndpoint(
+			() =>
+				new Response(JSON.stringify({}), {
+					status: 200,
+					headers: { "Content-Type": "application/json" },
+				}),
+		);
+		stub.release();
+
+		await assert.rejects(() => fetchBetterAuthToken(), AuthTokenError);
+	});
+
+	test("every caller sharing a failed mint sees the failure", async () => {
+		const stub = stubTokenEndpoint(
+			() => new Response("", { status: 429, statusText: "Too Many Requests" }),
+		);
+
+		const pending = Array.from({ length: 5 }, () =>
+			fetchBetterAuthToken().then(
+				() => "resolved",
+				(error: unknown) =>
+					error instanceof AuthTokenError ? "threw" : "other",
+			),
+		);
+		stub.release();
+		const outcomes = await Promise.all(pending);
+
+		assert.equal(stub.calls, 1);
+		assert.deepEqual(new Set(outcomes), new Set(["threw"]));
+	});
+
+	test("a failed mint is not replayed — the next caller mints again", async () => {
+		const failing = stubTokenEndpoint(() => new Response("", { status: 500 }));
+		failing.release();
+		await assert.rejects(() => fetchBetterAuthToken());
+
+		const succeeding = stubTokenEndpoint(() =>
+			tokenResponse(jwt("after-failure")),
+		);
+		succeeding.release();
+
+		assert.ok(await fetchBetterAuthToken());
+		assert.equal(succeeding.calls, 1);
+	});
+
+	test("a network failure propagates instead of yielding a tokenless request", async () => {
+		globalThis.fetch = (async () => {
+			throw new TypeError("Failed to fetch");
+		}) as typeof fetch;
+
+		await assert.rejects(
+			() => fetchBetterAuthToken(),
+			/could not be completed|Failed to fetch/i,
+		);
+	});
+});

package/src/auth/provider.tsx

@@ -22,9 +22,14 @@ export interface AuthProvider {
 	/** Called once at boot, before render, to initialize the identity SDK. */
 	configure(): void;
 	/**
-	 * The current session's bearer token, or `null` when signed out. The API
-	 * interceptor and the raw content fetch read it through here, so the identity
-	 * SDK stays inside the provider.
+	 * The current session's bearer token. The API interceptor and the raw content
+	 * fetch read it through here, so the identity SDK stays inside the provider.
+	 *
+	 * `null` means this deployment has no identity to present — no identity system
+	 * is composed, or none is configured — and the request is expected to travel
+	 * unauthenticated. It never means the token could not be produced: a provider
+	 * that holds a session and fails to mint a token throws, because a request
+	 * that cannot be authenticated must not be sent.
 	 */
 	getToken(): Promise<string | null>;
 	/** Drop any cached token so the next `getToken` re-mints. */

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/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/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,