@remit/ui 0.0.13 → 0.0.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/ui",
-  "version": "0.0.13",
+  "version": "0.0.14",
   "type": "module",
   "files": [
     "src"

package/src/components/folder-role.test.ts

@@ -0,0 +1,72 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { isVirtualFolderRole, provenanceFolderLabel } from "./folder-role.js";
+
+describe("provenanceFolderLabel", () => {
+	it("names an appointed role by its canonical label", () => {
+		assert.equal(provenanceFolderLabel({ role: "archive" }), "Archive");
+		assert.equal(provenanceFolderLabel({ role: "sent" }), "Sent");
+	});
+
+	it("reads a junk appointment as Spam whatever the server calls it", () => {
+		assert.equal(
+			provenanceFolderLabel({ role: "junk", providerPath: "Bulk Mail" }),
+			"Spam",
+		);
+	});
+
+	it("falls back to the leaf of a folder nobody appointed", () => {
+		assert.equal(
+			provenanceFolderLabel({ providerPath: "Projects/Bookkeeping" }),
+			"Bookkeeping",
+		);
+	});
+
+	it("refuses to label a view rather than a place", () => {
+		assert.equal(provenanceFolderLabel({ role: "all" }), undefined);
+		assert.equal(provenanceFolderLabel({ role: "flagged" }), undefined);
+	});
+
+	it("refuses to label Gmail's own reserved namespace", () => {
+		assert.equal(
+			provenanceFolderLabel({ providerPath: "[Gmail]/All Mail" }),
+			undefined,
+		);
+		assert.equal(
+			provenanceFolderLabel({ providerPath: "[Gmail]/Starred" }),
+			undefined,
+		);
+	});
+
+	it("refuses the googlemail.com spelling of the same namespace", () => {
+		assert.equal(
+			provenanceFolderLabel({ providerPath: "[Google Mail]/All Mail" }),
+			undefined,
+		);
+		assert.equal(
+			provenanceFolderLabel({ providerPath: "[Google Mail]/Starred" }),
+			undefined,
+		);
+	});
+
+	it("labels a user folder that merely mentions Gmail", () => {
+		assert.equal(provenanceFolderLabel({ providerPath: "Gmail" }), "Gmail");
+	});
+
+	it("has nothing to say about a folder it knows nothing about", () => {
+		assert.equal(provenanceFolderLabel({}), undefined);
+	});
+});
+
+describe("isVirtualFolderRole", () => {
+	it("counts All Mail and Starred as views", () => {
+		assert.equal(isVirtualFolderRole("all"), true);
+		assert.equal(isVirtualFolderRole("flagged"), true);
+	});
+
+	it("counts real folders as places", () => {
+		assert.equal(isVirtualFolderRole("inbox"), false);
+		assert.equal(isVirtualFolderRole("junk"), false);
+		assert.equal(isVirtualFolderRole("trash"), false);
+	});
+});

package/src/components/folder-role.tsx

@@ -54,6 +54,65 @@ export function providerLeaf(providerPath: string): string {
 	return parts[parts.length - 1] || providerPath;
 }
 
+/* ------------------------------------------------------------------ */
+/* Provenance: where a search result actually lives                    */
+/* ------------------------------------------------------------------ */
+
+/**
+ * The folder a search result was read from. `role` is the account's IMAP
+ * special-use appointment (`junk` is `\Junk`); accounts that expose a folder
+ * nobody appointed carry only a `providerPath`.
+ */
+export interface ResultFolder {
+	role?: FolderRole;
+	/** Provider path as the server spells it, e.g. `Projects/Bookkeeping`. */
+	providerPath?: string;
+}
+
+/**
+ * Roles that name a view rather than a place a message is filed. A message in
+ * All Mail or Starred is also somewhere real, so labelling a result with one of
+ * these says nothing about where it came from.
+ */
+const VIRTUAL_ROLES: ReadonlySet<FolderRole> = new Set(["all", "flagged"]);
+
+export function isVirtualFolderRole(role: FolderRole): boolean {
+	return VIRTUAL_ROLES.has(role);
+}
+
+/**
+ * Gmail exposes its views as ordinary folders under a reserved namespace. An
+ * account that appointed no role to them leaves the path as the only signal, so
+ * the namespace is matched by name — the one place a name is the honest test,
+ * because it is the provider's own reserved prefix and not a user's folder.
+ *
+ * Accounts provisioned under googlemail.com get the same namespace spelled
+ * `[Google Mail]`, so both forms count. A user folder plainly called `Gmail`
+ * does not — the brackets are what make the prefix reserved.
+ */
+const GMAIL_NAMESPACES: ReadonlySet<string> = new Set([
+	"[Gmail]",
+	"[Google Mail]",
+]);
+
+/**
+ * Label for the folder a result came from, or `undefined` when that folder is a
+ * view rather than a place — in which case no label is better than a misleading
+ * one. An appointed role wins over the provider's spelling, so a folder the
+ * account calls `Junk` still reads as "Spam".
+ */
+export function provenanceFolderLabel(
+	folder: ResultFolder,
+): string | undefined {
+	if (folder.role) {
+		if (isVirtualFolderRole(folder.role)) return undefined;
+		return canonicalRoleLabel(folder.role);
+	}
+	if (!folder.providerPath) return undefined;
+	if (GMAIL_NAMESPACES.has(folder.providerPath.split("/")[0])) return undefined;
+	return providerLeaf(folder.providerPath);
+}
+
 export function roleIcon(role: FolderRole): ReactNode {
 	if (role === "inbox") return <Inbox className="size-4" />;
 	if (role === "drafts") return <FileText className="size-4" />;

package/src/components/mobile-search-view.render.test.ts

@@ -0,0 +1,78 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { createElement } from "react";
+import { renderToString } from "react-dom/server";
+import { MobileSearchView } from "./mobile-search-view.js";
+import type { SearchResult } from "./search-result-row.js";
+
+const noop = () => {};
+
+const archived: SearchResult = {
+	id: "a1",
+	sender: "Mollie",
+	subject: "Invoice 2026-02",
+	snippet: "Payment already settled.",
+	date: "Feb 24",
+	folder: { role: "archive" },
+};
+
+const spam: SearchResult = {
+	id: "s1",
+	sender: "billing@unknown-vendor.test",
+	subject: "URGENT invoice attached",
+	snippet: "Wire the amount below.",
+	date: "Feb 11",
+	folder: { role: "junk" },
+};
+
+const sections = [
+	{ id: "top", label: "Top matches", results: [archived, spam] },
+];
+
+const base = {
+	value: "invoice",
+	onChange: noop,
+	onClear: noop,
+	onCancel: noop,
+	sections,
+};
+
+describe("MobileSearchView search scope", () => {
+	it("offers held-out spam on the phone tier too", () => {
+		const html = renderToString(
+			createElement(MobileSearchView, {
+				...base,
+				scope: { kind: "global" as const },
+				onScopeToSpam: noop,
+			}),
+		);
+		assert.doesNotMatch(html, /unknown-vendor/);
+		assert.match(html, /result from Spam/);
+		assert.match(html, /Archive/);
+	});
+
+	it("shows neither spam nor provenance labels when scoped", () => {
+		const html = renderToString(
+			createElement(MobileSearchView, {
+				...base,
+				scope: { kind: "folder" as const, role: "inbox" as const },
+				onScopeToSpam: noop,
+			}),
+		);
+		assert.doesNotMatch(html, /unknown-vendor/);
+		assert.doesNotMatch(html, /from Spam/);
+		assert.doesNotMatch(html, /Archive/);
+	});
+
+	it("passes a caller-supplied spam total through", () => {
+		const html = renderToString(
+			createElement(MobileSearchView, {
+				...base,
+				scope: { kind: "global" as const },
+				spamMatchCount: 42,
+				onScopeToSpam: noop,
+			}),
+		);
+		assert.match(html, />42</);
+	});
+});

package/src/components/mobile-search-view.stories.tsx

@@ -8,7 +8,7 @@ import {
 import { MobileSearchView } from "./mobile-search-view.js";
 import type { SearchChip } from "./search-chip-input.js";
 import type { SearchResult } from "./search-result-row.js";
-import type { SearchResultSection } from "./search-results.js";
+import type { SearchResultSection, SearchScope } from "./search-results.js";
 
 const phoneFrame: Decorator = (Story) => (
 	<div
@@ -97,6 +97,56 @@ const emptySections: SearchResultSection[] = [
 	{ id: "related", label: "Related", results: [] },
 ];
 
+/** Matches spread across ordinary folders, each carrying where it was read from. */
+const crossFolderMatches: SearchResult[] = [
+	{ ...topMatches[0], folder: { role: "inbox" } },
+	{ ...topMatches[1], folder: { role: "inbox" } },
+	{
+		id: "x1",
+		sender: "Mollie",
+		subject: "Invoice 2026-02 — archived",
+		snippet: "Filed last month; payment already settled.",
+		date: "Feb 24",
+		folder: { role: "archive" },
+	},
+	{
+		id: "x2",
+		sender: "Accountant",
+		subject: "Invoices for the quarter",
+		snippet: "The quarterly set, filed with the rest of the bookkeeping.",
+		date: "Jan 30",
+		folder: { providerPath: "Projects/Bookkeeping" },
+	},
+];
+
+/** Matches in the account's `\Junk` folder. */
+const spamMatches: SearchResult[] = [
+	{
+		id: "s1",
+		sender: "billing@unknown-vendor.test",
+		subject: "URGENT invoice attached",
+		snippet: "Wire the amount below within 24 hours to avoid suspension.",
+		date: "Feb 11",
+		folder: { role: "junk" },
+	},
+	{
+		id: "s2",
+		sender: "invoices@pay-now.test",
+		subject: "Outstanding invoice — final notice",
+		snippet: "Your account is overdue. Settle immediately.",
+		date: "Feb 4",
+		folder: { role: "junk" },
+	},
+];
+
+const acrossFoldersSections: SearchResultSection[] = [
+	{
+		id: "top",
+		label: "Top matches",
+		results: [...crossFolderMatches, ...spamMatches],
+	},
+];
+
 type Preset = "brief" | "inbox";
 
 function Harness({
@@ -105,12 +155,18 @@ function Harness({
 	loading,
 	sections,
 	preset,
+	scope,
+	spamMatchCount,
+	onScopeToSpam,
 }: {
 	initialValue?: string;
 	initialChips?: SearchChip[];
 	loading?: boolean;
 	sections?: SearchResultSection[];
 	preset: Preset;
+	scope?: SearchScope;
+	spamMatchCount?: number;
+	onScopeToSpam?: () => void;
 }) {
 	const [value, setValue] = useState(initialValue);
 	const [chips, setChips] = useState<SearchChip[]>(initialChips);
@@ -183,6 +239,9 @@ function Harness({
 			sections={sections}
 			loading={loading}
 			onSelectResult={setOpened}
+			scope={scope}
+			spamMatchCount={spamMatchCount}
+			onScopeToSpam={onScopeToSpam}
 		/>
 	);
 }
@@ -257,14 +316,70 @@ export const RelatedSelectable: Story = {
  * top bar uses, inside the full-screen takeover's own chrome. The chip is
  * removable in place — backspace at the start of the text reaches it just as it
  * does on desktop.
+ *
+ * The chip and the scope say the same thing, which is the point: an `in:spam`
+ * chip is what a Spam-scoped search looks like in the bar.
  */
 export const ScopedByChip: Story = {
 	render: () => (
 		<Harness
 			initialValue="invoice"
 			initialChips={[{ id: "in:spam", label: "in:spam" }]}
-			sections={resultSections}
+			sections={[{ id: "top", label: "Top matches", results: spamMatches }]}
+			scope={{ kind: "folder", role: "junk" }}
+			preset="inbox"
+		/>
+	),
+};
+
+/**
+ * Global search on the phone, holding spam out and offering it above the
+ * results — the same treatment the desktop list pane gives it, because both
+ * tiers render the one `SearchResults` body. Rows name the folder they came
+ * from; the two spam matches in the same data are not among them.
+ */
+export const GlobalAcrossFolders: Story = {
+	render: () => (
+		<Harness
+			initialValue="invoice"
+			sections={acrossFoldersSections}
+			scope={{ kind: "global" }}
+			onScopeToSpam={() => {}}
+			preset="brief"
+		/>
+	),
+};
+
+/**
+ * The same rows scoped to the inbox. No spam, no count, no offer, and no
+ * provenance labels — the chip in the bar already says where the search is
+ * looking.
+ */
+export const ScopedToInbox: Story = {
+	render: () => (
+		<Harness
+			initialValue="invoice"
+			initialChips={[{ id: "in:inbox", label: "in:inbox" }]}
+			sections={acrossFoldersSections}
+			scope={{ kind: "folder", role: "inbox" }}
+			onScopeToSpam={() => {}}
 			preset="inbox"
 		/>
 	),
 };
+
+/**
+ * A global phone search whose only matches are in Spam: the offer stands above
+ * the empty state rather than leaving the search looking fruitless.
+ */
+export const GlobalOnlySpamMatches: Story = {
+	render: () => (
+		<Harness
+			initialValue="invoice"
+			sections={[{ id: "top", label: "Top matches", results: spamMatches }]}
+			scope={{ kind: "global" }}
+			onScopeToSpam={() => {}}
+			preset="brief"
+		/>
+	),
+};

package/src/components/mobile-search-view.tsx

@@ -4,7 +4,11 @@ import { FilterSheet, type FilterSheetProps } from "./filter-sheet.js";
 import { SearchBar } from "./search-bar.js";
 import type { SearchChip } from "./search-chip-input.js";
 import type { SearchResult } from "./search-result-row.js";
-import { type SearchResultSection, SearchResults } from "./search-results.js";
+import {
+	type SearchResultSection,
+	SearchResults,
+	type SearchScope,
+} from "./search-results.js";
 
 export interface MobileSearchViewProps {
 	value: string;
@@ -40,6 +44,12 @@ export interface MobileSearchViewProps {
 	 */
 	chips?: readonly SearchChip[];
 	onRemoveChip?: (id: string) => void;
+	/** What the search covers; see `SearchResultsProps`. Defaults to global. */
+	scope?: SearchScope;
+	/** Total spam matches found; see `SearchResultsProps`. */
+	spamMatchCount?: number;
+	/** Scope the search to Spam; see `SearchResultsProps`. */
+	onScopeToSpam?: () => void;
 }
 
 /**
@@ -52,6 +62,9 @@ export interface MobileSearchViewProps {
  * the inboxes use) so search carries identical filters; pass no `filter` to drop
  * the chrome. Desktop reuses the same `SearchResults` body in the list pane.
  * Presentational and prop-driven.
+ *
+ * Search scope passes straight through, so the phone tier holds spam out,
+ * offers it and labels provenance on exactly the same terms as desktop.
  */
 export function MobileSearchView({
 	value,
@@ -67,6 +80,9 @@ export function MobileSearchView({
 	tokens,
 	chips,
 	onRemoveChip,
+	scope,
+	spamMatchCount,
+	onScopeToSpam,
 }: MobileSearchViewProps) {
 	const body = (
 		<SearchResults
@@ -77,6 +93,9 @@ export function MobileSearchView({
 			loading={loading}
 			onSelectResult={onSelectResult}
 			tokens={tokens}
+			scope={scope}
+			spamMatchCount={spamMatchCount}
+			onScopeToSpam={onScopeToSpam}
 		/>
 	);
 

package/src/components/search-result-row.tsx

@@ -2,6 +2,7 @@ import { Flag } from "lucide-react";
 import type { ReactNode } from "react";
 import { cn } from "../lib/cn.js";
 import { Badge } from "./badge.js";
+import { provenanceFolderLabel, type ResultFolder } from "./folder-role.js";
 
 export type SearchResultTone =
 	| "neutral"
@@ -27,6 +28,12 @@ export interface SearchResult {
 	threadId?: string;
 	/** The mailbox the result lives in; paired with {@link threadId} to open it. */
 	mailboxId?: string;
+	/**
+	 * The folder this row was read from. A search that reaches every folder
+	 * returns rows from all over, so the row says where it came from; see
+	 * {@link provenanceFolderLabel} for which folders can be named.
+	 */
+	folder?: ResultFolder;
 	/**
 	 * Why a semantic ("Related") hit matched — a plain-language label derived
 	 * from `matchedChunkType` (e.g. "body", "subject", "attachment"), so the user
@@ -43,6 +50,12 @@ export interface SearchResultRowProps {
 	onClick?: () => void;
 	/** When given, literal (case-insensitive) matches are bolded in subject/snippet. */
 	query?: string;
+	/**
+	 * Show the folder the row came from. Defaults to true. A search confined to
+	 * one folder turns it off — every row would carry the same label, which is
+	 * noise rather than provenance.
+	 */
+	showFolder?: boolean;
 }
 
 function highlight(text: string, query?: string): ReactNode {
@@ -79,7 +92,12 @@ export function SearchResultRow({
 	result,
 	onClick,
 	query,
+	showFolder = true,
 }: SearchResultRowProps) {
+	const folderLabel =
+		showFolder && result.folder
+			? provenanceFolderLabel(result.folder)
+			: undefined;
 	return (
 		<button
 			type="button"
@@ -118,6 +136,11 @@ export function SearchResultRow({
 				<span className="min-w-0 flex-1 truncate text-xs text-fg-subtle">
 					{highlight(result.snippet, query)}
 				</span>
+				{folderLabel && (
+					<Badge tone="neutral" className="shrink-0">
+						{folderLabel}
+					</Badge>
+				)}
 				{result.category && (
 					<Badge tone={result.category.tone ?? "neutral"} className="shrink-0">
 						{result.category.label}

package/src/components/search-results.render.test.ts

@@ -87,3 +87,184 @@ describe("SearchResults", () => {
 		assert.doesNotMatch(html, /Remove filter/);
 	});
 });
+
+const spamResult: SearchResult = {
+	id: "s1",
+	sender: "billing@unknown-vendor.test",
+	subject: "URGENT invoice attached",
+	snippet: "Wire the amount below.",
+	date: "Feb 11",
+	folder: { role: "junk" },
+};
+
+const archivedResult: SearchResult = {
+	...result,
+	id: "a1",
+	sender: "Mollie",
+	folder: { role: "archive" },
+};
+
+const mixed: SearchResultSection[] = [
+	{ id: "results", label: "Results", results: [archivedResult, spamResult] },
+];
+
+describe("SearchResults spam handling", () => {
+	it("holds spam out of a global search and offers it as a count", () => {
+		const html = renderToString(
+			createElement(SearchResults, {
+				value: "invoice",
+				sections: mixed,
+				scope: { kind: "global" },
+				onScopeToSpam: noop,
+			}),
+		);
+		assert.doesNotMatch(html, /unknown-vendor/);
+		assert.match(html, /result from Spam/);
+		assert.match(html, /Mollie/);
+	});
+
+	it("makes no offer when a global search found nothing in spam", () => {
+		const html = renderToString(
+			createElement(SearchResults, {
+				value: "invoice",
+				sections: [
+					{ id: "results", label: "Results", results: [archivedResult] },
+				],
+				scope: { kind: "global" },
+				onScopeToSpam: noop,
+			}),
+		);
+		assert.doesNotMatch(html, /from Spam/);
+	});
+
+	it("offers spam above the empty state when every match is spam", () => {
+		const html = renderToString(
+			createElement(SearchResults, {
+				value: "invoice",
+				sections: [{ id: "results", label: "Results", results: [spamResult] }],
+				scope: { kind: "global" },
+				onScopeToSpam: noop,
+			}),
+		);
+		assert.match(html, /No matches for/);
+		assert.match(html, /result from Spam/);
+	});
+
+	it("shows neither spam rows nor an offer when scoped elsewhere", () => {
+		const html = renderToString(
+			createElement(SearchResults, {
+				value: "invoice",
+				sections: mixed,
+				scope: { kind: "folder", role: "inbox" },
+				onScopeToSpam: noop,
+			}),
+		);
+		assert.doesNotMatch(html, /unknown-vendor/);
+		assert.doesNotMatch(html, /from Spam/);
+		assert.match(html, /Mollie/);
+	});
+
+	it("renders spam rows normally and makes no offer when scoped to spam", () => {
+		const html = renderToString(
+			createElement(SearchResults, {
+				value: "invoice",
+				sections: mixed,
+				scope: { kind: "folder", role: "junk" },
+				onScopeToSpam: noop,
+			}),
+		);
+		assert.match(html, /unknown-vendor/);
+		assert.doesNotMatch(html, /from Spam/);
+	});
+
+	it("makes no offer without a way to scope to spam", () => {
+		const html = renderToString(
+			createElement(SearchResults, {
+				value: "invoice",
+				sections: mixed,
+				scope: { kind: "global" },
+			}),
+		);
+		assert.doesNotMatch(html, /from Spam/);
+	});
+
+	it("prefers a caller-supplied total over the rows held out of this page", () => {
+		const html = renderToString(
+			createElement(SearchResults, {
+				value: "invoice",
+				sections: mixed,
+				scope: { kind: "global" },
+				spamMatchCount: 42,
+				onScopeToSpam: noop,
+			}),
+		);
+		assert.match(html, />42</);
+	});
+});
+
+describe("SearchResults provenance labels", () => {
+	it("names the folder each row came from in a global search", () => {
+		const html = renderToString(
+			createElement(SearchResults, {
+				value: "invoice",
+				sections: [
+					{
+						id: "results",
+						label: "Results",
+						results: [
+							archivedResult,
+							{
+								...result,
+								id: "c1",
+								folder: { providerPath: "Projects/Books" },
+							},
+						],
+					},
+				],
+				scope: { kind: "global" },
+			}),
+		);
+		assert.match(html, /Archive/);
+		assert.match(html, /Books/);
+	});
+
+	it("drops the labels when the search is scoped to one folder", () => {
+		const html = renderToString(
+			createElement(SearchResults, {
+				value: "invoice",
+				sections: [
+					{ id: "results", label: "Results", results: [archivedResult] },
+				],
+				scope: { kind: "folder", role: "archive" },
+			}),
+		);
+		assert.doesNotMatch(html, /Archive/);
+	});
+
+	it("leaves a row from a view rather than a folder unlabelled", () => {
+		const html = renderToString(
+			createElement(SearchResults, {
+				value: "invoice",
+				sections: [
+					{
+						id: "results",
+						label: "Results",
+						results: [
+							{ ...result, id: "v1", folder: { role: "all" } },
+							{ ...result, id: "v2", folder: { role: "flagged" } },
+							{
+								...result,
+								id: "v3",
+								folder: { providerPath: "[Gmail]/Important" },
+							},
+						],
+					},
+				],
+				scope: { kind: "global" },
+			}),
+		);
+		assert.doesNotMatch(html, /All Mail/);
+		assert.doesNotMatch(html, /Starred/);
+		assert.doesNotMatch(html, /Important/);
+	});
+});

package/src/components/search-results.stories.tsx

@@ -73,43 +73,71 @@ const resultSections: SearchResultSection[] = [
 ];
 
 /**
- * Matches from outside the inbox — Archive, Sent, Spam and a custom folder.
- * These are the rows an unscoped search returns that an INBOX-only one could
- * not, so they only ever appear under the brief's sections.
+ * Matches from outside the inbox — Archive, Sent and a custom folder — each
+ * carrying the folder it was read from. These are the rows a search reaching
+ * every folder returns that an INBOX-only one could not.
  */
 const crossFolderMatches: SearchResult[] = [
 	{
 		id: "x1",
 		sender: "Mollie",
 		subject: "Invoice 2026-02 — archived",
-		snippet: "Filed to Archive last month; payment already settled.",
+		snippet: "Filed last month; payment already settled.",
 		date: "Feb 24",
+		folder: { role: "archive" },
 		category: { label: "Receipt", tone: "positive" },
 	},
 	{
 		id: "x2",
 		sender: "me",
 		subject: "Re: invoice query",
-		snippet: "Sent — attaching the invoice you asked for.",
+		snippet: "Attaching the invoice you asked for.",
 		date: "Feb 18",
+		folder: { role: "sent" },
 	},
 	{
-		id: "x3",
+		id: "x4",
+		sender: "Accountant",
+		subject: "Invoices for the quarter",
+		snippet: "The quarterly set, filed with the rest of the bookkeeping.",
+		date: "Jan 30",
+		folder: { providerPath: "Projects/Bookkeeping" },
+	},
+];
+
+/**
+ * Matches that live in the account's `\Junk` folder. A global search holds
+ * these out of the sections entirely and offers them as a count instead.
+ */
+const spamMatches: SearchResult[] = [
+	{
+		id: "s1",
 		sender: "billing@unknown-vendor.test",
 		subject: "URGENT invoice attached",
-		snippet: "Marked as spam, but it is the invoice the user is looking for.",
+		snippet: "Wire the amount below within 24 hours to avoid suspension.",
 		date: "Feb 11",
-		category: { label: "Spam", tone: "warning" },
+		folder: { role: "junk" },
 	},
 	{
-		id: "x4",
-		sender: "Accountant",
-		subject: "Invoices for the quarter",
-		snippet: "Filed under Projects/Bookkeeping.",
-		date: "Jan 30",
+		id: "s2",
+		sender: "invoices@pay-now.test",
+		subject: "Outstanding invoice — final notice",
+		snippet: "Your account is overdue. Settle immediately.",
+		date: "Feb 4",
+		folder: { role: "junk" },
 	},
 ];
 
+/** The literal section a global search returns: inbox rows plus everywhere else. */
+const globalTopMatches: SearchResult[] = [
+	...topMatches.map((result) => ({
+		...result,
+		folder: { role: "inbox" as const },
+	})),
+	...crossFolderMatches,
+	...spamMatches,
+];
+
 const emptySections: SearchResultSection[] = [
 	{ id: "top", label: "Top matches", results: [] },
 ];
@@ -151,23 +179,45 @@ export const Idle: Story = {
 
 /**
  * The daily brief's unscoped search: no scope chip in the bar, and the literal
- * section carries matches from every folder — Archive, Sent, Spam and custom
- * folders alongside the inbox. Before the listing behind it took a search mode
- * it could only ever return inbox mail, so this section was silently narrower
- * than the bar promised.
+ * section carries matches from every folder — Archive, Sent and custom folders
+ * alongside the inbox. Each row says which folder it came from, because with
+ * nothing scoping the search the folder is the only thing placing the result.
  *
- * The rows themselves do not say which folder they came from; the sections are
- * ordered newest first regardless of where each message is filed.
+ * The two spam matches in the same data are not in this list. They are held out
+ * and offered above it as a count.
  */
-export const UnscopedAcrossFolders: Story = {
+export const GlobalAcrossFolders: Story = {
 	render: () => (
 		<Harness
 			value="invoice"
+			scope={{ kind: "global" }}
+			onScopeToSpam={() => {}}
+			sections={[
+				{ id: "top", label: "Top matches", results: globalTopMatches },
+				{ id: "related", label: "Related", results: related },
+			]}
+		/>
+	),
+};
+
+/**
+ * The same global search over an account whose Spam folder holds nothing
+ * matching. No spam rows to hold out, so no offer — the offer only ever appears
+ * because there is something behind it.
+ */
+export const GlobalWithoutSpamMatches: Story = {
+	render: () => (
+		<Harness
+			value="invoice"
+			scope={{ kind: "global" }}
+			onScopeToSpam={() => {}}
 			sections={[
 				{
 					id: "top",
 					label: "Top matches",
-					results: [...topMatches, ...crossFolderMatches],
+					results: globalTopMatches.filter(
+						(result) => result.folder?.role !== "junk",
+					),
 				},
 				{ id: "related", label: "Related", results: related },
 			]}
@@ -176,18 +226,105 @@ export const UnscopedAcrossFolders: Story = {
 };
 
 /**
- * A scoped view (a mailbox route, its `in:` chip in the bar). Both sections are
- * scoped to that folder and take the kit's default labels — the semantic
- * section used to run unscoped here under an "Everywhere" heading, which
- * contradicted the chip the same bar was showing.
+ * An account with no junk folder at all. Nothing is appointed `\Junk`, so no
+ * row can be spam and the component behaves exactly as it does when Spam is
+ * simply empty — there is no separate case to handle.
+ */
+export const GlobalAccountWithoutSpamFolder: Story = {
+	render: () => (
+		<Harness
+			value="invoice"
+			scope={{ kind: "global" }}
+			onScopeToSpam={() => {}}
+			sections={[
+				{ id: "top", label: "Top matches", results: crossFolderMatches },
+			]}
+		/>
+	),
+};
+
+/**
+ * A global search whose only matches are in Spam. The sections are empty, so
+ * the empty state stands — with the offer above it, which is the whole reason
+ * the user is not left thinking the search found nothing.
+ */
+export const GlobalOnlySpamMatches: Story = {
+	render: () => (
+		<Harness
+			value="invoice"
+			scope={{ kind: "global" }}
+			onScopeToSpam={() => {}}
+			sections={[{ id: "top", label: "Top matches", results: spamMatches }]}
+		/>
+	),
+};
+
+/**
+ * Scoped to the inbox (its `in:inbox` chip in the bar), given the very same
+ * rows as the global story — spam matches included. Nothing about Spam appears:
+ * no rows, no count, no offer. A scoped search shows its own scope and no more,
+ * and that asymmetry with the global view is deliberate.
+ *
+ * The rows also drop their folder labels here. Every row is in the scoped
+ * folder, so naming it on each one repeats the chip.
+ */
+export const ScopedToInbox: Story = {
+	render: () => (
+		<Harness
+			value="invoice"
+			scope={{ kind: "folder", role: "inbox" }}
+			onScopeToSpam={() => {}}
+			sections={[
+				{ id: "top", label: "Top matches", results: globalTopMatches },
+				{ id: "related", label: "Related", results: related },
+			]}
+		/>
+	),
+};
+
+/**
+ * Scoped to Spam — where taking the offer lands. Ordinary rows, rendered
+ * normally, and no offer, because the user is already here. This is the same
+ * scoped search reached by navigating to Spam with the query carried over; the
+ * offer is a shortcut into it, not a mode of its own.
+ */
+export const ScopedToSpam: Story = {
+	render: () => (
+		<Harness
+			value="invoice"
+			scope={{ kind: "folder", role: "junk" }}
+			onScopeToSpam={() => {}}
+			sections={[{ id: "top", label: "Top matches", results: spamMatches }]}
+		/>
+	),
+};
+
+/**
+ * A folder a search result can be in but never labelled with. All Mail and
+ * Starred are views over mail filed elsewhere, and Gmail exposes them as
+ * ordinary folders, so a row read from one carries no provenance label rather
+ * than a misleading one. The other rows keep theirs.
  */
-export const ScopedToOneFolder: Story = {
+export const VirtualFoldersGoUnlabelled: Story = {
 	render: () => (
 		<Harness
 			value="invoice"
+			scope={{ kind: "global" }}
 			sections={[
-				{ id: "top", label: "Top matches", results: topMatches.slice(0, 2) },
-				{ id: "related", label: "Related", results: related.slice(0, 1) },
+				{
+					id: "top",
+					label: "Top matches",
+					results: [
+						{ ...topMatches[0], id: "v1", folder: { role: "all" } },
+						{ ...topMatches[1], id: "v2", folder: { role: "flagged" } },
+						{
+							...topMatches[2],
+							id: "v3",
+							folder: { providerPath: "[Gmail]/Important" },
+						},
+						...crossFolderMatches.slice(0, 1),
+					],
+				},
 			]}
 		/>
 	),

package/src/components/search-results.tsx

@@ -1,8 +1,10 @@
 import { ChevronDown, Clock } from "lucide-react";
 import { useState } from "react";
 import { cn } from "../lib/cn.js";
+import type { FolderRole } from "./folder-role.js";
 import { type SearchResult, SearchResultRow } from "./search-result-row.js";
 import { SearchTokenChips } from "./search-token-chip.js";
+import { SpamResultsOffer } from "./spam-results-offer.js";
 
 /** Rows shown before the "Show N more" expander kicks in. */
 const SECTION_ROW_CAP = 6;
@@ -15,6 +17,44 @@ export interface SearchResultSection {
 	initialCollapsed?: boolean;
 }
 
+/**
+ * What the search currently covers. `global` is the unscoped search the daily
+ * brief runs — every account, every folder, no chip in the bar. `folder` is a
+ * search the sidebar narrowed to one place, which the bar shows as a chip.
+ */
+export type SearchScope =
+	| { kind: "global" }
+	| { kind: "folder"; role?: FolderRole };
+
+const GLOBAL_SCOPE: SearchScope = { kind: "global" };
+
+const isSpamScope = (scope: SearchScope): boolean =>
+	scope.kind === "folder" && scope.role === "junk";
+
+const isSpamResult = (result: SearchResult): boolean =>
+	result.folder?.role === "junk";
+
+/**
+ * Split spam matches out of the rows a search returned.
+ *
+ * Spam is identified by the account's `\Junk` special-use appointment, never by
+ * folder name, so an account that calls it `Junk`, `Bulk Mail` or nothing at
+ * all behaves the same, and an account with no junk folder simply never yields
+ * a spam row.
+ */
+export function partitionSpamResults(results: SearchResult[]): {
+	kept: SearchResult[];
+	spam: SearchResult[];
+} {
+	const kept: SearchResult[] = [];
+	const spam: SearchResult[] = [];
+	for (const result of results) {
+		if (isSpamResult(result)) spam.push(result);
+		else kept.push(result);
+	}
+	return { kept, spam };
+}
+
 export interface SearchResultsProps {
 	/** The current query — narrows what's shown and bolds literal matches. */
 	value: string;
@@ -32,6 +72,19 @@ export interface SearchResultsProps {
 	 * query has no recognized tokens.
 	 */
 	tokens?: { label: string; onRemove: () => void }[];
+	/** What the search covers. Defaults to the unscoped, global search. */
+	scope?: SearchScope;
+	/**
+	 * Total spam matches the search found, for when the app knows more than the
+	 * rows on this page. Defaults to the number of spam rows held out of
+	 * {@link sections}.
+	 */
+	spamMatchCount?: number;
+	/**
+	 * Scope the search to Spam. Without it there is no offer, so an app that has
+	 * nowhere to navigate simply never makes one.
+	 */
+	onScopeToSpam?: () => void;
 }
 
 /**
@@ -44,10 +97,12 @@ function CollapsibleResultSection({
 	section,
 	query,
 	onSelectResult,
+	showFolder,
 }: {
 	section: SearchResultSection;
 	query?: string;
 	onSelectResult?: (result: SearchResult) => void;
+	showFolder?: boolean;
 }) {
 	const [collapsed, setCollapsed] = useState(section.initialCollapsed ?? false);
 	const [expanded, setExpanded] = useState(false);
@@ -87,6 +142,7 @@ function CollapsibleResultSection({
 							key={result.id}
 							result={result}
 							query={query}
+							showFolder={showFolder}
 							onClick={
 								onSelectResult ? () => onSelectResult(result) : undefined
 							}
@@ -115,6 +171,18 @@ function CollapsibleResultSection({
  * sections — one implementation so both tiers render identical rows. The caller
  * owns the surrounding chrome and scroll container (a `FilterSheet`, the
  * takeover header, or the list-pane body). Presentational and prop-driven.
+ *
+ * Spam is the one folder that does not inline, and it behaves differently by
+ * scope:
+ *
+ * - **Global** — spam rows are held out of the sections and offered instead, as
+ *   a count with a way into a Spam-scoped search.
+ * - **Scoped to anything else** — spam rows are held out and nothing is offered.
+ *   A scoped search shows its own scope and no more.
+ * - **Scoped to Spam** — ordinary rows, rendered normally, no offer.
+ *
+ * Provenance labels follow the same logic: only a global search names the
+ * folder each row came from, because a scoped one would repeat itself.
  */
 export function SearchResults({
 	value,
@@ -124,11 +192,11 @@ export function SearchResults({
 	loading,
 	onSelectResult,
 	tokens,
+	scope = GLOBAL_SCOPE,
+	spamMatchCount,
+	onScopeToSpam,
 }: SearchResultsProps) {
 	const hasQuery = value.trim().length > 0;
-	const hasResults = (sections ?? []).some(
-		(section) => section.results.length > 0,
-	);
 
 	if (!hasQuery) {
 		if (recentSearches && recentSearches.length > 0) {
@@ -181,10 +249,36 @@ export function SearchResults({
 		);
 	}
 
+	const spamScoped = isSpamScope(scope);
+	const isGlobal = scope.kind === "global";
+
+	const partitioned = (sections ?? []).map((section) => {
+		if (spamScoped) return { section, spam: [] as SearchResult[] };
+		const { kept, spam } = partitionSpamResults(section.results);
+		return { section: { ...section, results: kept }, spam };
+	});
+
+	const visibleSections = partitioned.map((entry) => entry.section);
+	const heldOutSpamCount = partitioned.reduce(
+		(total, entry) => total + entry.spam.length,
+		0,
+	);
+	const spamCount = spamMatchCount ?? heldOutSpamCount;
+	const spamOffer = isGlobal &&
+		spamCount > 0 &&
+		onScopeToSpam !== undefined && (
+			<SpamResultsOffer count={spamCount} onScopeToSpam={onScopeToSpam} />
+		);
+
+	const hasResults = visibleSections.some(
+		(section) => section.results.length > 0,
+	);
+
 	if (!hasResults) {
 		return (
 			<div className="flex flex-col">
 				{chips}
+				{spamOffer}
 				<div className="px-row-inset py-10 text-center">
 					<p className="text-sm font-medium text-fg">
 						No matches for &ldquo;{value}&rdquo;
@@ -200,13 +294,15 @@ export function SearchResults({
 	return (
 		<div className="flex flex-col">
 			{chips}
-			{sections
-				?.filter((section) => section.results.length > 0)
+			{spamOffer}
+			{visibleSections
+				.filter((section) => section.results.length > 0)
 				.map((section) => (
 					<CollapsibleResultSection
 						key={section.id}
 						section={section}
 						query={value}
+						showFolder={isGlobal}
 						onSelectResult={onSelectResult}
 					/>
 				))}

package/src/components/spam-results-offer.render.test.ts

@@ -0,0 +1,26 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { createElement } from "react";
+import { renderToString } from "react-dom/server";
+import { SpamResultsOffer } from "./spam-results-offer.js";
+
+const noop = () => {};
+
+describe("SpamResultsOffer", () => {
+	it("states the count and offers a way into Spam", () => {
+		const html = renderToString(
+			createElement(SpamResultsOffer, { count: 3, onScopeToSpam: noop }),
+		);
+		assert.match(html, />3</);
+		assert.match(html, /results from Spam/);
+		assert.match(html, /View them/);
+	});
+
+	it("reads in the singular for one match", () => {
+		const html = renderToString(
+			createElement(SpamResultsOffer, { count: 1, onScopeToSpam: noop }),
+		);
+		assert.match(html, /result from Spam/);
+		assert.doesNotMatch(html, /results from Spam/);
+	});
+});

package/src/components/spam-results-offer.stories.tsx

@@ -0,0 +1,41 @@
+import type { Decorator, Meta, StoryObj } from "@storybook/react";
+import { SpamResultsOffer } from "./spam-results-offer.js";
+
+/** Frames the offer at the width of the list pane it sits at the top of. */
+const listPaneFrame: Decorator = (Story) => (
+	<div
+		className="overflow-hidden rounded-lg border border-line bg-canvas"
+		style={{ width: 360 }}
+	>
+		<Story />
+	</div>
+);
+
+const meta: Meta<typeof SpamResultsOffer> = {
+	title: "Components/SpamResultsOffer",
+	component: SpamResultsOffer,
+	parameters: { layout: "centered" },
+	decorators: [listPaneFrame],
+};
+export default meta;
+
+type Story = StoryObj<typeof SpamResultsOffer>;
+
+/**
+ * Spam matches a global search held out of its results. Deliberately quiet —
+ * an offer, not a warning — and the action scopes the search to Spam rather
+ * than opening a view of its own.
+ */
+export const Default: Story = {
+	args: { count: 3, onScopeToSpam: () => {} },
+};
+
+/** One match reads in the singular. */
+export const SingleResult: Story = {
+	args: { count: 1, onScopeToSpam: () => {} },
+};
+
+/** Large counts stay on one line; the figure is tabular so it does not jitter. */
+export const ManyResults: Story = {
+	args: { count: 128, onScopeToSpam: () => {} },
+};

package/src/components/spam-results-offer.tsx

@@ -0,0 +1,52 @@
+import { Banner } from "./banner.js";
+import { Button } from "./button.js";
+
+export interface SpamResultsOfferProps {
+	/** How many matches the search found in Spam. */
+	count: number;
+	/**
+	 * Scope the search to Spam. This is a shortcut to the state reached by
+	 * navigating to Spam with the query carried over — the same scoped search,
+	 * with the same `in:spam` chip — not a separate result mode.
+	 */
+	onScopeToSpam: () => void;
+}
+
+const plural = (n: number): string => (n === 1 ? "result" : "results");
+
+/**
+ * Spam matches held out of a global search, offered rather than mixed in. Spam
+ * is the one folder a search that reaches everywhere does not inline, because
+ * the whole point of the folder is that its contents are unwanted until asked
+ * for. Taking the offer scopes the search to Spam.
+ *
+ * Quiet on purpose: this is an offer, not a warning. Presentational — the
+ * caller owns what "scope to spam" does.
+ */
+export function SpamResultsOffer({
+	count,
+	onScopeToSpam,
+}: SpamResultsOfferProps) {
+	return (
+		<Banner
+			tone="info"
+			variant="soft"
+			className="items-center justify-between gap-3 rounded-none border-b border-line"
+		>
+			<div className="flex items-center justify-between gap-3">
+				<p className="min-w-0 text-xs text-fg-muted">
+					<span className="font-semibold text-fg tabular-nums">{count}</span>{" "}
+					{`${plural(count)} from Spam`}
+				</p>
+				<Button
+					variant="ghost"
+					size="sm"
+					onClick={onScopeToSpam}
+					className="shrink-0 text-accent"
+				>
+					View them
+				</Button>
+			</div>
+		</Banner>
+	);
+}

package/src/index.ts

@@ -121,7 +121,10 @@ export {
 export {
 	canonicalRoleLabel,
 	type FolderRole,
+	isVirtualFolderRole,
+	provenanceFolderLabel,
 	providerLeaf,
+	type ResultFolder,
 	roleIcon,
 } from "./components/folder-role.js";
 export {
@@ -304,9 +307,11 @@ export {
 	type SearchResultTone,
 } from "./components/search-result-row.js";
 export {
+	partitionSpamResults,
 	type SearchResultSection,
 	SearchResults,
 	type SearchResultsProps,
+	type SearchScope,
 } from "./components/search-results.js";
 export {
 	SearchChipRow,
@@ -358,6 +363,10 @@ export {
 	SlidePanel,
 	type SlidePanelProps,
 } from "./components/slide-panel.js";
+export {
+	SpamResultsOffer,
+	type SpamResultsOfferProps,
+} from "./components/spam-results-offer.js";
 export {
 	commitPeek,
 	SwipeableRow,