@remit/web-client 0.0.222 → 0.0.224

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/web-client",
-  "version": "0.0.222",
+  "version": "0.0.224",
   "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/compose/MobileComposeSheet.tsx

@@ -1,5 +1,5 @@
 import { configOperationsGetConfigOptions } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
-import { ConfirmDialog } from "@remit/ui";
+import { ConfirmDialog, useOverlayScope } from "@remit/ui";
 import { useQuery } from "@tanstack/react-query";
 import { useCallback, useRef, useState } from "react";
 import { Drawer } from "vaul";
@@ -75,6 +75,10 @@ export const MobileComposeSheet = () => {
 		setShowConfirm(false);
 	}, []);
 
+	// vaul answers Escape itself; declaring the scope is what keeps the rest of
+	// the keyboard off the list behind the sheet.
+	useOverlayScope({ id: "mobile-compose", open: true });
+
 	return (
 		<Drawer.Root
 			open

package/src/components/layout/Drawer.tsx

@@ -1,4 +1,4 @@
-import { cn } from "@remit/ui";
+import { cn, type OverlayAnswers, useOverlayScope } from "@remit/ui";
 import { X } from "lucide-react";
 import { type ReactNode, useEffect, useRef } from "react";
 
@@ -40,6 +40,13 @@ interface DrawerProps {
 	ariaLabel?: string;
 	side?: "left" | "right";
 	widthClassName?: string;
+	/**
+	 * Shortcuts the drawer keeps serving while it is up, beyond Escape. The key
+	 * that opened it is the one that has to reach it — `i` closes the
+	 * intelligence drawer it opened — and everything left undeclared is
+	 * contained, so no verb acts on the list behind the scrim.
+	 */
+	answers?: OverlayAnswers;
 }
 
 /**
@@ -58,21 +65,23 @@ export const Drawer = ({
 	ariaLabel = "Navigation",
 	side = "left",
 	widthClassName = "w-[80vw] max-w-[320px]",
+	answers,
 }: DrawerProps) => {
 	const drawerRef = useRef<HTMLDivElement>(null);
 	const previouslyFocusedRef = useRef<HTMLElement | null>(null);
 
+	useOverlayScope({
+		id: "drawer",
+		open: isOpen,
+		answers: { back: onClose, ...answers },
+	});
+
 	useEffect(() => {
 		if (!isOpen) return;
 
 		previouslyFocusedRef.current = document.activeElement as HTMLElement | null;
 
 		const handleKey = (event: KeyboardEvent) => {
-			if (event.key === "Escape") {
-				event.preventDefault();
-				onClose();
-				return;
-			}
 			// Trap Tab inside the drawer's ring: walking off either end cycles
 			// round, and focus that is in the drawer but outside the ring — a
 			// control behind a nested dialog's backdrop — is pulled in, so Tab
@@ -115,7 +124,7 @@ export const Drawer = ({
 			document.body.style.overflow = previousOverflow;
 			previouslyFocusedRef.current?.focus();
 		};
-	}, [isOpen, onClose]);
+	}, [isOpen]);
 
 	if (!isOpen) return null;
 

package/src/components/mail/ConversationView.tsx

@@ -292,25 +292,62 @@ export const ConversationView = ({
 			...(listOnScreen
 				? []
 				: [
-						{ key: "j", handler: focusNext, preventDefault: true },
-						{ key: "ArrowDown", handler: focusNext, preventDefault: true },
-						{ key: "k", handler: focusPrevious, preventDefault: true },
-						{ key: "ArrowUp", handler: focusPrevious, preventDefault: true },
+						{
+							key: "j",
+							action: "focusNext" as const,
+							handler: focusNext,
+							preventDefault: true,
+						},
+						{
+							key: "ArrowDown",
+							action: "focusNext" as const,
+							handler: focusNext,
+							preventDefault: true,
+						},
+						{
+							key: "k",
+							action: "focusPrevious" as const,
+							handler: focusPrevious,
+							preventDefault: true,
+						},
+						{
+							key: "ArrowUp",
+							action: "focusPrevious" as const,
+							handler: focusPrevious,
+							preventDefault: true,
+						},
 						{
 							key: "Enter",
+							action: "openFocused" as const,
+							handler: toggleFocusedMessage,
+							preventDefault: true,
+						},
+						{
+							key: "o",
+							action: "openFocused" as const,
 							handler: toggleFocusedMessage,
 							preventDefault: true,
 						},
-						{ key: "o", handler: toggleFocusedMessage, preventDefault: true },
 					]),
-			{ key: "r", handler: handleReply, preventDefault: true },
+			{
+				key: "r",
+				action: "reply" as const,
+				handler: handleReply,
+				preventDefault: true,
+			},
 			{
 				key: "R",
+				action: "replyAll" as const,
 				handler: handleReplyAll,
 				noModifiers: false,
 				preventDefault: true,
 			},
-			{ key: "f", handler: handleForward, preventDefault: true },
+			{
+				key: "f",
+				action: "forward" as const,
+				handler: handleForward,
+				preventDefault: true,
+			},
 		],
 	});
 

package/src/components/mail/DailyBrief.tsx

@@ -873,7 +873,6 @@ export function DailyBrief({
 				onOpen={openRow}
 				onDeleteMessages={onDeleteMessages}
 				onSelectionVerb={wizard.start}
-				wizardOpen={wizard.isOpen}
 				commandsRef={commandsRef}
 				onTriageContextChange={onTriageContextChange}
 			>

package/src/components/mail/FlaggedList.tsx

@@ -268,7 +268,6 @@ export function FlaggedList({
 				onOpen={openRow}
 				onDeleteMessages={onDeleteMessages}
 				onSelectionVerb={wizard.start}
-				wizardOpen={wizard.isOpen}
 				commandsRef={commandsRef}
 				onTriageContextChange={onTriageContextChange}
 			>

package/src/components/mail/IntelligenceDrawer.tsx

@@ -30,6 +30,9 @@ export function IntelligenceDrawer({
 			onClose={onClose}
 			ariaLabel="Message details"
 			side="right"
+			// The key that raised it takes it away again (#840); every other verb
+			// stays with the list behind the scrim, which is not the subject here.
+			answers={{ toggleIntelligence: onClose }}
 		>
 			<IntelligencePane
 				onClose={onClose}

package/src/components/mail/MailboxPane.tsx

@@ -214,7 +214,6 @@ interface MailboxPaneContextValue {
 		focusedMessageId: string | undefined;
 		selectedIds: string[];
 		hasList: boolean;
-		blocksKeyboard: boolean;
 	}) => void;
 	/** Where the list publishes the commands the keyboard layer drives. */
 	listCommandsRef: RefObject<MessageListCommands | null>;

package/src/components/mail/MessageList.tsx

@@ -160,14 +160,6 @@ interface MessageListProps {
 		 * owns (Enter, Space, ⌘A) are left to the browser everywhere else.
 		 */
 		hasList: boolean;
-		/**
-		 * Whether the list has a modal open that owns the keyboard — the delete
-		 * confirmation, or the wizard. The route suspends the whole triage layer
-		 * while it does, so no shortcut can act behind it: a second Delete press
-		 * must not reach a delete, and none may start a second flow behind the
-		 * screen already asking about one.
-		 */
-		blocksKeyboard: boolean;
 	}) => void;
 	/**
 	 * Ref the list publishes its {@link MessageListCommands} into, so the route's
@@ -432,9 +424,8 @@ export const MessageList = ({
 	// Whether the list can serve keyboard commands at all. It stays true while
 	// the delete confirmation is open — withdrawing the commands there would let
 	// the route fall through to its own unconfirmed delete on a second Delete
-	// press. The route suspends the whole keyboard layer for the dialog instead.
+	// press. The dialog is on the overlay stack, which suspends every layer.
 	const commandsAvailable = !isLoading && threads.length > 0;
-	const confirmOpen = pendingDelete !== null;
 
 	const virtualizer = useVirtualizer({
 		count: threads.length,
@@ -908,16 +899,8 @@ export const MessageList = ({
 			focusedMessageId,
 			selectedIds: Array.from(selectedIds),
 			hasList: commandsAvailable,
-			blocksKeyboard: confirmOpen || wizard.isOpen,
 		});
-	}, [
-		focusedMessageId,
-		selectedIds,
-		commandsAvailable,
-		confirmOpen,
-		wizard.isOpen,
-		onTriageContextChange,
-	]);
+	}, [focusedMessageId, selectedIds, commandsAvailable, onTriageContextChange]);
 
 	// Retract the context when the list goes away (drafts view, phone reading
 	// view). Without this the route keeps its list key handlers registered
@@ -931,7 +914,6 @@ export const MessageList = ({
 				focusedMessageId: undefined,
 				selectedIds: [],
 				hasList: false,
-				blocksKeyboard: false,
 			}),
 		[],
 	);

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

@@ -174,13 +174,24 @@ describe("MoveToTrigger", () => {
 		const isOpen = () =>
 			dom.byLabel("Move to folder").getAttribute("aria-expanded") === "true";
 
+		// The window-level triage layer maps Escape to `back`, which closes the
+		// conversation behind the picker; one press must not do both (#732, #958).
+		const seen: string[] = [];
+		const listener = (event: Event) => seen.push((event as KeyboardEvent).key);
+		dom.window.addEventListener("keydown", listener);
+
 		dom.click(dom.byLabel("Move to folder"));
 		assert.equal(isOpen(), true);
 		dom.dispatch(
-			dom.window.document,
-			new dom.window.KeyboardEvent("keydown", { key: "Escape" }),
+			dom.window.document.body,
+			new dom.window.KeyboardEvent("keydown", {
+				key: "Escape",
+				bubbles: true,
+			}),
 		);
 		assert.equal(isOpen(), false);
+		assert.deepEqual(seen, [], "the layer behind the picker saw the press");
+		dom.window.removeEventListener("keydown", listener);
 
 		dom.click(dom.byLabel("Move to folder"));
 		assert.equal(isOpen(), true);

package/src/components/mail/MoveToTrigger.tsx

@@ -5,6 +5,7 @@ import {
 	type FolderTreeNode,
 	FolderTreePicker,
 	PopoverMenuPortal,
+	useOverlayScope,
 } from "@remit/ui";
 import { useQuery } from "@tanstack/react-query";
 import { FolderInput } from "lucide-react";
@@ -145,7 +146,14 @@ export const MoveToTrigger = ({
 		onMove(picked.id);
 	}, [picked, close, onMove]);
 
-	// Desktop popover: dismiss on outside click + Escape.
+	// The picker owns Escape while it is open (#732): on the shared overlay stack,
+	// so the triage layer underneath never maps the same press to `back` and
+	// closes the conversation with it. A second Escape closes as usual. Both
+	// surfaces register — the phone's vaul drawer is a modal like any other, and
+	// a narrow window with a keyboard attached is an ordinary way to meet it.
+	useOverlayScope({ id: "move-to", open: isOpen, answers: { back: close } });
+
+	// Desktop popover: dismiss on outside click.
 	useEffect(() => {
 		if (!isOpen || !isDesktop) return;
 		const handlePointer = (event: MouseEvent) => {
@@ -157,22 +165,8 @@ export const MoveToTrigger = ({
 			if (panelRef.current?.contains(target)) return;
 			close();
 		};
-		// The popover owns Escape while it is open (#732). The global triage
-		// layer listens on window and maps Escape to `back`, which closes the
-		// conversation; stopping propagation keeps one press from dismissing
-		// both. A second Escape then reaches the layer and closes as usual.
-		const handleKey = (event: KeyboardEvent) => {
-			if (event.key === "Escape") {
-				event.stopPropagation();
-				close();
-			}
-		};
 		document.addEventListener("mousedown", handlePointer);
-		document.addEventListener("keydown", handleKey);
-		return () => {
-			document.removeEventListener("mousedown", handlePointer);
-			document.removeEventListener("keydown", handleKey);
-		};
+		return () => document.removeEventListener("mousedown", handlePointer);
 	}, [isOpen, isDesktop, close]);
 
 	const anchorRect = () =>

package/src/components/mail/SelectionWizardHost.tsx

@@ -22,6 +22,7 @@ import {
 	stepIndex,
 	stepsFor,
 	suggestRuleName,
+	useOverlayScope,
 	type Verb,
 	type WizardDraft,
 	type WizardMessage,
@@ -1097,6 +1098,10 @@ export function SelectionWizardHost(props: SelectionWizardHostProps) {
 	const { step, goToStep, goBack, closeWizard } = useWizardStep(
 		fromSearch ? "properties" : "match",
 	);
+	// A walk in progress owns the keyboard. It answers nothing itself — Back and
+	// Close are on screen, and Escape abandoning a half-run selection is not what
+	// the reader asked for — so every triage key is contained until it closes.
+	useOverlayScope({ id: "selection-wizard", open: step !== undefined });
 	if (!step) return null;
 	const conversion = fromSearch
 		? (searchConversion ?? NO_CONVERSION)

package/src/components/mail/ThreadListInteraction.tsx

@@ -177,8 +177,6 @@ interface ThreadListInteractionProps {
 	 * second unreviewed route to the same verb.
 	 */
 	onSelectionVerb: (verb: Verb) => void;
-	/** The wizard owns the screen, so this list's keyboard layer stands down. */
-	wizardOpen?: boolean;
 	isDeleting?: boolean;
 	commandsRef?: RefObject<MessageListCommands | null>;
 	onTriageContextChange?: (context: TriageContextUpdate) => void;
@@ -191,7 +189,6 @@ export function ThreadListInteraction({
 	onOpen,
 	onDeleteMessages,
 	onSelectionVerb,
-	wizardOpen = false,
 	isDeleting = false,
 	commandsRef,
 	onTriageContextChange,
@@ -408,11 +405,6 @@ export function ThreadListInteraction({
 			selectedIds: selectedIdList,
 			orderedIds,
 			hasList,
-			// The dialog and the wizard each own the keyboard while they are up, so
-			// the triage layer suspends rather than acting behind them: a second
-			// Delete must not reach a delete, and no shortcut may start a second flow
-			// behind the screen already asking about one.
-			blocksKeyboard: confirmOpen || wizardOpen,
 		});
 	}, [
 		onTriageContextChange,
@@ -420,8 +412,6 @@ export function ThreadListInteraction({
 		selectedIdList,
 		orderedIds,
 		hasList,
-		confirmOpen,
-		wizardOpen,
 	]);
 
 	const tabStop = tabStopId(orderedIds, focusedMessageId);

package/src/components/mail/two-window-listeners-one-key.render.test.ts

@@ -201,7 +201,6 @@ function PaneShell({
 			focusedMessageId: MESSAGE_ID,
 			selectedIds: [],
 			hasList,
-			blocksKeyboard: false,
 			orderedIds: [MESSAGE_ID, OTHER_MESSAGE_ID],
 		});
 	}, []);

package/src/components/overlay-escape.render.test.ts

@@ -0,0 +1,151 @@
+/**
+ * Escape on an open overlay closes the overlay and nothing else (#958), and no
+ * other shortcut acts through one (#959).
+ *
+ * The window-level triage layer maps Escape to `back` — close the conversation,
+ * or the list behind it — and `c` to compose. The client's three own overlays
+ * used to let both reach it, so one Escape dismissed two things and `c` opened
+ * compose out from under a modal. They share the kit's overlay stack now, and
+ * the reading is the same for each: a listener on `window` never sees the key.
+ */
+import "@remit/test-dom";
+import assert from "node:assert/strict";
+import { afterEach, beforeEach, describe, it } from "node:test";
+import { ConfirmDialog, useTriageKeyboard } from "@remit/ui";
+import { act, createElement, type ReactNode } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { Drawer } from "./layout/Drawer";
+import { DropdownMenu, DropdownMenuItem } from "./ui/DropdownMenu";
+import { KeyboardShortcutsModal } from "./ui/KeyboardShortcutsModal";
+
+let root: Root;
+let container: HTMLElement;
+let seen: string[];
+let listener: (event: KeyboardEvent) => void;
+
+beforeEach(() => {
+	container = document.createElement("div");
+	document.body.appendChild(container);
+	root = createRoot(container);
+	seen = [];
+	listener = (event) => seen.push(event.key);
+	window.addEventListener("keydown", listener);
+});
+
+afterEach(() => {
+	window.removeEventListener("keydown", listener);
+	act(() => root.unmount());
+	container.remove();
+});
+
+const render = (element: ReactNode) => {
+	act(() => root.render(element));
+};
+
+const press = (key: string) => {
+	act(() => {
+		document.body.dispatchEvent(
+			new window.KeyboardEvent("keydown", { key, bubbles: true }),
+		);
+	});
+};
+
+const assertScoped = (closed: number) => {
+	assert.equal(closed, 1, "the overlay did not close itself");
+	assert.deepEqual(seen, [], "the layer behind the overlay saw the same press");
+};
+
+describe("Escape is scoped to the overlay it lands on (#958)", () => {
+	it("Drawer closes and swallows the key", () => {
+		let closed = 0;
+		render(
+			createElement(Drawer, {
+				isOpen: true,
+				onClose: () => closed++,
+				// biome-ignore lint/correctness/noChildrenProp: no JSX in a `.ts` test, and createElement's variadic children do not satisfy a required prop
+				children: createElement("button", { type: "button" }, "Inbox"),
+			}),
+		);
+
+		press("Escape");
+
+		assertScoped(closed);
+	});
+
+	it("KeyboardShortcutsModal closes and swallows the key", () => {
+		let closed = 0;
+		render(
+			createElement(KeyboardShortcutsModal, {
+				isOpen: true,
+				onClose: () => closed++,
+			}),
+		);
+
+		press("Escape");
+
+		assertScoped(closed);
+	});
+
+	it("DropdownMenu closes and swallows the key", () => {
+		render(
+			createElement(DropdownMenu, {
+				trigger: "More",
+				// biome-ignore lint/correctness/noChildrenProp: no JSX in a `.ts` test, and createElement's variadic children do not satisfy a required prop
+				children: createElement(DropdownMenuItem, {
+					onClick: () => undefined,
+					// biome-ignore lint/correctness/noChildrenProp: same
+					children: "Mark as read",
+				}),
+			}),
+		);
+		const trigger = container.querySelector("button") as HTMLButtonElement;
+		act(() => trigger.click());
+		assert.ok(container.textContent?.includes("Mark as read"));
+
+		press("Escape");
+
+		assert.equal(
+			container.textContent?.includes("Mark as read"),
+			false,
+			"the menu did not close itself",
+		);
+		assert.deepEqual(seen, [], "the layer behind the menu saw the same press");
+	});
+});
+
+/**
+ * The route-level compose layer, mounted the way `/mail` mounts it: `c` off a
+ * mailbox is served there and nowhere else, so on the brief and on Flagged it
+ * was the only layer answering the key — and the only one with no guard.
+ */
+function ComposeLayer({
+	modal,
+	onCompose,
+}: {
+	modal: boolean;
+	onCompose: () => void;
+}) {
+	useTriageKeyboard({ handlers: { compose: onCompose } });
+	return createElement(ConfirmDialog, {
+		isOpen: modal,
+		title: "Delete 3 messages?",
+		confirmLabel: "Delete",
+		onConfirm: () => undefined,
+		onCancel: () => undefined,
+	});
+}
+
+describe("c under a confirmation on the brief (#959)", () => {
+	it("stays inert while the dialog is up, and works once it is gone", () => {
+		const composed: string[] = [];
+		const onCompose = () => composed.push("c");
+
+		render(createElement(ComposeLayer, { modal: true, onCompose }));
+		press("c");
+		assert.deepEqual(composed, [], "c opened compose from under the dialog");
+
+		render(createElement(ComposeLayer, { modal: false, onCompose }));
+		press("c");
+		assert.deepEqual(composed, ["c"], "c stayed dead after the dialog closed");
+	});
+});

package/src/components/ui/DropdownMenu.tsx

@@ -1,4 +1,4 @@
-import { cn } from "@remit/ui";
+import { cn, useOverlayScope } from "@remit/ui";
 import { useCallback, useEffect, useRef, useState } from "react";
 
 interface DropdownMenuProps {
@@ -21,22 +21,16 @@ export const DropdownMenu = ({
 		}
 	}, []);
 
-	const handleKeyDown = useCallback((event: KeyboardEvent) => {
-		if (event.key === "Escape") {
-			setIsOpen(false);
-		}
-	}, []);
+	useOverlayScope({
+		id: "dropdown-menu",
+		open: isOpen,
+		answers: { back: () => setIsOpen(false) },
+	});
 
 	useEffect(() => {
-		if (isOpen) {
-			document.addEventListener("mousedown", handleClickOutside);
-			document.addEventListener("keydown", handleKeyDown);
-		}
-		return () => {
-			document.removeEventListener("mousedown", handleClickOutside);
-			document.removeEventListener("keydown", handleKeyDown);
-		};
-	}, [isOpen, handleClickOutside, handleKeyDown]);
+		if (isOpen) document.addEventListener("mousedown", handleClickOutside);
+		return () => document.removeEventListener("mousedown", handleClickOutside);
+	}, [isOpen, handleClickOutside]);
 
 	return (
 		<div ref={menuRef} className="relative">

package/src/components/ui/FatalErrorOverlay.tsx

@@ -1,3 +1,4 @@
+import { useOverlayScope } from "@remit/ui";
 import { AlertOctagon } from "lucide-react";
 import { useEffect, useState } from "react";
 import {
@@ -65,6 +66,9 @@ const seedFromFatal = (fatal: FatalError): BugReportSeed => ({
  * by the route-level error boundary without going through the subscription.
  */
 export const FatalErrorScreen = ({ fatal, onRetry }: FatalErrorScreenProps) => {
+	// Nothing under it is in a state to act, and there is no dismissal to offer:
+	// the screen's own controls are the only way out.
+	useOverlayScope({ id: "fatal-error", open: true });
 	const [copied, setCopied] = useState(false);
 
 	const handleReload = () => {

package/src/components/ui/KeyboardShortcutsModal.tsx

@@ -1,6 +1,12 @@
-import { cn, DialogBackdrop, Kbd, KEY_HINT_GROUPS } from "@remit/ui";
+import {
+	cn,
+	DialogBackdrop,
+	Kbd,
+	KEY_HINT_GROUPS,
+	useOverlayScope,
+} from "@remit/ui";
 import { X } from "lucide-react";
-import { Fragment, useCallback, useEffect } from "react";
+import { Fragment } from "react";
 
 interface KeyboardShortcutsModalProps {
 	isOpen: boolean;
@@ -16,27 +22,11 @@ export const KeyboardShortcutsModal = ({
 	isOpen,
 	onClose,
 }: KeyboardShortcutsModalProps) => {
-	// Close on Escape
-	const handleKeyDown = useCallback(
-		(event: KeyboardEvent) => {
-			if (event.key === "Escape") {
-				event.preventDefault();
-				event.stopPropagation();
-				event.stopImmediatePropagation();
-				onClose();
-			}
-		},
-		[onClose],
-	);
-
-	useEffect(() => {
-		if (!isOpen) return;
-		// 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]);
+	useOverlayScope({
+		id: "shortcuts",
+		open: isOpen,
+		answers: { back: onClose },
+	});
 
 	if (!isOpen) return null;
 

package/src/hooks/useKeyboardNavigation.ts

@@ -1,3 +1,4 @@
+import { resolveAgainstOverlays, type TriageAction } from "@remit/ui";
 import { useCallback, useEffect } from "react";
 
 type KeyHandler = (event: KeyboardEvent) => void;
@@ -29,6 +30,14 @@ interface KeyBinding {
 	 * pre-empt a route-level Esc that would also navigate).
 	 */
 	stopPropagation?: boolean;
+	/**
+	 * Which triage action this key means. Naming it puts the binding under the
+	 * overlay stack: an open overlay answers the action itself or contains it,
+	 * and either way this binding stands down. Every key that also exists in the
+	 * global key map owes one, or it acts through whatever is on top of it —
+	 * `r` opening a reply behind the Move popover (#959) is that bug.
+	 */
+	action?: TriageAction;
 }
 
 interface UseKeyboardNavigationOptions {
@@ -71,6 +80,8 @@ export const useKeyboardNavigation = ({
 					event.key.toLowerCase() === binding.key.toLowerCase();
 				if (!keyMatches) continue;
 
+				if (binding.action && resolveAgainstOverlays(binding.action)) continue;
+
 				// Shift gate: when a binding pins shift on/off, it only matches that
 				// exact state so plain and shift variants stay distinct.
 				if (

package/src/hooks/useRefreshControl.test.ts

@@ -0,0 +1,129 @@
+import assert from "node:assert/strict";
+import { describe, test } from "node:test";
+import { type SyncStatusReading, waitForSettled } from "./useRefreshControl.js";
+
+const BASELINE = 1_700_000_000_000;
+const LATER = BASELINE + 5_000;
+
+/** Replays `readings` in order and holds on the last one, counting reads so a
+ * test can say when the wait made up its mind. */
+const scriptedReader = (readings: readonly SyncStatusReading[]) => {
+	const state = { reads: 0 };
+	const readStatus = async (): Promise<SyncStatusReading> => {
+		const reading = readings[Math.min(state.reads, readings.length - 1)];
+		state.reads += 1;
+		if (!reading) throw new Error("no reading scripted");
+		return reading;
+	};
+	return { state, readStatus };
+};
+
+const wait = (
+	readings: readonly SyncStatusReading[],
+	deadline = Date.now() + 10_000,
+) => {
+	const { state, readStatus } = scriptedReader(readings);
+	return {
+		state,
+		outcome: waitForSettled({
+			accountId: "a-1",
+			readStatus,
+			baselineLastSyncAt: BASELINE,
+			deadline,
+			pollMs: 0,
+		}),
+	};
+};
+
+describe("waitForSettled", () => {
+	// #953: the tab's own background poll, another tab, and every GET /config
+	// start rounds the user never clicked for. Seeing one of those in flight and
+	// then complete used to be read as confirmation, so the button showed a
+	// checkmark and invalidated the list with the clicked round still unrun —
+	// new mail stayed unshown until the next poll. Only the account's own
+	// round-start stamp moving past the pre-trigger reading counts.
+	test("does not confirm on a round that was already in flight at the trigger", async () => {
+		const { state, outcome } = wait([
+			{ syncPhase: "syncing_inbox", lastSyncAt: BASELINE },
+			{ syncPhase: "complete", lastSyncAt: BASELINE },
+			{ syncPhase: "complete", lastSyncAt: LATER },
+		]);
+
+		assert.equal(await outcome, undefined);
+		assert.equal(state.reads, 3);
+	});
+
+	test("a settled foreign round times out rather than confirming", async () => {
+		const { outcome } = wait(
+			[{ syncPhase: "complete", lastSyncAt: BASELINE }],
+			Date.now() - 1,
+		);
+
+		assert.deepEqual(await outcome, {
+			accountId: "a-1",
+			message: "Refresh is taking longer than usual",
+		});
+	});
+
+	test("confirms once the account's own round has started and settled", async () => {
+		const { state, outcome } = wait([
+			{ syncPhase: "complete", lastSyncAt: LATER },
+		]);
+
+		assert.equal(await outcome, undefined);
+		assert.equal(state.reads, 1);
+	});
+
+	test("reports the failure of a round that started after the trigger", async () => {
+		const { outcome } = wait([{ syncPhase: "error", lastSyncAt: LATER }]);
+
+		assert.deepEqual(await outcome, {
+			accountId: "a-1",
+			message: "Sync failed for this account",
+		});
+	});
+
+	// The stale-phase half of the same rule: POST /sync only enqueues, so the
+	// first reading back can still carry the previous round's error phase.
+	test("does not borrow the error phase of a round that predates the trigger", async () => {
+		const { outcome } = wait(
+			[{ syncPhase: "error", lastSyncAt: BASELINE }],
+			Date.now() - 1,
+		);
+
+		assert.deepEqual(await outcome, {
+			accountId: "a-1",
+			message: "Refresh is taking longer than usual",
+		});
+	});
+
+	test("an account that has never synced confirms on its first stamp", async () => {
+		const { state, readStatus } = scriptedReader([
+			{ syncPhase: "idle", lastSyncAt: undefined },
+			{ syncPhase: "complete", lastSyncAt: LATER },
+		]);
+
+		const outcome = await waitForSettled({
+			accountId: "a-1",
+			readStatus,
+			baselineLastSyncAt: 0,
+			deadline: Date.now() + 10_000,
+			pollMs: 0,
+		});
+
+		assert.equal(outcome, undefined);
+		assert.equal(state.reads, 2);
+	});
+
+	test("surfaces a failed status read", async () => {
+		const outcome = await waitForSettled({
+			accountId: "a-1",
+			readStatus: () => Promise.reject(new Error("signed out")),
+			baselineLastSyncAt: BASELINE,
+			deadline: Date.now() + 10_000,
+			pollMs: 0,
+		});
+
+		assert.deepEqual(outcome, { accountId: "a-1", message: "signed out" });
+	});
+});

package/src/hooks/useRefreshControl.ts

@@ -3,7 +3,7 @@ import {
 	syncOperationsGetSyncStatusOptions,
 } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
 import { syncOperationsTriggerSync } from "@remit/api-http-client/sdk.gen.ts";
-import type { RemitImapMailboxSyncProgress } from "@remit/api-http-client/types.gen.ts";
+import type { RemitImapSyncPhase } from "@remit/api-http-client/types.gen.ts";
 import type { RefreshControlState } from "@remit/ui";
 import { type QueryClient, useQueryClient } from "@tanstack/react-query";
 import { useCallback, useEffect, useRef, useState } from "react";
@@ -41,14 +41,6 @@ const escalateIfFatal = (error: unknown): void => {
 	}
 };
 
-const maxLastSynced = (
-	mailboxes: readonly RemitImapMailboxSyncProgress[],
-): number =>
-	mailboxes.reduce(
-		(max, mailbox) => Math.max(max, mailbox.lastSyncedAt ?? 0),
-		0,
-	);
-
 /**
  * `getSyncStatus` for one account, always as a real network read: `staleTime:
  * 0` means even a reading `MailFreshnessProvider` fetched a moment ago is
@@ -71,59 +63,74 @@ const fetchStatus = (queryClient: QueryClient, accountId: string) =>
 		staleTime: 0,
 	});
 
-interface AccountOutcome {
+export interface AccountOutcome {
 	accountId: string;
 	message?: string;
 }
 
+/** The two fields of `getSyncStatus` that identify a round, named so the wait
+ * below can be driven from a scripted sequence of readings. */
+export interface SyncStatusReading {
+	syncPhase?: RemitImapSyncPhase;
+	lastSyncAt?: number;
+}
+
+export interface WaitForSettledOptions {
+	accountId: string;
+	readStatus: () => Promise<SyncStatusReading>;
+	/** `lastSyncAt` as it read immediately before this refresh triggered. */
+	baselineLastSyncAt: number;
+	deadline: number;
+	pollMs?: number;
+}
+
 /**
- * Poll one account's sync status until a round that started after
- * `baselineMaxLastSynced` was captured has settled, or `deadline` passes.
+ * Poll one account's sync status until a round that started at or after this
+ * refresh triggered has settled, or `deadline` passes.
  *
- * `POST /sync` only enqueues the round (the worker runs it later), so the
- * very first status read after triggering can still show the *previous*
- * round's phase — reading that as "settled" would report success, or a
- * stale failed phase, before the new round ever ran (#582 review). This
- * waits for positive evidence the triggered round actually happened: either
- * the phase was observed mid-flight, or some mailbox's `lastSyncedAt`
- * advanced past the baseline taken before the trigger.
+ * `account.lastSyncAt` is the worker's own once-per-round stamp, and it is the
+ * only thing here that tells one round from another. A phase seen mid-flight
+ * does not: the tab's background poll, another tab, and every `GET /config`
+ * trigger rounds nobody clicked for, so a click landing while one of those is
+ * in flight used to confirm on it — a checkmark and an invalidated list with
+ * the clicked round still unrun, and the new mail it would have fetched unseen
+ * until the next poll (#953). Requiring the stamp to pass the reading taken
+ * before the trigger admits only a round that started after it.
+ *
+ * `POST /sync` enqueues and returns, so the first reading after triggering
+ * still shows the previous round — including a previous round's `error` phase,
+ * which is why that phase only speaks once the stamp has moved.
  *
  * Read-only (`getSyncStatus`, no IMAP call, no queue write), so waiting costs
  * a handful of cheap GETs — never a refetch of the account's own message
  * list.
  */
-const waitForSettled = async (
-	queryClient: QueryClient,
-	accountId: string,
-	baselineMaxLastSynced: number,
-	deadline: number,
-): Promise<AccountOutcome | undefined> => {
-	let observedInProgress = false;
+export const waitForSettled = async ({
+	accountId,
+	readStatus,
+	baselineLastSyncAt,
+	deadline,
+	pollMs = REFRESH_POLL_MS,
+}: WaitForSettledOptions): Promise<AccountOutcome | undefined> => {
 	for (;;) {
-		const outcome = await fetchStatus(queryClient, accountId)
+		const outcome = await readStatus()
 			.then((data) => ({ ok: true as const, data }))
 			.catch((error: unknown) => ({ ok: false as const, error }));
 		if (!outcome.ok) {
 			return { accountId, message: messageFor(outcome.error) };
 		}
-		const { syncPhase, mailboxes } = outcome.data;
-		if (isSyncingPhase(syncPhase)) {
-			observedInProgress = true;
-		} else {
-			const confirmed =
-				observedInProgress ||
-				maxLastSynced(mailboxes ?? []) > baselineMaxLastSynced;
-			if (confirmed) {
-				if (syncPhase === "error") {
-					return { accountId, message: "Sync failed for this account" };
-				}
-				return undefined;
+		const { syncPhase, lastSyncAt } = outcome.data;
+		const startedAfterTrigger = (lastSyncAt ?? 0) > baselineLastSyncAt;
+		if (startedAfterTrigger && !isSyncingPhase(syncPhase)) {
+			if (syncPhase === "error") {
+				return { accountId, message: "Sync failed for this account" };
 			}
+			return undefined;
 		}
 		if (Date.now() >= deadline) {
 			return { accountId, message: "Refresh is taking longer than usual" };
 		}
-		await sleep(REFRESH_POLL_MS);
+		await sleep(pollMs);
 	}
 };
 
@@ -146,7 +153,7 @@ const refreshOneAccount = async (
 	const baseline = await fetchStatus(queryClient, accountId)
 		.then((data) => ({
 			ok: true as const,
-			maxLastSynced: maxLastSynced(data.mailboxes ?? []),
+			lastSyncAt: data.lastSyncAt ?? 0,
 		}))
 		.catch((error: unknown) => ({ ok: false as const, error }));
 	if (!baseline.ok) {
@@ -175,12 +182,12 @@ const refreshOneAccount = async (
 	}
 	telemetry.recordEvent("sync.triggered");
 
-	const settled = await waitForSettled(
-		queryClient,
+	const settled = await waitForSettled({
 		accountId,
-		baseline.maxLastSynced,
+		readStatus: () => fetchStatus(queryClient, accountId),
+		baselineLastSyncAt: baseline.lastSyncAt,
 		deadline,
-	);
+	});
 	if (settled)
 		return { accountId, enqueued: true, ok: false, message: settled.message };
 	return { accountId, enqueued: true, ok: true };

package/src/hooks/useTriageLayer.ts

@@ -14,6 +14,11 @@
  * context comes first, the pane builds its handlers from it, and the keyboard
  * registration comes last.
  *
+ * A modal open over the pane is not this layer's problem. Every overlay declares
+ * itself on the shared stack (`@remit/ui`'s `overlay-scope`) and `useTriageKeyboard`
+ * contains what the top frame does not serve, so the pane no longer reports which
+ * of its own dialogs is up and every other layer on the page suspends with it.
+ *
  * While a thread is open, `ConversationView` binds its own window listener for
  * the messages inside it, and both used to act on one press (#723). The split
  * is the one `shortcut-tree` already declares: the cursor keys belong to
@@ -30,7 +35,6 @@ export interface TriageContextUpdate {
 	focusedMessageId: string | undefined;
 	selectedIds: string[];
 	hasList: boolean;
-	blocksKeyboard: boolean;
 	/** Row ids in display order, when the list knows them. Feeds adjacency. */
 	orderedIds?: string[];
 }
@@ -45,7 +49,6 @@ export interface TriageContext {
 	/** Row ids in display order, as last reported by the list. */
 	orderedIds: string[];
 	hasList: boolean;
-	blocksKeyboard: boolean;
 }
 
 export const useTriageContext = (): TriageContext => {
@@ -58,14 +61,12 @@ export const useTriageContext = (): TriageContext => {
 	// keyboard layer then simply has nothing to drive.
 	const listCommandsRef = useRef<MessageListCommands | null>(null);
 	const [hasList, setHasList] = useState(false);
-	const [blocksKeyboard, setBlocksKeyboard] = useState(false);
 
 	const onTriageContextChange = useCallback((context: TriageContextUpdate) => {
 		setFocusedMessageId(context.focusedMessageId);
 		setSelectedIds(context.selectedIds);
 		if (context.orderedIds) setOrderedIds(context.orderedIds);
 		setHasList(context.hasList);
-		setBlocksKeyboard(context.blocksKeyboard);
 	}, []);
 
 	return {
@@ -75,7 +76,6 @@ export const useTriageContext = (): TriageContext => {
 		selectedIds,
 		orderedIds,
 		hasList,
-		blocksKeyboard,
 	};
 };
 
@@ -118,7 +118,7 @@ export const useTriageLayer = ({
 	handlers,
 	hasOpenThread = false,
 }: UseTriageLayerOptions): TriageLayer => {
-	const { listCommandsRef, hasList, blocksKeyboard } = context;
+	const { listCommandsRef, hasList } = context;
 
 	const goBack = useCallback(() => {
 		if (listCommandsRef.current?.clearSelection()) return;
@@ -132,10 +132,7 @@ export const useTriageLayer = ({
 	const { reply, replyAll, forward, ...restHandlers } = handlers;
 
 	useTriageKeyboard({
-		// A modal owns the keyboard outright. Suspending the layer is what keeps a
-		// second Delete press from reaching a delete while the confirmation for the
-		// first one is still on screen.
-		enabled: enabled && !blocksKeyboard,
+		enabled,
 		handlers: {
 			// Registered only while a list is mounted to serve them. An unregistered
 			// action is never preventDefault-ed, so with no list the browser keeps

package/src/routes/mail.tsx

@@ -128,6 +128,7 @@ function MailLayout() {
 		bindings: [
 			{
 				key: "?",
+				action: "help",
 				handler: () => showOverlay("shortcuts"),
 				noModifiers: false, // Allow shift+/
 				preventDefault: true,
@@ -138,7 +139,9 @@ function MailLayout() {
 	// `c` / ⌘N off the mailbox routes — the brief, Flagged, the outbox. On a
 	// mailbox the pane's own triage layer owns the key, so this is disabled there
 	// rather than firing a second compose alongside it, and while the composer is
-	// up the key belongs to whatever is being typed.
+	// up the key belongs to whatever is being typed. An open modal contains the
+	// key through the shared overlay stack, so this layer never opens compose out
+	// from under one (#959).
 	const openCompose = useOpenCompose();
 	const isComposing = useIsComposing();
 	const onMailbox = useRouterState({