@remit/web-client 0.0.12 → 0.0.14

package/src/hooks/useToggleStar.ts

@@ -9,6 +9,7 @@ import type { RemitImapThreadMessageResponse } from "@remit/api-http-client/type
 import { useMutation, useQueryClient } from "@tanstack/react-query";
 import { useErrorBanners } from "@/components/ui/ErrorBannerProvider";
 import { formatErrorDetail } from "@/components/ui/error-banners";
+import { patchThreadListCache, type ThreadListCache } from "@/lib/thread-cache";
 
 interface UseToggleStarOptions {
 	threadId: string;
@@ -46,15 +47,12 @@ interface ThreadMessagesData {
 	[key: string]: unknown;
 }
 
-interface ThreadsListPage {
-	items: RemitImapThreadMessageResponse[];
-	[key: string]: unknown;
-}
-
-interface ThreadsListData {
-	pages: ThreadsListPage[];
-	pageParams: Array<string | undefined>;
-}
+/**
+ * Either shape a thread list/search query caches — the infinite mailbox list
+ * or a single-shot page. `setQueriesData` matches by key prefix, so the
+ * optimistic updater sees both.
+ */
+type ThreadsListData = ThreadListCache;
 
 interface SnapshotEntry<T> {
 	queryKey: readonly unknown[];
@@ -156,39 +154,36 @@ export const useToggleStar = ({
 				)
 				.map(([queryKey, data]) => ({ queryKey, data }));
 
-			const patchItemsData = (old: ThreadMessagesData | undefined) => {
-				if (!old) return old;
-				return {
-					...old,
-					items: toggleStarsInItems(old.items, messageId, nextStarred),
-				};
-			};
-
-			queryClient.setQueriesData<ThreadMessagesData>(
+			// The unified-threads prefix carries both shapes too: the Flagged view
+			// runs an infinite query on `listAllThreads({ starred: true })`, which
+			// sits under the same prefix as the single-shot readers. Patching it as
+			// a plain `{ items }` threw on that entry and failed the star before it
+			// was sent — the same defect as the mailbox list (issues #51, #55), so
+			// it goes through the same helper.
+			const patchItemsData = (old: unknown) =>
+				patchThreadListCache(old, (items) =>
+					toggleStarsInItems(items, messageId, nextStarred),
+				);
+
+			queryClient.setQueriesData(
 				{ queryKey: threadMessagesPrefix },
 				patchItemsData,
 			);
-			queryClient.setQueriesData<ThreadMessagesData>(
+			queryClient.setQueriesData(
 				{ queryKey: unifiedThreadsPrefix },
 				patchItemsData,
 			);
 
-			const patchListData = (old: ThreadsListData | undefined) => {
-				if (!old) return old;
-				return {
-					...old,
-					pages: old.pages.map((page) => ({
-						...page,
-						items: toggleStarsInItems(page.items, messageId, nextStarred),
-					})),
-				};
-			};
+			const patchListData = (old: unknown) =>
+				patchThreadListCache(old, (items) =>
+					toggleStarsInItems(items, messageId, nextStarred),
+				);
 
-			queryClient.setQueriesData<ThreadsListData>(
+			queryClient.setQueriesData(
 				{ queryKey: threadsListPrefix },
 				patchListData,
 			);
-			queryClient.setQueriesData<ThreadsListData>(
+			queryClient.setQueriesData(
 				{ queryKey: threadsSearchPrefix },
 				patchListData,
 			);
@@ -221,6 +216,7 @@ export const useToggleStar = ({
 					? "Couldn't star message"
 					: "Couldn't unstar message",
 				detail: formatErrorDetail(err),
+				error: err,
 			});
 		},
 		onSettled: (_data, _err, _vars, context) => {

package/src/hooks/useUpdateAddressFlags.ts

@@ -12,6 +12,7 @@ import { useCallback } from "react";
 import { useErrorBanners } from "@/components/ui/ErrorBannerProvider";
 import { formatErrorDetail } from "@/components/ui/error-banners";
 import { reportFatalError } from "@/lib/fatal-error";
+import { senderAddressSearchQuery } from "@/lib/sender-address";
 
 interface UseUpdateAddressFlagsOptions {
 	addressId: string | undefined;
@@ -61,7 +62,7 @@ export function useUpdateAddressFlags({
 	const { pushError } = useErrorBanners();
 
 	const addressCacheKey = addressOperationsSearchAddressesQueryKey({
-		query: { q: senderEmail ?? "", limit: 1 },
+		query: senderAddressSearchQuery(senderEmail),
 	});
 
 	const { mutate, isPending } = useMutation({
@@ -99,6 +100,7 @@ export function useUpdateAddressFlags({
 			pushError({
 				title: "Couldn't update sender preference",
 				detail: formatErrorDetail(err),
+				error: err,
 			});
 		},
 		onSettled: () => {

package/src/lib/api.ts

@@ -1,3 +1,5 @@
+import { taggedFetch } from "./network-error";
+
 export class ApiError extends Error {
 	constructor(
 		message: string,
@@ -38,7 +40,7 @@ const request = async <T>(
 
 	const url = buildUrl(path, params);
 
-	const response = await fetch(url, {
+	const response = await taggedFetch(url, {
 		method,
 		headers: {
 			"Content-Type": "application/json",

package/src/lib/client.ts

@@ -1,6 +1,7 @@
 import { client } from "@remit/api-http-client/client.gen.ts";
 import { getRuntimeConfig } from "../runtime-config";
 import { ApiError } from "./api";
+import { taggedFetch } from "./network-error";
 
 // In production, the config.js apiUrl points at the deployed API Gateway.
 // In local dev, the Vite proxy forwards /api -> localhost:4321 (see vite.config.ts).
@@ -8,6 +9,8 @@ const baseUrl = getRuntimeConfig().apiUrl;
 
 client.setConfig({
 	baseUrl,
+	// Transport failures are tagged where they happen; see `network-error.ts`.
+	fetch: taggedFetch,
 });
 
 /**

package/src/lib/compose-routes.test.ts

@@ -0,0 +1,44 @@
+/**
+ * The one route resolver behind both compose entry points — the desktop top
+ * bar's button and the mobile `ComposeFab`. When they each carried their own
+ * copy the two disagreed, and the FAB opened compose state on routes that
+ * mount no surface: a dead button.
+ */
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { hostsComposeSurface } from "./compose-routes";
+
+describe("hostsComposeSurface", () => {
+	it("is true for a mailbox route, which mounts FullCompose", () => {
+		assert.equal(hostsComposeSurface("/mail/INBOX"), true);
+		assert.equal(hostsComposeSurface("/mail/abc-123"), true);
+	});
+
+	it("is false for the virtual views, which mount no surface", () => {
+		assert.equal(hostsComposeSurface("/mail/outbox"), false);
+		assert.equal(hostsComposeSurface("/mail/flagged"), false);
+	});
+
+	it("is false for the daily brief, which is /mail itself", () => {
+		assert.equal(hostsComposeSurface("/mail"), false);
+		assert.equal(hostsComposeSurface("/mail/"), false);
+	});
+
+	it("is false outside the mail shell", () => {
+		assert.equal(hostsComposeSurface("/settings/accounts"), false);
+		assert.equal(hostsComposeSurface("/"), false);
+		assert.equal(hostsComposeSurface("/mailroom/x"), false);
+	});
+
+	it("matches whole segments, so a mailbox may be named after a view", () => {
+		assert.equal(hostsComposeSurface("/mail/outbox-2024"), true);
+		assert.equal(hostsComposeSurface("/mail/flagged-archive"), true);
+		assert.equal(hostsComposeSurface("/mail/outboxes"), true);
+	});
+
+	it("ignores a query string or hash on the path", () => {
+		assert.equal(hostsComposeSurface("/mail/INBOX?q=invoice"), true);
+		assert.equal(hostsComposeSurface("/mail/outbox?q=invoice"), false);
+		assert.equal(hostsComposeSurface("/mail/INBOX#top"), true);
+	});
+});

package/src/lib/compose-routes.ts

@@ -0,0 +1,25 @@
+/**
+ * Which routes mount the compose surface.
+ *
+ * `FullCompose` is mounted by the mailbox route only, so compose started from
+ * anywhere else has to carry the user to a mailbox first. Kept apart from
+ * `useComposeTarget` so it stays a plain function with no React or API
+ * dependencies — both compose entry points resolve routes through this one
+ * definition, and a divergent second copy is what left the mobile FAB dead on
+ * `/mail/flagged` and on the brief.
+ */
+
+/** `/mail/<segment>` values that name a view rather than a mailbox. */
+const VIRTUAL_MAIL_VIEWS = new Set(["outbox", "flagged"]);
+
+/**
+ * True for `/mail/<id>` where `<id>` is a real mailbox.
+ *
+ * Compares whole path segments: a mailbox genuinely named `outbox-2024` hosts
+ * the surface and must not be read as the virtual outbox.
+ */
+export const hostsComposeSurface = (pathname: string): boolean => {
+	const [, root, view] = pathname.split(/[?#]/)[0].split("/");
+	if (root !== "mail" || !view) return false;
+	return !VIRTUAL_MAIL_VIEWS.has(view);
+};

package/src/lib/error-classifier.test.ts

@@ -5,10 +5,18 @@ import {
 	getErrorStatus,
 	hasHttpStatus,
 	isAbortError,
+	isClientBug,
 	isNetworkError,
 	isServerError,
 	shouldEscalate,
 } from "./error-classifier";
+import { NetworkError, taggedFetch } from "./network-error";
+
+const timeoutError = (): Error => {
+	const error = new Error("The operation timed out.");
+	error.name = "TimeoutError";
+	return error;
+};
 
 const abortError = (): Error => {
 	const error = new Error("aborted");
@@ -75,9 +83,31 @@ describe("isAbortError", () => {
 });
 
 describe("isNetworkError", () => {
-	it("is true for a statusless transport failure", () => {
-		assert.equal(isNetworkError(new TypeError("Failed to fetch")), true);
-		assert.equal(isNetworkError(new Error("network down")), true);
+	// The boundary tags the failure, so the browser's wording never matters.
+	// These are the real rejections `fetch` produces, across engines — every one
+	// of them has to stay soft, whatever it happens to say.
+	const transportFailures = [
+		new TypeError("Failed to fetch"), // Chrome, Edge
+		new TypeError("NetworkError when attempting to fetch resource."), // Firefox
+		new TypeError("Load failed"), // WebKit
+		new TypeError("The network connection was lost."), // WebKit, wifi dropped
+		new TypeError("The request timed out."), // WebKit
+		new TypeError("fetch failed"), // undici
+		new Error("something no engine has said yet"),
+	];
+
+	it("is true for anything the fetch boundary tagged, whatever it says", () => {
+		for (const failure of transportFailures) {
+			assert.equal(
+				isNetworkError(new NetworkError(failure)),
+				true,
+				`"${failure.message}" must stay soft`,
+			);
+		}
+	});
+
+	it("is true for a timeout — a timeout is a transport failure", () => {
+		assert.equal(isNetworkError(new NetworkError(timeoutError())), true);
 	});
 
 	it("is false for an aborted request (its own category)", () => {
@@ -88,6 +118,108 @@ describe("isNetworkError", () => {
 		assert.equal(isNetworkError(new ApiError("boom", 500)), false);
 		assert.equal(isNetworkError(new ApiError("not found", 404)), false);
 	});
+
+	it("is false for an exception thrown by our own code", () => {
+		assert.equal(
+			isNetworkError(
+				new TypeError('can\'t access property "map", x is undefined'),
+			),
+			false,
+		);
+	});
+
+	it("does not mistake an untagged error for transport just because it reads like one", () => {
+		// A bug whose message happens to contain a fetch-failure phrase is still a
+		// bug. Only the boundary gets to say otherwise.
+		assert.equal(isNetworkError(new TypeError("Failed to fetch")), false);
+	});
+});
+
+describe("taggedFetch — where the decision is actually made", () => {
+	const withFetch = async (
+		impl: typeof fetch,
+		run: () => Promise<void>,
+	): Promise<void> => {
+		const original = globalThis.fetch;
+		globalThis.fetch = impl;
+		try {
+			await run();
+		} finally {
+			globalThis.fetch = original;
+		}
+	};
+
+	it("tags every transport rejection, regardless of its message", async () => {
+		for (const message of [
+			"Failed to fetch",
+			"The network connection was lost.",
+			"fetch failed",
+			"anything at all",
+		]) {
+			await withFetch(
+				() => Promise.reject(new TypeError(message)),
+				async () => {
+					const error = await taggedFetch("/x").catch((e: unknown) => e);
+					assert.ok(error instanceof NetworkError);
+					assert.equal(isNetworkError(error), true);
+					assert.equal(shouldEscalate(error), false);
+				},
+			);
+		}
+	});
+
+	it("tags a timeout, because a timeout never reached a server", async () => {
+		await withFetch(
+			() => Promise.reject(timeoutError()),
+			async () => {
+				const error = await taggedFetch("/x").catch((e: unknown) => e);
+				assert.ok(error instanceof NetworkError);
+				assert.equal(shouldEscalate(error), false);
+			},
+		);
+	});
+
+	it("leaves a deliberate abort untagged — it is not a failure", async () => {
+		await withFetch(
+			() => Promise.reject(abortError()),
+			async () => {
+				const error = await taggedFetch("/x").catch((e: unknown) => e);
+				assert.ok(!(error instanceof NetworkError));
+				assert.equal(isAbortError(error), true);
+			},
+		);
+	});
+
+	it("passes a response through untouched, including an error status", async () => {
+		const response = new Response("nope", { status: 500 });
+		await withFetch(
+			() => Promise.resolve(response),
+			async () => {
+				assert.equal(await taggedFetch("/x"), response);
+			},
+		);
+	});
+});
+
+describe("isClientBug", () => {
+	it("is true for an exception raised inside our own code", () => {
+		assert.equal(
+			isClientBug(
+				new TypeError('can\'t access property "map", x is undefined'),
+			),
+			true,
+		);
+	});
+
+	it("is false for a request that reached, or failed to reach, a server", () => {
+		assert.equal(isClientBug(new ApiError("boom", 500)), false);
+		assert.equal(isClientBug(new ApiError("not found", 404)), false);
+		assert.equal(
+			isClientBug(new NetworkError(new TypeError("Failed to fetch"))),
+			false,
+		);
+		assert.equal(isClientBug(abortError()), false);
+	});
 });
 
 describe("shouldEscalate (the fail-fast decision table — #1059)", () => {
@@ -119,15 +251,31 @@ describe("shouldEscalate (the fail-fast decision table — #1059)", () => {
 		assert.equal(shouldEscalate(abortError()), false);
 	});
 
-	it("does NOT escalate a statusless network/offline blip", () => {
-		assert.equal(shouldEscalate(new TypeError("Failed to fetch")), false);
-		assert.equal(shouldEscalate(new Error("network down")), false);
+	it("does NOT escalate a network/offline blip", () => {
+		assert.equal(
+			shouldEscalate(new NetworkError(new TypeError("Failed to fetch"))),
+			false,
+		);
+		assert.equal(
+			shouldEscalate(
+				new NetworkError(new TypeError("The network connection was lost.")),
+			),
+			false,
+		);
 	});
 
-	it("a statusless error is soft regardless of meta", () => {
+	it("a network error is soft regardless of meta", () => {
 		assert.equal(
-			shouldEscalate(new TypeError("Failed to fetch"), { softError: false }),
+			shouldEscalate(new NetworkError(new TypeError("Failed to fetch")), {
+				softError: false,
+			}),
 			false,
 		);
 	});
+
+	it("escalates an exception thrown by our own code, softError or not", () => {
+		const bug = new TypeError('can\'t access property "map", x is undefined');
+		assert.equal(shouldEscalate(bug), true);
+		assert.equal(shouldEscalate(bug, { softError: true }), true);
+	});
 });

package/src/lib/error-classifier.ts

@@ -1,4 +1,5 @@
 import { ApiError } from "./api";
+import { NetworkError } from "./network-error";
 
 /**
  * Extract an HTTP status code from a thrown error, regardless of which client
@@ -55,14 +56,50 @@ export const isAbortError = (error: unknown): boolean => {
 	return false;
 };
 
+const isOffline = (): boolean =>
+	typeof navigator !== "undefined" && navigator.onLine === false;
+
+/**
+ * A transport failure from a wifi drop, tab wake, captive portal, or a timeout:
+ * the request never reached a server, so it is environmental, not a proven
+ * first-party failure.
+ *
+ * This is decided at the fetch boundary, not inferred here. Every app-owned
+ * request goes through `taggedFetch`, which knows a `fetch()` rejection is
+ * transport-level because `fetch` rejects for no other reason, and tags it a
+ * `NetworkError`. Reading that tag is exact; matching browser failure strings
+ * was not — the list is open-ended (WebKit alone has four, undici another) and
+ * anything missed would put a full-screen fatal page in front of someone who
+ * had merely walked out of wifi range.
+ *
+ * `navigator.onLine === false` is kept as a second signal for an error that
+ * reached us from outside that boundary while the browser reports no
+ * connectivity at all.
+ */
+export const isNetworkError = (error: unknown): boolean => {
+	if (isAbortError(error)) return false;
+	if (hasHttpStatus(error)) return false;
+	if (error instanceof NetworkError) return true;
+	return isOffline();
+};
+
+/**
+ * An exception raised by our own client code rather than by a request: it
+ * carries no HTTP status, is not an abort, and was not tagged as transport.
+ * That leaves a programming error — the one class the user can do nothing
+ * about and must never be asked to shrug off.
+ */
+export const isClientBug = (error: unknown): boolean =>
+	!hasHttpStatus(error) && !isAbortError(error) && !isNetworkError(error);
+
 /**
- * A statusless transport/network failure (`TypeError: Failed to fetch` from a
- * wifi drop, tab wake, captive portal, or a background refetch): the request
- * never reached a server, so it is environmental, not a proven first-party
- * failure. Excludes deliberate aborts (also statusless, but their own category).
+ * Fatal with no opt-out: our API answered "I'm broken", or our own code threw.
+ * Neither is something a call site can reclassify as soft, and neither may be
+ * reduced to a dismissible banner — both belong on the full-screen page, which
+ * offers a way forward and a bug report (issue #55).
  */
-export const isNetworkError = (error: unknown): boolean =>
-	!isAbortError(error) && !hasHttpStatus(error);
+export const isAlwaysFatal = (error: unknown): boolean =>
+	isServerError(error) || isClientBug(error);
 
 const isSoftErrorMeta = (meta: Record<string, unknown> | undefined): boolean =>
 	meta?.softError === true;
@@ -76,10 +113,12 @@ const isSoftErrorMeta = (meta: Record<string, unknown> | undefined): boolean =>
  *  2. A 5xx (500–599) ALWAYS escalates — no opt-out, even on a background
  *     refetch, even when the call site marked `meta.softError`. Our API
  *     answered "I'm broken"; that is never benign.
- *  3. The ONLY soft (do-NOT-escalate) exemptions:
+ *  3. A client-side exception ALWAYS escalates, on the same terms. It is our
+ *     bug; there is nothing for the user to retry and nothing to dismiss.
+ *  4. The ONLY soft (do-NOT-escalate) exemptions:
  *     a. aborts / cancellations — never a failure;
- *     b. statusless network/offline errors — environmental, recovered by React
- *        Query's reconnect/retry;
+ *     b. network/offline errors — environmental, recovered by React Query's
+ *        reconnect/retry;
  *     c. a non-5xx error on a query/mutation that opted out via
  *        `meta.softError === true` — the call site owns that error's UX
  *        (e.g. a 404 empty state, a 4xx "Reconnect" banner).
@@ -91,6 +130,7 @@ export const shouldEscalate = (
 	if (isServerError(error)) return true;
 	if (isAbortError(error)) return false;
 	if (isNetworkError(error)) return false;
+	if (isAlwaysFatal(error)) return true;
 	if (isSoftErrorMeta(meta)) return false;
 	return true;
 };

package/src/lib/network-error.ts

@@ -0,0 +1,58 @@
+/**
+ * Transport failures are identified where they happen, not guessed at later.
+ *
+ * `fetch()` rejects for exactly two reasons: the request never completed at the
+ * transport level (DNS, TLS, connection lost, captive portal, timeout), or it
+ * was aborted. It never rejects for an HTTP status. So the one place that knows
+ * for certain that an error is a network error is the call site that wrapped
+ * `fetch` — everywhere downstream is guessing.
+ *
+ * Guessing is what the classifier used to do, first by treating every error
+ * without an HTTP status as a network blip (which swallowed our own exceptions),
+ * then by matching browser failure strings (which is unbounded: WebKit alone
+ * says "Failed to fetch", "Load failed", "The network connection was lost." and
+ * "The request timed out.", and undici says "fetch failed"). Tagging at the
+ * boundary makes the question decidable and the browser's wording irrelevant.
+ */
+
+/** A request that never reached a server. Always soft — never escalated. */
+export class NetworkError extends Error {
+	constructor(cause: unknown) {
+		super(
+			cause instanceof Error && cause.message
+				? cause.message
+				: "The request could not be completed.",
+			{ cause },
+		);
+		this.name = "NetworkError";
+	}
+}
+
+/**
+ * A deliberate cancellation — a route change, a React Query cancellation, a
+ * caller's own `AbortController`. Its own category: not a failure at all, so it
+ * passes through untagged.
+ *
+ * `AbortSignal.timeout()` rejects with a `TimeoutError` rather than an
+ * `AbortError`, and a timeout IS a transport failure, so it is deliberately not
+ * matched here and gets tagged like any other.
+ */
+const isDeliberateAbort = (error: unknown): boolean =>
+	typeof error === "object" &&
+	error !== null &&
+	"name" in error &&
+	(error as { name?: unknown }).name === "AbortError";
+
+/**
+ * `fetch`, with transport failures tagged. Every app-owned request goes through
+ * this — the generated client is configured with it, and the hand-written
+ * wrapper calls it — so a `NetworkError` downstream is a fact, not an inference.
+ */
+export const taggedFetch: typeof fetch = async (input, init) => {
+	try {
+		return await fetch(input, init);
+	} catch (error) {
+		if (isDeliberateAbort(error)) throw error;
+		throw new NetworkError(error);
+	}
+};

package/src/lib/query-error-handler.test.ts

@@ -3,6 +3,7 @@ import { afterEach, describe, it } from "node:test";
 import type { Mutation, Query } from "@tanstack/react-query";
 import { ApiError } from "./api";
 import { __resetFatalError, subscribeFatalError } from "./fatal-error";
+import { NetworkError } from "./network-error";
 import {
 	handleMutationCacheError,
 	handleQueryCacheError,
@@ -95,12 +96,15 @@ describe("handleQueryCacheError (fail-fast contract #1059)", () => {
 		assert.equal(escalated, false);
 	});
 
-	it("does NOT escalate a statusless network blip", () => {
+	it("does NOT escalate a network blip tagged at the fetch boundary", () => {
 		let escalated = false;
 		subscribeFatalError(() => {
 			escalated = true;
 		});
-		handleQueryCacheError(new TypeError("Failed to fetch"), fakeQuery());
+		handleQueryCacheError(
+			new NetworkError(new TypeError("Failed to fetch")),
+			fakeQuery(),
+		);
 		assert.equal(escalated, false);
 	});
 });

package/src/lib/query-escalation.integration.test.ts

@@ -11,6 +11,7 @@ import { afterEach, describe, it } from "node:test";
 import { MutationCache, QueryCache, QueryClient } from "@tanstack/react-query";
 import { ApiError } from "./api";
 import { __resetFatalError, subscribeFatalError } from "./fatal-error";
+import { NetworkError } from "./network-error";
 import {
 	handleMutationCacheError,
 	handleQueryCacheError,
@@ -117,7 +118,7 @@ describe("global query/mutation escalation", () => {
 		assert.deepEqual(seen, ["not found"]);
 	});
 
-	it("a statusless `Failed to fetch` (offline blip) from a query does NOT escalate", async () => {
+	it("an offline blip tagged at the fetch boundary does NOT escalate", async () => {
 		let escalated = false;
 		subscribeFatalError(() => {
 			escalated = true;
@@ -128,7 +129,7 @@ describe("global query/mutation escalation", () => {
 			.fetchQuery({
 				queryKey: ["offline"],
 				queryFn: async () => {
-					throw new TypeError("Failed to fetch");
+					throw new NetworkError(new TypeError("Failed to fetch"));
 				},
 			})
 			.catch(() => {});

package/src/lib/route-search-query.test.ts

@@ -0,0 +1,48 @@
+/**
+ * `q` lives on the parent `/mail` route, but every child re-declares it: a
+ * child's `validateSearch` is authoritative for its own URL, so a child that
+ * omits `q` strips it. The top bar mounts a search field on all four of these
+ * routes, so a stripped `q` means typing a query does nothing and the query is
+ * lost on the next navigation.
+ */
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { z } from "zod";
+import { Route as MailboxRoute } from "../routes/mail/$mailboxId";
+import { Route as FlaggedRoute } from "../routes/mail/flagged";
+import { Route as BriefRoute } from "../routes/mail/index";
+import { Route as OutboxRoute } from "../routes/mail/outbox";
+
+const routes = {
+	"/mail/ (daily brief)": BriefRoute,
+	"/mail/flagged": FlaggedRoute,
+	"/mail/outbox": OutboxRoute,
+	"/mail/$mailboxId": MailboxRoute,
+};
+
+const parse = (route: { options: { validateSearch?: unknown } }) => {
+	const schema = route.options.validateSearch;
+	assert.ok(
+		schema instanceof z.ZodType,
+		"route must validate its search with a zod schema",
+	);
+	return (search: Record<string, unknown>) => schema.parse(search);
+};
+
+describe("every /mail child route carries `q` through its own validation", () => {
+	for (const [name, route] of Object.entries(routes)) {
+		it(`${name} preserves a query`, () => {
+			const parsed = parse(route)({ q: "invoice" }) as { q?: string };
+			assert.equal(
+				parsed.q,
+				"invoice",
+				`${name} drops q, so the top bar's search field is inert there`,
+			);
+		});
+
+		it(`${name} leaves q absent when there is none`, () => {
+			const parsed = parse(route)({}) as { q?: string };
+			assert.equal(parsed.q, undefined);
+		});
+	}
+});