@remit/web-client 0.0.165 → 0.0.166

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/web-client",
-  "version": "0.0.165",
+  "version": "0.0.166",
   "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/mail/BriefPane.tsx

@@ -44,7 +44,7 @@ import { useMailContext } from "@/lib/mail-context";
 import {
 	type OpenThreadPath,
 	type OpenThreadTarget,
-	retainOpenPanels,
+	useRetainOpenPanels,
 } from "@/routing";
 
 /* ------------------------------------------------------------------ */
@@ -102,6 +102,7 @@ interface BriefPaneProps {
 
 function BriefPaneProvider({ thread, children }: BriefPaneProps) {
 	const navigate = useNavigate();
+	const retainPanels = useRetainOpenPanels();
 	const { searchInput } = useMailContext();
 	const threadId = thread?.threadId;
 	const pointedAtMessageId = thread?.messageId;
@@ -152,19 +153,19 @@ function BriefPaneProvider({ thread, children }: BriefPaneProps) {
 				// `searchInput`: a row can be tapped before the debounce settles, when
 				// the committed query is still empty.
 				search: (prev) => ({ ...prev, q: searchInput || undefined }),
-				hash: retainOpenPanels,
+				hash: retainPanels,
 			});
 		},
-		[navigate, searchInput],
+		[navigate, retainPanels, searchInput],
 	);
 
 	const handleCloseThread = useCallback(() => {
 		navigate({
 			to: "/mail/brief",
 			search: (prev) => prev,
-			hash: retainOpenPanels,
+			hash: retainPanels,
 		});
-	}, [navigate]);
+	}, [navigate, retainPanels]);
 
 	const handleDeselectIfRemoved = useCallback(
 		(removedIds: string[]) => {

package/src/components/mail/DraftsView.tsx

@@ -41,7 +41,7 @@ import { FileText, Inbox, Trash2 } from "lucide-react";
 import { useMemo } from "react";
 import { useCompose } from "@/components/compose/ComposeProvider";
 import { groupDraftSections } from "@/lib/drafts";
-import { retainOpenPanels } from "@/routing";
+import { useRetainOpenPanels } from "@/routing";
 import { NavMenuButton } from "./NavMenuButton";
 
 // ---------------------------------------------------------------------------
@@ -156,6 +156,7 @@ export function DraftsView({
 }: DraftsViewProps) {
 	const { openCompose, state: composeState } = useCompose();
 	const navigate = useNavigate();
+	const retainPanels = useRetainOpenPanels();
 	const queryClient = useQueryClient();
 
 	// Fetch the full outbox list — both sources are already fetched by the
@@ -198,7 +199,7 @@ export function DraftsView({
 			to: "/mail/$mailboxId/$threadId/$messageId",
 			params: { mailboxId, threadId, messageId },
 			search: (prev) => prev,
-			hash: retainOpenPanels,
+			hash: retainPanels,
 		});
 	};
 

package/src/components/mail/FlaggedPane.tsx

@@ -55,7 +55,7 @@ import { useMailContext } from "@/lib/mail-context";
 import {
 	type OpenThreadPath,
 	type OpenThreadTarget,
-	retainOpenPanels,
+	useRetainOpenPanels,
 } from "@/routing";
 
 /* ------------------------------------------------------------------ */
@@ -113,6 +113,7 @@ interface FlaggedPaneProps {
 
 function FlaggedPaneProvider({ thread, children }: FlaggedPaneProps) {
 	const navigate = useNavigate();
+	const retainPanels = useRetainOpenPanels();
 	const { searchInput } = useMailContext();
 	const threadId = thread?.threadId;
 	const pointedAtMessageId = thread?.messageId;
@@ -158,19 +159,19 @@ function FlaggedPaneProvider({ thread, children }: FlaggedPaneProps) {
 				// `searchInput`: a row can be tapped before the debounce settles, when
 				// the committed query is still empty.
 				search: (prev) => ({ ...prev, q: searchInput || undefined }),
-				hash: retainOpenPanels,
+				hash: retainPanels,
 			});
 		},
-		[navigate, searchInput],
+		[navigate, retainPanels, searchInput],
 	);
 
 	const handleCloseThread = useCallback(() => {
 		navigate({
 			to: "/mail/flagged",
 			search: (prev) => prev,
-			hash: retainOpenPanels,
+			hash: retainPanels,
 		});
-	}, [navigate]);
+	}, [navigate, retainPanels]);
 
 	const handleDeselectIfRemoved = useCallback(
 		(removedIds: string[]) => {

package/src/components/mail/MailboxPane.tsx

@@ -127,7 +127,7 @@ import {
 import {
 	type OpenThreadPath,
 	type OpenThreadTarget,
-	retainOpenPanels,
+	useRetainOpenPanels,
 } from "@/routing";
 import { MailViewChrome } from "./MailViewChrome";
 
@@ -264,6 +264,7 @@ function MailboxPaneProvider({
 	children,
 }: MailboxPaneProps) {
 	const navigate = useNavigate();
+	const retainPanels = useRetainOpenPanels();
 	const threadId = thread?.threadId;
 	const pointedAtMessageId = thread?.messageId;
 	const telemetry = useTelemetry();
@@ -467,9 +468,9 @@ function MailboxPaneProvider({
 			to: "/mail/$mailboxId",
 			params: { mailboxId },
 			search: (prev) => prev,
-			hash: retainOpenPanels,
+			hash: retainPanels,
 		});
-	}, [mailboxId, navigate]);
+	}, [mailboxId, navigate, retainPanels]);
 
 	const handleOpenThread = useCallback(
 		(target: OpenThreadTarget) => {
@@ -477,10 +478,10 @@ function MailboxPaneProvider({
 				to: "/mail/$mailboxId/$threadId/$messageId",
 				params: { mailboxId, ...target },
 				search: (prev) => prev,
-				hash: retainOpenPanels,
+				hash: retainPanels,
 			});
 		},
-		[mailboxId, navigate],
+		[mailboxId, navigate, retainPanels],
 	);
 
 	const handleDeselectIfRemoved = useCallback(
@@ -942,6 +943,7 @@ function MailboxList() {
 		useMailContext();
 	const tier = useLayoutTier();
 	const navigate = useNavigate();
+	const retainPanels = useRetainOpenPanels();
 
 	const listTitle = mailboxName ?? "Inbox";
 	const preset = useMemo(() => inboxFilterConfig(), []);
@@ -1029,10 +1031,10 @@ function MailboxList() {
 				// `searchInput`: a row can be tapped before the debounce settles, when
 				// the committed query is still empty.
 				search: (prev) => ({ ...prev, q: searchInput || undefined }),
-				hash: retainOpenPanels,
+				hash: retainPanels,
 			});
 		},
-		[mailboxId, navigate, searchInput, threads],
+		[mailboxId, navigate, retainPanels, searchInput, threads],
 	);
 
 	// Drafts keep their own dedicated view (and header); they don't carry the

package/src/components/mail/MessageActionMenu.tsx

@@ -35,7 +35,7 @@ import {
 	type ThreadListSnapshotEntry,
 	threadListCacheKeys,
 } from "@/lib/thread-list-cache";
-import { retainOpenPanels, useOpenThreadPath } from "@/routing";
+import { useOpenThreadPath, useRetainOpenPanels } from "@/routing";
 import { MoveToTrigger } from "./MoveToTrigger";
 
 interface ThreadMessagesData {
@@ -103,6 +103,7 @@ export const MessageActionMenu = ({
 }: MessageActionMenuProps) => {
 	const queryClient = useQueryClient();
 	const navigate = useNavigate();
+	const retainPanels = useRetainOpenPanels();
 	const { pushError } = useErrorBanners();
 	const selectedMessageId = useOpenThreadPath()?.messageId;
 
@@ -193,10 +194,10 @@ export const MessageActionMenu = ({
 				to: "/mail/$mailboxId",
 				params: { mailboxId },
 				search: (prev) => prev,
-				hash: retainOpenPanels,
+				hash: retainPanels,
 			});
 		},
-		[selectedMessageId, mailboxId, navigate],
+		[selectedMessageId, mailboxId, navigate, retainPanels],
 	);
 
 	const { deleteMessages, isPending: isDeleting } = useDeleteMessages({

package/src/components/mail/MessageList.tsx

@@ -53,7 +53,7 @@ import { useListHeaderChrome } from "@/lib/list-header-chrome";
 import { listVerbRequest } from "@/lib/list-verb-request";
 import { shouldExitSelectionOnNavigate } from "@/lib/selection-mode";
 import { useSelectionWizard, useWizardStepValue } from "@/lib/wizard-history";
-import { retainOpenPanels } from "@/routing";
+import { useRetainOpenPanels } from "@/routing";
 import { LabelApplyTrigger } from "./LabelApplyTrigger";
 import {
 	type EscalatedSelection,
@@ -234,6 +234,7 @@ export const MessageList = ({
 }: MessageListProps) => {
 	const parentRef = useRef<HTMLDivElement>(null);
 	const navigate = useNavigate();
+	const retainPanels = useRetainOpenPanels();
 	const isDesktop = useIsDesktop();
 	const wizard = useSelectionWizard();
 	const { verb: wizardVerb, start: startWizard, startFromSearch } = wizard;
@@ -635,11 +636,11 @@ export const MessageList = ({
 				to: "/mail/$mailboxId/$threadId/$messageId",
 				params: { mailboxId, threadId, messageId },
 				search: (prev) => prev,
-				hash: retainOpenPanels,
+				hash: retainPanels,
 				replace: options?.replace,
 			});
 		},
-		[navigate, mailboxId, threads],
+		[navigate, retainPanels, mailboxId, threads],
 	);
 
 	// Enter: open the focused row in the reading pane. This is the focus→open

package/src/components/mail/OutboxPane.tsx

@@ -63,7 +63,7 @@ import {
 import { isOutboxListRow, isUnsendableStatus } from "@/lib/outbox-status";
 import { normalizeSearchQuery } from "@/lib/search-query";
 import { parseSearchTokens } from "@/lib/search-tokens";
-import { retainOpenPanels } from "@/routing";
+import { useRetainOpenPanels } from "@/routing";
 
 /* ------------------------------------------------------------------ */
 /* Helpers (shared between List, Reading, Phone sub-views)             */
@@ -174,6 +174,7 @@ function OutboxPaneProvider({
 	children,
 }: OutboxPaneProps) {
 	const navigate = useNavigate();
+	const retainPanels = useRetainOpenPanels();
 
 	const { data: outboxResponse, isLoading } = useQuery(
 		outboxOperationsListOutboxMessagesOptions(),
@@ -219,19 +220,19 @@ function OutboxPaneProvider({
 				to: "/mail/outbox/draft/$outboxMessageId",
 				params: { outboxMessageId },
 				search: (prev) => prev,
-				hash: retainOpenPanels,
+				hash: retainPanels,
 			});
 		},
-		[navigate],
+		[navigate, retainPanels],
 	);
 
 	const handleCloseMessage = useCallback(() => {
 		navigate({
 			to: "/mail/outbox",
 			search: (prev) => prev,
-			hash: retainOpenPanels,
+			hash: retainPanels,
 		});
-	}, [navigate]);
+	}, [navigate, retainPanels]);
 
 	const ctx: OutboxPaneContextValue = {
 		messages,

package/src/components/mail/SwipeableMessageRow.tsx

@@ -10,7 +10,7 @@ import { useNavigate } from "@tanstack/react-router";
 import { useCallback, useState } from "react";
 import { toDisplayCategory } from "@/lib/display-category";
 import { formatEmailDate } from "@/lib/format";
-import { retainOpenPanels } from "@/routing";
+import { useRetainOpenPanels } from "@/routing";
 import { MessageListItem } from "./MessageListItem";
 import { useModifierSelect } from "./useModifierSelect";
 
@@ -75,6 +75,7 @@ export const SwipeableMessageRow = ({
 }: SwipeableMessageRowProps) => {
 	const [peek, setPeek] = useState<SwipePeek>("none");
 	const navigate = useNavigate();
+	const retainPanels = useRetainOpenPanels();
 
 	const handleAct = useCallback(
 		(side: "leading" | "trailing") => {
@@ -106,9 +107,9 @@ export const SwipeableMessageRow = ({
 				messageId: thread.messageId,
 			},
 			search: (prev) => prev,
-			hash: retainOpenPanels,
+			hash: retainPanels,
 		});
-	}, [navigate, mailboxId, thread.threadId, thread.messageId]);
+	}, [navigate, retainPanels, mailboxId, thread.threadId, thread.messageId]);
 
 	const modifierSelect = useModifierSelect(thread.messageId, onRowSelect);
 

package/src/components/mail/intelligence-drawer.stories.tsx

@@ -0,0 +1,208 @@
+import { type IntelligenceData, IntelligencePanel } from "@remit/ui";
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { ChevronLeft, Info } from "lucide-react";
+import { useState } from "react";
+import { expect, userEvent, within } from "storybook/test";
+import { Drawer } from "@/components/layout/Drawer";
+import { resolveRailOpen } from "@/lib/intelligence-pref";
+import { parseOpenPanels, retainOpenPanelsAtTier } from "@/routing";
+
+/**
+ * The intelligence drawer below the desktop tier (#777).
+ *
+ * There is no fourth pane here: the rail is a full-screen drawer over the open
+ * message, so it belongs to the thread it was opened for. The address is the
+ * only place its open state lives, and a navigation drops it — otherwise a DKIM
+ * mismatch on one message leaves the drawer covering every message opened
+ * after it.
+ *
+ * Both rules are the app's own: the fragment goes through
+ * `retainOpenPanelsAtTier`, and what is up is `resolveRailOpen`.
+ */
+const meta: Meta = {
+	title: "Flows/Reading/Intelligence Drawer",
+	parameters: { layout: "centered" },
+};
+export default meta;
+
+type Story = StoryObj;
+
+const PHONE_WIDTH = 390;
+const PHONE_HEIGHT = 720;
+
+const retainOnPhone = retainOpenPanelsAtTier(false);
+
+const intelligence: IntelligenceData = {
+	sender: {
+		name: "Mondial Relay",
+		email: "delivery.notice.4421@gmail.example",
+		trust: "unknown",
+		firstSeenLabel: "today",
+		inboundCount: 1,
+		replyCount: 0,
+	},
+	authenticity: {
+		verdict: "mismatch",
+		fromDomain: "mondialrelay.fr",
+		dkimDomain: "gmail.example",
+		claimedBrand: "Mondial Relay",
+		summary:
+			"The display name claims “Mondial Relay”, but the message was sent and signed by a personal gmail.example mailbox — not mondialrelay.fr.",
+		similarCount: 15,
+	},
+	category: { value: "automated" },
+	similar: [],
+};
+
+interface Message {
+	id: string;
+	from: string;
+	subject: string;
+	body: string;
+}
+
+const messages: readonly Message[] = [
+	{
+		id: "msg-parcel",
+		from: "Mondial Relay",
+		subject: "Your parcel could not be delivered",
+		body: "We attempted to deliver your parcel today and nobody was home. Pay the outstanding €2.40 redelivery fee within 24 hours.",
+	},
+	{
+		id: "msg-standup",
+		from: "Alex Rivera",
+		subject: "Standup moved to 10:15",
+		body: "Pushing today's standup back fifteen minutes — the room is taken until then.",
+	},
+];
+
+/**
+ * The phone reader, driven by the address alone: `hash` is the whole state,
+ * and every navigation writes it through the same helper the panes use.
+ */
+const PhoneReader = ({ initialHash = "" }: { initialHash?: string }) => {
+	const [hash, setHash] = useState(initialHash);
+	const [openId, setOpenId] = useState<string | undefined>(messages[0]?.id);
+	const open = messages.find((message) => message.id === openId);
+	const drawerOpen = resolveRailOpen({
+		panels: parseOpenPanels(hash),
+		prefersOpen: true,
+		isDesktop: false,
+		hasThread: open !== undefined,
+	});
+	const navigate = (nextId: string | undefined) => {
+		setHash(retainOnPhone(hash));
+		setOpenId(nextId);
+	};
+
+	return (
+		<div className="flex flex-col gap-2">
+			<div
+				className="flex flex-col overflow-hidden rounded-lg border border-line bg-canvas"
+				// The transform makes the frame a containing block, so the drawer's
+				// `position: fixed` resolves against the phone instead of the canvas.
+				style={{
+					width: PHONE_WIDTH,
+					height: PHONE_HEIGHT,
+					transform: "translateZ(0)",
+				}}
+			>
+				{open ? (
+					<>
+						<header className="flex items-center gap-1 border-b border-line px-2 py-2">
+							<button
+								type="button"
+								aria-label="Back"
+								onClick={() => navigate(undefined)}
+								className="inline-flex size-11 items-center justify-center rounded-md text-fg hover:bg-surface-raised"
+							>
+								<ChevronLeft className="size-5" />
+							</button>
+							<h1 className="min-w-0 flex-1 truncate text-sm font-semibold text-fg">
+								{open.subject}
+							</h1>
+							<button
+								type="button"
+								aria-label="Message details"
+								onClick={() => setHash("intelligence")}
+								className="inline-flex size-11 items-center justify-center rounded-md text-fg hover:bg-surface-raised"
+							>
+								<Info className="size-5" />
+							</button>
+						</header>
+						<div className="min-h-0 flex-1 overflow-y-auto px-4 py-3 text-sm text-fg">
+							<p className="mb-2 text-2xs text-fg-subtle">{open.from}</p>
+							<p>{open.body}</p>
+						</div>
+					</>
+				) : (
+					<ul className="flex flex-col">
+						{messages.map((message) => (
+							<li key={message.id}>
+								<button
+									type="button"
+									onClick={() => navigate(message.id)}
+									className="flex w-full flex-col items-start gap-0.5 border-b border-line px-4 py-3 text-left hover:bg-surface-raised"
+								>
+									<span className="text-sm font-semibold text-fg">
+										{message.from}
+									</span>
+									<span className="text-sm text-fg-muted">
+										{message.subject}
+									</span>
+								</button>
+							</li>
+						))}
+					</ul>
+				)}
+				<Drawer
+					isOpen={drawerOpen}
+					onClose={() => setHash("")}
+					ariaLabel="Message details"
+					side="right"
+				>
+					<IntelligencePanel data={intelligence} hideCloseButton />
+				</Drawer>
+			</div>
+			<p className="font-mono text-2xs text-fg-subtle">
+				{`/mail/inbox${open ? `/${open.id}` : ""}${hash ? `#${hash}` : ""}`}
+			</p>
+		</div>
+	);
+};
+
+/** A message with no drawer over it: the address names no panel. */
+export const Closed: Story = {
+	render: () => <PhoneReader />,
+};
+
+/**
+ * The drawer over the message it was opened for — here by a DKIM mismatch,
+ * which opens it without being asked.
+ */
+export const OpenOverThread: Story = {
+	render: () => <PhoneReader initialHash="intelligence" />,
+};
+
+/**
+ * The same drawer, then Back and another message. The fragment is dropped on
+ * the way out, so the second message is not covered by a panel opened for the
+ * first. Press Back with the drawer up to walk it.
+ */
+export const DroppedByNavigation: Story = {
+	render: () => <PhoneReader initialHash="intelligence" />,
+	play: async ({ canvasElement }) => {
+		const canvas = within(canvasElement);
+		await userEvent.click(canvas.getByLabelText("Back"));
+		await userEvent.click(canvas.getByText("Standup moved to 10:15"));
+		await expect(canvas.queryByRole("dialog")).toBeNull();
+		await expect(canvas.getByText("/mail/inbox/msg-standup")).toBeVisible();
+	},
+};
+
+/** The drawer over the dark theme. */
+export const OpenOverThreadDark: Story = {
+	name: "Open Over Thread (dark)",
+	parameters: { theme: "dark" },
+	render: () => <PhoneReader initialHash="intelligence" />,
+};

package/src/routing/fragment.render.test.ts

@@ -0,0 +1,98 @@
+/**
+ * `useRetainOpenPanels` reads the tier off the app's own desktop breakpoint
+ * (#777), so a navigation below it lands without the rail in the address —
+ * which is what keeps the drawer with the thread it was opened for.
+ */
+
+import assert from "node:assert/strict";
+import { afterEach, describe, it } from "node:test";
+import {
+	type AnyRouter,
+	createMemoryHistory,
+	createRootRoute,
+	createRoute,
+	createRouter,
+	RouterProvider,
+	useNavigate,
+} from "@tanstack/react-router";
+import { createElement } from "react";
+import { createDomHarness, type DomHarness } from "../test-support/dom";
+import { useRetainOpenPanels } from "./fragment";
+
+const PHONE_WIDTH = 390;
+const DESKTOP_WIDTH = 1440;
+
+let harness: DomHarness | undefined;
+
+afterEach(() => {
+	harness?.close();
+	harness = undefined;
+});
+
+// The router reads `self` at construction; the shared jsdom globals stop at
+// `window`.
+(globalThis as { self?: typeof globalThis }).self ??= globalThis;
+
+function CloseThread() {
+	const navigate = useNavigate();
+	const retainPanels = useRetainOpenPanels();
+	return createElement(
+		"button",
+		{
+			type: "button",
+			onClick: () => {
+				void navigate({ to: "/mail", hash: retainPanels });
+			},
+		},
+		"Back",
+	);
+}
+
+const rootRoute = createRootRoute();
+const listRoute = createRoute({
+	getParentRoute: () => rootRoute,
+	path: "/mail",
+});
+const threadRoute = createRoute({
+	getParentRoute: () => rootRoute,
+	path: "/mail/thread",
+	component: CloseThread,
+});
+
+const openDrawerOverThread = (): AnyRouter =>
+	createRouter({
+		routeTree: rootRoute.addChildren([listRoute, threadRoute]),
+		history: createMemoryHistory({
+			initialEntries: ["/mail/thread#intelligence"],
+		}),
+	}) as unknown as AnyRouter;
+
+const walkUpToTheList = async (viewportWidth: number): Promise<AnyRouter> => {
+	const router = openDrawerOverThread();
+	harness = createDomHarness({ viewportWidth });
+	// Resolve the first match before mounting: `RouterProvider` renders its
+	// pending state until the router has loaded, and nothing here waits for it.
+	await router.load();
+	harness.render(createElement(RouterProvider, { router }));
+	await harness.flush();
+	harness.click(harness.byText("button", "Back"));
+	await harness.flush();
+	await harness.wait(20);
+	return router;
+};
+
+describe("useRetainOpenPanels (#777)", () => {
+	it("leaves the drawer behind on a phone", async () => {
+		const router = await walkUpToTheList(PHONE_WIDTH);
+
+		assert.equal(router.state.location.pathname, "/mail");
+		assert.equal(router.state.location.hash, "");
+	});
+
+	it("carries the rail across on desktop, where it is a pane", async () => {
+		const router = await walkUpToTheList(DESKTOP_WIDTH);
+
+		assert.equal(router.state.location.pathname, "/mail");
+		assert.equal(router.state.location.hash, "intelligence");
+	});
+});

package/src/routing/fragment.test.ts

@@ -4,9 +4,12 @@ import {
 	formatOpenPanels,
 	panelFragments,
 	parseOpenPanels,
-	retainOpenPanels,
+	retainOpenPanelsAtTier,
 } from "./fragment.js";
 
+const retainOnDesktop = retainOpenPanelsAtTier(true);
+const retainOnPhone = retainOpenPanelsAtTier(false);
+
 describe("parseOpenPanels", () => {
 	it("reads every panel the union names", () => {
 		for (const panel of panelFragments) {
@@ -50,19 +53,61 @@ describe("formatOpenPanels", () => {
 	});
 });
 
-describe("retainOpenPanels", () => {
-	it("carries a pane across a navigation", () => {
-		assert.equal(retainOpenPanels("intelligence"), "intelligence");
+describe("retainOpenPanelsAtTier", () => {
+	it("carries a pane across a navigation on the tier that has one", () => {
+		assert.equal(retainOnDesktop("intelligence"), "intelligence");
 	});
 
 	it("leaves the overlays behind, and keeps the pane under them", () => {
-		assert.equal(retainOpenPanels("nav"), "");
-		assert.equal(retainOpenPanels("shortcuts"), "");
-		assert.equal(retainOpenPanels("intelligence,shortcuts"), "intelligence");
+		assert.equal(retainOnDesktop("nav"), "");
+		assert.equal(retainOnDesktop("shortcuts"), "");
+		assert.equal(retainOnDesktop("intelligence,shortcuts"), "intelligence");
 	});
 
 	it("drops a fragment it does not recognise rather than passing it on", () => {
-		assert.equal(retainOpenPanels(), "");
-		assert.equal(retainOpenPanels("confirm-delete"), "");
+		assert.equal(retainOnDesktop(), "");
+		assert.equal(retainOnDesktop("confirm-delete"), "");
+		assert.equal(retainOnPhone("confirm-delete"), "");
+	});
+});
+
+/**
+ * Below desktop the rail is a full-screen drawer over the open message, so it
+ * belongs to the thread it was opened for. Every navigation that handed the
+ * fragment on put the drawer over the next message the reader opened.
+ *
+ * Each case walks the fragment through the navigations of one reachable path,
+ * starting from the address the open drawer wrote.
+ */
+describe("the drawer stays with its thread below desktop (#777)", () => {
+	const walk = (
+		retain: (hash?: string) => string,
+		hash: string,
+		steps: number,
+	): string => {
+		let current = hash;
+		for (let step = 0; step < steps; step += 1) current = retain(current);
+		return current;
+	};
+
+	// A DKIM mismatch opens the drawer; the reader taps the back arrow instead
+	// of closing it, then taps another row.
+	it("drops the rail between the back arrow and the next row", () => {
+		assert.equal(walk(retainOnPhone, "intelligence", 2), "");
+		assert.equal(walk(retainOnDesktop, "intelligence", 2), "intelligence");
+	});
+
+	// "Report spam" inside the open drawer removes the thread the drawer is
+	// reading, which closes it up to the list — one navigation, no back button.
+	it("drops the rail when a quick action in the drawer removes the thread", () => {
+		assert.equal(retainOnPhone("intelligence"), "");
+		assert.equal(retainOnDesktop("intelligence"), "intelligence");
+	});
+
+	// The brief and the flagged list open a thread from a cross-mailbox row,
+	// and the shortcuts sheet may be up over the drawer when they do.
+	it("drops the rail when the brief or the flagged list opens a thread", () => {
+		assert.equal(retainOnPhone("intelligence,shortcuts"), "");
+		assert.equal(retainOnDesktop("intelligence,shortcuts"), "intelligence");
 	});
 });

package/src/routing/fragment.ts

@@ -1,6 +1,7 @@
 import { useLocation, useNavigate } from "@tanstack/react-router";
 import { useCallback, useMemo } from "react";
 import { z } from "zod";
+import { useIsDesktop } from "@/hooks/useMediaQuery";
 
 /**
  * The fragment tier carries panel visibility and nothing else — no identity, no
@@ -57,21 +58,48 @@ export function useOpenPanels(): readonly PanelFragment[] {
 	return useMemo(() => parseOpenPanels(hash), [hash]);
 }
 
+/**
+ * Whether a navigation carries this panel at this tier.
+ *
+ * A pane is chrome a reader keeps up while they move from one conversation to
+ * the next; an overlay is dismissed by going somewhere, which is what closing
+ * it means. Below desktop the rail is not a pane at all — it is a full-screen
+ * drawer over the open message — so it belongs to the thread it was opened for
+ * and a navigation leaves it behind, rather than covering a message nobody
+ * asked to cover (#777).
+ */
+const isRetainedPanel = (panel: PanelFragment, isDesktop: boolean): boolean =>
+	!isOverlayPanel(panel) && isDesktop;
+
 /**
  * A destination's `hash`, for a navigation that keeps the reader where they
  * are. The router drops the fragment on every navigation unless the destination
  * asks for it, so this is what a link or a `navigate` call passes to state the
- * rule rather than restate it: a pane is chrome a reader keeps up while they
- * move from one conversation to the next, and an overlay is dismissed by going
- * somewhere, which is what closing it means.
+ * rule rather than restate it.
  *
- * The parameter is optional because the router hands a `hash` updater the
- * previous fragment as `string | undefined`.
+ * The tier is bound here rather than passed at the call site, so the updater
+ * still has the shape the router hands a previous fragment to. That parameter
+ * is optional because the router types it `string | undefined`.
  */
-export function retainOpenPanels(hash = ""): string {
-	return formatOpenPanels(
-		parseOpenPanels(hash).filter((panel) => !isOverlayPanel(panel)),
-	);
+export function retainOpenPanelsAtTier(
+	isDesktop: boolean,
+): (hash?: string) => string {
+	return (hash = "") =>
+		formatOpenPanels(
+			parseOpenPanels(hash).filter((panel) =>
+				isRetainedPanel(panel, isDesktop),
+			),
+		);
+}
+
+/**
+ * The `hash` updater for a navigation from the surface the reader is on. The
+ * layout tier is read here, once, so no call site decides for itself what a
+ * navigation keeps.
+ */
+export function useRetainOpenPanels(): (hash?: string) => string {
+	const isDesktop = useIsDesktop();
+	return useMemo(() => retainOpenPanelsAtTier(isDesktop), [isDesktop]);
 }
 
 /**

package/src/routing/index.ts

@@ -6,8 +6,9 @@ export {
 	type PanelFragment,
 	panelFragments,
 	parseOpenPanels,
-	retainOpenPanels,
+	retainOpenPanelsAtTier,
 	useOpenPanels,
+	useRetainOpenPanels,
 	useSetOpenPanels,
 } from "./fragment";
 export { NavLink, type NavLinkProps } from "./nav-link";

package/src/routing/nav-link.tsx

@@ -7,7 +7,7 @@ import type {
 } from "@tanstack/react-router";
 import { createLink } from "@tanstack/react-router";
 import type { ReactElement } from "react";
-import { type PanelFragment, retainOpenPanels } from "./fragment";
+import { type PanelFragment, useRetainOpenPanels } from "./fragment";
 
 const RouterNavLink = createLink(NavLinkSurface);
 
@@ -45,7 +45,8 @@ export type NavLinkProps<
  *
  * A link that names no panel carries the open panes across: the rail is up
  * until the reader puts it down, and every row in a list is a link. Overlays
- * are left behind, because going somewhere is what dismisses one.
+ * are left behind, because going somewhere is what dismisses one — and below
+ * desktop so is the rail, which is a drawer over the message there.
  */
 export function NavLink<
 	TRouter extends AnyRouter = RegisteredRouter,
@@ -58,5 +59,6 @@ export function NavLink({
 	fragment,
 	...props
 }: CreateLinkProps & { fragment?: PanelFragment }): ReactElement {
-	return <RouterNavLink {...props} hash={fragment ?? retainOpenPanels} />;
+	const retainPanels = useRetainOpenPanels();
+	return <RouterNavLink {...props} hash={fragment ?? retainPanels} />;
 }