@remit/web-client 0.0.179 → 0.0.180

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/web-client",
-  "version": "0.0.179",
+  "version": "0.0.180",
   "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/hooks/search-mirror-convergence.render.test.ts

@@ -0,0 +1,197 @@
+/**
+ * The mirror corrects an address that has drifted from the settled query
+ * (#808).
+ *
+ * Typing lands more than one navigation: the debounce settles mid-word, the
+ * mirror writes that prefix, and the word is finished while that write is still
+ * in flight. The two can commit out of order, and an e2e run caught the result
+ * — the field holding `invoice`, the address holding `q=invo`, and neither
+ * moving again for the remaining two minutes of the test. The mirror compared
+ * against the URL without re-running on it, so a disagreement it had not caused
+ * was permanent.
+ *
+ * Driven through a real router, because the state under test is one only the
+ * router can produce: the address is moved out from under a mirror that has
+ * already settled, with the field and the committed query left where they were.
+ * The re-render is provoked rather than awaited — this harness does not
+ * propagate a router store change into React on its own, where the running app
+ * renders on every `q` — so what each case actually asks is whether the mirror
+ * reconsiders once it renders again.
+ */
+
+import assert from "node:assert/strict";
+import { afterEach, describe, it } from "node:test";
+import {
+	type AnyRouter,
+	createMemoryHistory,
+	createRootRoute,
+	createRoute,
+	createRouter,
+	Outlet,
+	RouterProvider,
+} from "@tanstack/react-router";
+import { createElement, useState } from "react";
+import { MailContext, type MailContextValue } from "@/lib/mail-context";
+import { EMPTY_RESULT_FOLDER_INDEX } from "@/lib/result-folder";
+import { createDomHarness, type DomHarness } from "../test-support/dom";
+import { useSearchMirror } from "./useSearchMirror";
+
+let harness: DomHarness | undefined;
+
+afterEach(() => {
+	harness?.close();
+	harness = undefined;
+});
+
+// The router reads `self` at construction; the shared jsdom globals stop at
+// `window`.
+(globalThis as { self?: typeof globalThis }).self ??= globalThis;
+
+const LIST_PATH = "/mail/brief";
+const RENDER_AGAIN = "render again";
+
+const mailContext = (input: string, committed: string): MailContextValue => ({
+	accounts: [],
+	mailboxNameIndex: new Map(),
+	accountNameIndex: new Map(),
+	resultFolderIndex: EMPTY_RESULT_FOLDER_INDEX,
+	searchQuery: committed,
+	searchInput: input,
+	searchViewKey: LIST_PATH,
+	onSearchChange: () => {},
+	onSearchClear: () => {},
+	onSearchClearQuery: () => {},
+	intelligenceOpen: false,
+	onToggleIntelligence: () => {},
+});
+
+/**
+ * The brief on its own. Where a correcting write lands, and what it may close
+ * under it, is `search-mirror-detail.render.test.ts`'s question; this file asks
+ * only whether the address ends up saying the settled query.
+ */
+const buildRouter = (href: string): AnyRouter => {
+	const passthrough = (search: Record<string, unknown>) => search;
+	const rootRoute = createRootRoute({ component: Outlet });
+	const mailRoute = createRoute({
+		getParentRoute: () => rootRoute,
+		path: "/mail",
+		validateSearch: passthrough,
+		component: Outlet,
+	});
+	const briefRoute = createRoute({
+		getParentRoute: () => mailRoute,
+		path: "/brief",
+		validateSearch: passthrough,
+		component: function BriefLayout() {
+			const [renders, setRenders] = useState(0);
+			useSearchMirror({ to: LIST_PATH });
+			return createElement(
+				"div",
+				null,
+				createElement(
+					"button",
+					{
+						type: "button",
+						"aria-label": RENDER_AGAIN,
+						onClick: () => setRenders(renders + 1),
+					},
+					String(renders),
+				),
+				createElement(Outlet),
+			);
+		},
+	});
+	const routeTree = rootRoute.addChildren([
+		mailRoute.addChildren([briefRoute]),
+	]);
+	return createRouter({
+		routeTree,
+		history: createMemoryHistory({ initialEntries: [href] }),
+	}) as unknown as AnyRouter;
+};
+
+const mount = async (
+	router: AnyRouter,
+	input: string,
+	committed: string,
+): Promise<DomHarness> => {
+	const created = createDomHarness();
+	harness = created;
+	await router.load();
+	created.renderApp(
+		createElement(
+			MailContext.Provider,
+			{ value: mailContext(input, committed) },
+			createElement(RouterProvider, { router }),
+		),
+	);
+	await created.flush();
+	await created.wait(20);
+	return created;
+};
+
+/**
+ * The write that was still in flight, landing after the one that followed it,
+ * and then the next render of the list it landed under.
+ */
+const driftTo = async (
+	created: DomHarness,
+	router: AnyRouter,
+	q: string | undefined,
+): Promise<void> => {
+	void router.navigate({ to: ".", search: { q }, replace: true });
+	await created.wait(20);
+	created.click(created.byLabel(RENDER_AGAIN));
+	await created.wait(50);
+};
+
+describe("an address that drifts from the settled query", () => {
+	it("is written again, rather than left on the prefix", async () => {
+		const router = buildRouter(`${LIST_PATH}?q=invoice`);
+		const created = await mount(router, "invoice", "invoice");
+		assert.match(router.history.location.search, /q=invoice/);
+
+		await driftTo(created, router, "invo");
+
+		assert.match(
+			router.history.location.search,
+			/q=invoice/,
+			"the mirror never reconsidered the address it had already agreed with",
+		);
+		assert.equal(router.history.location.pathname, LIST_PATH);
+	});
+
+	it("is written again when the query was dropped from it entirely", async () => {
+		const router = buildRouter(`${LIST_PATH}?q=invoice`);
+		const created = await mount(router, "invoice", "invoice");
+
+		await driftTo(created, router, undefined);
+
+		assert.match(router.history.location.search, /q=invoice/);
+	});
+
+	it("leaves an address that already says the settled query alone", async () => {
+		const router = buildRouter(`${LIST_PATH}?q=invoice`);
+		const created = await mount(router, "invoice", "invoice");
+		const before = router.history.length;
+
+		await driftTo(created, router, "invoice");
+
+		assert.match(router.history.location.search, /q=invoice/);
+		assert.equal(router.history.length, before);
+	});
+
+	it("does not fight a query arriving mid-debounce", async () => {
+		// A deep link or a saved search lands while the field is still catching
+		// up. The committed query is the previous one, so the mirror has nothing
+		// settled to write and must not strip what just arrived.
+		const router = buildRouter(`${LIST_PATH}?q=receipts`);
+		const created = await mount(router, "invoice", "");
+
+		created.click(created.byLabel(RENDER_AGAIN));
+		await created.wait(50);
+
+		assert.match(router.history.location.search, /q=receipts/);
+	});
+});

package/src/hooks/search-mirror-detail.render.test.ts

@@ -197,8 +197,9 @@ for (const listPath of LIST_PATHS) {
  * re-seeds on a view change, so the view key of the list and of the thread route
  * under it must be equal.
  *
- * Read off the matches the router resolved for a real address, so the ids under
- * test are the ones path segments produce rather than ids written out here.
+ * Read off the address the router committed for a real navigation, so the keys
+ * under test are the ones path segments produce rather than ids written out
+ * here.
  */
 describe("the view key of an open thread", () => {
 	const viewKeyAt = async (
@@ -207,11 +208,7 @@ describe("the view key of an open thread", () => {
 	): Promise<string> => {
 		const router = routerAt(listPath, href);
 		await router.load();
-		return mailViewKey(
-			router.state.matches.map((match: { routeId: string }) => ({
-				routeId: match.routeId,
-			})),
-		);
+		return mailViewKey(router.state.location.pathname);
 	};
 
 	for (const listPath of LIST_PATHS) {

package/src/hooks/useSearchField.render.test.ts

@@ -0,0 +1,216 @@
+/**
+ * A query typed as the reader arrives on a list (#808).
+ *
+ * Three e2e specs hung their whole timeout on `waitForURL(/q=invoice/)` because
+ * the query never reached the address at all. Typing in the window between the
+ * router committing the next mailbox and React rendering it put the keystroke
+ * and the view change in one render, where the view-change re-seed took the
+ * field back to the destination's `q` — empty. The field held nothing, so the
+ * mirror had nothing to write, and no later render had any reason to reconsider.
+ *
+ * Driven through a real router, because the window under test is the router's
+ * own: the address commits before the matches swap, and a route the reader has
+ * not visited yet has its component to fetch before it can. Reasoning about
+ * that from the outside is not evidence, so the mailbox route here loads on a
+ * delay the way an unvisited one does.
+ *
+ * The other half is here too: a query ending with the view it was typed in
+ * (#47). That window is the same one, read the other way round — the address
+ * has moved and the matches have not — and the field must re-seed from the
+ * address rather than from the query the outgoing list still answers with.
+ * `lib/search-view.test.ts` drives the rules themselves.
+ */
+
+import assert from "node:assert/strict";
+import { afterEach, describe, it } from "node:test";
+import {
+	type AnyRouter,
+	createMemoryHistory,
+	createRootRoute,
+	createRoute,
+	createRouter,
+	Outlet,
+	RouterProvider,
+} from "@tanstack/react-router";
+import { createElement, useState } from "react";
+import { createDomHarness, type DomHarness } from "../test-support/dom";
+import { useSearchField } from "./useSearchField";
+
+let harness: DomHarness | undefined;
+
+afterEach(() => {
+	harness?.close();
+	harness = undefined;
+});
+
+// The router reads `self` at construction; the shared jsdom globals stop at
+// `window`.
+(globalThis as { self?: typeof globalThis }).self ??= globalThis;
+
+const FIELD_LABEL = "Search mail";
+const MAILBOX_ID = "9f1c-abc";
+const RENDER_AGAIN = "render again";
+
+/** What the field committed, so a test can assert what the mirror would write. */
+let committed = "";
+
+/**
+ * The field, plus a way to make it render on demand. Typing renders it; a
+ * navigation on its own does not, because this harness does not propagate a
+ * router store change into React the way the running app does — so a test that
+ * only navigates is asking nothing.
+ */
+function SearchField() {
+	const { searchInput, committedQuery, setSearchInput } = useSearchField();
+	const [renders, setRenders] = useState(0);
+	committed = committedQuery;
+	return createElement(
+		"div",
+		null,
+		createElement("input", {
+			"aria-label": FIELD_LABEL,
+			value: searchInput,
+			onChange: (event: { target: { value: string } }) =>
+				setSearchInput(event.target.value),
+		}),
+		createElement(
+			"button",
+			{
+				type: "button",
+				"aria-label": RENDER_AGAIN,
+				onClick: () => setRenders(renders + 1),
+			},
+			String(renders),
+		),
+	);
+}
+
+/**
+ * The mail shell over its four lists. Only the mailbox route loads on a delay:
+ * it stands for the list the reader has not been to yet, which is the one they
+ * navigate to and then type on.
+ */
+const buildRouter = (
+	mailboxLoadMs: number,
+	href = "/mail/brief",
+): AnyRouter => {
+	const passthrough = (search: Record<string, unknown>) => search;
+	const rootRoute = createRootRoute({ component: Outlet });
+	const mailRoute = createRoute({
+		getParentRoute: () => rootRoute,
+		path: "/mail",
+		validateSearch: passthrough,
+		component: () => createElement(SearchField, null),
+	});
+	const briefRoute = createRoute({
+		getParentRoute: () => mailRoute,
+		path: "/brief",
+		validateSearch: passthrough,
+		component: () => null,
+	});
+	const mailboxRoute = createRoute({
+		getParentRoute: () => mailRoute,
+		path: "/$mailboxId",
+		validateSearch: passthrough,
+		loader: async () => {
+			await new Promise((resolve) => setTimeout(resolve, mailboxLoadMs));
+			return null;
+		},
+		component: () => null,
+	});
+	const routeTree = rootRoute.addChildren([
+		mailRoute.addChildren([briefRoute, mailboxRoute]),
+	]);
+	return createRouter({
+		routeTree,
+		history: createMemoryHistory({ initialEntries: [href] }),
+	}) as unknown as AnyRouter;
+};
+
+const mount = async (
+	router: AnyRouter,
+): Promise<{ created: DomHarness; field: HTMLInputElement }> => {
+	const created = createDomHarness();
+	harness = created;
+	committed = "";
+	await router.load();
+	created.renderApp(createElement(RouterProvider, { router }));
+	await created.flush();
+	return {
+		created,
+		field: created.byLabel(FIELD_LABEL) as HTMLInputElement,
+	};
+};
+
+/** Long enough for the 200 ms debounce to settle on whatever the field holds. */
+const DEBOUNCE_SETTLED = 400;
+
+const openMailbox = (router: AnyRouter, mailboxId: string): void => {
+	void router.navigate({ to: "/mail/$mailboxId", params: { mailboxId } });
+};
+
+describe("a query the reader left behind on the previous list (#47)", () => {
+	// The sidebar link drops `q`, so the destination's address carries none. The
+	// field is re-seeded from that address and the mirror then has nothing to
+	// write, which is what keeps the query out of the next mailbox's URL.
+	for (const mailboxLoadMs of [0, 300]) {
+		it(`does not follow them into the next list (list ready in ${mailboxLoadMs}ms)`, async () => {
+			const router = buildRouter(mailboxLoadMs, "/mail/brief?q=invoice");
+			const { created, field } = await mount(router);
+			assert.equal(field.value, "invoice");
+
+			openMailbox(router, MAILBOX_ID);
+			await created.wait(10);
+			// The render inside the window the address has moved in and the
+			// matches have not: the outgoing list still answers `q=invoice`, and
+			// re-seeding from it hands the query to the mailbox being opened.
+			created.click(created.byLabel(RENDER_AGAIN));
+			await created.wait(mailboxLoadMs + DEBOUNCE_SETTLED);
+			created.click(created.byLabel(RENDER_AGAIN));
+			await created.wait(DEBOUNCE_SETTLED);
+
+			assert.equal(field.value, "");
+			assert.equal(committed, "");
+		});
+	}
+
+	it("arrives with a query the destination carries", async () => {
+		// The scope chip sends the reader to the brief to search everything, so
+		// the query travels in the address it navigates to and is kept.
+		const router = buildRouter(0, "/mail/9f1c-abc?q=invoice");
+		const { created, field } = await mount(router);
+
+		void router.navigate({ to: "/mail/brief", search: { q: "invoice" } });
+		await created.wait(10);
+		created.click(created.byLabel(RENDER_AGAIN));
+		await created.wait(DEBOUNCE_SETTLED);
+
+		assert.equal(field.value, "invoice");
+		assert.equal(committed, "invoice");
+	});
+});
+
+describe("a query typed as the reader arrives on a mailbox", () => {
+	// The address is already the mailbox — that is what `waitForURL` returns on
+	// — so the text was typed on the mailbox and is the mailbox's query.
+	for (const mailboxLoadMs of [0, 300]) {
+		it(`survives the view change it followed (list ready in ${mailboxLoadMs}ms)`, async () => {
+			const router = buildRouter(mailboxLoadMs);
+			const { created, field } = await mount(router);
+
+			openMailbox(router, MAILBOX_ID);
+			await created.wait(10);
+			assert.equal(
+				router.state.location.pathname,
+				`/mail/${MAILBOX_ID}`,
+				"the address moves before the list is on screen",
+			);
+
+			created.type(field, "invoice");
+			await created.wait(mailboxLoadMs + DEBOUNCE_SETTLED);
+
+			assert.equal(field.value, "invoice");
+			assert.equal(committed, "invoice");
+		});
+	}
+});

package/src/hooks/useSearchField.ts

@@ -0,0 +1,85 @@
+import { useRouter, useRouterState } from "@tanstack/react-router";
+import { useCallback, useState } from "react";
+import { addressQuery, mailViewKey } from "@/lib/mail-route";
+import { committedSearchQuery, searchInputForView } from "@/lib/search-view";
+import { useDebouncedValue } from "./useDebouncedValue";
+
+export interface SearchField {
+	/** The live field text, which every search surface binds. */
+	searchInput: string;
+	/** The debounced query the search APIs run and the mirror writes. */
+	committedQuery: string;
+	/** The view the field is searching (`lib/mail-route.ts`). */
+	viewKey: string;
+	/** Every write to the field — typed, cleared, or a chip edited. */
+	setSearchInput: (query: string) => void;
+}
+
+/**
+ * The one search field, held by the /mail shell so it outlives every child
+ * route, and the query it commits.
+ *
+ * Within a view the URL's `q` seeds it and is a one-directional write target:
+ * the committed value drives the search APIs and each list's `useSearchMirror`
+ * writes it back. Across views the URL wins again — search is a mode of the
+ * view it was typed in, so leaving that view re-seeds the field from wherever
+ * the reader lands (#47), empty when the sidebar dropped `q` and the carried
+ * query when the scope chip sent them to the brief to search everything.
+ *
+ * The re-seed is adjusted during render, not in an effect: React's documented
+ * "adjusting state when a prop changes" pattern, so nothing is painted carrying
+ * the previous view's text. An effect would commit one frame with the stale
+ * query in it, which the mirror then has to be defended against.
+ *
+ * Text carries the view it was typed in, rather than the field simply taking
+ * whatever the last render's view key was (#808). The address moves a render
+ * ahead of React — a keystroke and the view change it followed arrive in the
+ * same render, and the re-seed cannot tell them apart from what it has on
+ * screen. Stamping the view at the keystroke, off the address the router has
+ * already committed, says which of the two came second: type into the field
+ * once the address names the next mailbox and that text is the new view's, not
+ * a leftover of the one being left. Without it a query typed in that window was
+ * wiped in the render that followed, and since the field then held nothing the
+ * mirror had nothing to write — the query never reached the URL at all.
+ *
+ * Which view and which query both come off the committed address, never one
+ * from the address and the other from the matched route. The matches swap a
+ * render behind the address, so mixing the two reads the destination's view
+ * against the outgoing list's `q` and re-seeds the field with the query the
+ * reader has just navigated away from — the stamp then calls that text the new
+ * view's, and nothing reconsiders it (#47).
+ */
+export function useSearchField(): SearchField {
+	const router = useRouter();
+	const viewKey = useRouterState({
+		select: (state) => mailViewKey(state.location.pathname),
+	});
+	const urlQuery = useRouterState({
+		select: (state) => addressQuery(state.location.search),
+	});
+
+	const [searchInput, setInput] = useState(urlQuery);
+	const debouncedSearchInput = useDebouncedValue(searchInput, 200);
+
+	const [typedInView, setTypedInView] = useState(viewKey);
+	if (typedInView !== viewKey) {
+		const seeded = searchInputForView(typedInView, viewKey, urlQuery);
+		setTypedInView(viewKey);
+		if (seeded !== undefined) setInput(seeded);
+	}
+
+	const setSearchInput = useCallback(
+		(query: string) => {
+			setTypedInView(mailViewKey(router.state.location.pathname));
+			setInput(query);
+		},
+		[router],
+	);
+
+	return {
+		searchInput,
+		committedQuery: committedSearchQuery(searchInput, debouncedSearchInput),
+		viewKey,
+		setSearchInput,
+	};
+}

package/src/hooks/useSearchMirror.ts

@@ -1,6 +1,7 @@
-import { useNavigate, useRouterState, useSearch } from "@tanstack/react-router";
-import { useEffect, useRef } from "react";
+import { useNavigate, useRouterState } from "@tanstack/react-router";
+import { useEffect } from "react";
 import { useMailContext } from "@/lib/mail-context";
+import { addressQuery } from "@/lib/mail-route";
 import { shouldMirrorQuery } from "@/lib/search-view";
 import { useIsComposing, useIsReplying } from "@/routing";
 
@@ -22,6 +23,20 @@ export type SearchMirrorTarget =
  * the query the user just left behind is never written onto the view they landed
  * on (`shouldMirrorQuery`).
  *
+ * It watches the URL as well as the field, so a settled query that the address
+ * stops agreeing with is written again rather than left (#808). Typing lands
+ * more than one navigation — the debounce settles mid-word, and the word is
+ * finished while that write is still in flight — and the two can commit out of
+ * order, leaving the address on the prefix. Comparing against the URL without
+ * re-running on it made that final: the field said `invoice`, the address said
+ * `invo`, and nothing was left to disagree with. Re-running cannot start a
+ * loop, because every write makes the URL equal the committed query and the
+ * next run has nothing to do. The `q` it compares against is the committed
+ * address's, the same place the pathname below comes from: the matched route
+ * answers with the outgoing list's query for a render after the address has
+ * moved on, and a mirror reading one from each would write against a URL that
+ * no longer exists.
+ *
  * It also writes only while the reader is still on this list. A list stays
  * mounted, effects and all, until the list they navigated to is ready to paint,
  * and by then the address is already the new one — so a debounce settling in
@@ -51,17 +66,14 @@ export type SearchMirrorTarget =
 export function useSearchMirror(target: SearchMirrorTarget): void {
 	const navigate = useNavigate();
 	const { searchInput, searchQuery: committedQuery } = useMailContext();
-	const { q: urlQuery = "" } = useSearch({ from: "/mail" });
+	const urlQuery = useRouterState({
+		select: (s) => addressQuery(s.location.search),
+	});
 	const pathname = useRouterState({ select: (s) => s.location.pathname });
 	const isComposing = useIsComposing();
 	const isReplying = useIsReplying();
 	const isWriting = isComposing || isReplying;
 
-	// Read at effect time rather than depended on: the URL is what the mirror
-	// compares against, not what re-triggers it.
-	const urlQueryRef = useRef(urlQuery);
-	urlQueryRef.current = urlQuery;
-
 	const { to } = target;
 	const mailboxId = "params" in target ? target.params.mailboxId : undefined;
 	const listPath = mailboxId ? `/mail/${mailboxId}` : to;
@@ -70,13 +82,13 @@ export function useSearchMirror(target: SearchMirrorTarget): void {
 		const mayWrite = shouldMirrorQuery({
 			searchInput,
 			committedQuery,
-			urlQuery: urlQueryRef.current,
+			urlQuery,
 			pathname,
 			listPath,
 		});
 		if (!mayWrite) return;
 		const queryGoesActive =
-			Boolean(committedQuery) && urlQueryRef.current !== committedQuery;
+			Boolean(committedQuery) && urlQuery !== committedQuery;
 		// A message being written is the reader's own, not a leftover of the list
 		// they were on, so a query going active narrows the list behind it and
 		// leaves it where it is.
@@ -106,6 +118,7 @@ export function useSearchMirror(target: SearchMirrorTarget): void {
 	}, [
 		searchInput,
 		committedQuery,
+		urlQuery,
 		navigate,
 		to,
 		mailboxId,

package/src/lib/mail-route.test.ts

@@ -2,9 +2,9 @@
  * Three contracts, each of which has already cost a regression.
  *
  * The list is read off a matched route id, never the parent /mail layout's
- * pathname: that pathname is "/mail" on every child route, and keying off it
- * routed every mailbox through the brief pane, so the message-row anchors
- * vanished.
+ * own pathname: that pathname is "/mail" on every child route, and keying off
+ * it routed every mailbox through the brief pane, so the message-row anchors
+ * vanished. The location's pathname is the whole address and says which list.
  *
  * The view key of a list equals the view key of anything nested under it. A
  * thread is a child route of the list it was opened from, so a key that moved
@@ -12,13 +12,15 @@
  * the view — and the query they had just typed would be re-seeded from the URL
  * and disappear the moment they opened a hit.
  *
- * And "am I the current list" is answered by the pathname, not by the matches,
+ * And "where is the reader" is answered by the pathname, not by the matches,
  * because the matches lag a navigation by as long as the destination takes to
- * mount.
+ * mount — both for "am I the current list" and for which view the search field
+ * is searching (#808).
  */
 import assert from "node:assert/strict";
 import { describe, it } from "node:test";
 import {
+	addressQuery,
 	locationIsOnList,
 	locationOpensDetail,
 	MAIL_BRIEF_ROUTE_ID,
@@ -26,6 +28,7 @@ import {
 	MAIL_MAILBOX_ROUTE_ID,
 	MAIL_OUTBOX_ROUTE_ID,
 	type MailRouteMatch,
+	mailboxViewKey,
 	mailListRoute,
 	mailViewKey,
 } from "./mail-route.js";
@@ -85,47 +88,57 @@ describe("mailListRoute", () => {
 
 describe("mailViewKey", () => {
 	it("gives the four lists four distinct keys", () => {
-		const keys = [brief, flagged, outbox, mailbox].map(mailViewKey);
+		const keys = [
+			"/mail/brief",
+			"/mail/flagged",
+			"/mail/outbox",
+			"/mail/inbox-1",
+		].map(mailViewKey);
 		assert.equal(new Set(keys).size, 4);
 	});
 
 	it("distinguishes two mailboxes", () => {
 		assert.notEqual(
-			mailViewKey(matches([MAIL_MAILBOX_ROUTE_ID], { mailboxId: "inbox-1" })),
-			mailViewKey(matches([MAIL_MAILBOX_ROUTE_ID], { mailboxId: "archive-1" })),
+			mailViewKey("/mail/inbox-1"),
+			mailViewKey("/mail/archive-1"),
 		);
 	});
 
 	it("is empty outside the mail shell", () => {
-		assert.equal(mailViewKey([{ routeId: "__root__" }]), "");
+		assert.equal(mailViewKey("/onboarding"), "");
 	});
 
-	it("is empty on a mailbox route whose param has not resolved", () => {
-		assert.equal(mailViewKey(matches([MAIL_MAILBOX_ROUTE_ID])), "");
+	it("is empty on /mail itself, which names no list", () => {
+		assert.equal(mailViewKey("/mail"), "");
+	});
+
+	it("reads the list from the address the router has committed", () => {
+		// The matches lag a navigation by as long as the destination takes to
+		// mount, and the search field follows the address: text typed once this
+		// says the next mailbox is that mailbox's query, not the previous view's.
+		assert.equal(mailViewKey("/mail/inbox-1"), mailboxViewKey("inbox-1"));
+		assert.equal(mailViewKey("/mail/brief"), MAIL_BRIEF_ROUTE_ID);
+		assert.equal(mailViewKey("/mail/flagged"), MAIL_FLAGGED_ROUTE_ID);
+		assert.equal(mailViewKey("/mail/outbox"), MAIL_OUTBOX_ROUTE_ID);
 	});
 
 	// The trap: opening a thread must not read as leaving the list, or the
 	// search field re-seeds and the typed query is gone.
 	it("gives a list and its open thread the same key", () => {
-		const lists: [readonly string[], Record<string, string> | undefined][] = [
-			[[MAIL_BRIEF_ROUTE_ID], undefined],
-			[[MAIL_FLAGGED_ROUTE_ID], undefined],
-			[[MAIL_OUTBOX_ROUTE_ID], undefined],
-			[[MAIL_MAILBOX_ROUTE_ID], { mailboxId: "inbox-1" }],
-		];
-
-		for (const [routeIds, params] of lists) {
-			const list = routeIds[0];
-			const thread = `${list}/$threadId`;
-			const message = `${thread}/$messageId`;
+		for (const list of [
+			"/mail/brief",
+			"/mail/flagged",
+			"/mail/outbox",
+			"/mail/inbox-1",
+		]) {
 			assert.equal(
-				mailViewKey(matches([list, thread], params)),
-				mailViewKey(matches([list], params)),
+				mailViewKey(`${list}/th-1`),
+				mailViewKey(list),
 				`${list} changes view key when a thread opens`,
 			);
 			assert.equal(
-				mailViewKey(matches([list, thread, message], params)),
-				mailViewKey(matches([list], params)),
+				mailViewKey(`${list}/th-1/msg-1`),
+				mailViewKey(list),
 				`${list} changes view key when a message expands`,
 			);
 		}
@@ -135,34 +148,23 @@ describe("mailViewKey", () => {
 	// moved when it opened would wipe the query the reader was mid-search on.
 	it("gives a list and its compose surface the same key", () => {
 		assert.equal(
-			mailViewKey(
-				matches([
-					MAIL_BRIEF_ROUTE_ID,
-					`${MAIL_BRIEF_ROUTE_ID}/compose/{-$outboxMessageId}`,
-				]),
-			),
-			mailViewKey(brief),
+			mailViewKey("/mail/brief/compose"),
+			mailViewKey("/mail/brief"),
 		);
 		assert.equal(
-			mailViewKey(
-				matches(
-					[
-						MAIL_MAILBOX_ROUTE_ID,
-						`${MAIL_MAILBOX_ROUTE_ID}/compose/{-$outboxMessageId}`,
-					],
-					{
-						mailboxId: "inbox-1",
-					},
-				),
-			),
-			mailViewKey(mailbox),
+			mailViewKey("/mail/inbox-1/compose/draft-1"),
+			mailViewKey("/mail/inbox-1"),
 		);
 	});
 
-	it("gives a list and its reading-pane index child the same key", () => {
+	it("ignores a query string and a fragment", () => {
 		assert.equal(
-			mailViewKey(matches([MAIL_BRIEF_ROUTE_ID, `${MAIL_BRIEF_ROUTE_ID}/`])),
-			mailViewKey(brief),
+			mailViewKey("/mail/brief?q=invoice"),
+			mailViewKey("/mail/brief"),
+		);
+		assert.equal(
+			mailViewKey("/mail/brief#intelligence"),
+			mailViewKey("/mail/brief"),
 		);
 	});
 });
@@ -238,3 +240,22 @@ describe("locationOpensDetail", () => {
 		assert.equal(locationOpensDetail("/onboarding"), false);
 	});
 });
+
+describe("addressQuery", () => {
+	it("reads the query the address carries", () => {
+		assert.equal(addressQuery({ q: "invoice" }), "invoice");
+	});
+
+	it("is empty where the address carries none", () => {
+		assert.equal(addressQuery({}), "");
+		assert.equal(addressQuery({ wizard: "pick" }), "");
+	});
+
+	it("is empty for anything that is not a query string", () => {
+		// The location's search is parsed, not validated: a hand-edited `?q[]=`
+		// arrives as an array and must not reach the field as one.
+		assert.equal(addressQuery({ q: ["invoice"] }), "");
+		assert.equal(addressQuery(undefined), "");
+		assert.equal(addressQuery(null), "");
+	});
+});

package/src/lib/mail-route.ts

@@ -56,20 +56,42 @@ export function mailListRoute(
  * key of a list and of anything nested under it are equal; `lib/search-view.ts`
  * re-seeds the search field whenever this changes, and a key that moved when a
  * message opened would wipe the query the reader had just typed.
+ *
+ * Read off the location's pathname, for the reason `locationIsOnList` is: the
+ * router commits the address before it swaps the matches, and a route the
+ * reader has not visited yet has its component to fetch before it can. The
+ * search field follows the address, so text typed once the address says the
+ * next mailbox belongs to that mailbox — keying this off the matches instead
+ * made those keystrokes read as the previous view's leftovers and dropped them.
+ *
+ * The whole address, never the /mail match's own pathname, which is "/mail" on
+ * every child route.
  */
-export function mailViewKey(matches: readonly MailRouteMatch[]): string {
-	const route = mailListRoute(matches);
-	if (!route) return "";
-	switch (route.list) {
-		case "mailbox":
-			return route.mailboxId ? mailboxViewKey(route.mailboxId) : "";
-		case "flagged":
-			return MAIL_FLAGGED_ROUTE_ID;
-		case "outbox":
-			return MAIL_OUTBOX_ROUTE_ID;
-		case "brief":
-			return MAIL_BRIEF_ROUTE_ID;
-	}
+export function mailViewKey(pathname: string): string {
+	const segments = pathname.split(/[?#]/)[0].split("/").filter(Boolean);
+	if (segments[0] !== "mail") return "";
+	const list = segments[1];
+	if (!list) return "";
+	if (list === "brief") return MAIL_BRIEF_ROUTE_ID;
+	if (list === "flagged") return MAIL_FLAGGED_ROUTE_ID;
+	if (list === "outbox") return MAIL_OUTBOX_ROUTE_ID;
+	return mailboxViewKey(list);
+}
+
+/**
+ * What the address says the query is.
+ *
+ * Read off the location's own search, never off the matched route's, for the
+ * reason `mailViewKey` reads the location's pathname: the router commits the
+ * whole address at once and swaps the matches afterwards. Taking the view from
+ * one and the query from the other splits a single move in two — the field sees
+ * the mailbox it is going to next to the query of the one it is leaving, and
+ * re-seeds itself with a query the reader has already navigated away from (#47).
+ */
+export function addressQuery(search: unknown): string {
+	if (typeof search !== "object" || search === null) return "";
+	const { q } = search as { q?: unknown };
+	return typeof q === "string" ? q : "";
 }
 
 /** One mailbox's view key. Two mailboxes are two views. */

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

@@ -6,23 +6,13 @@
  */
 import assert from "node:assert/strict";
 import { describe, it } from "node:test";
-import {
-	MAIL_BRIEF_ROUTE_ID,
-	type MailRouteMatch,
-	mailViewKey,
-} from "./mail-route.js";
+import { MAIL_BRIEF_ROUTE_ID, 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("searchInputForView", () => {
 	it("clears the field when the destination carries no query", () => {
 		assert.equal(
@@ -173,7 +163,10 @@ describe("shouldMirrorQuery", () => {
  * both have to end it without ever writing over what the user is typing.
  */
 interface Shell {
+	/** The view the address names, which is what a render reads. */
 	viewKey: string;
+	/** The view the text in the field was typed in (`hooks/useSearchField.ts`). */
+	typedInView: string;
 	/** The path of the list whose mirror is running. */
 	listPath: string;
 	field: string;
@@ -189,10 +182,8 @@ const render = (
 	listPath = shell.listPath,
 ): Shell => {
 	const field =
-		viewKey === shell.viewKey
-			? shell.field
-			: (searchInputForView(shell.viewKey, viewKey, url) ?? shell.field);
-	return { ...shell, viewKey, listPath, field, url };
+		searchInputForView(shell.typedInView, viewKey, url) ?? shell.field;
+	return { ...shell, viewKey, typedInView: viewKey, listPath, field, url };
 };
 
 /**
@@ -213,15 +204,22 @@ const mirror = (shell: Shell, pathname = shell.listPath): Shell => {
 	return { ...shell, url: committed };
 };
 
-const typing = (shell: Shell, text: string): Shell => ({
+/**
+ * A keystroke, stamped with the view the address named when it landed. That is
+ * the address the router has already committed, which for one render is ahead
+ * of the view the shell is showing.
+ */
+const typing = (shell: Shell, text: string, atView = shell.viewKey): Shell => ({
 	...shell,
 	field: text,
+	typedInView: atView,
 });
 const settle = (shell: Shell): Shell => ({ ...shell, debounced: shell.field });
 
 describe("search across a view change", () => {
 	const searching: Shell = {
-		viewKey: mailViewKey(matches("/mail/$mailboxId", "inbox-1")),
+		viewKey: mailViewKey("/mail/inbox-1"),
+		typedInView: mailViewKey("/mail/inbox-1"),
 		listPath: "/mail/inbox-1",
 		field: "invoice",
 		debounced: "invoice",
@@ -231,12 +229,7 @@ describe("search across a view change", () => {
 	it("ends the search when the user leaves the view", () => {
 		// The nav link drops `q`, so the destination carries none.
 		const next = mirror(
-			render(
-				searching,
-				mailViewKey(matches("/mail/$mailboxId", "sent-1")),
-				"",
-				"/mail/sent-1",
-			),
+			render(searching, mailViewKey("/mail/sent-1"), "", "/mail/sent-1"),
 		);
 		assert.equal(next.field, "");
 		assert.equal(next.url, "");
@@ -248,7 +241,8 @@ describe("search across a view change", () => {
 	// the reader had just pushed, so Inbox never arrives.
 	it("does not navigate back to the list the reader is leaving", () => {
 		const brief: Shell = {
-			viewKey: mailViewKey(matches(MAIL_BRIEF_ROUTE_ID)),
+			viewKey: mailViewKey(MAIL_BRIEF_ROUTE_ID),
+			typedInView: mailViewKey(MAIL_BRIEF_ROUTE_ID),
 			listPath: MAIL_BRIEF_ROUTE_ID,
 			field: "inv",
 			debounced: "",
@@ -266,7 +260,7 @@ describe("search across a view change", () => {
 		// mirror must not write it back — that is #47 returning by another route.
 		const landed = render(
 			searching,
-			mailViewKey(matches("/mail/$mailboxId", "sent-1")),
+			mailViewKey("/mail/sent-1"),
 			"",
 			"/mail/sent-1",
 		);
@@ -280,7 +274,7 @@ describe("search across a view change", () => {
 		const next = mirror(
 			render(
 				searching,
-				mailViewKey(matches(MAIL_BRIEF_ROUTE_ID)),
+				mailViewKey(MAIL_BRIEF_ROUTE_ID),
 				"invoice",
 				MAIL_BRIEF_ROUTE_ID,
 			),
@@ -289,10 +283,27 @@ describe("search across a view change", () => {
 		assert.equal(next.url, "invoice");
 	});
 
+	// #808: `waitForURL` returns on the address, so a reader — and a test — can
+	// type before the destination is on screen. That keystroke and the view
+	// change arrive in one render, and re-seeding it away left the field empty,
+	// the mirror with nothing to write, and no later render any reason to
+	// reconsider: the query never reached the URL at all.
+	it("keeps a query typed once the address already named the destination", () => {
+		const sent = mailViewKey("/mail/sent-1");
+		const typedOnArrival = typing(
+			{ ...searching, field: "", debounced: "", url: "" },
+			"invoice",
+			sent,
+		);
+		const landed = settle(render(typedOnArrival, sent, "", "/mail/sent-1"));
+		assert.equal(landed.field, "invoice");
+		assert.equal(mirror(landed).url, "invoice");
+	});
+
 	it("never clobbers characters the user is still typing", () => {
 		// Opening a result and the q-mirror both re-render the same view. Neither
 		// is a view change, so neither may reach into the field.
-		const mailbox = mailViewKey(matches("/mail/$mailboxId", "inbox-1"));
+		const mailbox = mailViewKey("/mail/inbox-1");
 		let shell = typing(
 			{ ...searching, field: "", debounced: "", url: "" },
 			"i",

package/src/lib/search-view.ts

@@ -9,19 +9,29 @@
  * 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.
+ *
+ * "Every view change" is the move the reader made, not every render that
+ * notices one. Text typed once the address already names the destination was
+ * typed in the destination, so it is that view's query and survives
+ * (`hooks/useSearchField.ts`).
  */
 import { locationIsOnList } from "./mail-route";
 
 /**
  * The field text after a view transition, or `undefined` when nothing changes
  * (same view — typing, opening a result, mirroring `q` back to the URL).
+ *
+ * `typedInView` is the view the text in the field was written in, not the view
+ * of the previous render. The two differ for exactly one render after the
+ * address moves, which is where a keystroke that followed the move lands
+ * (#808); calling it the previous render's view re-seeded that keystroke away.
  */
 export function searchInputForView(
-	previousViewKey: string,
+	typedInView: string,
 	viewKey: string,
 	urlQuery: string,
 ): string | undefined {
-	if (previousViewKey === viewKey) return undefined;
+	if (typedInView === viewKey) return undefined;
 	return urlQuery;
 }
 
@@ -64,6 +74,15 @@ export interface MirrorDecision {
  * address is already the new one. A write from the outgoing list in that window
  * navigates back to itself, superseding the load in flight and replacing the
  * entry the reader just pushed — they click Inbox and land on the brief.
+ *
+ * The mirror asks this again whenever the address moves, not only when the
+ * field does (#808), so a settled query the URL has drifted away from is
+ * written again. That cannot loop: the answer is false the moment the URL says
+ * the committed query, which is what every write makes it say. Nor does it let
+ * the mirror fight a query arriving by URL — that arrives mid-debounce, where
+ * the first rule already refuses, and by the time the debounce settles the
+ * field has been re-seeded from the address it landed on
+ * (`hooks/useSearchField.ts`).
  */
 export function shouldMirrorQuery({
 	searchInput,

package/src/routes/mail.tsx

@@ -9,7 +9,6 @@ import {
 	Outlet,
 	useNavigate,
 	useRouterState,
-	useSearch,
 } from "@tanstack/react-router";
 import { useCallback, useEffect, useMemo, useState } from "react";
 import { z } from "zod";
@@ -19,11 +18,11 @@ import { MailTopBar } from "@/components/layout/MailTopBar";
 import { MailNav } from "@/components/mail/MailNav";
 import { ErrorState } from "@/components/ui/ErrorState";
 import { KeyboardShortcutsModal } from "@/components/ui/KeyboardShortcutsModal";
-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 { useSearchField } from "@/hooks/useSearchField";
 import { useStaleAccountSync } from "@/hooks/useStaleAccountSync";
 import {
 	readIntelligencePref,
@@ -32,9 +31,8 @@ import {
 } from "@/lib/intelligence-pref";
 import { MailContext } from "@/lib/mail-context";
 import { MailFreshnessProvider } from "@/lib/mail-freshness";
-import { mailListRoute, mailViewKey } from "@/lib/mail-route";
+import { mailListRoute } from "@/lib/mail-route";
 import { buildAccountNameIndex } from "@/lib/search-token-index";
-import { committedSearchQuery, searchInputForView } from "@/lib/search-view";
 import { wizardEntryValue, wizardStepValue } from "@/lib/wizard-history";
 import {
 	isOverlayPanel,
@@ -80,7 +78,6 @@ export const Route = createFileRoute("/mail")({
 });
 
 function MailLayout() {
-	const { q: searchQuery = "" } = useSearch({ from: "/mail" });
 	const navigate = useNavigate();
 	const tier = useLayoutTier();
 	// Below the reading boundary (phone AND tablet) the shell shows a SINGLE
@@ -141,38 +138,11 @@ function MailLayout() {
 		[intelligenceOpen, showPanels],
 	);
 
-	// 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 by the list route's own `useSearchMirror`. Across views the URL wins
-	// again — see the view-change adjustment below and `lib/search-view.ts` (#47).
-	const [searchInput, setSearchInput] = useState(searchQuery);
-	const debouncedSearchInput = useDebouncedValue(searchInput, 200);
-	const committedQuery = committedSearchQuery(
-		searchInput,
-		debouncedSearchInput,
-	);
-
-	// Search is a mode of the view it was typed in, so leaving that view re-seeds
-	// the field from wherever we land (#47): empty when the sidebar dropped `q`
-	// (a folder switch starts that folder's search fresh), and the carried query
-	// when the top bar's scope chip was removed and sent the user to the brief to
-	// search everything. Views that differ only in what is open below the list —
-	// a thread, a mirrored `q` — are the same view, so in-flight typing survives
-	// them (`searchInputForView`, `mailViewKey`).
-	//
-	// Adjusted during render, not in an effect. This is React's documented
-	// "adjusting state when a prop changes" pattern: both updates are to this
-	// component's own state and are guarded by a changed value, so React re-runs
-	// the render before committing and nothing is painted with the stale query.
-	// An effect would commit one frame carrying the previous view's text, which
-	// the mirror then has to be defended against.
-	const viewKey = useRouterState({ select: (s) => mailViewKey(s.matches) });
-	const [searchViewKey, setSearchViewKey] = useState(viewKey);
-	if (searchViewKey !== viewKey) {
-		const seeded = searchInputForView(searchViewKey, viewKey, searchQuery);
-		setSearchViewKey(viewKey);
-		if (seeded !== undefined) setSearchInput(seeded);
-	}
+	// The one search field and the query it commits (`useSearchField`): seeded
+	// from the URL, mirrored back by each list route's own `useSearchMirror`,
+	// and re-seeded from the address whenever the reader leaves the view (#47).
+	const { searchInput, committedQuery, viewKey, setSearchInput } =
+		useSearchField();
 
 	const {
 		data: config,
@@ -229,20 +199,16 @@ function MailLayout() {
 		handlers: composeHandlers,
 	});
 
-	const handleSearchChange = useCallback((query: string) => {
-		setSearchInput(query);
-	}, []);
-
 	// Clears the search field; the list route's mirror drops `q` from the URL
 	// after the debounce settles.
 	const handleSearchClear = useCallback(() => {
 		setSearchInput("");
-	}, []);
+	}, [setSearchInput]);
 
 	// Esc inside the search field clears only the query (#489).
 	const handleSearchClearQuery = useCallback(() => {
 		setSearchInput("");
-	}, []);
+	}, [setSearchInput]);
 
 	const handleToggleIntelligence = useCallback(() => {
 		handleSetIntelligenceOpen(!intelligenceOpen);
@@ -283,7 +249,7 @@ function MailLayout() {
 		searchQuery: committedQuery,
 		searchInput,
 		searchViewKey: viewKey,
-		onSearchChange: handleSearchChange,
+		onSearchChange: setSearchInput,
 		onSearchClear: handleSearchClear,
 		onSearchClearQuery: handleSearchClearQuery,
 		intelligenceOpen,