@remit/web-client 0.0.1

package/src/routeTree.gen.ts

@@ -0,0 +1,392 @@
+/* eslint-disable */
+
+// @ts-nocheck
+
+// noinspection JSUnusedGlobalSymbols
+
+// This file was automatically generated by TanStack Router.
+// You should NOT make any changes in this file as it will be overwritten.
+// Additionally, you should also exclude this file from your linter and/or formatter to prevent it from being checked or modified.
+
+import { Route as rootRouteImport } from './routes/__root'
+import { Route as IndexRouteImport } from './routes/index'
+import { Route as MailRouteImport } from './routes/mail'
+import { Route as OnboardingRouteImport } from './routes/onboarding'
+import { Route as SettingsRouteImport } from './routes/settings'
+import { Route as MailIndexRouteImport } from './routes/mail/index'
+import { Route as MailMailboxIdRouteImport } from './routes/mail/$mailboxId'
+import { Route as MailFlaggedRouteImport } from './routes/mail/flagged'
+import { Route as MailOutboxRouteImport } from './routes/mail/outbox'
+import { Route as SettingsIndexRouteImport } from './routes/settings/index'
+import { Route as SettingsAccountsRouteImport } from './routes/settings/accounts'
+import { Route as SettingsAdvancedRouteImport } from './routes/settings/advanced'
+import { Route as SettingsAppearanceRouteImport } from './routes/settings/appearance'
+import { Route as SettingsFiltersRouteImport } from './routes/settings/filters'
+import { Route as SettingsFoldersRouteImport } from './routes/settings/folders'
+import { Route as SettingsSendersRouteImport } from './routes/settings/senders'
+import { Route as SettingsSuggestedVipsRouteImport } from './routes/settings/suggested-vips'
+
+const IndexRoute = IndexRouteImport.update({
+  id: '/',
+  path: '/',
+  getParentRoute: () => rootRouteImport,
+} as any)
+const MailRoute = MailRouteImport.update({
+  id: '/mail',
+  path: '/mail',
+  getParentRoute: () => rootRouteImport,
+} as any)
+const OnboardingRoute = OnboardingRouteImport.update({
+  id: '/onboarding',
+  path: '/onboarding',
+  getParentRoute: () => rootRouteImport,
+} as any)
+const SettingsRoute = SettingsRouteImport.update({
+  id: '/settings',
+  path: '/settings',
+  getParentRoute: () => rootRouteImport,
+} as any)
+const MailIndexRoute = MailIndexRouteImport.update({
+  id: '/',
+  path: '/',
+  getParentRoute: () => MailRoute,
+} as any)
+const MailMailboxIdRoute = MailMailboxIdRouteImport.update({
+  id: '/$mailboxId',
+  path: '/$mailboxId',
+  getParentRoute: () => MailRoute,
+} as any)
+const MailFlaggedRoute = MailFlaggedRouteImport.update({
+  id: '/flagged',
+  path: '/flagged',
+  getParentRoute: () => MailRoute,
+} as any)
+const MailOutboxRoute = MailOutboxRouteImport.update({
+  id: '/outbox',
+  path: '/outbox',
+  getParentRoute: () => MailRoute,
+} as any)
+const SettingsIndexRoute = SettingsIndexRouteImport.update({
+  id: '/',
+  path: '/',
+  getParentRoute: () => SettingsRoute,
+} as any)
+const SettingsAccountsRoute = SettingsAccountsRouteImport.update({
+  id: '/accounts',
+  path: '/accounts',
+  getParentRoute: () => SettingsRoute,
+} as any)
+const SettingsAdvancedRoute = SettingsAdvancedRouteImport.update({
+  id: '/advanced',
+  path: '/advanced',
+  getParentRoute: () => SettingsRoute,
+} as any)
+const SettingsAppearanceRoute = SettingsAppearanceRouteImport.update({
+  id: '/appearance',
+  path: '/appearance',
+  getParentRoute: () => SettingsRoute,
+} as any)
+const SettingsFiltersRoute = SettingsFiltersRouteImport.update({
+  id: '/filters',
+  path: '/filters',
+  getParentRoute: () => SettingsRoute,
+} as any)
+const SettingsFoldersRoute = SettingsFoldersRouteImport.update({
+  id: '/folders',
+  path: '/folders',
+  getParentRoute: () => SettingsRoute,
+} as any)
+const SettingsSendersRoute = SettingsSendersRouteImport.update({
+  id: '/senders',
+  path: '/senders',
+  getParentRoute: () => SettingsRoute,
+} as any)
+const SettingsSuggestedVipsRoute = SettingsSuggestedVipsRouteImport.update({
+  id: '/suggested-vips',
+  path: '/suggested-vips',
+  getParentRoute: () => SettingsRoute,
+} as any)
+
+export interface FileRoutesByFullPath {
+  '/': typeof IndexRoute
+  '/mail': typeof MailRouteWithChildren
+  '/onboarding': typeof OnboardingRoute
+  '/settings': typeof SettingsRouteWithChildren
+  '/mail/$mailboxId': typeof MailMailboxIdRoute
+  '/mail/flagged': typeof MailFlaggedRoute
+  '/mail/outbox': typeof MailOutboxRoute
+  '/settings/accounts': typeof SettingsAccountsRoute
+  '/settings/advanced': typeof SettingsAdvancedRoute
+  '/settings/appearance': typeof SettingsAppearanceRoute
+  '/settings/filters': typeof SettingsFiltersRoute
+  '/settings/folders': typeof SettingsFoldersRoute
+  '/settings/senders': typeof SettingsSendersRoute
+  '/settings/suggested-vips': typeof SettingsSuggestedVipsRoute
+  '/mail/': typeof MailIndexRoute
+  '/settings/': typeof SettingsIndexRoute
+}
+export interface FileRoutesByTo {
+  '/': typeof IndexRoute
+  '/onboarding': typeof OnboardingRoute
+  '/mail/$mailboxId': typeof MailMailboxIdRoute
+  '/mail/flagged': typeof MailFlaggedRoute
+  '/mail/outbox': typeof MailOutboxRoute
+  '/settings/accounts': typeof SettingsAccountsRoute
+  '/settings/advanced': typeof SettingsAdvancedRoute
+  '/settings/appearance': typeof SettingsAppearanceRoute
+  '/settings/filters': typeof SettingsFiltersRoute
+  '/settings/folders': typeof SettingsFoldersRoute
+  '/settings/senders': typeof SettingsSendersRoute
+  '/settings/suggested-vips': typeof SettingsSuggestedVipsRoute
+  '/mail': typeof MailIndexRoute
+  '/settings': typeof SettingsIndexRoute
+}
+export interface FileRoutesById {
+  __root__: typeof rootRouteImport
+  '/': typeof IndexRoute
+  '/mail': typeof MailRouteWithChildren
+  '/onboarding': typeof OnboardingRoute
+  '/settings': typeof SettingsRouteWithChildren
+  '/mail/$mailboxId': typeof MailMailboxIdRoute
+  '/mail/flagged': typeof MailFlaggedRoute
+  '/mail/outbox': typeof MailOutboxRoute
+  '/settings/accounts': typeof SettingsAccountsRoute
+  '/settings/advanced': typeof SettingsAdvancedRoute
+  '/settings/appearance': typeof SettingsAppearanceRoute
+  '/settings/filters': typeof SettingsFiltersRoute
+  '/settings/folders': typeof SettingsFoldersRoute
+  '/settings/senders': typeof SettingsSendersRoute
+  '/settings/suggested-vips': typeof SettingsSuggestedVipsRoute
+  '/mail/': typeof MailIndexRoute
+  '/settings/': typeof SettingsIndexRoute
+}
+export interface FileRouteTypes {
+  fileRoutesByFullPath: FileRoutesByFullPath
+  fullPaths:
+    | '/'
+    | '/mail'
+    | '/onboarding'
+    | '/settings'
+    | '/mail/$mailboxId'
+    | '/mail/flagged'
+    | '/mail/outbox'
+    | '/settings/accounts'
+    | '/settings/advanced'
+    | '/settings/appearance'
+    | '/settings/filters'
+    | '/settings/folders'
+    | '/settings/senders'
+    | '/settings/suggested-vips'
+    | '/mail/'
+    | '/settings/'
+  fileRoutesByTo: FileRoutesByTo
+  to:
+    | '/'
+    | '/onboarding'
+    | '/mail/$mailboxId'
+    | '/mail/flagged'
+    | '/mail/outbox'
+    | '/settings/accounts'
+    | '/settings/advanced'
+    | '/settings/appearance'
+    | '/settings/filters'
+    | '/settings/folders'
+    | '/settings/senders'
+    | '/settings/suggested-vips'
+    | '/mail'
+    | '/settings'
+  id:
+    | '__root__'
+    | '/'
+    | '/mail'
+    | '/onboarding'
+    | '/settings'
+    | '/mail/$mailboxId'
+    | '/mail/flagged'
+    | '/mail/outbox'
+    | '/settings/accounts'
+    | '/settings/advanced'
+    | '/settings/appearance'
+    | '/settings/filters'
+    | '/settings/folders'
+    | '/settings/senders'
+    | '/settings/suggested-vips'
+    | '/mail/'
+    | '/settings/'
+  fileRoutesById: FileRoutesById
+}
+export interface RootRouteChildren {
+  IndexRoute: typeof IndexRoute
+  MailRoute: typeof MailRouteWithChildren
+  OnboardingRoute: typeof OnboardingRoute
+  SettingsRoute: typeof SettingsRouteWithChildren
+}
+
+declare module '@tanstack/react-router' {
+  interface FileRoutesByPath {
+    '/': {
+      id: '/'
+      path: '/'
+      fullPath: '/'
+      preLoaderRoute: typeof IndexRouteImport
+      parentRoute: typeof rootRouteImport
+    }
+    '/mail': {
+      id: '/mail'
+      path: '/mail'
+      fullPath: '/mail'
+      preLoaderRoute: typeof MailRouteImport
+      parentRoute: typeof rootRouteImport
+    }
+    '/onboarding': {
+      id: '/onboarding'
+      path: '/onboarding'
+      fullPath: '/onboarding'
+      preLoaderRoute: typeof OnboardingRouteImport
+      parentRoute: typeof rootRouteImport
+    }
+    '/settings': {
+      id: '/settings'
+      path: '/settings'
+      fullPath: '/settings'
+      preLoaderRoute: typeof SettingsRouteImport
+      parentRoute: typeof rootRouteImport
+    }
+    '/mail/': {
+      id: '/mail/'
+      path: '/'
+      fullPath: '/mail/'
+      preLoaderRoute: typeof MailIndexRouteImport
+      parentRoute: typeof MailRoute
+    }
+    '/mail/$mailboxId': {
+      id: '/mail/$mailboxId'
+      path: '/$mailboxId'
+      fullPath: '/mail/$mailboxId'
+      preLoaderRoute: typeof MailMailboxIdRouteImport
+      parentRoute: typeof MailRoute
+    }
+    '/mail/flagged': {
+      id: '/mail/flagged'
+      path: '/flagged'
+      fullPath: '/mail/flagged'
+      preLoaderRoute: typeof MailFlaggedRouteImport
+      parentRoute: typeof MailRoute
+    }
+    '/mail/outbox': {
+      id: '/mail/outbox'
+      path: '/outbox'
+      fullPath: '/mail/outbox'
+      preLoaderRoute: typeof MailOutboxRouteImport
+      parentRoute: typeof MailRoute
+    }
+    '/settings/': {
+      id: '/settings/'
+      path: '/'
+      fullPath: '/settings/'
+      preLoaderRoute: typeof SettingsIndexRouteImport
+      parentRoute: typeof SettingsRoute
+    }
+    '/settings/accounts': {
+      id: '/settings/accounts'
+      path: '/accounts'
+      fullPath: '/settings/accounts'
+      preLoaderRoute: typeof SettingsAccountsRouteImport
+      parentRoute: typeof SettingsRoute
+    }
+    '/settings/advanced': {
+      id: '/settings/advanced'
+      path: '/advanced'
+      fullPath: '/settings/advanced'
+      preLoaderRoute: typeof SettingsAdvancedRouteImport
+      parentRoute: typeof SettingsRoute
+    }
+    '/settings/appearance': {
+      id: '/settings/appearance'
+      path: '/appearance'
+      fullPath: '/settings/appearance'
+      preLoaderRoute: typeof SettingsAppearanceRouteImport
+      parentRoute: typeof SettingsRoute
+    }
+    '/settings/filters': {
+      id: '/settings/filters'
+      path: '/filters'
+      fullPath: '/settings/filters'
+      preLoaderRoute: typeof SettingsFiltersRouteImport
+      parentRoute: typeof SettingsRoute
+    }
+    '/settings/folders': {
+      id: '/settings/folders'
+      path: '/folders'
+      fullPath: '/settings/folders'
+      preLoaderRoute: typeof SettingsFoldersRouteImport
+      parentRoute: typeof SettingsRoute
+    }
+    '/settings/senders': {
+      id: '/settings/senders'
+      path: '/senders'
+      fullPath: '/settings/senders'
+      preLoaderRoute: typeof SettingsSendersRouteImport
+      parentRoute: typeof SettingsRoute
+    }
+    '/settings/suggested-vips': {
+      id: '/settings/suggested-vips'
+      path: '/suggested-vips'
+      fullPath: '/settings/suggested-vips'
+      preLoaderRoute: typeof SettingsSuggestedVipsRouteImport
+      parentRoute: typeof SettingsRoute
+    }
+  }
+}
+
+interface MailRouteChildren {
+  MailMailboxIdRoute: typeof MailMailboxIdRoute
+  MailFlaggedRoute: typeof MailFlaggedRoute
+  MailOutboxRoute: typeof MailOutboxRoute
+  MailIndexRoute: typeof MailIndexRoute
+}
+
+const MailRouteChildren: MailRouteChildren = {
+  MailMailboxIdRoute: MailMailboxIdRoute,
+  MailFlaggedRoute: MailFlaggedRoute,
+  MailOutboxRoute: MailOutboxRoute,
+  MailIndexRoute: MailIndexRoute,
+}
+
+const MailRouteWithChildren = MailRoute._addFileChildren(MailRouteChildren)
+
+interface SettingsRouteChildren {
+  SettingsAccountsRoute: typeof SettingsAccountsRoute
+  SettingsAdvancedRoute: typeof SettingsAdvancedRoute
+  SettingsAppearanceRoute: typeof SettingsAppearanceRoute
+  SettingsFiltersRoute: typeof SettingsFiltersRoute
+  SettingsFoldersRoute: typeof SettingsFoldersRoute
+  SettingsSendersRoute: typeof SettingsSendersRoute
+  SettingsSuggestedVipsRoute: typeof SettingsSuggestedVipsRoute
+  SettingsIndexRoute: typeof SettingsIndexRoute
+}
+
+const SettingsRouteChildren: SettingsRouteChildren = {
+  SettingsAccountsRoute: SettingsAccountsRoute,
+  SettingsAdvancedRoute: SettingsAdvancedRoute,
+  SettingsAppearanceRoute: SettingsAppearanceRoute,
+  SettingsFiltersRoute: SettingsFiltersRoute,
+  SettingsFoldersRoute: SettingsFoldersRoute,
+  SettingsSendersRoute: SettingsSendersRoute,
+  SettingsSuggestedVipsRoute: SettingsSuggestedVipsRoute,
+  SettingsIndexRoute: SettingsIndexRoute,
+}
+
+const SettingsRouteWithChildren = SettingsRoute._addFileChildren(
+  SettingsRouteChildren,
+)
+
+const rootRouteChildren: RootRouteChildren = {
+  IndexRoute: IndexRoute,
+  MailRoute: MailRouteWithChildren,
+  OnboardingRoute: OnboardingRoute,
+  SettingsRoute: SettingsRouteWithChildren,
+}
+export const routeTree = rootRouteImport
+  ._addFileChildren(rootRouteChildren)
+  ._addFileTypes<FileRouteTypes>()

package/src/router.test.ts

@@ -0,0 +1,81 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import type { Telemetry } from "./lib/telemetry";
+
+interface SubscribeCall {
+	eventType: string;
+	fn: (event: { toLocation: { pathname: string } }) => void;
+}
+
+interface RouterStub {
+	subscribeCalls: SubscribeCall[];
+	subscribe(
+		eventType: string,
+		fn: (event: { toLocation: { pathname: string } }) => void,
+	): () => void;
+}
+
+function makeRouterStub(): RouterStub {
+	const stub: RouterStub = {
+		subscribeCalls: [],
+		subscribe(eventType, fn) {
+			stub.subscribeCalls.push({ eventType, fn });
+			return () => undefined;
+		},
+	};
+	return stub;
+}
+
+function makeTelemetryStub(): Telemetry & { pageViews: string[] } {
+	const stub = {
+		pageViews: [] as string[],
+		recordPageView(path: string) {
+			stub.pageViews.push(path);
+		},
+		recordError: () => undefined,
+		recordEvent: () => undefined,
+		recordTiming: () => undefined,
+	};
+	return stub;
+}
+
+function wirePageViews(router: RouterStub, telemetry: Telemetry): void {
+	router.subscribe("onResolved", (event) => {
+		telemetry.recordPageView(event.toLocation.pathname);
+	});
+}
+
+describe("router page-view telemetry wiring", () => {
+	it("subscribes to onResolved", () => {
+		const router = makeRouterStub();
+		const telemetry = makeTelemetryStub();
+		wirePageViews(router, telemetry);
+		assert.equal(router.subscribeCalls.length, 1);
+		assert.equal(router.subscribeCalls[0]?.eventType, "onResolved");
+	});
+
+	it("calls recordPageView with pathname on each navigation", () => {
+		const router = makeRouterStub();
+		const telemetry = makeTelemetryStub();
+		wirePageViews(router, telemetry);
+
+		const handler = router.subscribeCalls[0]?.fn;
+		assert.ok(handler, "Expected a subscribe handler");
+
+		handler({ toLocation: { pathname: "/mail" } });
+		handler({ toLocation: { pathname: "/settings" } });
+
+		assert.deepEqual(telemetry.pageViews, ["/mail", "/settings"]);
+	});
+
+	it("is a no-op when telemetry is noopTelemetry (does not throw)", () => {
+		const router = makeRouterStub();
+		const telemetry = makeTelemetryStub();
+		telemetry.recordPageView = () => undefined;
+		wirePageViews(router, telemetry);
+
+		const handler = router.subscribeCalls[0]?.fn;
+		assert.ok(handler);
+		assert.doesNotThrow(() => handler({ toLocation: { pathname: "/mail" } }));
+	});
+});

package/src/router.tsx

@@ -0,0 +1,31 @@
+import type { QueryClient } from "@tanstack/react-query";
+import { createRouter } from "@tanstack/react-router";
+import type { Telemetry } from "./lib/telemetry";
+import { routeTree } from "./routeTree.gen";
+
+export interface RouterContext {
+	queryClient: QueryClient;
+}
+
+export const createAppRouter = (
+	queryClient: QueryClient,
+	telemetry: Telemetry,
+) => {
+	const router = createRouter({
+		routeTree,
+		context: { queryClient },
+		defaultPreload: "intent",
+	});
+
+	router.subscribe("onResolved", (event) => {
+		telemetry.recordPageView(event.toLocation.pathname);
+	});
+
+	return router;
+};
+
+declare module "@tanstack/react-router" {
+	interface Register {
+		router: ReturnType<typeof createAppRouter>;
+	}
+}

package/src/routes/__root.tsx

@@ -0,0 +1,69 @@
+import {
+	createRootRouteWithContext,
+	type ErrorComponentProps,
+	Outlet,
+} from "@tanstack/react-router";
+import { Suspense } from "react";
+import { useTranslation } from "react-i18next";
+import { ComposeProvider } from "@/components/compose/ComposeProvider";
+import { AppShellSkeleton } from "@/components/layout/AppShellSkeleton";
+import { ErrorBannerProvider } from "@/components/ui/ErrorBannerProvider";
+import {
+	FatalErrorOverlay,
+	FatalErrorScreen,
+} from "@/components/ui/FatalErrorOverlay";
+import { isServerError } from "@/lib/error-classifier";
+import { reportFatalError } from "@/lib/fatal-error";
+import type { RouterContext } from "@/router";
+
+const RootErrorComponent = ({ error, reset, info }: ErrorComponentProps) => {
+	// Everything that bubbles to the route boundary escalates to the loud
+	// full-screen fatal page — never the soft grey "Something went wrong" that
+	// implied recovery. A bubbled 5xx is transient (Retry re-runs the loader via
+	// reset); a caught render exception is deterministic — retry re-crashes, so
+	// it is fatal with no Retry, offering a safe route out instead (issue #1231).
+	const recoverable = isServerError(error);
+	const fatal = reportFatalError(error, {
+		recoverable,
+		componentStack: info?.componentStack,
+	});
+	return (
+		<FatalErrorScreen fatal={fatal} onRetry={recoverable ? reset : undefined} />
+	);
+};
+
+export const Route = createRootRouteWithContext<RouterContext>()({
+	component: RootLayout,
+	errorComponent: RootErrorComponent,
+});
+
+const SkipLink = () => {
+	// Provide a string fallback so Suspense doesn't render the raw i18n key
+	// while the common namespace is still loading over HTTP.
+	const { t } = useTranslation("common", { useSuspense: false });
+
+	return (
+		<a
+			href="#main-content"
+			className="sr-only focus:not-sr-only focus:absolute focus:z-50 focus:p-4 focus:bg-canvas focus:text-fg focus:rounded-md"
+		>
+			{t("accessibility.skipToContent", "Skip to main content")}
+		</a>
+	);
+};
+
+function RootLayout() {
+	return (
+		<ErrorBannerProvider>
+			<ComposeProvider>
+				<SkipLink />
+				<main id="main-content" className="h-dvh overflow-hidden">
+					<Suspense fallback={<AppShellSkeleton />}>
+						<Outlet />
+					</Suspense>
+				</main>
+			</ComposeProvider>
+			<FatalErrorOverlay />
+		</ErrorBannerProvider>
+	);
+}

package/src/routes/index.tsx

@@ -0,0 +1,7 @@
+import { createFileRoute, redirect } from "@tanstack/react-router";
+
+export const Route = createFileRoute("/")({
+	beforeLoad: () => {
+		throw redirect({ to: "/mail" });
+	},
+});

package/src/routes/mail/$mailboxId.tsx

@@ -0,0 +1,27 @@
+/**
+ * /mail/$mailboxId route — shell activation only.
+ *
+ * The component returns null because rendering is lifted to `mail.tsx`
+ * which reads the active mailboxId via `useRouterState` and mounts
+ * `<MailboxPane>` directly into `<AppShellSlotted>` slots. TanStack Router
+ * still needs this file to:
+ *   - Register the route so URL matching works
+ *   - Validate the search params so selectedMessageId is properly typed
+ */
+import { createFileRoute } from "@tanstack/react-router";
+import { z } from "zod";
+
+// Search schema includes q from parent route for proper inheritance
+const mailboxSearchSchema = z.object({
+	selectedMessageId: z.string().optional(),
+	// A tapped semantic "Related" hit can point at a message outside the loaded
+	// list; carrying its thread lets the mailbox open it directly (the mailbox is
+	// the route param). See `buildConversationTarget`.
+	selectedThreadId: z.string().optional(),
+	q: z.string().optional(),
+});
+
+export const Route = createFileRoute("/mail/$mailboxId")({
+	component: () => null,
+	validateSearch: mailboxSearchSchema,
+});

package/src/routes/mail/flagged.tsx

@@ -0,0 +1,37 @@
+/**
+ * /mail/flagged route (Flagged virtual mailbox) — shell activation only.
+ *
+ * The component returns null because rendering is lifted to `mail.tsx`, which
+ * detects the flagged route via `useRouterState` and mounts `<FlaggedPane>`
+ * directly into `<AppShellSlotted>` slots — the same pattern the brief uses.
+ */
+import {
+	createFileRoute,
+	type ErrorComponentProps,
+} from "@tanstack/react-router";
+import { z } from "zod";
+import { ErrorState } from "@/components/ui/ErrorState";
+
+const FlaggedError = ({ error, reset }: ErrorComponentProps) => (
+	<div className="flex h-full items-center justify-center bg-canvas p-4">
+		<ErrorState
+			title="Couldn't load your flagged mail"
+			error={error}
+			onRetry={reset}
+		/>
+	</div>
+);
+
+// `q` is inherited from the parent /mail route; re-declared here so it survives
+// this route's own search validation and isn't dropped when navigating with a
+// functional search updater.
+const flaggedSearchSchema = z.object({
+	selectedMessageId: z.string().optional(),
+	q: z.string().optional(),
+});
+
+export const Route = createFileRoute("/mail/flagged")({
+	component: () => null,
+	validateSearch: flaggedSearchSchema,
+	errorComponent: FlaggedError,
+});

package/src/routes/mail/index.tsx

@@ -0,0 +1,41 @@
+/**
+ * /mail/ route (Daily Brief) — shell activation only.
+ *
+ * The component returns null because rendering is lifted to `mail.tsx`
+ * which detects the brief route via `useRouterState` and mounts
+ * `<BriefPane>` directly into `<AppShellSlotted>` slots.
+ */
+import {
+	createFileRoute,
+	type ErrorComponentProps,
+} from "@tanstack/react-router";
+import { z } from "zod";
+import { ErrorState } from "@/components/ui/ErrorState";
+
+const MailIndexError = ({ error, reset }: ErrorComponentProps) => (
+	<div className="flex h-full items-center justify-center bg-canvas p-4">
+		<ErrorState
+			title="Couldn't load your mailboxes"
+			error={error}
+			onRetry={reset}
+		/>
+	</div>
+);
+
+// `q` is inherited from the parent /mail route; re-declared here so it
+// survives this route's own search validation and isn't dropped when
+// navigating with a functional search updater.
+const briefSearchSchema = z.object({
+	selectedMessageId: z.string().optional(),
+	// A tapped semantic "Related" hit can point at a message outside the loaded
+	// brief list; carrying its thread + mailbox lets the brief open it directly.
+	selectedThreadId: z.string().optional(),
+	selectedMailboxId: z.string().optional(),
+	q: z.string().optional(),
+});
+
+export const Route = createFileRoute("/mail/")({
+	component: () => null,
+	validateSearch: briefSearchSchema,
+	errorComponent: MailIndexError,
+});