@remit/web-client 0.0.46 → 0.0.48

package/package.json

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

@@ -1,10 +1,11 @@
 /**
  * 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.
+ * Mounted by the `/mail` shell over the list, the reading pane and the
+ * intelligence rail, starting on the list's left edge. 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,
@@ -54,11 +55,6 @@ export function MailTopBar({ accounts }: MailTopBarProps) {
 
 	return (
 		<AppTopBar
-			leading={
-				<span className="px-1 text-sm font-semibold tracking-tight text-fg">
-					remit
-				</span>
-			}
 			search={
 				<SearchBar
 					value={searchInput}

package/src/components/mail/DailyBrief.tsx

@@ -21,17 +21,12 @@ import {
 } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
 import type { RemitImapAccountResponse } from "@remit/api-http-client/types.gen.ts";
 import {
-	Avatar,
 	type BriefCategoryFilter,
 	BriefSections,
 	briefFilterConfig,
-	ComfortableRowTextContent,
-	cn,
-	comfortableRowClass,
 	type FilterSheetProps,
 	type FilterSheetSource,
 	KeyboardHintBar,
-	LIST_ROW_ATTRIBUTE,
 	type SearchResult,
 	type ThreadRowData,
 	type ThreadSection,
@@ -56,6 +51,7 @@ import { useMailContext } from "@/lib/mail-context";
 import { relatedSearchResults, rowToSearchResult } from "@/lib/search-result";
 import { parseSearchTokens } from "@/lib/search-tokens";
 import { MailListHeader } from "./MailListHeader";
+import { MessageRow } from "./MessageRow";
 
 /* The brief's attribute chips as predicates (mirrors the kit `briefFilterChips`
    ids) so the phone search takeover narrows results the same way the list does. */
@@ -124,36 +120,6 @@ const ErrorBanner = ({ accountEmail }: ErrorBannerProps) => {
 	);
 };
 
-// ---------------------------------------------------------------------------
-// Brief row — a navigation-aware row satisfying remit-ui's BriefRowComponent
-// ---------------------------------------------------------------------------
-
-const BriefRow = ({
-	thread,
-	active,
-	onClick,
-}: {
-	thread: ThreadRowData;
-	active?: boolean;
-	onClick?: () => void;
-}) => {
-	const unread = !thread.isRead;
-	return (
-		<button
-			type="button"
-			{...LIST_ROW_ATTRIBUTE}
-			onClick={onClick}
-			className={cn("group w-full", comfortableRowClass({ active }))}
-		>
-			{unread && (
-				<span className="absolute left-1.5 top-1/2 size-1.5 -translate-y-1/2 rounded-full bg-accent" />
-			)}
-			<Avatar name={thread.fromName} email={thread.fromEmail} size="sm" />
-			<ComfortableRowTextContent thread={thread} />
-		</button>
-	);
-};
-
 // ---------------------------------------------------------------------------
 // Main component
 // ---------------------------------------------------------------------------
@@ -441,7 +407,7 @@ export function DailyBrief({
 	) : (
 		<BriefSections
 			sections={sections}
-			Row={BriefRow}
+			Row={MessageRow}
 			briefCategory={selectedCategory}
 			onSelectBriefCategory={setSelectedCategory}
 			sources={accountSources}

package/src/components/mail/FlaggedList.tsx

@@ -14,7 +14,6 @@
  * `listBody` so the real rows render at every width.
  */
 import {
-	ComfortableRow,
 	flaggedFilterConfig,
 	LIST_ROW_SELECTOR,
 	MessageListPane,
@@ -37,6 +36,7 @@ import { rowToSearchResult } from "@/lib/search-result";
 import { parseSearchTokens } from "@/lib/search-tokens";
 import { dedupeByThread } from "@/lib/starred-rows";
 import { MailViewChrome } from "./MailViewChrome";
+import { MessageRow } from "./MessageRow";
 
 const FILTER_PREDICATES: Record<string, (t: ThreadRowData) => boolean> = {
 	unread: (t) => !t.isRead,
@@ -138,7 +138,7 @@ export function FlaggedList({
 		<div ref={listRef} className="flex-1 overflow-y-auto">
 			<div className="divide-y divide-line">
 				{rows.map((thread) => (
-					<ComfortableRow
+					<MessageRow
 						key={thread.id}
 						thread={thread}
 						active={thread.id === selectedMessageId}

package/src/components/mail/MessageListItem.tsx

@@ -1,31 +1,19 @@
-import { messageOperationsDescribeMessageOptions } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+/**
+ * MessageListItem — the mailbox list's adapter onto the shared `MessageRow`.
+ *
+ * It maps an API thread to the row's `ThreadRowData` shape and supplies the two
+ * things only the mailbox list has: route-linking rows and the auto-moved
+ * badge. Everything visual and interactive lives in `MessageRow`, which the
+ * brief and Flagged render too.
+ */
 import type { RemitImapThreadMessageResponse } from "@remit/api-http-client/types.gen.ts";
-import {
-	Avatar,
-	ComfortableRowTextContent,
-	CompactRowBody,
-	comfortableRowClass,
-	compactRowClass,
-	type Density,
-	mergeProps,
-	type SenderTrustLevel,
-	type ThreadRowData,
-	useLongPress,
-} from "@remit/ui";
-import { useQueryClient } from "@tanstack/react-query";
-import { Link } from "@tanstack/react-router";
-import { Check } from "lucide-react";
-import { type MouseEvent, memo, useCallback } from "react";
+import type { Density, SenderTrustLevel, ThreadRowData } from "@remit/ui";
+import { memo } from "react";
 import type { SelectionModifiers } from "@/hooks/useSelection";
 import { toDisplayCategory } from "@/lib/display-category";
 import { formatEmailDate } from "@/lib/format";
-import { cn } from "@/lib/utils";
 import { AutoMovedIndicator } from "./AutoMovedIndicator";
-
-interface MailboxLinkSearch {
-	selectedMessageId?: string;
-	q?: string;
-}
+import { MessageRow } from "./MessageRow";
 
 interface MessageListItemProps {
 	thread: RemitImapThreadMessageResponse;
@@ -33,305 +21,94 @@ interface MessageListItemProps {
 	/** Owning account, used to resolve the Inbox/Junk mailboxes for the auto-moved badge's undo action. */
 	accountId?: string;
 	isSelected: boolean;
-	/**
-	 * Roving keyboard focus cursor (#429). Distinct from `isSelected` (the open
-	 * thread): a focused-but-not-open row shows the left accent rail; the open
-	 * row shows the full highlight. Both can be true (the open row stays focused).
-	 */
 	isFocused?: boolean;
-	/**
-	 * Whether this row holds the list's single tab stop (roving tabindex). Every
-	 * other row is `tabIndex={-1}`, so Tab enters the list at the cursor and
-	 * Shift+Tab leaves it rather than stepping through hundreds of rows.
-	 */
 	isTabStop?: boolean;
-	/** Called when the row takes DOM focus, so the roving cursor follows it. */
 	onFocusRow?: (messageId: string) => void;
 	isChecked: boolean;
 	onToggleCheck: (id: string) => void;
-	/**
-	 * Desktop mouse selection. Called from the row's onClick with the click
-	 * modifiers. Returns true when selection consumed the click (the row should
-	 * not navigate); false for a plain click (navigation proceeds).
-	 */
 	onRowSelect: (messageId: string, modifiers: SelectionModifiers) => boolean;
 	messageCount?: number;
-	/** When true, the checkbox is always visible (e.g. mobile multi-select mode). */
 	isMultiSelectMode?: boolean;
-	/** Called on long press (mobile only). Receives the row's messageId. */
 	onLongPress?: (messageId: string) => void;
-	/** Whether the current viewport is desktop size. */
 	isDesktop?: boolean;
-	/** Row density — comfortable (default) or compact (mutt mode). */
 	density?: Density;
 }
 
 /**
- * Map a RemitImapThreadMessageResponse to the ThreadRowData shape used by
- * remit-ui row body components.
+ * Map a RemitImapThreadMessageResponse to the ThreadRowData shape the shared
+ * row renders.
  */
-const toThreadRowData = (
+export const threadToRowData = (
 	thread: RemitImapThreadMessageResponse,
-	messageCount: number | undefined,
-): ThreadRowData => {
-	// Use the backend's authoritative DKIM-alignment verdict rather than
-	// re-deriving it in the view: dkimMismatch already accounts for the
-	// multi-signature / alignment semantics a single string compare misses.
-	const suspicious = thread.authenticity?.dkimMismatch === true;
-
-	return {
-		id: thread.messageId,
-		accountId: thread.accountConfigId,
-		fromName: thread.fromName ?? thread.fromEmail ?? "Unknown",
-		fromEmail: thread.fromEmail ?? "",
-		subject: thread.subject ?? "(No subject)",
-		snippet: thread.snippet ?? "",
-		timeLabel: formatEmailDate(thread.sentDate),
-		isRead: thread.isRead,
-		hasAttachment: thread.hasAttachment,
-		starred: thread.hasStars === true,
-		trust: thread.senderTrust as SenderTrustLevel,
-		category: toDisplayCategory(thread.category),
-		messageCount,
-		suspicious,
-	};
-};
+	messageCount?: number,
+): ThreadRowData => ({
+	id: thread.messageId,
+	accountId: thread.accountConfigId,
+	mailboxId: thread.mailboxId,
+	fromName: thread.fromName ?? thread.fromEmail ?? "Unknown",
+	fromEmail: thread.fromEmail ?? "",
+	subject: thread.subject ?? "(No subject)",
+	snippet: thread.snippet ?? "",
+	timeLabel: formatEmailDate(thread.sentDate),
+	isRead: thread.isRead,
+	hasAttachment: thread.hasAttachment,
+	starred: thread.hasStars === true,
+	trust: thread.senderTrust as SenderTrustLevel,
+	category: toDisplayCategory(thread.category),
+	messageCount,
+	// The backend's DKIM-alignment verdict is authoritative: it already accounts
+	// for the multi-signature / alignment semantics a single string compare
+	// misses.
+	suspicious: thread.authenticity?.dkimMismatch === true,
+});
 
 const MessageListItemComponent = ({
 	thread,
 	mailboxId,
 	accountId,
 	isSelected,
-	isFocused = false,
-	isTabStop = false,
+	isFocused,
+	isTabStop,
 	onFocusRow,
 	isChecked,
 	onToggleCheck,
 	onRowSelect,
 	messageCount,
-	isMultiSelectMode = false,
+	isMultiSelectMode,
 	onLongPress,
-	isDesktop = true,
-	density = "comfortable",
-}: MessageListItemProps) => {
-	const queryClient = useQueryClient();
-	const messageId = thread.messageId;
-	const rowData = toThreadRowData(thread, messageCount);
-
-	const handleCheckboxClick = (e: MouseEvent) => {
-		e.preventDefault();
-		e.stopPropagation();
-		onToggleCheck(thread.messageId);
-	};
-
-	// Desktop mouse selection semantics. Plain click falls through to the Link's
-	// navigation; shift / cmd / ctrl click is routed to selection and the
-	// navigation is suppressed.
-	//
-	// A modified click must preventDefault: the router skips navigation for any
-	// modified click and leaves the anchor's own default in place, which in a
-	// browser means shift-click opens a new window and cmd-click a new tab.
-	// Shift-click also drags a native text selection across the rows it spans,
-	// so drop it — the row highlight is the selection the user asked for.
-	//
-	// On mobile, once selection mode is active (#92) a plain tap toggles the
-	// row instead of opening it — the same tap-to-toggle contract every
-	// reference mail client uses once you're mid-selection. Outside selection
-	// mode a short tap still falls through to the Link's native navigation.
-	const handleRowClick = useCallback(
-		(e: MouseEvent) => {
-			if (!isDesktop) {
-				if (!isMultiSelectMode) return;
-				e.preventDefault();
-				e.stopPropagation();
-				onToggleCheck(messageId);
-				return;
-			}
-			const modifiers = {
-				shiftKey: e.shiftKey,
-				metaKey: e.metaKey,
-				ctrlKey: e.ctrlKey,
-			};
-			const handled = onRowSelect(messageId, modifiers);
-			if (!handled) return;
-			e.preventDefault();
-			e.stopPropagation();
-			if (modifiers.shiftKey) {
-				window.getSelection()?.removeAllRanges();
-			}
-		},
-		[isDesktop, isMultiSelectMode, onToggleCheck, onRowSelect, messageId],
-	);
-
-	// Shift-click starts a native text selection on mousedown; suppressing it
-	// there keeps the drag from painting a text range over the rows.
-	const handleRowMouseDown = useCallback(
-		(e: MouseEvent) => {
-			if (!isDesktop) return;
-			if (e.shiftKey) e.preventDefault();
-		},
-		[isDesktop],
-	);
-
-	const handleLongPress = useCallback(() => {
-		onLongPress?.(messageId);
-	}, [onLongPress, messageId]);
-
-	const { longPressProps } = useLongPress({
-		onLongPress: handleLongPress,
-		delayMs: 500,
-		accessibilityDescription: isChecked ? "Deselect message" : "Select message",
-	});
-
-	// Intent-based prefetch: by the time the user clicks, the body is in
-	// React Query's cache and the detail pane renders without a spinner.
-	const prefetchMessage = useCallback(() => {
-		queryClient.prefetchQuery(
-			messageOperationsDescribeMessageOptions({
-				path: { messageId: thread.messageId },
-			}),
-		);
-	}, [queryClient, thread.messageId]);
-
-	const handleRowFocus = useCallback(() => {
-		prefetchMessage();
-		onFocusRow?.(messageId);
-	}, [prefetchMessage, onFocusRow, messageId]);
-
-	// Listbox semantics + roving tabindex, shared by both densities. Merged
-	// (not spread) with the mobile long-press props: react-aria's pressProps
-	// carries its own onClick for its internal press bookkeeping, and a plain
-	// object spread would silently drop whichever onClick landed second
-	// instead of running both.
-	const rowInteractionProps = mergeProps(
-		{
-			"data-message-row": true,
-			"data-message-id": messageId,
-			role: "option" as const,
-			"aria-selected": isChecked,
-			tabIndex: isTabStop ? 0 : -1,
-			onClick: handleRowClick,
-			onMouseDown: handleRowMouseDown,
-			onMouseEnter: prefetchMessage,
-			onFocus: handleRowFocus,
-		},
-		isDesktop ? {} : longPressProps,
-	);
-
-	const unread = !thread.isRead;
-
-	if (density === "compact") {
-		return (
-			<Link
-				to="/mail/$mailboxId"
-				params={{ mailboxId }}
-				search={(prev: MailboxLinkSearch) => ({
-					...prev,
-					selectedMessageId: thread.messageId,
-				})}
-				{...rowInteractionProps}
-				className={cn(
-					compactRowClass({ active: isSelected, focused: isFocused }),
-					"outline-none focus-visible:ring-2 focus-visible:ring-accent focus-visible:ring-inset",
-					isChecked && "bg-accent-soft",
-					// Long-press enters selection mode; without these, Android Chrome
-					// opens the link context menu / starts text selection and iOS
-					// Safari fires the callout, racing the app's handler. react-aria
-					// suppresses contextmenu/text-selection but not iOS's callout —
-					// it fires no cancelable event, so CSS is the only lever.
-					!isDesktop && "min-h-11 select-none [-webkit-touch-callout:none]",
-				)}
-			>
-				<CompactRowBody thread={rowData} />
-			</Link>
-		);
-	}
-
-	// Comfortable density: avatar/checkbox leading slot + text content.
-	// The slot is a fixed 36px so the row never reflows when state changes.
-	// Unread dot is positioned absolute (left-1.5, vertically centered).
-	return (
-		<Link
-			to="/mail/$mailboxId"
-			params={{ mailboxId }}
-			search={(prev: MailboxLinkSearch) => ({
-				...prev,
-				selectedMessageId: thread.messageId,
-			})}
-			{...rowInteractionProps}
-			className={cn(
-				"group",
-				comfortableRowClass({ active: isSelected, focused: isFocused }),
-				"outline-none focus-visible:ring-2 focus-visible:ring-accent focus-visible:ring-inset",
-				isChecked && "bg-accent-soft",
-				// See the compact-density Link above for why both are required.
-				!isDesktop && "min-h-11 select-none [-webkit-touch-callout:none]",
-			)}
-		>
-			{/* Absolute unread dot — 6px gutter from the left pane hairline */}
-			{unread && (
-				<span className="absolute left-1.5 top-1/2 size-1.5 -translate-y-1/2 rounded-full bg-accent" />
-			)}
-
-			{/* Leading slot: avatar by default, checkbox on hover (desktop) or
-			    while checked / in multi-select mode. Fixed 28px slot (size-7,
-			    matching Avatar size="sm" in remit-ui ComfortableRow). */}
-			<div className="relative size-7 shrink-0">
-				<Avatar
-					name={thread.fromName ?? thread.fromEmail ?? "?"}
-					email={thread.fromEmail ?? undefined}
+	isDesktop,
+	density,
+}: MessageListItemProps) => (
+	<MessageRow
+		thread={threadToRowData(thread, messageCount)}
+		linkMailboxId={mailboxId}
+		inListbox
+		active={isSelected}
+		focused={isFocused}
+		isTabStop={isTabStop}
+		density={density}
+		isDesktop={isDesktop}
+		onFocusRow={onFocusRow}
+		selection={{
+			isChecked,
+			onToggleCheck,
+			onRowSelect,
+			isMultiSelectMode,
+			onLongPress,
+		}}
+		badge={
+			thread.autoMoved ? (
+				<AutoMovedIndicator
+					accountId={accountId}
+					messageId={thread.messageId}
+					threadId={thread.threadId}
+					mailboxId={thread.mailboxId}
+					autoMoved={thread.autoMoved}
 					size="sm"
-					className={cn(
-						"absolute inset-0",
-						"sm:group-hover:opacity-0 transition-opacity",
-						(isChecked || isMultiSelectMode) && "opacity-0",
-					)}
 				/>
-				<button
-					type="button"
-					// Out of the tab order: the row is the list's single tab stop, and
-					// this control is `opacity-0` until hover, so a tabbable one would
-					// put focus on something invisible on every row.
-					tabIndex={-1}
-					onClick={handleCheckboxClick}
-					className={cn(
-						"absolute inset-0 size-7 rounded-full border items-center justify-center transition-opacity",
-						isMultiSelectMode ? "flex" : "hidden sm:flex",
-						isChecked
-							? "bg-accent border-accent text-accent-fg opacity-100"
-							: isMultiSelectMode
-								? "border-fg-subtle/40 opacity-100 bg-canvas"
-								: "border-fg-subtle/40 opacity-0 group-hover:opacity-100 bg-canvas",
-					)}
-					aria-label={isChecked ? "Deselect message" : "Select message"}
-				>
-					{isChecked && <Check className="size-3" />}
-				</button>
-			</div>
-
-			{/* Text/glyph content block */}
-			<ComfortableRowTextContent
-				thread={rowData}
-				badge={
-					thread.autoMoved && (
-						<AutoMovedIndicator
-							accountId={accountId}
-							messageId={thread.messageId}
-							threadId={thread.threadId}
-							mailboxId={thread.mailboxId}
-							autoMoved={thread.autoMoved}
-							size="sm"
-						/>
-					)
-				}
-			/>
-		</Link>
-	);
-};
+			) : undefined
+		}
+	/>
+);
 
-// Wrapped in React.memo so virtualized rows don't re-render on every parent
-// state change. The `search` callback prop on Link is inline, but it gets a
-// stable reference because the parent itself is stable across re-renders
-// (mailboxId is a string from route params). React.memo with default shallow
-// equality is appropriate here since props are primitives + stable callback.
 export const MessageListItem = memo(MessageListItemComponent);

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

@@ -0,0 +1,61 @@
+/**
+ * Row semantics for the shared `MessageRow` (#149).
+ *
+ * `role="option"` belongs to the mailbox list, whose rows sit inside a
+ * `role="listbox"` container. The brief and Flagged render rows in ordinary
+ * containers: an orphan `option` there is invalid ARIA and, more concretely,
+ * strips the row of its button role — which is how the black-box suite and any
+ * screen reader address it.
+ */
+
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import type { ThreadRowData } from "@remit/ui";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import React, { createElement } from "react";
+import { renderToString } from "react-dom/server";
+import { MessageRow } from "./MessageRow";
+
+(globalThis as { React?: typeof React }).React = React;
+
+const thread: ThreadRowData = {
+	id: "m1",
+	accountId: "a1",
+	fromName: "Alex Rivera",
+	fromEmail: "alex@example.com",
+	subject: "Quarterly numbers are in",
+	snippet: "The deck is on the shared drive.",
+	timeLabel: "9:42",
+	isRead: true,
+};
+
+const render = (props: Parameters<typeof MessageRow>[0]): string =>
+	renderToString(
+		createElement(
+			QueryClientProvider,
+			{ client: new QueryClient() },
+			createElement(MessageRow, props),
+		) as never,
+	);
+
+describe("MessageRow semantics", () => {
+	it("renders a plain button outside a listbox (brief, Flagged)", () => {
+		const html = render({ thread });
+		assert.match(html, /<button/);
+		assert.doesNotMatch(html, /role="option"/);
+		assert.doesNotMatch(html, /aria-selected/);
+	});
+
+	it("renders listbox option semantics when the container is a listbox", () => {
+		const html = render({ thread, inListbox: true });
+		assert.match(html, /role="option"/);
+		assert.match(html, /aria-selected/);
+	});
+
+	it("renders the row's sender, subject and snippet", () => {
+		const html = render({ thread });
+		assert.match(html, /Alex Rivera/);
+		assert.match(html, /Quarterly numbers are in/);
+		assert.match(html, /shared drive/);
+	});
+});

package/src/components/mail/MessageRow.tsx

@@ -0,0 +1,279 @@
+/**
+ * MessageRow — the one thread row every list in the app renders.
+ *
+ * The mailbox list, the daily brief and Flagged used to carry three
+ * near-identical rows (#149). They differ in two axes only, both props here:
+ *
+ * - `linkMailboxId` — set for the mailbox list, whose rows are real links so a
+ *   plain click routes and a middle click opens a tab. Omitted for the brief
+ *   and Flagged, whose rows report the tap through `onClick`.
+ * - `selection` — set where multi-select is available. Absent renders the
+ *   avatar alone with no checkbox, which is what "non-selectable mode" means.
+ */
+import { messageOperationsDescribeMessageOptions } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import {
+	ComfortableRowBody,
+	CompactRowBody,
+	comfortableRowClass,
+	compactRowClass,
+	type Density,
+	mergeProps,
+	type ThreadRowData,
+	useLongPress,
+} from "@remit/ui";
+import { useQueryClient } from "@tanstack/react-query";
+import { Link } from "@tanstack/react-router";
+import { type MouseEvent, memo, type ReactNode, useCallback } from "react";
+import type { SelectionModifiers } from "@/hooks/useSelection";
+import { cn } from "@/lib/utils";
+
+interface MailboxLinkSearch {
+	selectedMessageId?: string;
+	q?: string;
+}
+
+export interface MessageRowSelection {
+	isChecked: boolean;
+	onToggleCheck: (messageId: string) => void;
+	/**
+	 * Desktop mouse selection. Returns true when selection consumed the click
+	 * (the row must not open); false for a plain click.
+	 */
+	onRowSelect: (messageId: string, modifiers: SelectionModifiers) => boolean;
+	/** Checkbox stays visible — mobile multi-select mode. */
+	isMultiSelectMode?: boolean;
+	/** Long press enters selection mode (mobile only). */
+	onLongPress?: (messageId: string) => void;
+}
+
+export interface MessageRowProps {
+	thread: ThreadRowData;
+	/** The row is the open thread. */
+	active?: boolean;
+	/**
+	 * Roving keyboard focus cursor (#429). Distinct from `active`: a
+	 * focused-but-not-open row shows the left accent rail; the open row shows the
+	 * full highlight. Both can be true.
+	 */
+	focused?: boolean;
+	/**
+	 * Whether this row holds the list's single tab stop (roving tabindex). Every
+	 * other row is `tabIndex={-1}`, so Tab enters the list at the cursor and
+	 * Shift+Tab leaves it rather than stepping through hundreds of rows.
+	 */
+	isTabStop?: boolean;
+	density?: Density;
+	isDesktop?: boolean;
+	/** Extra chip after the category badge (e.g. the auto-moved indicator). */
+	badge?: ReactNode;
+	selection?: MessageRowSelection;
+	/**
+	 * The row sits inside a container with `role="listbox"` (the mailbox list),
+	 * so it carries `role="option"` and `aria-selected`. Off everywhere else:
+	 * the brief and Flagged render their rows in ordinary containers, where an
+	 * orphan `option` is invalid ARIA and costs the row its button semantics.
+	 */
+	inListbox?: boolean;
+	/** Mailbox whose route the row links to; omit for callback-driven rows. */
+	linkMailboxId?: string;
+	/** Called when the row is opened by a plain click on a non-linking row. */
+	onClick?: () => void;
+	/** Called when the row takes DOM focus, so the roving cursor follows it. */
+	onFocusRow?: (messageId: string) => void;
+}
+
+const MessageRowComponent = ({
+	thread,
+	active = false,
+	focused = false,
+	isTabStop = false,
+	density = "comfortable",
+	isDesktop = true,
+	badge,
+	selection,
+	inListbox = false,
+	linkMailboxId,
+	onClick,
+	onFocusRow,
+}: MessageRowProps) => {
+	const queryClient = useQueryClient();
+	const messageId = thread.id;
+	const isChecked = selection?.isChecked ?? false;
+	const isMultiSelectMode = selection?.isMultiSelectMode ?? false;
+	const onToggleCheck = selection?.onToggleCheck;
+	const onRowSelect = selection?.onRowSelect;
+	const onLongPress = selection?.onLongPress;
+
+	const handleCheckboxClick = useCallback(
+		(e: MouseEvent) => {
+			e.preventDefault();
+			e.stopPropagation();
+			onToggleCheck?.(messageId);
+		},
+		[onToggleCheck, messageId],
+	);
+
+	// Desktop mouse selection semantics. Plain click falls through to the Link's
+	// navigation (or `onClick` on a non-linking row); shift / cmd / ctrl click is
+	// routed to selection and the navigation is suppressed.
+	//
+	// A modified click must preventDefault: the router skips navigation for any
+	// modified click and leaves the anchor's own default in place, which in a
+	// browser means shift-click opens a new window and cmd-click a new tab.
+	// Shift-click also drags a native text selection across the rows it spans,
+	// so drop it — the row highlight is the selection the user asked for.
+	//
+	// On mobile, once selection mode is active (#92) a plain tap toggles the row
+	// instead of opening it — the same tap-to-toggle contract every reference
+	// mail client uses once you're mid-selection.
+	const handleRowClick = useCallback(
+		(e: MouseEvent) => {
+			if (!isDesktop) {
+				if (isMultiSelectMode) {
+					e.preventDefault();
+					e.stopPropagation();
+					onToggleCheck?.(messageId);
+					return;
+				}
+				onClick?.();
+				return;
+			}
+			const modifiers = {
+				shiftKey: e.shiftKey,
+				metaKey: e.metaKey,
+				ctrlKey: e.ctrlKey,
+			};
+			if (onRowSelect?.(messageId, modifiers)) {
+				e.preventDefault();
+				e.stopPropagation();
+				if (modifiers.shiftKey) window.getSelection()?.removeAllRanges();
+				return;
+			}
+			onClick?.();
+		},
+		[
+			isDesktop,
+			isMultiSelectMode,
+			onToggleCheck,
+			onRowSelect,
+			onClick,
+			messageId,
+		],
+	);
+
+	// Shift-click starts a native text selection on mousedown; suppressing it
+	// there keeps the drag from painting a text range over the rows.
+	const handleRowMouseDown = useCallback(
+		(e: MouseEvent) => {
+			if (!isDesktop) return;
+			if (e.shiftKey) e.preventDefault();
+		},
+		[isDesktop],
+	);
+
+	const handleLongPress = useCallback(() => {
+		onLongPress?.(messageId);
+	}, [onLongPress, messageId]);
+
+	const { longPressProps } = useLongPress({
+		onLongPress: handleLongPress,
+		delayMs: 500,
+		accessibilityDescription: isChecked ? "Deselect message" : "Select message",
+	});
+
+	// Intent-based prefetch: by the time the user clicks, the body is in
+	// React Query's cache and the detail pane renders without a spinner.
+	const prefetchMessage = useCallback(() => {
+		queryClient.prefetchQuery(
+			messageOperationsDescribeMessageOptions({ path: { messageId } }),
+		);
+	}, [queryClient, messageId]);
+
+	const handleRowFocus = useCallback(() => {
+		prefetchMessage();
+		onFocusRow?.(messageId);
+	}, [prefetchMessage, onFocusRow, messageId]);
+
+	// Listbox semantics + roving tabindex, shared by both densities. Merged (not
+	// spread) with the mobile long-press props: react-aria's pressProps carries
+	// its own onClick for its internal press bookkeeping, and a plain object
+	// spread would silently drop whichever onClick landed second instead of
+	// running both.
+	const interactionProps = mergeProps(
+		{
+			"data-list-row": "",
+			"data-message-row": true,
+			"data-message-id": messageId,
+			...(inListbox
+				? { role: "option" as const, "aria-selected": isChecked }
+				: {}),
+			tabIndex: isTabStop ? 0 : -1,
+			onClick: handleRowClick,
+			onMouseDown: handleRowMouseDown,
+			onMouseEnter: prefetchMessage,
+			onFocus: handleRowFocus,
+		},
+		isDesktop || !selection ? {} : longPressProps,
+	);
+
+	const className = cn(
+		density === "compact"
+			? compactRowClass({ active, focused })
+			: cn("group", comfortableRowClass({ active, focused })),
+		"outline-none focus-visible:ring-2 focus-visible:ring-accent focus-visible:ring-inset",
+		isChecked && "bg-accent-soft",
+		// Long-press enters selection mode; without these, Android Chrome opens
+		// the link context menu / starts text selection and iOS Safari fires the
+		// callout, racing the app's handler. react-aria suppresses
+		// contextmenu/text-selection but not iOS's callout — it fires no
+		// cancelable event, so CSS is the only lever.
+		!isDesktop && "min-h-11 select-none [-webkit-touch-callout:none]",
+	);
+
+	const body =
+		density === "compact" ? (
+			<CompactRowBody thread={thread} />
+		) : (
+			<ComfortableRowBody
+				thread={thread}
+				badge={badge}
+				selection={
+					selection
+						? {
+								checked: isChecked,
+								alwaysVisible: isMultiSelectMode,
+								onToggle: handleCheckboxClick,
+							}
+						: undefined
+				}
+			/>
+		);
+
+	if (linkMailboxId === undefined) {
+		return (
+			<button type="button" {...interactionProps} className={className}>
+				{body}
+			</button>
+		);
+	}
+
+	return (
+		<Link
+			to="/mail/$mailboxId"
+			params={{ mailboxId: linkMailboxId }}
+			search={(prev: MailboxLinkSearch) => ({
+				...prev,
+				selectedMessageId: messageId,
+			})}
+			{...interactionProps}
+			className={className}
+		>
+			{body}
+		</Link>
+	);
+};
+
+// Wrapped in React.memo so virtualized rows don't re-render on every parent
+// state change. Props are primitives plus callbacks the parents keep stable, so
+// default shallow equality is appropriate.
+export const MessageRow = memo(MessageRowComponent);