@remit/web-client 0.0.12 → 0.0.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/web-client",
-  "version": "0.0.12",
+  "version": "0.0.13",
   "type": "module",
   "description": "Remit web client, published as composable primitives — the app shell, auth shells, and runtime config. A distributor imports what it composes and bundles it.",
   "exports": {

package/src/components/layout/ComposeFab.tsx

@@ -1,16 +1,8 @@
-import { useLocation, useNavigate } from "@tanstack/react-router";
+import type { RemitImapAccountResponse } from "@remit/api-http-client/types.gen.ts";
+import { useLocation } from "@tanstack/react-router";
 import { Pencil } from "lucide-react";
-import { startTransition } from "react";
 import { useCompose } from "@/components/compose/ComposeProvider";
-
-/**
- * Returns true when `pathname` is `/mail/<id>` for any id other than
- * the reserved `outbox` segment. That route owns a `FullCompose` mount
- * point, so the FAB can open compose in-place. From every other route
- * the FAB has to send the user there first.
- */
-const isOnMailboxRoute = (pathname: string): boolean =>
-	/^\/mail\/(?!outbox)[^/?]+/.test(pathname);
+import { useGlobalCompose } from "@/hooks/useComposeTarget";
 
 /**
  * Primary mobile surfaces where the FAB belongs: anywhere under
@@ -21,30 +13,34 @@ const isOnMailboxRoute = (pathname: string): boolean =>
 const isOnPrimaryMobileRoute = (pathname: string): boolean =>
 	pathname.startsWith("/mail") || pathname.startsWith("/settings");
 
+interface ComposeFabProps {
+	accounts: RemitImapAccountResponse[];
+}
+
 /**
  * Floating Action Button for composing a new message. Mobile-only.
  *
  * Layout follows Material 3: 56×56 surface, 16px from the right and
  * bottom edges (plus the iOS safe-area inset). Hidden when any of:
- *   - Viewport is `≥ md` (desktop has compose in the sidebar / etc.).
+ *   - Viewport is `≥ lg` (1024px), where the top bar owns compose. The
+ *     `/mail` shell also stops mounting the FAB above that width; the
+ *     `lg:hidden` class covers the pre-hydration frame.
  *   - The compose surface is already open.
  *   - The user is reading a thread (`?selectedMessageId=…`) — the
  *     conversation's Reply/Forward action bar covers that workflow.
  *   - The user is not on a primary mobile route (`/mail` or
  *     `/settings`).
  *
- * From routes that don't host a `FullCompose` (everything except
- * `/mail/<mailboxId>` — i.e. `/mail`, `/mail/outbox`, `/settings/*`)
- * tapping the FAB opens compose state and navigates to `/mail`, which
- * the index loader redirects to the preferred mailbox (PR #138). The
- * compose state survives the route transition because `ComposeProvider`
- * lives in `__root.tsx`, so the destination route mounts straight into
- * compose.
+ * The tap itself is `useGlobalCompose`, shared with the desktop top bar:
+ * it opens compose in place on routes that mount `FullCompose` and
+ * otherwise carries the user to a real mailbox that does. Compose state
+ * survives that transition because `ComposeProvider` lives in
+ * `__root.tsx`.
  */
-export const ComposeFab = () => {
-	const { state, openCompose } = useCompose();
+export const ComposeFab = ({ accounts }: ComposeFabProps) => {
+	const { state } = useCompose();
 	const location = useLocation();
-	const navigate = useNavigate();
+	const compose = useGlobalCompose(accounts);
 
 	const search = location.search as Record<string, unknown> | undefined;
 	const isReadingThread =
@@ -58,21 +54,10 @@ export const ComposeFab = () => {
 	)
 		return null;
 
-	const handleClick = () => {
-		// Wrap in startTransition so the suspension that ComposeForm
-		// triggers on first mount (lazy chunks, queries) doesn't
-		// snap the surrounding chrome into a route-level fallback.
-		startTransition(() => {
-			openCompose({ mode: "new" });
-		});
-		if (isOnMailboxRoute(location.pathname)) return;
-		navigate({ to: "/mail" });
-	};
-
 	return (
 		<button
 			type="button"
-			onClick={handleClick}
+			onClick={compose}
 			aria-label="Compose new message"
 			className="lg:hidden fixed right-4 z-30 h-14 w-14 rounded-full bg-accent text-accent-fg shadow-lg flex items-center justify-center hover:opacity-90 active:scale-95 transition-all"
 			style={{

package/src/components/layout/MailTopBar.tsx

@@ -0,0 +1,64 @@
+/**
+ * MailTopBar — the app's one search surface and its global actions.
+ *
+ * Mounted above every pane by the `/mail` shell, so the field spans the nav,
+ * the list and the reading pane. It is the app's search, not the list's: the
+ * list header drops its own field wherever this bar is mounted, so exactly one
+ * search input exists on the page and the "/" shortcut has one target.
+ *
+ * The actions here are the ones that belong to the app rather than to whatever
+ * is currently listed or open — compose, bug report, account. Reply, delete,
+ * move and the rest stay on the reading pane's own toolbar, under this bar.
+ */
+import type { RemitImapAccountResponse } from "@remit/api-http-client/types.gen.ts";
+import { AppTopBar, Button, SearchBar } from "@remit/ui";
+import { SquarePen } from "lucide-react";
+import { AccountMenu } from "@/auth/AccountMenu";
+import { BugReportButton } from "@/components/ui/BugReportButton";
+import { useGlobalCompose } from "@/hooks/useComposeTarget";
+import { tooltipForAction } from "@/lib/keymap";
+import { useMailContext } from "@/lib/mail-context";
+
+interface MailTopBarProps {
+	accounts: RemitImapAccountResponse[];
+}
+
+export function MailTopBar({ accounts }: MailTopBarProps) {
+	const { searchInput, onSearchChange, onSearchClear, onSearchClearQuery } =
+		useMailContext();
+	const compose = useGlobalCompose(accounts);
+
+	return (
+		<AppTopBar
+			leading={
+				<span className="px-1 text-sm font-semibold tracking-tight text-fg">
+					remit
+				</span>
+			}
+			search={
+				<SearchBar
+					value={searchInput}
+					onChange={onSearchChange}
+					onClear={onSearchClear}
+					onClearQuery={onSearchClearQuery}
+					placeholder="Search all mail"
+					size="lg"
+				/>
+			}
+			actions={
+				<>
+					<Button
+						variant="ghost"
+						size="sm"
+						icon={<SquarePen className="size-4" />}
+						title={`Compose ${tooltipForAction("compose")}`}
+						aria-label="Compose"
+						onClick={compose}
+					/>
+					<BugReportButton />
+					<AccountMenu />
+				</>
+			}
+		/>
+	);
+}

package/src/components/mail/BriefPane.tsx

@@ -184,26 +184,15 @@ function BriefList() {
  */
 function BriefReading() {
 	const { conversation } = useBriefPane();
-	const {
-		onToggleIntelligence,
-		searchInput,
-		onSearchChange,
-		onSearchClear,
-		onSearchClearQuery,
-	} = useMailContext();
+	const { onToggleIntelligence } = useMailContext();
 
 	return (
 		<section className="flex h-full w-full min-w-0 flex-col bg-canvas">
 			<MessageToolbar
 				hasThread={Boolean(conversation)}
-				onCompose={() => undefined}
 				intelligenceOpen={false}
 				showIntelligenceToggle={false}
 				onToggleIntelligence={onToggleIntelligence}
-				searchValue={searchInput}
-				onSearchChange={onSearchChange}
-				onSearchClear={onSearchClear}
-				onSearchClearQuery={onSearchClearQuery}
 			/>
 			<div className="min-h-0 flex-1 overflow-hidden">
 				{conversation ? (

package/src/components/mail/FlaggedPane.tsx

@@ -128,26 +128,15 @@ function FlaggedListSlot() {
  */
 function FlaggedReading() {
 	const { selectedThread } = useFlaggedPane();
-	const {
-		onToggleIntelligence,
-		searchInput,
-		onSearchChange,
-		onSearchClear,
-		onSearchClearQuery,
-	} = useMailContext();
+	const { onToggleIntelligence } = useMailContext();
 
 	return (
 		<section className="flex h-full w-full min-w-0 flex-col bg-canvas">
 			<MessageToolbar
 				hasThread={Boolean(selectedThread)}
-				onCompose={() => undefined}
 				intelligenceOpen={false}
 				showIntelligenceToggle={false}
 				onToggleIntelligence={onToggleIntelligence}
-				searchValue={searchInput}
-				onSearchChange={onSearchChange}
-				onSearchClear={onSearchClear}
-				onSearchClearQuery={onSearchClearQuery}
 			/>
 			<div className="min-h-0 flex-1 overflow-hidden">
 				{selectedThread ? (

package/src/components/mail/MailListHeader.tsx

@@ -31,7 +31,7 @@ import {
 	useAppShellLayout,
 } from "@remit/ui";
 import { type ReactNode, useState } from "react";
-import { useLayoutTier } from "@/hooks/useLayoutTier";
+import { isSinglePaneTier, useLayoutTier } from "@/hooks/useLayoutTier";
 import { useMailContext } from "@/lib/mail-context";
 import { loadRecentSearches, saveRecentSearch } from "@/lib/recent-searches";
 import {
@@ -168,11 +168,15 @@ export function MailListHeader({
 			<MailHeader
 				title={title}
 				unreadCount={unreadCount}
-				// The list pane is narrow even on desktop, and the reading-pane
-				// toolbar owns the wide search; keep the header's search compact (a
-				// magnifier) at every width. On phone the magnifier opens the
-				// full-screen takeover above; on tablet it expands over the title.
+				// Desktop mounts the app top bar, which owns search for the whole
+				// shell — the list header shows no field there, so the page never
+				// has two search inputs competing for "/" and for focus. Below
+				// desktop the header keeps a compact magnifier: on phone it opens
+				// the full-screen takeover above, on tablet it expands over the
+				// title. `isSinglePaneTier` is the same predicate the shell gates
+				// the top bar on, so the two cannot drift into zero or two fields.
 				isDesktop={false}
+				showSearch={isSinglePaneTier(tier)}
 				onMenuClick={() => layout?.openNav()}
 				searchValue={searchInput}
 				onSearchChange={onSearchChange}

package/src/components/mail/MailboxPane.tsx

@@ -202,7 +202,6 @@ interface MailboxPaneContextValue {
 	onToolbarDiscardDraft: () => void;
 	onToolbarMove: (destMailboxId: string) => void;
 	composeState: ReturnType<typeof useCompose>["state"];
-	openCompose: () => void;
 	closeCompose: () => void;
 	hasRemitDraftOpen: boolean;
 	// Phone actions
@@ -843,7 +842,6 @@ function MailboxPaneProvider({
 		onToolbarDiscardDraft: handleToolbarDiscardDraft,
 		onToolbarMove: handleToolbarMove,
 		composeState,
-		openCompose: handleNewCompose,
 		closeCompose,
 		hasRemitDraftOpen,
 		onBack: goBack,
@@ -1044,10 +1042,7 @@ function MailboxReading() {
 		onToolbarDiscardDraft,
 		onToolbarMove,
 		composeState,
-		openCompose,
 	} = useMailboxPane();
-	const { searchInput, onSearchChange, onSearchClear, onSearchClearQuery } =
-		useMailContext();
 	const tier = useLayoutTier();
 	const isDesktop = tier === "desktop";
 	const hasThread = Boolean(conversation);
@@ -1078,14 +1073,9 @@ function MailboxReading() {
 		<section className="flex h-full w-full min-w-0 flex-col bg-canvas">
 			<MessageToolbar
 				hasThread={hasThread}
-				onCompose={openCompose}
 				intelligenceOpen={showIntelligence}
 				showIntelligenceToggle={isDesktop && hasThread}
 				onToggleIntelligence={onToggleIntelligence}
-				searchValue={searchInput}
-				onSearchChange={onSearchChange}
-				onSearchClear={onSearchClear}
-				onSearchClearQuery={onSearchClearQuery}
 				onReply={hasThread ? onToolbarReply : undefined}
 				onReplyAll={hasThread ? onToolbarReplyAll : undefined}
 				onForward={hasThread ? onToolbarForward : undefined}

package/src/components/mail/MessageToolbar.render.test.ts

@@ -12,6 +12,7 @@ import { describe, it } from "node:test";
 import { MailActionToolbar } from "@remit/ui";
 import React, { createElement } from "react";
 import { renderToString } from "react-dom/server";
+import { MessageToolbar } from "./MessageToolbar";
 
 // The node test loader transpiles remit-ui's `.tsx` (resolved through
 // node_modules) with the classic JSX runtime, which references a global
@@ -55,3 +56,41 @@ describe("MailActionToolbar never disables its action buttons (#799)", () => {
 		assert.doesNotMatch(html, /aria-label="Archive"/);
 	});
 });
+
+/**
+ * The reading-pane toolbar carries message context only (#49). Search, compose,
+ * bug report and the account menu moved up into the app top bar, which spans
+ * every pane. Two search fields on one screen fight over "/" and over focus, so
+ * the absence of one here is the thing worth pinning.
+ */
+describe("MessageToolbar carries message context only (#49)", () => {
+	const render = (hasThread: boolean): string =>
+		renderToString(
+			createElement(MessageToolbar, {
+				hasThread,
+				intelligenceOpen: false,
+				showIntelligenceToggle: true,
+				onToggleIntelligence: () => undefined,
+			}) as never,
+		);
+
+	it("mounts no search field", () => {
+		for (const hasThread of [false, true]) {
+			assert.doesNotMatch(render(hasThread), /aria-label="Search mail"/);
+		}
+	});
+
+	it("carries no global actions — compose, bug report, account", () => {
+		const html = render(true);
+		assert.doesNotMatch(html, /aria-label="Compose"/);
+		assert.doesNotMatch(html, /aria-label="Report a bug"/);
+		assert.doesNotMatch(html, /aria-label="Account menu"/);
+	});
+
+	it("keeps the message verbs and the intelligence toggle", () => {
+		const html = render(true);
+		assert.match(html, /aria-label="Reply"/);
+		assert.match(html, /aria-label="Star"/);
+		assert.match(html, /intelligence sidebar/);
+	});
+});

package/src/components/mail/MessageToolbar.tsx

@@ -1,22 +1,17 @@
-import {
-	Button,
-	type MailAction,
-	MailActionToolbar,
-	SearchBar,
-} from "@remit/ui";
-import { Info, SquarePen } from "lucide-react";
+import { Button, type MailAction, MailActionToolbar } from "@remit/ui";
+import { Info } from "lucide-react";
 import { useState } from "react";
-import { AccountMenu } from "@/auth/AccountMenu";
-import { BugReportButton } from "@/components/ui/BugReportButton";
 import { tooltipForAction } from "@/lib/keymap";
 import { MoveToTrigger } from "./MoveToTrigger";
 
 /**
  * Message action toolbar on the pane-header datum (40px, the shared
- * `--spacing-pane-header`). The reading pane's verbs — reply / reply-all /
- * forward, then delete / move / flag — Apple-Mail-style ghost icon buttons,
- * then the search field top-right (still filters the current list), compose
- * (✎) and the intelligence toggle (#422).
+ * `--spacing-pane-header`). Everything here acts on the open message: reply /
+ * reply-all / forward, then delete / move / flag — Apple-Mail-style ghost icon
+ * buttons — and the intelligence toggle (#422).
+ *
+ * Search, compose, bug report and the account menu are not message context;
+ * they live in the app top bar above every pane (`MailTopBar`, #49).
  *
  * Buttons are always pressable (never `disabled`): with no thread open a press
  * is a no-op that surfaces a one-line inline explanation rather than greying
@@ -24,7 +19,6 @@ import { MoveToTrigger } from "./MoveToTrigger";
  */
 export interface MessageToolbarProps {
 	hasThread: boolean;
-	onCompose: () => void;
 	intelligenceOpen: boolean;
 	/**
 	 * Whether the intelligence toggle is shown at all. The rail is contextual
@@ -33,12 +27,6 @@ export interface MessageToolbarProps {
 	 */
 	showIntelligenceToggle: boolean;
 	onToggleIntelligence: () => void;
-	searchValue: string;
-	onSearchChange: (value: string) => void;
-	/** Full clear (X button): drops the query and any selected thread (#538). */
-	onSearchClear: () => void;
-	/** Query-only clear (Esc): drops the query, keeps the thread open (#489). */
-	onSearchClearQuery?: () => void;
 
 	/* ---- wired action callbacks (omit to keep the no-op-explain behaviour) ---- */
 	onReply?: () => void;
@@ -71,14 +59,9 @@ const OPEN_FIRST = "Open a message first";
 
 export const MessageToolbar = ({
 	hasThread,
-	onCompose,
 	intelligenceOpen,
 	showIntelligenceToggle,
 	onToggleIntelligence,
-	searchValue,
-	onSearchChange,
-	onSearchClear,
-	onSearchClearQuery,
 	onReply,
 	onReplyAll,
 	onForward,
@@ -120,27 +103,6 @@ export const MessageToolbar = ({
 				) : undefined
 			}
 		>
-			{/* Apple Mail geometry: search sits top-right over the message area
-			    but still filters the current list. Reuses the wired SearchBar
-			    (the global "/" focus shortcut + Escape handling live in it). */}
-			<div className="w-64 min-w-40 shrink">
-				<SearchBar
-					value={searchValue}
-					onChange={onSearchChange}
-					onClear={onSearchClear}
-					onClearQuery={onSearchClearQuery}
-					placeholder="Search mail"
-				/>
-			</div>
-			<span className="mx-1 h-4 w-px bg-line" aria-hidden />
-			<Button
-				variant="ghost"
-				size="sm"
-				icon={<SquarePen className="size-4" />}
-				title={`Compose ${tooltipForAction("compose")}`}
-				aria-label="Compose"
-				onClick={onCompose}
-			/>
 			{showIntelligenceToggle && (
 				<Button
 					variant="ghost"
@@ -159,8 +121,6 @@ export const MessageToolbar = ({
 					}
 				/>
 			)}
-			<BugReportButton />
-			<AccountMenu />
 		</MailActionToolbar>
 	);
 };

package/src/hooks/useComposeTarget.ts

@@ -0,0 +1,92 @@
+/**
+ * Where a global compose has to land.
+ *
+ * The compose surface (`FullCompose`) is mounted by the mailbox route only, so
+ * compose started from anywhere else — the daily brief, flagged, outbox — has
+ * to carry the user to a mailbox first. The target is the first account's
+ * inbox, falling back to its first mailbox.
+ *
+ * Both compose entry points use this: the top bar's button on desktop and the
+ * mobile `ComposeFab`. One resolver, so the two surfaces cannot disagree about
+ * which routes host the compose surface.
+ */
+import { mailboxOperationsListMailboxesOptions } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import type { RemitImapAccountResponse } from "@remit/api-http-client/types.gen.ts";
+import { useQueries } from "@tanstack/react-query";
+import { useLocation, useNavigate } from "@tanstack/react-router";
+import { startTransition, useCallback } from "react";
+import { useCompose } from "@/components/compose/ComposeProvider";
+import { hostsComposeSurface } from "@/lib/compose-routes";
+import { buildMailboxRoleMap } from "@/lib/folder-roles";
+
+/**
+ * The mailbox id a global compose should navigate to, or undefined if none is
+ * known yet.
+ *
+ * Accounts resolve in order and an account whose mailbox query is still in
+ * flight blocks rather than being skipped: skipping hands back a later
+ * account's inbox and then silently swaps the target once the earlier query
+ * settles.
+ */
+export function useComposeTargetMailboxId(
+	accounts: RemitImapAccountResponse[],
+): string | undefined {
+	const mailboxQueries = useQueries({
+		queries: accounts.map((account) => ({
+			...mailboxOperationsListMailboxesOptions({
+				path: { accountId: account.accountId },
+			}),
+			staleTime: Infinity,
+		})),
+	});
+
+	for (const [index, account] of accounts.entries()) {
+		const query = mailboxQueries[index];
+		if (!query || query.isPending) return undefined;
+		const mailboxes = query.data?.items ?? [];
+		if (mailboxes.length === 0) continue;
+		const roleMap = buildMailboxRoleMap(account.folderAppointments);
+		const inbox = mailboxes.find(
+			(mailbox) => roleMap.get(mailbox.mailboxId) === "inbox",
+		);
+		return (inbox ?? mailboxes[0])?.mailboxId;
+	}
+	return undefined;
+}
+
+/**
+ * A compose action that works from every view: opens compose in place when the
+ * current route already hosts the surface, otherwise navigates to the target
+ * mailbox — compose state lives in `ComposeProvider` (mounted at the root), so
+ * it survives the transition and the destination mounts straight into it.
+ *
+ * With no target resolved yet — a cold load whose mailbox queries have not
+ * settled, or accounts with no mailboxes — the action does nothing. Opening
+ * compose state first would leave it open with nothing rendering it, and it
+ * would then pop up unprompted on the next navigation.
+ */
+export function useGlobalCompose(
+	accounts: RemitImapAccountResponse[],
+): () => void {
+	const { openCompose } = useCompose();
+	const navigate = useNavigate();
+	const location = useLocation();
+	const targetMailboxId = useComposeTargetMailboxId(accounts);
+
+	return useCallback(() => {
+		if (hostsComposeSurface(location.pathname)) {
+			startTransition(() => {
+				openCompose({ mode: "new" });
+			});
+			return;
+		}
+		if (!targetMailboxId) return;
+		startTransition(() => {
+			openCompose({ mode: "new" });
+		});
+		navigate({
+			to: "/mail/$mailboxId",
+			params: { mailboxId: targetMailboxId },
+		});
+	}, [openCompose, navigate, location.pathname, targetMailboxId]);
+}

package/src/hooks/useLayoutTier.test.ts

@@ -45,3 +45,29 @@ describe("isSinglePaneTier — compose surface must mount below desktop", () =>
 		assert.equal(isSinglePaneTier(resolveLayoutTier(1024)), false);
 	});
 });
+
+describe("exactly one search field is mounted at every width", () => {
+	// Two call sites decide this from the same tier: `mail.tsx` mounts the top
+	// bar's field when the layout is not single-pane, and `MailListHeader`
+	// passes `showSearch` to keep the header's field otherwise. Both read
+	// `isSinglePaneTier`, so they are each other's complement by construction —
+	// if either is rewritten to its own expression this fails. Two mounted
+	// fields compete for "/" and for focus (#59); zero leaves no way to search.
+	const mountsTopBarField = (width: number): boolean =>
+		!isSinglePaneTier(resolveLayoutTier(width));
+	const mountsHeaderField = (width: number): boolean =>
+		isSinglePaneTier(resolveLayoutTier(width));
+
+	for (const width of [0, 390, 767, 768, 1023, 1024, 1440]) {
+		it(`mounts one field at ${width}px`, () => {
+			const fields =
+				Number(mountsTopBarField(width)) + Number(mountsHeaderField(width));
+			assert.equal(fields, 1, `${width}px mounts ${fields} search fields`);
+		});
+	}
+
+	it("puts the field in the top bar only from desktop up", () => {
+		assert.equal(mountsTopBarField(1023), false);
+		assert.equal(mountsTopBarField(1024), true);
+	});
+});

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/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);
+		});
+	}
+});

package/src/routes/mail/outbox.tsx

@@ -3,8 +3,13 @@ import { z } from "zod";
 
 // Search schema: `selectedOutboxMessageId` is read by `OutboxPane` in the
 // parent `/mail` shell via `useSearch({ strict: false })`.
+//
+// `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 outboxSearchSchema = z.object({
 	selectedOutboxMessageId: z.string().optional(),
+	q: z.string().optional(),
 });
 
 export const Route = createFileRoute("/mail/outbox")({

package/src/routes/mail.tsx

@@ -15,6 +15,7 @@ import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { z } from "zod";
 import { AppShellSkeleton } from "@/components/layout/AppShellSkeleton";
 import { ComposeFab } from "@/components/layout/ComposeFab";
+import { MailTopBar } from "@/components/layout/MailTopBar";
 import { BriefPane } from "@/components/mail/BriefPane";
 import { FlaggedPane } from "@/components/mail/FlaggedPane";
 import { MailboxPane } from "@/components/mail/MailboxPane";
@@ -268,7 +269,16 @@ function MailLayout() {
 	const navContent = (
 		<MailNav accounts={accounts} onMailboxSelect={handleMailboxSelect} />
 	);
-	const overlayContent = <ComposeFab />;
+	// Single-pane only, where the FAB is the compose entry point. Above it the
+	// top bar owns compose, and mounting the FAB there would resolve the same
+	// compose target twice for a button CSS keeps hidden.
+	const overlayContent = isSinglePane ? (
+		<ComposeFab accounts={accounts} />
+	) : undefined;
+	// Desktop only. Below 1024px the single pane keeps its own header search and
+	// the phone takeover; there is no room for a bar spanning panes that do not
+	// exist side by side.
+	const topBar = isSinglePane ? undefined : <MailTopBar accounts={accounts} />;
 	const navSlideOver = {
 		navOpen: drawerOpen,
 		onOpenNav: () => setDrawerOpen(true),
@@ -303,6 +313,7 @@ function MailLayout() {
 					) : (
 						<AppShellSlotted
 							nav={navContent}
+							topBar={topBar}
 							list={<BriefPane.List />}
 							reading={<BriefPane.Reading />}
 							intelligenceOpen={intelligenceOpen}
@@ -330,6 +341,7 @@ function MailLayout() {
 					) : (
 						<AppShellSlotted
 							nav={navContent}
+							topBar={topBar}
 							list={<FlaggedPane.List />}
 							reading={<FlaggedPane.Reading />}
 							intelligenceOpen={intelligenceOpen}
@@ -359,6 +371,7 @@ function MailLayout() {
 					) : (
 						<AppShellSlotted
 							nav={navContent}
+							topBar={topBar}
 							list={<MailboxPane.List />}
 							reading={<MailboxPane.Reading />}
 							intelligence={<MailboxPane.Intelligence />}
@@ -386,6 +399,7 @@ function MailLayout() {
 					) : (
 						<AppShellSlotted
 							nav={navContent}
+							topBar={topBar}
 							list={<OutboxPane.List />}
 							reading={<OutboxPane.Reading />}
 							intelligenceOpen={false}