@remit/web-client 0.0.162 → 0.0.163

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/web-client",
-  "version": "0.0.162",
+  "version": "0.0.163",
   "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

@@ -41,7 +41,11 @@ import {
 } from "@/hooks/useTriageLayer";
 import type { ConversationTarget } from "@/lib/conversation-target";
 import { useMailContext } from "@/lib/mail-context";
-import type { OpenThreadPath, OpenThreadTarget } from "@/routing";
+import {
+	type OpenThreadPath,
+	type OpenThreadTarget,
+	retainOpenPanels,
+} from "@/routing";
 
 /* ------------------------------------------------------------------ */
 /* Context                                                              */
@@ -148,13 +152,18 @@ 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,
 			});
 		},
 		[navigate, searchInput],
 	);
 
 	const handleCloseThread = useCallback(() => {
-		navigate({ to: "/mail/brief", search: (prev) => prev });
+		navigate({
+			to: "/mail/brief",
+			search: (prev) => prev,
+			hash: retainOpenPanels,
+		});
 	}, [navigate]);
 
 	const handleDeselectIfRemoved = useCallback(

package/src/components/mail/DraftsView.tsx

@@ -41,6 +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 { NavMenuButton } from "./NavMenuButton";
 
 // ---------------------------------------------------------------------------
@@ -197,6 +198,7 @@ export function DraftsView({
 			to: "/mail/$mailboxId/$threadId/$messageId",
 			params: { mailboxId, threadId, messageId },
 			search: (prev) => prev,
+			hash: retainOpenPanels,
 		});
 	};
 

package/src/components/mail/FlaggedPane.tsx

@@ -52,7 +52,11 @@ import {
 } from "@/hooks/useTriageLayer";
 import type { ConversationTarget } from "@/lib/conversation-target";
 import { useMailContext } from "@/lib/mail-context";
-import type { OpenThreadPath, OpenThreadTarget } from "@/routing";
+import {
+	type OpenThreadPath,
+	type OpenThreadTarget,
+	retainOpenPanels,
+} from "@/routing";
 
 /* ------------------------------------------------------------------ */
 /* Context                                                              */
@@ -154,13 +158,18 @@ 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,
 			});
 		},
 		[navigate, searchInput],
 	);
 
 	const handleCloseThread = useCallback(() => {
-		navigate({ to: "/mail/flagged", search: (prev) => prev });
+		navigate({
+			to: "/mail/flagged",
+			search: (prev) => prev,
+			hash: retainOpenPanels,
+		});
 	}, [navigate]);
 
 	const handleDeselectIfRemoved = useCallback(

package/src/components/mail/MailboxPane.tsx

@@ -108,7 +108,6 @@ import {
 	inboxFilterParams,
 	sameInboxFilter,
 } from "@/lib/inbox-filters";
-import { readIntelligencePref } from "@/lib/intelligence-pref";
 import { junkDestination } from "@/lib/junk-destination";
 import { useMailContext } from "@/lib/mail-context";
 import { useMailFreshness } from "@/lib/mail-freshness";
@@ -125,7 +124,11 @@ import {
 	applyResidualTokens,
 	threadSearchTokens,
 } from "@/lib/thread-search-tokens";
-import type { OpenThreadPath, OpenThreadTarget } from "@/routing";
+import {
+	type OpenThreadPath,
+	type OpenThreadTarget,
+	retainOpenPanels,
+} from "@/routing";
 import { MailViewChrome } from "./MailViewChrome";
 
 /* ------------------------------------------------------------------ */
@@ -263,16 +266,9 @@ function MailboxPaneProvider({
 	const navigate = useNavigate();
 	const threadId = thread?.threadId;
 	const pointedAtMessageId = thread?.messageId;
-	const tier = useLayoutTier();
-	const isDesktop = tier === "desktop";
 	const telemetry = useTelemetry();
-	const {
-		accounts,
-		searchQuery,
-		intelligenceOpen,
-		onToggleIntelligence,
-		onSetIntelligenceOpen,
-	} = useMailContext();
+	const { accounts, searchQuery, intelligenceOpen, onToggleIntelligence } =
+		useMailContext();
 	const tokenContext = useSearchTokenContext();
 
 	const normalizedSearchQuery = normalizeSearchQuery(searchQuery);
@@ -471,6 +467,7 @@ function MailboxPaneProvider({
 			to: "/mail/$mailboxId",
 			params: { mailboxId },
 			search: (prev) => prev,
+			hash: retainOpenPanels,
 		});
 	}, [mailboxId, navigate]);
 
@@ -480,6 +477,7 @@ function MailboxPaneProvider({
 				to: "/mail/$mailboxId/$threadId/$messageId",
 				params: { mailboxId, ...target },
 				search: (prev) => prev,
+				hash: retainOpenPanels,
 			});
 		},
 		[mailboxId, navigate],
@@ -535,23 +533,6 @@ function MailboxPaneProvider({
 		onToggleIntelligence,
 	]);
 
-	// Desktop default-open (#782)
-	const appliedDefaultRef = useRef(false);
-	useEffect(() => {
-		if (appliedDefaultRef.current) return;
-		if (!isDesktop) return;
-		if (!selectedThread?.messageId) return;
-		appliedDefaultRef.current = true;
-		if (readIntelligencePref() && !intelligenceOpen) {
-			onSetIntelligenceOpen(true);
-		}
-	}, [
-		isDesktop,
-		selectedThread?.messageId,
-		intelligenceOpen,
-		onSetIntelligenceOpen,
-	]);
-
 	// The mailbox's own unseen total. A count over the loaded pages undercounts
 	// every mailbox larger than one page and creeps upward as the user scrolls,
 	// so there is no fallback: until the mailbox resolves there is no number.
@@ -1048,6 +1029,7 @@ 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,
 			});
 		},
 		[mailboxId, navigate, searchInput, threads],

package/src/components/mail/MessageActionMenu.tsx

@@ -35,7 +35,7 @@ import {
 	type ThreadListSnapshotEntry,
 	threadListCacheKeys,
 } from "@/lib/thread-list-cache";
-import { useOpenThreadPath } from "@/routing";
+import { retainOpenPanels, useOpenThreadPath } from "@/routing";
 import { MoveToTrigger } from "./MoveToTrigger";
 
 interface ThreadMessagesData {
@@ -193,6 +193,7 @@ export const MessageActionMenu = ({
 				to: "/mail/$mailboxId",
 				params: { mailboxId },
 				search: (prev) => prev,
+				hash: retainOpenPanels,
 			});
 		},
 		[selectedMessageId, mailboxId, navigate],

package/src/components/mail/MessageList.tsx

@@ -53,6 +53,7 @@ import { listVerbRequest } from "@/lib/list-verb-request";
 import { shouldExitSelectionOnNavigate } from "@/lib/selection-mode";
 import { cn } from "@/lib/utils";
 import { useSelectionWizard, useWizardStepValue } from "@/lib/wizard-history";
+import { retainOpenPanels } from "@/routing";
 import { LabelApplyTrigger } from "./LabelApplyTrigger";
 import {
 	type EscalatedSelection,
@@ -634,6 +635,7 @@ export const MessageList = ({
 				to: "/mail/$mailboxId/$threadId/$messageId",
 				params: { mailboxId, threadId, messageId },
 				search: (prev) => prev,
+				hash: retainOpenPanels,
 				replace: options?.replace,
 			});
 		},

package/src/components/mail/OutboxPane.tsx

@@ -63,6 +63,7 @@ import { isOutboxListRow, isUnsendableStatus } from "@/lib/outbox-status";
 import { normalizeSearchQuery } from "@/lib/search-query";
 import { parseSearchTokens } from "@/lib/search-tokens";
 import { cn } from "@/lib/utils";
+import { retainOpenPanels } from "@/routing";
 
 /* ------------------------------------------------------------------ */
 /* Helpers (shared between List, Reading, Phone sub-views)             */
@@ -218,13 +219,18 @@ function OutboxPaneProvider({
 				to: "/mail/outbox/draft/$outboxMessageId",
 				params: { outboxMessageId },
 				search: (prev) => prev,
+				hash: retainOpenPanels,
 			});
 		},
 		[navigate],
 	);
 
 	const handleCloseMessage = useCallback(() => {
-		navigate({ to: "/mail/outbox", search: (prev) => prev });
+		navigate({
+			to: "/mail/outbox",
+			search: (prev) => prev,
+			hash: retainOpenPanels,
+		});
 	}, [navigate]);
 
 	const ctx: OutboxPaneContextValue = {

package/src/components/mail/SwipeableMessageRow.tsx

@@ -10,6 +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 { MessageListItem } from "./MessageListItem";
 import { useModifierSelect } from "./useModifierSelect";
 
@@ -105,6 +106,7 @@ export const SwipeableMessageRow = ({
 				messageId: thread.messageId,
 			},
 			search: (prev) => prev,
+			hash: retainOpenPanels,
 		});
 	}, [navigate, mailboxId, thread.threadId, thread.messageId]);
 

package/src/components/ui/KeyboardShortcutsModal.tsx

@@ -22,6 +22,8 @@ export const KeyboardShortcutsModal = ({
 		(event: KeyboardEvent) => {
 			if (event.key === "Escape") {
 				event.preventDefault();
+				event.stopPropagation();
+				event.stopImmediatePropagation();
 				onClose();
 			}
 		},
@@ -30,8 +32,11 @@ export const KeyboardShortcutsModal = ({
 
 	useEffect(() => {
 		if (!isOpen) return;
-		window.addEventListener("keydown", handleKeyDown);
-		return () => window.removeEventListener("keydown", handleKeyDown);
+		// Capture phase, as `ConfirmDialog` does: the sheet is the topmost surface,
+		// so Escape dismisses it and nothing else. Shared with the list's own
+		// Escape, the one keystroke also closed the conversation underneath.
+		window.addEventListener("keydown", handleKeyDown, true);
+		return () => window.removeEventListener("keydown", handleKeyDown, true);
 	}, [isOpen, handleKeyDown]);
 
 	if (!isOpen) return null;

package/src/hooks/search-mirror-detail.render.test.ts

@@ -65,7 +65,6 @@ const mailContext = (
 	onSearchClearQuery: () => {},
 	intelligenceOpen: false,
 	onToggleIntelligence: () => {},
-	onSetIntelligenceOpen: () => {},
 });
 
 type ListPath = "/mail/brief" | "/mail/flagged";

package/src/hooks/useSearchMirror.ts

@@ -71,16 +71,24 @@ export function useSearchMirror(target: SearchMirrorTarget): void {
 			...prev,
 			q: committedQuery || undefined,
 		});
+		// A query is a mode of the view the reader is already in, so the panels
+		// they have up are not ones they navigated away from.
 		if (!queryGoesActive) {
-			navigate({ to: ".", search, replace: true });
+			navigate({ to: ".", search, hash: true, replace: true });
 			return;
 		}
 		if (to === "/mail/$mailboxId") {
 			if (!mailboxId) return;
-			navigate({ to, params: { mailboxId }, search, replace: true });
+			navigate({
+				to,
+				params: { mailboxId },
+				search,
+				hash: true,
+				replace: true,
+			});
 			return;
 		}
-		navigate({ to, search, replace: true });
+		navigate({ to, search, hash: true, replace: true });
 	}, [
 		searchInput,
 		committedQuery,

package/src/lib/intelligence-pref.test.ts

@@ -2,6 +2,7 @@ import assert from "node:assert/strict";
 import { afterEach, beforeEach, describe, it } from "node:test";
 import {
 	readIntelligencePref,
+	resolveRailOpen,
 	writeIntelligencePref,
 } from "./intelligence-pref.js";
 
@@ -55,3 +56,79 @@ describe("intelligence-pref (#782)", () => {
 		assert.doesNotThrow(() => writeIntelligencePref(false));
 	});
 });
+
+describe("resolveRailOpen (#722)", () => {
+	const withThread = { hasThread: true, isDesktop: true };
+
+	it("opens the rail with the thread where the address says nothing", () => {
+		assert.equal(
+			resolveRailOpen({ ...withThread, panels: [], prefersOpen: true }),
+			true,
+		);
+	});
+
+	it("leaves the rail down where the address says nothing and the reader collapsed it", () => {
+		assert.equal(
+			resolveRailOpen({ ...withThread, panels: [], prefersOpen: false }),
+			false,
+		);
+	});
+
+	it("never seeds the rail below the tier that has one", () => {
+		assert.equal(
+			resolveRailOpen({
+				panels: [],
+				prefersOpen: true,
+				isDesktop: false,
+				hasThread: true,
+			}),
+			false,
+		);
+	});
+
+	// Otherwise the address claims a pane the shell has nothing to put in it.
+	it("never seeds the rail with no conversation open", () => {
+		assert.equal(
+			resolveRailOpen({
+				panels: [],
+				prefersOpen: true,
+				isDesktop: true,
+				hasThread: false,
+			}),
+			false,
+		);
+	});
+
+	// A shared link naming another panel is an address that has spoken: the
+	// recipient's own preference does not get to add the rail to it.
+	it("hands a shared link's panels to the reader who opened it", () => {
+		assert.equal(
+			resolveRailOpen({
+				...withThread,
+				panels: ["shortcuts"],
+				prefersOpen: true,
+			}),
+			false,
+		);
+		assert.equal(
+			resolveRailOpen({
+				...withThread,
+				panels: ["intelligence", "shortcuts"],
+				prefersOpen: false,
+			}),
+			true,
+		);
+	});
+
+	it("opens the rail from an address on any tier", () => {
+		assert.equal(
+			resolveRailOpen({
+				panels: ["intelligence"],
+				prefersOpen: false,
+				isDesktop: false,
+				hasThread: true,
+			}),
+			true,
+		);
+	});
+});

package/src/lib/intelligence-pref.ts

@@ -1,10 +1,12 @@
 /**
- * Persistence for the intelligence-pane open/closed preference (#782).
+ * Persistence for the intelligence-pane open/closed preference (#782), and the
+ * precedence between it and the address (#722).
  *
  * The pane opens with the thread by default; a manual collapse sticks across
  * sessions. Storage failures (private mode / quota) fall back to the default
  * (open) rather than crashing.
  */
+import type { PanelFragment } from "@/routing";
 
 export const INTELLIGENCE_PREF_KEY = "remit:intelligence-open";
 
@@ -23,3 +25,33 @@ export function writeIntelligencePref(open: boolean): void {
 		// Storage unavailable — the in-memory default stands.
 	}
 }
+
+export interface RailVisibility {
+	/** The panels the address names. */
+	panels: readonly PanelFragment[];
+	prefersOpen: boolean;
+	/** The rail is a pane of the desktop shell; narrower tiers have a drawer. */
+	isDesktop: boolean;
+	/** The rail reads a conversation, so with none open there is nothing to be up. */
+	hasThread: boolean;
+}
+
+/**
+ * Whether the rail is up.
+ *
+ * An address that names any panel is the only owner of what is open, so a
+ * shared link showing the shortcuts sheet is not overwritten by the recipient's
+ * own preference. The preference speaks only where the address is silent, and
+ * only with a conversation open on the tier that has a rail — it opens with the
+ * thread there (#782), while a phone would get a full-screen drawer over a
+ * message nobody asked to cover.
+ */
+export function resolveRailOpen({
+	panels,
+	prefersOpen,
+	isDesktop,
+	hasThread,
+}: RailVisibility): boolean {
+	if (panels.length > 0) return panels.includes("intelligence");
+	return isDesktop && hasThread && prefersOpen;
+}

package/src/lib/mail-context.ts

@@ -47,13 +47,14 @@ export interface MailContextValue {
 	onSearchClear: () => void;
 	/** Query-only clear (Esc): drops the query, keeps the thread open (#489). */
 	onSearchClearQuery: () => void;
-	/** Pane 4 (intelligence) visibility. The shared toggle starts closed; the
-	 *  desktop route opens it by default with the thread, honouring the stored
-	 *  preference (#782). */
+	/**
+	 * Whether pane 4 (intelligence) is up. Resolved once by the `/mail` layout
+	 * from the address and this device's preference (`resolveRailOpen`), and
+	 * handed down as the answer — a consumer re-deriving it from the fragment
+	 * alone would lose the preference and disagree with the shell.
+	 */
 	intelligenceOpen: boolean;
 	onToggleIntelligence: () => void;
-	/** Set the pane open/closed and persist the choice (desktop default-open). */
-	onSetIntelligenceOpen: (open: boolean) => void;
 }
 
 export const MailContext = createContext<MailContextValue | null>(null);
@@ -77,7 +78,6 @@ export const useMailContext = (): MailContextValue => {
 			onSearchClearQuery: () => {},
 			intelligenceOpen: false,
 			onToggleIntelligence: () => {},
-			onSetIntelligenceOpen: () => {},
 		}
 	);
 };

package/src/routes/mail.tsx

@@ -27,13 +27,24 @@ import { useMailboxNameIndex } from "@/hooks/useMailboxNameIndex";
 import { useResultFolderIndex } from "@/hooks/useResultFolderIndex";
 import { useStaleAccountSync } from "@/hooks/useStaleAccountSync";
 import { hostsComposeSurface } from "@/lib/compose-routes";
-import { writeIntelligencePref } from "@/lib/intelligence-pref";
+import {
+	readIntelligencePref,
+	resolveRailOpen,
+	writeIntelligencePref,
+} from "@/lib/intelligence-pref";
 import { MailContext } from "@/lib/mail-context";
 import { MailFreshnessProvider } from "@/lib/mail-freshness";
 import { mailViewKey } from "@/lib/mail-route";
 import { buildAccountNameIndex } from "@/lib/search-token-index";
 import { committedSearchQuery, searchInputForView } from "@/lib/search-view";
 import { wizardEntryValue, wizardStepValue } from "@/lib/wizard-history";
+import {
+	isOverlayPanel,
+	type OverlayPanel,
+	useOpenPanels,
+	useOpenThreadPath,
+	useSetOpenPanels,
+} from "@/routing";
 import "@/lib/client";
 
 // `MailContext` / `useMailContext` live in `@/lib/mail-context` so the provider
@@ -79,19 +90,56 @@ function MailLayout() {
 	// tablet with no compose surface (compose lives in the reading pane, which
 	// tablet doesn't mount) — the "c" shortcut / FAB opened nothing.
 	const isSinglePane = isSinglePaneTier(tier);
-	const [showShortcuts, setShowShortcuts] = useState(false);
-	const [drawerOpen, setDrawerOpen] = useState(false);
-	// Pane 4 / the mobile details drawer share this toggle. It starts closed so
-	// the phone never slams a full-screen intelligence drawer over a freshly
-	// opened thread; the DESKTOP route opens it by default with the thread (the
-	// intelligence rail is the product's core value) and honours the persisted
-	// collapse preference there (#782). DKIM-mismatch auto-open still fires on
-	// every tier. Explicit toggles persist the user's choice.
-	const [intelligenceOpen, setIntelligenceOpen] = useState(false);
-	const handleSetIntelligenceOpen = useCallback((open: boolean) => {
-		setIntelligenceOpen(open);
-		writeIntelligencePref(open);
-	}, []);
+	// The panels the address carries (#722): the intelligence rail, the nav
+	// slide-over and the shortcuts sheet. The rail is a pane and the other two
+	// cover it, so the address holds a pane and an overlay at once — a sheet
+	// opening never takes the rail down — while two overlays cannot both be up.
+	const openPanels = useOpenPanels();
+	const setOpenPanels = useSetOpenPanels();
+	const openOverlay = openPanels.find(isOverlayPanel);
+	const showShortcuts = openOverlay === "shortcuts";
+	const drawerOpen = openOverlay === "nav";
+	// Pane 4 on desktop, the details drawer below it. `resolveRailOpen` is the
+	// one place the address and the stored preference meet: the address decides
+	// whenever it says anything at all, and the preference opens the rail with
+	// the thread where it is silent (#782).
+	const openThread = useOpenThreadPath();
+	// Held in state, not read back from storage each render: closing the rail
+	// where the address is silent changes nothing about the address, and the
+	// answer has to move anyway.
+	const [prefersRail, setPrefersRail] = useState(readIntelligencePref);
+	const intelligenceOpen = resolveRailOpen({
+		panels: openPanels,
+		prefersOpen: prefersRail,
+		isDesktop: tier === "desktop",
+		hasThread: openThread !== undefined,
+	});
+	// Every write states the whole set, because it is composed from what is
+	// showing rather than from what the address happens to spell: the rail open
+	// by preference alone is still open, and an overlay must not close it.
+	const showPanels = useCallback(
+		(rail: boolean, overlay: OverlayPanel | undefined) => {
+			setOpenPanels([
+				...(rail ? (["intelligence"] as const) : []),
+				...(overlay ? [overlay] : []),
+			]);
+		},
+		[setOpenPanels],
+	);
+	const handleSetIntelligenceOpen = useCallback(
+		(open: boolean) => {
+			writeIntelligencePref(open);
+			setPrefersRail(open);
+			showPanels(open, openOverlay);
+		},
+		[openOverlay, showPanels],
+	);
+	const showOverlay = useCallback(
+		(overlay: OverlayPanel | undefined) => {
+			showPanels(intelligenceOpen, overlay);
+		},
+		[intelligenceOpen, showPanels],
+	);
 
 	// Within one view, URL `q` seeds the input and is a one-directional write
 	// target: the debounced local value drives the search API and is mirrored
@@ -157,7 +205,7 @@ function MailLayout() {
 		bindings: [
 			{
 				key: "?",
-				handler: () => setShowShortcuts(true),
+				handler: () => showOverlay("shortcuts"),
 				noModifiers: false, // Allow shift+/
 				preventDefault: true,
 			},
@@ -193,12 +241,8 @@ function MailLayout() {
 	}, []);
 
 	const handleToggleIntelligence = useCallback(() => {
-		setIntelligenceOpen((open) => {
-			const next = !open;
-			writeIntelligencePref(next);
-			return next;
-		});
-	}, []);
+		handleSetIntelligenceOpen(!intelligenceOpen);
+	}, [handleSetIntelligenceOpen, intelligenceOpen]);
 
 	const accounts = config?.accounts ?? [];
 	const accountIds = useMemo(
@@ -218,11 +262,12 @@ function MailLayout() {
 	useStaleAccountSync(accounts);
 
 	const handleMailboxSelect = useCallback(() => {
-		// Auto-collapse the mobile drawer after the user picks an inbox
-		// from the sidebar (#199). Desktop sidebar isn't a drawer so the
-		// noop is fine there.
-		setDrawerOpen(false);
-	}, []);
+		// Auto-collapse the mobile drawer after the user picks an inbox from the
+		// sidebar (#199). Above the slide-over the sidebar is a pane, and there is
+		// no overlay of its own to take down.
+		if (openOverlay !== "nav") return;
+		showOverlay(undefined);
+	}, [openOverlay, showOverlay]);
 
 	const mailContextValue = {
 		accounts,
@@ -239,7 +284,6 @@ function MailLayout() {
 		onSearchClearQuery: handleSearchClearQuery,
 		intelligenceOpen,
 		onToggleIntelligence: handleToggleIntelligence,
-		onSetIntelligenceOpen: handleSetIntelligenceOpen,
 	};
 
 	// Single nav node: the kit renders it as a pane (≥1024px) or inside its
@@ -259,8 +303,8 @@ function MailLayout() {
 		// top bar owns compose.
 		overlay: isSinglePane ? <ComposeFab /> : undefined,
 		navOpen: drawerOpen,
-		onOpenNav: () => setDrawerOpen(true),
-		onCloseNav: () => setDrawerOpen(false),
+		onOpenNav: () => showOverlay("nav"),
+		onCloseNav: () => showOverlay(undefined),
 	};
 
 	return (
@@ -284,7 +328,7 @@ function MailLayout() {
 				)}
 				<KeyboardShortcutsModal
 					isOpen={showShortcuts}
-					onClose={() => setShowShortcuts(false)}
+					onClose={() => showOverlay(undefined)}
 				/>
 			</MailFreshnessProvider>
 		</MailContext.Provider>

package/src/routing/fragment.test.ts

@@ -0,0 +1,68 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import {
+	formatOpenPanels,
+	panelFragments,
+	parseOpenPanels,
+	retainOpenPanels,
+} from "./fragment.js";
+
+describe("parseOpenPanels", () => {
+	it("reads every panel the union names", () => {
+		for (const panel of panelFragments) {
+			assert.deepEqual(parseOpenPanels(panel), [panel]);
+		}
+	});
+
+	it("reads a pane and an overlay together", () => {
+		assert.deepEqual(parseOpenPanels("intelligence,shortcuts"), [
+			"intelligence",
+			"shortcuts",
+		]);
+	});
+
+	it("spells one set of panels one way", () => {
+		assert.deepEqual(parseOpenPanels("shortcuts,intelligence,shortcuts"), [
+			"intelligence",
+			"shortcuts",
+		]);
+	});
+
+	it("reads an empty, unknown or mis-cased fragment as no panel", () => {
+		assert.deepEqual(parseOpenPanels(""), []);
+		assert.deepEqual(parseOpenPanels("confirm-delete"), []);
+		assert.deepEqual(parseOpenPanels("Intelligence"), []);
+		assert.deepEqual(parseOpenPanels("form:input:to"), []);
+	});
+
+	it("keeps the panels it recognises out of a fragment carrying junk", () => {
+		assert.deepEqual(parseOpenPanels("filters,intelligence"), ["intelligence"]);
+	});
+});
+
+describe("formatOpenPanels", () => {
+	it("writes the address a set of panels is read back from", () => {
+		assert.equal(
+			formatOpenPanels(["shortcuts", "intelligence"]),
+			"intelligence,shortcuts",
+		);
+		assert.equal(formatOpenPanels([]), "");
+	});
+});
+
+describe("retainOpenPanels", () => {
+	it("carries a pane across a navigation", () => {
+		assert.equal(retainOpenPanels("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");
+	});
+
+	it("drops a fragment it does not recognise rather than passing it on", () => {
+		assert.equal(retainOpenPanels(), "");
+		assert.equal(retainOpenPanels("confirm-delete"), "");
+	});
+});

package/src/routing/fragment.ts

@@ -1,4 +1,5 @@
-import { useLocation } from "@tanstack/react-router";
+import { useLocation, useNavigate } from "@tanstack/react-router";
+import { useCallback, useMemo } from "react";
 import { z } from "zod";
 
 /**
@@ -7,29 +8,91 @@ import { z } from "zod";
  * independent of in-memory data, so a cold load of the URL reproduces it
  * exactly.
  */
-export const panelFragments = [
-	"intelligence",
-	"nav",
-	"shortcuts",
-	"filters",
-] as const;
+export const panelFragments = ["intelligence", "nav", "shortcuts"] as const;
 
 export type PanelFragment = (typeof panelFragments)[number];
 
+/**
+ * The panels that cover the view rather than sit in it. The rail is a pane in
+ * the shell's row and the other two are modal over it, so a sheet opening can
+ * never take the rail down with it — the address holds the pane and the overlay
+ * at once. Two overlays cannot be up together, because the second one hides the
+ * first.
+ */
+export const overlayPanels = ["nav", "shortcuts"] as const;
+
+export type OverlayPanel = (typeof overlayPanels)[number];
+
+export const isOverlayPanel = (panel: PanelFragment): panel is OverlayPanel =>
+	(overlayPanels as readonly PanelFragment[]).includes(panel);
+
 const panelFragmentSchema = z.enum(panelFragments);
 
 /**
- * A hand-edited or stale URL is a normal thing to receive, so an unrecognised
- * fragment reads as "no panel open" instead of throwing.
+ * The panels the address asks for, in the union's own order so one set of open
+ * panels has one spelling. A hand-edited or stale URL is a normal thing to
+ * receive, so an unrecognised name is dropped instead of throwing.
  */
-export function parsePanelFragment(hash: string): PanelFragment | undefined {
-	const parsed = panelFragmentSchema.safeParse(hash);
-	return parsed.success ? parsed.data : undefined;
+export function parseOpenPanels(hash: string): readonly PanelFragment[] {
+	const named = new Set(
+		hash
+			.split(",")
+			.map((token) => panelFragmentSchema.safeParse(token))
+			.filter((parsed) => parsed.success)
+			.map((parsed) => parsed.data),
+	);
+	return panelFragments.filter((panel) => named.has(panel));
+}
+
+/** The address a set of open panels is written as. */
+export function formatOpenPanels(panels: readonly PanelFragment[]): string {
+	return panelFragments.filter((panel) => panels.includes(panel)).join(",");
 }
 
-/** The panel the URL currently asks for, if any. */
-export function useOpenPanel(): PanelFragment | undefined {
-	return useLocation({
-		select: (location) => parsePanelFragment(location.hash),
+/** The panels the address currently asks for. */
+export function useOpenPanels(): readonly PanelFragment[] {
+	const hash = useLocation({
+		select: (location) => formatOpenPanels(parseOpenPanels(location.hash)),
 	});
+	return useMemo(() => parseOpenPanels(hash), [hash]);
+}
+
+/**
+ * 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.
+ *
+ * The parameter is optional because the router hands a `hash` updater the
+ * previous fragment as `string | undefined`.
+ */
+export function retainOpenPanels(hash = ""): string {
+	return formatOpenPanels(
+		parseOpenPanels(hash).filter((panel) => !isOverlayPanel(panel)),
+	);
+}
+
+/**
+ * Puts a set of panels up, replacing whatever was up before.
+ *
+ * `replace`, because a panel is chrome over the current view rather than a place
+ * to go: Back belongs to the message the reader came from, not to the rail they
+ * just collapsed. The fragment names panels and never an element, so it is not
+ * an anchor to scroll to either.
+ */
+export function useSetOpenPanels(): (panels: readonly PanelFragment[]) => void {
+	const navigate = useNavigate();
+	return useCallback(
+		(panels: readonly PanelFragment[]) => {
+			navigate({
+				search: true,
+				hash: formatOpenPanels(panels),
+				replace: true,
+				hashScrollIntoView: false,
+			});
+		},
+		[navigate],
+	);
 }

package/src/routing/index.ts

@@ -1,8 +1,14 @@
 export {
+	formatOpenPanels,
+	isOverlayPanel,
+	type OverlayPanel,
+	overlayPanels,
 	type PanelFragment,
 	panelFragments,
-	parsePanelFragment,
-	useOpenPanel,
+	parseOpenPanels,
+	retainOpenPanels,
+	useOpenPanels,
+	useSetOpenPanels,
 } from "./fragment";
 export { NavLink, type NavLinkProps } from "./nav-link";
 export {

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 } from "./fragment";
+import { type PanelFragment, retainOpenPanels } from "./fragment";
 
 const RouterNavLink = createLink(NavLinkSurface);
 
@@ -42,6 +42,10 @@ export type NavLinkProps<
  * The application's only navigation link. `createLink` keeps the router's `to` /
  * `params` / `search` inference, so a route that does not exist or a param set
  * that does not match it fails to compile instead of rendering a blank pane.
+ *
+ * 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.
  */
 export function NavLink<
 	TRouter extends AnyRouter = RegisteredRouter,
@@ -54,5 +58,5 @@ export function NavLink({
 	fragment,
 	...props
 }: CreateLinkProps & { fragment?: PanelFragment }): ReactElement {
-	return <RouterNavLink {...props} hash={fragment} />;
+	return <RouterNavLink {...props} hash={fragment ?? retainOpenPanels} />;
 }