@remit/web-client 0.0.16 → 0.0.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/web-client",
-  "version": "0.0.16",
+  "version": "0.0.18",
   "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/FlaggedList.tsx

@@ -1,28 +1,28 @@
 /**
  * FlaggedList — a FLAT, cross-account inbox of starred mail.
  *
- * Reads GET /threads with `starred=true`, which is served by the `byStarred`
- * index and returns every starred thread in the config across all non-muted
- * mailboxes, paged. Starredness is decided server-side from `hasStars`; the
- * client neither re-filters nor caps the set, so a starred thread outside the
- * newest inbox page still appears. Rendered as one continuous list (no category
+ * Reads the starred listing through `useStarredThreads` — GET /threads with
+ * `starred=true`, served by the `byStarred` index — which returns every starred
+ * thread in the config across all non-muted mailboxes, paged. `FlaggedPane`
+ * resolves the open thread from that same hook, so every row rendered here can
+ * be opened. Starredness is decided server-side from `hasStars`; the client
+ * neither re-filters nor caps the set, so a starred thread outside the newest
+ * inbox page still appears. Rendered as one continuous list (no category
  * sections). The shared `MailViewChrome` owns the `MailHeader` + filter
  * expando; the kit `MessageListPane` (flat, no `briefFilters`) owns the loading
  * / empty / error chrome and keyboard hints, with a consumer-supplied
  * `listBody` so the real rows render at every width.
  */
-import { unifiedThreadOperationsListAllThreadsQueryKey } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
-import { unifiedThreadOperationsListAllThreads } from "@remit/api-http-client/sdk.gen.ts";
 import {
 	ComfortableRow,
 	flaggedFilterConfig,
 	MessageListPane,
 	type ThreadRowData,
 } from "@remit/ui";
-import { useInfiniteQuery } from "@tanstack/react-query";
 import { useCallback, useMemo, useState } from "react";
 import { formatErrorMessage } from "@/components/ui/ErrorState";
 import { useIsDesktop } from "@/hooks/useMediaQuery";
+import { useStarredThreads } from "@/hooks/useStarredThreads";
 import {
 	matchesBriefSearch,
 	matchesSearchTokens,
@@ -72,7 +72,7 @@ export function FlaggedList({
 	}, []);
 
 	const {
-		data: threadsData,
+		threads,
 		isLoading,
 		isError,
 		error,
@@ -80,25 +80,7 @@ export function FlaggedList({
 		fetchNextPage,
 		hasNextPage,
 		isFetchingNextPage,
-	} = useInfiniteQuery({
-		queryKey: unifiedThreadOperationsListAllThreadsQueryKey({
-			query: { starred: true, order: "desc" },
-		}),
-		queryFn: async ({ pageParam }) => {
-			const { data } = await unifiedThreadOperationsListAllThreads({
-				query: {
-					starred: true,
-					order: "desc",
-					continuationToken: pageParam,
-				},
-				throwOnError: true,
-			});
-			return data;
-		},
-		initialPageParam: undefined as string | undefined,
-		getNextPageParam: (lastPage) => lastPage.continuationToken,
-		staleTime: 60_000,
-	});
+	} = useStarredThreads();
 
 	const { freeText: sq, tokens: queryTokens } = parseSearchTokens(
 		searchQuery.trim().toLowerCase(),
@@ -109,9 +91,7 @@ export function FlaggedList({
 		const predicates = Array.from(activeFilters)
 			.map((id) => FILTER_PREDICATES[id])
 			.filter((p): p is (t: ThreadRowData) => boolean => p != null);
-		return dedupeByThread(
-			(threadsData?.pages ?? []).flatMap((page) => page.items ?? []),
-		)
+		return dedupeByThread(threads)
 			.map(toThreadRowData)
 			.filter(
 				(t) =>
@@ -120,7 +100,7 @@ export function FlaggedList({
 					(!sq || matchesBriefSearch(t, sq)) &&
 					matchesSearchTokens(t, queryTokens),
 			);
-	}, [threadsData, selectedCategory, activeFilters, sq, queryTokens]);
+	}, [threads, selectedCategory, activeFilters, sq, queryTokens]);
 
 	const preset = useMemo(() => flaggedFilterConfig(), []);
 

package/src/components/mail/FlaggedPane.tsx

@@ -2,9 +2,14 @@
  * FlaggedPane — compound component for the Flagged virtual mailbox
  * (/mail/flagged route).
  *
- * Mirrors BriefPane: it reads the unified cross-account thread list to resolve
- * the open thread and owns the list / reading / phone slots. The list itself is
- * a FLAT inbox of starred mail (see `FlaggedList`), not the sectioned brief.
+ * Mirrors BriefPane in shape: it resolves the open thread and owns the list /
+ * reading / phone slots. The list itself is a FLAT inbox of starred mail (see
+ * `FlaggedList`), not the sectioned brief.
+ *
+ * The selection resolves from the starred listing, the same query that produced
+ * the rows. The unified listing is INBOX-scoped, so resolving against it left
+ * every starred thread filed elsewhere — Sent, an archive folder, anything past
+ * the inbox window — visible in the list but impossible to open (issue #70).
  *
  *   <FlaggedPane selectedMessageId={...}>
  *     <AppShellSlotted
@@ -15,10 +20,8 @@
  *
  * On phone, use `<FlaggedPane.Phone />` instead.
  */
-import { unifiedThreadOperationsListAllThreadsOptions } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
 import type { RemitImapThreadMessageResponse } from "@remit/api-http-client/types.gen.ts";
 import { ReadingPaneEmpty, useAppShellLayout } from "@remit/ui";
-import { useQuery } from "@tanstack/react-query";
 import { useNavigate } from "@tanstack/react-router";
 import {
 	createContext,
@@ -32,6 +35,7 @@ import { ConversationView } from "@/components/mail/ConversationView";
 import { FlaggedList } from "@/components/mail/FlaggedList";
 import { IntelligencePane } from "@/components/mail/IntelligencePane";
 import { MessageToolbar } from "@/components/mail/MessageToolbar";
+import { useStarredThreads } from "@/hooks/useStarredThreads";
 import { useMailContext } from "@/lib/mail-context";
 
 /* ------------------------------------------------------------------ */
@@ -68,15 +72,12 @@ function FlaggedPaneProvider({
 }: FlaggedPaneProps) {
 	const navigate = useNavigate();
 
-	const { data: threadsData } = useQuery({
-		...unifiedThreadOperationsListAllThreadsOptions(),
-		staleTime: 60_000,
-	});
+	const { threads } = useStarredThreads();
 
 	const selectedThread = useMemo(() => {
 		if (!selectedMessageId) return undefined;
-		return threadsData?.items.find((t) => t.messageId === selectedMessageId);
-	}, [threadsData, selectedMessageId]);
+		return threads.find((t) => t.messageId === selectedMessageId);
+	}, [threads, selectedMessageId]);
 
 	const handleSelectMessage = useCallback(
 		(id: string) => {

package/src/components/mail/MailListHeader.tsx

@@ -14,11 +14,13 @@
  * `SearchResults` sections under the shared `FilterSheet`. Consumers feed the
  * filter chrome and query-narrowed results; both tiers render identical rows.
  *
- * Results split into two sections: "Top matches" (literal/instant search) and
- * "Related" (semantic). The consumer dedupes them — a thread in both appears
- * only under "Top matches". Each loads independently; an empty section drops out
- * kit-side, so a "Related"-only result still shows when the literal search finds
- * nothing. The hamburger opens the nav drawer via the enclosing `AppShellSlotted`.
+ * Results split into two sections, one per engine: literal/instant and semantic.
+ * The consumer dedupes them — a thread in both appears only under the literal
+ * section — and names them, so a view whose engines reach different mail says so
+ * ("In Archive" / "Everywhere"). Each loads independently; an empty section
+ * 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`.
  */
 import {
 	FilterSheet,
@@ -30,7 +32,7 @@ import {
 	SearchResults,
 	useAppShellLayout,
 } from "@remit/ui";
-import { type ReactNode, useState } from "react";
+import { type ReactNode, useEffect, useRef, useState } from "react";
 import { isSinglePaneTier, useLayoutTier } from "@/hooks/useLayoutTier";
 import { useMailContext } from "@/lib/mail-context";
 import { loadRecentSearches, saveRecentSearch } from "@/lib/recent-searches";
@@ -56,6 +58,13 @@ interface MailListHeaderProps {
 	relatedResults?: SearchResult[];
 	relatedLoading?: boolean;
 	onSelectSearchResult?: (result: SearchResult) => void;
+	/**
+	 * Section headings. A view whose two engines cover different ground names
+	 * them by that ground ("In Archive" / "Everywhere") so the reach of a result
+	 * is on screen rather than inferred.
+	 */
+	searchResultsLabel?: string;
+	relatedResultsLabel?: string;
 }
 
 export function MailListHeader({
@@ -69,11 +78,14 @@ export function MailListHeader({
 	relatedResults,
 	relatedLoading,
 	onSelectSearchResult,
+	searchResultsLabel = "Top matches",
+	relatedResultsLabel = "Related",
 }: MailListHeaderProps) {
 	const {
 		searchInput,
 		onSearchChange,
 		onSearchClear,
+		searchViewKey,
 		mailboxNameIndex,
 		accountNameIndex,
 	} = useMailContext();
@@ -82,6 +94,16 @@ export function MailListHeader({
 	const [searchOpen, setSearchOpen] = useState(false);
 	const [recentSearches, setRecentSearches] = useState(loadRecentSearches);
 
+	// Leaving the view ends the search: the shell drops the query, and the chrome
+	// it opened — the phone takeover, the expanded tablet field — closes with it
+	// rather than sitting there empty over the new mailbox (#47).
+	const searchViewRef = useRef(searchViewKey);
+	useEffect(() => {
+		if (searchViewRef.current === searchViewKey) return;
+		searchViewRef.current = searchViewKey;
+		setSearchOpen(false);
+	}, [searchViewKey]);
+
 	const hasQuery = searchInput.trim().length > 0;
 	// Filter tokens (`from:`, `has:attachment`, `in:`, `account:`, …) parsed live
 	// from the typed query render as removable chips above the sections;
@@ -102,8 +124,8 @@ export function MailListHeader({
 	// state. The empty-query case (recent searches) is the kit's job.
 	const sections: SearchResultSection[] = hasQuery
 		? [
-				{ id: "top", label: "Top matches", results: topMatches },
-				{ id: "related", label: "Related", results: related },
+				{ id: "top", label: searchResultsLabel, results: topMatches },
+				{ id: "related", label: relatedResultsLabel, results: related },
 			]
 		: [];
 	// Skeleton only while nothing is in yet — once either section has rows, show

package/src/components/mail/MailViewChrome.tsx

@@ -41,6 +41,9 @@ interface MailViewChromeProps {
 	relatedResults?: SearchResult[];
 	relatedLoading?: boolean;
 	onSelectSearchResult?: (result: SearchResult) => void;
+	/** Section headings; see `MailListHeader`. */
+	searchResultsLabel?: string;
+	relatedResultsLabel?: string;
 }
 
 export function MailViewChrome({
@@ -60,6 +63,8 @@ export function MailViewChrome({
 	relatedResults,
 	relatedLoading,
 	onSelectSearchResult,
+	searchResultsLabel,
+	relatedResultsLabel,
 }: MailViewChromeProps) {
 	const [expanded, setExpanded] = useState(false);
 
@@ -88,6 +93,8 @@ export function MailViewChrome({
 			relatedResults={relatedResults}
 			relatedLoading={relatedLoading}
 			onSelectSearchResult={onSelectSearchResult}
+			searchResultsLabel={searchResultsLabel}
+			relatedResultsLabel={relatedResultsLabel}
 		>
 			<FilterSheet {...filterConfig}>{children}</FilterSheet>
 		</MailListHeader>

package/src/components/mail/MailboxPane.tsx

@@ -949,10 +949,13 @@ function MailboxList() {
 		() => threads.map(threadToSearchResult),
 		[threads],
 	);
-	// "Related" (semantic) is scoped to this mailbox and deduped against the
-	// literal "Top matches" by thread, so a thread never shows in both.
+	// The field above every pane says "Search all mail", and it means it (#47).
+	// The literal engine only searches one mailbox at a time (there is no
+	// cross-mailbox thread search), so this view names that section after the
+	// mailbox and lets the semantic engine run unscoped — the "Everywhere"
+	// section reaches the rest of the mail. Results are deduped by thread, so a
+	// thread never shows in both.
 	const { hits: semanticHits, isLoading: relatedLoading } = useSemanticSearch({
-		mailboxId,
 		filterCategory,
 	});
 	const relatedResults = useMemo(
@@ -967,7 +970,10 @@ function MailboxList() {
 		(result: SearchResult) =>
 			navigate({
 				to: "/mail/$mailboxId",
-				params: { mailboxId },
+				// A hit from the unscoped "Everywhere" section lives in another
+				// mailbox; open it there, so the list, the toolbar's verbs and the
+				// message all belong to the same mailbox.
+				params: { mailboxId: result.mailboxId ?? mailboxId },
 				search: (prev: Record<string, unknown>) => ({
 					...prev,
 					// Commit the active query alongside the selection. The debounced
@@ -1061,6 +1067,8 @@ function MailboxList() {
 			relatedResults={relatedResults}
 			relatedLoading={relatedLoading}
 			onSelectSearchResult={handleSelectSearchResult}
+			searchResultsLabel={`In ${listTitle}`}
+			relatedResultsLabel="Everywhere"
 		>
 			{body}
 		</MailViewChrome>

package/src/hooks/useStarredThreads.test.ts

@@ -0,0 +1,143 @@
+/**
+ * useStarredThreads — regression cover for issue #70.
+ *
+ * The Starred pane rendered its rows from `GET /threads?starred=true` but
+ * resolved the open thread from the unfiltered (INBOX-scoped) listing. Rows for
+ * starred mail filed outside INBOX therefore had nothing to resolve to and
+ * opened no reading pane.
+ *
+ * Strategy follows useRescueCandidates.test.ts: pre-seed a QueryClient under the
+ * key the hook generates and render it synchronously, so the queryFn never
+ * fires. The last two cases are the ones that fail if the wrong listing comes
+ * back — the unfiltered key is seeded alongside and must not be read.
+ */
+
+import assert from "node:assert/strict";
+import { describe, test } from "node:test";
+import { unifiedThreadOperationsListAllThreadsQueryKey } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import type { RemitImapThreadMessageResponse } from "@remit/api-http-client/types.gen.ts";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { createElement } from "react";
+import { renderToString } from "react-dom/server";
+import {
+	starredThreadsQueryKey,
+	useStarredThreads,
+} from "./useStarredThreads.js";
+
+interface Page {
+	items: RemitImapThreadMessageResponse[];
+	continuationToken?: string;
+}
+
+function makeThread(
+	messageId: string,
+	overrides: Partial<RemitImapThreadMessageResponse> = {},
+): RemitImapThreadMessageResponse {
+	return {
+		messageId,
+		threadMessageId: `tm-${messageId}`,
+		threadId: `t-${messageId}`,
+		accountConfigId: "acc",
+		mailboxId: "mb-inbox",
+		sentDate: 1_000_000,
+		isRead: false,
+		hasAttachment: false,
+		hasStars: true,
+		isDeleted: false,
+		createdAt: 1_000_000,
+		updatedAt: 1_000_000,
+		fromName: "Anna de Vries",
+		fromEmail: "anna@example.nl",
+		subject: `subject ${messageId}`,
+		snippet: "…",
+		senderTrust: "vip",
+		...overrides,
+	} as RemitImapThreadMessageResponse;
+}
+
+/**
+ * Renders the hook against a cache holding `starredPages` under the starred key
+ * and `unfilteredItems` under the unfiltered one, so a hook reading the wrong
+ * listing returns the wrong threads instead of returning nothing.
+ */
+function renderHook(
+	starredPages: Page[],
+	unfilteredItems: RemitImapThreadMessageResponse[] = [],
+): RemitImapThreadMessageResponse[] {
+	const client = new QueryClient({
+		defaultOptions: { queries: { retry: false } },
+	});
+	client.setQueryData(starredThreadsQueryKey(), {
+		pages: starredPages,
+		pageParams: starredPages.map((_, index) =>
+			index === 0 ? undefined : `page-${index}`,
+		),
+	});
+	client.setQueryData(unifiedThreadOperationsListAllThreadsQueryKey(), {
+		items: unfilteredItems,
+	});
+
+	let captured: RemitImapThreadMessageResponse[] = [];
+
+	function Capture() {
+		captured = useStarredThreads().threads;
+		return null;
+	}
+
+	renderToString(
+		createElement(
+			QueryClientProvider,
+			{ client },
+			createElement(Capture),
+		) as never,
+	);
+
+	return captured;
+}
+
+describe("starredThreadsQueryKey", () => {
+	test("asks for the starred listing, newest first", () => {
+		const [params] = starredThreadsQueryKey() as [
+			{ query?: { starred?: boolean; order?: string } },
+		];
+		assert.equal(params.query?.starred, true);
+		assert.equal(params.query?.order, "desc");
+	});
+});
+
+describe("useStarredThreads", () => {
+	test("returns no threads when the listing is empty", () => {
+		assert.deepEqual(renderHook([{ items: [] }]), []);
+	});
+
+	test("flattens every loaded page, in page order", () => {
+		const threads = renderHook([
+			{ items: [makeThread("m1"), makeThread("m2")], continuationToken: "p2" },
+			{ items: [makeThread("m3")] },
+		]);
+		assert.deepEqual(
+			threads.map((thread) => thread.messageId),
+			["m1", "m2", "m3"],
+		);
+	});
+
+	test("returns a starred thread that lives outside INBOX", () => {
+		// The case issue #70 could not open: starred, filed in Sent, and absent
+		// from the unfiltered listing the pane used to resolve against.
+		const sent = makeThread("m-sent", { mailboxId: "mb-sent" });
+		const threads = renderHook([{ items: [sent] }], [makeThread("m-inbox")]);
+		assert.deepEqual(
+			threads.map((thread) => thread.messageId),
+			["m-sent"],
+		);
+		assert.equal(
+			threads.find((thread) => thread.messageId === "m-sent")?.mailboxId,
+			"mb-sent",
+		);
+	});
+
+	test("does not read the unfiltered INBOX listing", () => {
+		const threads = renderHook([{ items: [] }], [makeThread("m-inbox")]);
+		assert.deepEqual(threads, []);
+	});
+});

package/src/hooks/useStarredThreads.ts

@@ -0,0 +1,78 @@
+/**
+ * The starred listing — `GET /threads?starred=true`, served by the `byStarred`
+ * index — as one hook, so the Starred pane's list and its selection resolve
+ * from the same query.
+ *
+ * The two are the same cache entry, not two requests: they share a query key,
+ * so `threads` here is exactly the set of rows the list rendered. Resolving a
+ * selection from any other listing reintroduces issue #70 — the INBOX-scoped
+ * unified listing cannot see a starred thread filed elsewhere, so its row is
+ * clickable but resolves to nothing and no reading pane opens.
+ */
+import { unifiedThreadOperationsListAllThreadsQueryKey } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import { unifiedThreadOperationsListAllThreads } from "@remit/api-http-client/sdk.gen.ts";
+import type { RemitImapThreadMessageResponse } from "@remit/api-http-client/types.gen.ts";
+import { useInfiniteQuery } from "@tanstack/react-query";
+import { useMemo } from "react";
+
+export const starredThreadsQueryKey = () =>
+	unifiedThreadOperationsListAllThreadsQueryKey({
+		query: { starred: true, order: "desc" },
+	});
+
+interface StarredThreads {
+	/** Every starred thread across the pages loaded so far, newest first. */
+	threads: RemitImapThreadMessageResponse[];
+	isLoading: boolean;
+	isError: boolean;
+	error: unknown;
+	refetch: () => void;
+	fetchNextPage: () => void;
+	hasNextPage: boolean;
+	isFetchingNextPage: boolean;
+}
+
+export function useStarredThreads(): StarredThreads {
+	const {
+		data,
+		isLoading,
+		isError,
+		error,
+		refetch,
+		fetchNextPage,
+		hasNextPage,
+		isFetchingNextPage,
+	} = useInfiniteQuery({
+		queryKey: starredThreadsQueryKey(),
+		queryFn: async ({ pageParam }) => {
+			const { data: page } = await unifiedThreadOperationsListAllThreads({
+				query: {
+					starred: true,
+					order: "desc",
+					continuationToken: pageParam,
+				},
+				throwOnError: true,
+			});
+			return page;
+		},
+		initialPageParam: undefined as string | undefined,
+		getNextPageParam: (lastPage) => lastPage.continuationToken,
+		staleTime: 60_000,
+	});
+
+	const threads = useMemo(
+		() => (data?.pages ?? []).flatMap((page) => page.items ?? []),
+		[data],
+	);
+
+	return {
+		threads,
+		isLoading,
+		isError,
+		error,
+		refetch,
+		fetchNextPage,
+		hasNextPage,
+		isFetchingNextPage,
+	};
+}

package/src/lib/mail-context.ts

@@ -23,8 +23,14 @@ export interface MailContextValue {
 	mailboxNameIndex: ReadonlyMap<string, string>;
 	accountNameIndex: ReadonlyMap<string, string>;
 	searchQuery: string;
-	/** Live (pre-debounce) search input — the toolbar's search field binds this. */
+	/** Live (pre-debounce) search input — the search field binds this. */
 	searchInput: string;
+	/**
+	 * Identity of the view the current search belongs to (`lib/mail-route.ts`).
+	 * It changes when the user leaves that view, which is when search ends: the
+	 * query re-seeds from the new URL and any search chrome collapses (#47).
+	 */
+	searchViewKey: string;
 	onSearchChange: (query: string) => void;
 	/** Full clear (X button): drops the query and any selected thread (#538). */
 	onSearchClear: () => void;
@@ -53,6 +59,7 @@ export const useMailContext = (): MailContextValue => {
 			accountNameIndex: new Map(),
 			searchQuery: "",
 			searchInput: "",
+			searchViewKey: "",
 			onSearchChange: () => {},
 			onSearchClear: () => {},
 			onSearchClearQuery: () => {},

package/src/lib/mail-route.ts

@@ -15,6 +15,7 @@
 /** A matched route, minimal shape needed for pane detection. */
 export interface MailRouteMatch {
 	routeId: string;
+	params?: Record<string, string | undefined>;
 }
 
 /** The leaf route ids the /mail shell branches on. */
@@ -42,3 +43,19 @@ export function isOutboxRoute(matches: readonly MailRouteMatch[]): boolean {
 export function isMailboxRoute(matches: readonly MailRouteMatch[]): boolean {
 	return matches.some((m) => m.routeId === MAIL_MAILBOX_ROUTE_ID);
 }
+
+/**
+ * Identity of the list view the shell is showing — one mailbox, the brief, the
+ * flagged list, or the outbox. Two locations share a key when they differ only
+ * in search params (opening a result, mirroring `q`), so opening a hit is not a
+ * view change while switching mailbox is. `lib/search-view.ts` re-seeds the
+ * search field whenever this changes.
+ */
+export function mailViewKey(matches: readonly MailRouteMatch[]): string {
+	const mailboxId = matches.find((m) => m.params?.mailboxId)?.params?.mailboxId;
+	if (mailboxId) return `${MAIL_MAILBOX_ROUTE_ID}:${mailboxId}`;
+	if (isFlaggedRoute(matches)) return MAIL_FLAGGED_ROUTE_ID;
+	if (isOutboxRoute(matches)) return MAIL_OUTBOX_ROUTE_ID;
+	if (isBriefRoute(matches)) return MAIL_BRIEF_ROUTE_ID;
+	return "";
+}

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

@@ -0,0 +1,111 @@
+/**
+ * Regression (#47): the search query must not survive a move to another
+ * mailbox. The /mail shell holds the field state and never unmounts between
+ * child routes, so without these rules the text — and the query it drives —
+ * followed the user from inbox to inbox.
+ */
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { type MailRouteMatch, mailViewKey } from "./mail-route.js";
+import {
+	committedSearchQuery,
+	searchInputForView,
+	shouldMirrorQuery,
+} from "./search-view.js";
+
+const matches = (routeId: string, mailboxId?: string): MailRouteMatch[] => [
+	{ routeId: "__root__" },
+	{ routeId: "/mail" },
+	{ routeId, ...(mailboxId ? { params: { mailboxId } } : {}) },
+];
+
+describe("mailViewKey", () => {
+	it("distinguishes two mailboxes", () => {
+		assert.notEqual(
+			mailViewKey(matches("/mail/$mailboxId", "inbox-1")),
+			mailViewKey(matches("/mail/$mailboxId", "archive-1")),
+		);
+	});
+
+	it("gives the same mailbox one key regardless of search params", () => {
+		assert.equal(
+			mailViewKey(matches("/mail/$mailboxId", "inbox-1")),
+			mailViewKey(matches("/mail/$mailboxId", "inbox-1")),
+		);
+	});
+
+	it("separates the brief, flagged and outbox views", () => {
+		const keys = [
+			mailViewKey(matches("/mail/")),
+			mailViewKey(matches("/mail/flagged")),
+			mailViewKey(matches("/mail/outbox")),
+		];
+		assert.equal(new Set(keys).size, 3);
+	});
+});
+
+describe("searchInputForView", () => {
+	it("clears the field when the destination carries no query", () => {
+		assert.equal(
+			searchInputForView(
+				"/mail/$mailboxId:inbox-1",
+				"/mail/$mailboxId:arch",
+				"",
+			),
+			"",
+		);
+	});
+
+	it("leaves the field alone while the view stays the same", () => {
+		// Opening a result and the q-mirror both re-render on the same view; the
+		// user's in-flight typing must survive both.
+		assert.equal(
+			searchInputForView(
+				"/mail/$mailboxId:inbox-1",
+				"/mail/$mailboxId:inbox-1",
+				"",
+			),
+			undefined,
+		);
+	});
+
+	it("seeds from the destination's own query (deep link, saved search)", () => {
+		assert.equal(
+			searchInputForView("/mail/$mailboxId:inbox-1", "/mail/", "invoice"),
+			"invoice",
+		);
+	});
+});
+
+describe("committedSearchQuery", () => {
+	it("commits an empty field immediately, without waiting on the debounce", () => {
+		assert.equal(committedSearchQuery("", "stale query"), "");
+	});
+
+	it("debounces everything else", () => {
+		assert.equal(committedSearchQuery("inv", ""), "");
+		assert.equal(committedSearchQuery("invoice", "inv"), "inv");
+	});
+});
+
+describe("shouldMirrorQuery", () => {
+	it("writes a settled query the URL does not have yet", () => {
+		assert.equal(shouldMirrorQuery("invoice", "invoice", ""), true);
+	});
+
+	it("stays quiet once the URL already says it", () => {
+		assert.equal(shouldMirrorQuery("invoice", "invoice", "invoice"), false);
+	});
+
+	it("does not strip the query a deep link just arrived with", () => {
+		// The field is seeded from the URL and the debounce has not caught up, so
+		// the committed query is still the previous view's. Writing it would drop
+		// `q` for the length of the debounce — and with it the search the link
+		// asked for.
+		assert.equal(shouldMirrorQuery("invoice", "", "invoice"), false);
+	});
+
+	it("waits for the debounce while the user is still typing", () => {
+		assert.equal(shouldMirrorQuery("invoi", "inv", ""), false);
+	});
+});

package/src/lib/search-view.ts

@@ -0,0 +1,54 @@
+/**
+ * Search is a view-level mode, not a persistent global filter (#47).
+ *
+ * The query belongs to the location it was typed in: the URL's `q` is what a
+ * view is searching for, and the nav links already drop `q` when they switch
+ * mailbox. The search field, however, is local state in the /mail shell — which
+ * outlives every child route — so it kept the old text and went on querying the
+ * new mailbox with it (the confusing Mac Mail behaviour). These rules make the
+ * URL win on every view change: the field re-seeds from the location it lands
+ * on, so switching mailbox clears a stale query while a deep link or a saved
+ * search that carries `q` still arrives with the query intact.
+ */
+
+/**
+ * The field text after a view transition, or `undefined` when nothing changes
+ * (same view — typing, opening a result, mirroring `q` back to the URL).
+ */
+export function searchInputForView(
+	previousViewKey: string,
+	viewKey: string,
+	urlQuery: string,
+): string | undefined {
+	if (previousViewKey === viewKey) return undefined;
+	return urlQuery;
+}
+
+/**
+ * The committed query the search APIs run. Typing debounces, but an empty field
+ * commits immediately — otherwise a view change fires one more request for the
+ * query the user just left behind.
+ */
+export function committedSearchQuery(
+	searchInput: string,
+	debouncedSearchInput: string,
+): string {
+	return searchInput === "" ? "" : debouncedSearchInput;
+}
+
+/**
+ * Whether the committed query may be written back to the URL. Only a settled
+ * one may: mid-debounce the committed value is the *previous* query, and
+ * writing it would overwrite the URL that a deep link or a saved search just
+ * arrived with — stripping `q` for as long as the debounce lasts, and taking
+ * the search with it. The mirror waits for the field and the committed query to
+ * agree, then writes only if the URL says something else.
+ */
+export function shouldMirrorQuery(
+	searchInput: string,
+	committedQuery: string,
+	urlQuery: string,
+): boolean {
+	if (committedQuery !== searchInput) return false;
+	return committedQuery !== urlQuery;
+}

package/src/routes/mail.tsx

@@ -30,8 +30,18 @@ import { useMailboxNameIndex } from "@/hooks/useMailboxNameIndex";
 import { useStaleAccountSync } from "@/hooks/useStaleAccountSync";
 import { writeIntelligencePref } from "@/lib/intelligence-pref";
 import { MailContext } from "@/lib/mail-context";
-import { isBriefRoute, isFlaggedRoute, isOutboxRoute } from "@/lib/mail-route";
+import {
+	isBriefRoute,
+	isFlaggedRoute,
+	isOutboxRoute,
+	mailViewKey,
+} from "@/lib/mail-route";
 import { buildAccountNameIndex } from "@/lib/search-token-index";
+import {
+	committedSearchQuery,
+	searchInputForView,
+	shouldMirrorQuery,
+} from "@/lib/search-view";
 import "@/lib/client";
 
 // `MailContext` / `useMailContext` live in `@/lib/mail-context` so the provider
@@ -86,19 +96,25 @@ function MailLayout() {
 		writeIntelligencePref(open);
 	}, []);
 
-	// URL `q` is a load-once seed for the input and a one-directional write
-	// target. The debounced local value is the source of truth and drives the
-	// search API; it is mirrored back to the URL but the URL is never read into
-	// state after mount.
+	// Within one view, URL `q` seeds the input and is a one-directional write
+	// target: the debounced local value drives the search API and is mirrored
+	// back. Across views the URL wins again — see the view-change effect below
+	// and `lib/search-view.ts` (#47).
 	const [searchInput, setSearchInput] = useState(searchQuery);
 	const debouncedSearchInput = useDebouncedValue(searchInput, 200);
+	const committedQuery = committedSearchQuery(
+		searchInput,
+		debouncedSearchInput,
+	);
 
 	const searchQueryRef = useRef(searchQuery);
 	searchQueryRef.current = searchQuery;
 
-	// Mirror the debounced search into the URL so links are shareable and a
-	// refresh restores the query. One-directional: the URL is never read back
-	// into state, so there is no sync loop.
+	// Mirror the settled search into the URL so links are shareable and a
+	// refresh restores the query. Within a view this is one-directional — the
+	// URL is not read back into state, so there is no sync loop — and it writes
+	// only once the debounce agrees with the field, so a query arriving by URL
+	// is never overwritten mid-debounce (`shouldMirrorQuery`).
 	// When a query *goes* active, also strip selectedMessageId so the reading
 	// pane closes (#539): an open message from the pre-search list is not
 	// meaningful in the search result set. Only strip on that transition though —
@@ -108,16 +124,17 @@ function MailLayout() {
 	// the row shows before the debounce settles, so this mirror can land just
 	// after the open and close it again.
 	useEffect(() => {
-		if (debouncedSearchInput === searchQueryRef.current) return;
+		if (!shouldMirrorQuery(searchInput, committedQuery, searchQueryRef.current))
+			return;
 		navigate({
 			to: ".",
 			search: (prev) => {
 				const queryAlreadyActive =
-					(prev as { q?: string }).q === debouncedSearchInput;
+					(prev as { q?: string }).q === committedQuery;
 				return {
 					...prev,
-					q: debouncedSearchInput || undefined,
-					...(debouncedSearchInput && !queryAlreadyActive
+					q: committedQuery || undefined,
+					...(committedQuery && !queryAlreadyActive
 						? {
 								selectedMessageId: undefined,
 								selectedThreadId: undefined,
@@ -128,7 +145,25 @@ function MailLayout() {
 			},
 			replace: true,
 		});
-	}, [debouncedSearchInput, navigate]);
+	}, [searchInput, committedQuery, navigate]);
+
+	// Search is a mode of the view it was typed in, so leaving that view re-seeds
+	// the field from wherever we land. The nav links already drop `q` when they
+	// switch mailbox, so this clears the query instead of silently re-running it
+	// against the new mailbox (#47), while a deep link or a saved search that
+	// carries `q` still arrives searching.
+	const viewKey = useRouterState({ select: (s) => mailViewKey(s.matches) });
+	const viewKeyRef = useRef(viewKey);
+	useEffect(() => {
+		const next = searchInputForView(
+			viewKeyRef.current,
+			viewKey,
+			searchQueryRef.current,
+		);
+		viewKeyRef.current = viewKey;
+		if (next === undefined) return;
+		setSearchInput(next);
+	}, [viewKey]);
 
 	const {
 		data: config,
@@ -250,10 +285,11 @@ function MailLayout() {
 		accounts,
 		mailboxNameIndex,
 		accountNameIndex,
-		// Debounced local value is the source of truth for search; it is
-		// mirrored to the URL one-directionally for shareable links.
-		searchQuery: debouncedSearchInput,
+		// The committed local value is the source of truth for search; it is
+		// mirrored to the URL for shareable links.
+		searchQuery: committedQuery,
 		searchInput,
+		searchViewKey: viewKey,
 		onSearchChange: handleSearchChange,
 		onSearchClear: handleSearchClear,
 		onSearchClearQuery: handleSearchClearQuery,