@remit/ui 0.0.153 → 0.0.154

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/ui",
-  "version": "0.0.153",
+  "version": "0.0.154",
   "type": "module",
   "files": [
     "src"

package/src/components/bottom-sheet.tsx

@@ -1,6 +1,7 @@
 import type { ReactNode } from "react";
 import { useCallback, useLayoutEffect, useRef, useState } from "react";
 import { cn } from "../lib/cn.js";
+import { useOverlayScope } from "../lib/overlay-scope.js";
 
 const SNAP_MS = 320;
 const SNAP_EASE = "cubic-bezier(0.32, 0.9, 0.3, 1)";
@@ -32,6 +33,8 @@ export function BottomSheet({
 	children,
 	dismissLabel = "Dismiss",
 }: BottomSheetProps) {
+	useOverlayScope({ id: "bottom-sheet", open, answers: { back: onClose } });
+
 	const sheetRef = useRef<HTMLDivElement>(null);
 	const [height, setHeight] = useState(HEIGHT_FALLBACK);
 	const [drag, setDrag] = useState<number | null>(null);

package/src/components/confirm-dialog.tsx

@@ -1,5 +1,6 @@
-import { useCallback, useEffect, useRef } from "react";
+import { useEffect, useRef } from "react";
 import { cn } from "../lib/cn.js";
+import { useOverlayScope } from "../lib/overlay-scope.js";
 import { DialogBackdrop } from "./dialog-backdrop.js";
 
 export interface ConfirmDialogProps {
@@ -38,25 +39,11 @@ export const ConfirmDialog = ({
 }: ConfirmDialogProps) => {
 	const cancelRef = useRef<HTMLButtonElement>(null);
 
-	const handleKeyDown = useCallback(
-		(event: KeyboardEvent) => {
-			if (event.key === "Escape") {
-				event.preventDefault();
-				event.stopPropagation();
-				event.stopImmediatePropagation();
-				onCancel();
-			}
-		},
-		[onCancel],
-	);
-
-	useEffect(() => {
-		if (!isOpen) return;
-		// Capture phase so Esc closes the dialog before any list-level Esc
-		// handler (e.g. clearSelection) also fires on the same keystroke.
-		window.addEventListener("keydown", handleKeyDown, true);
-		return () => window.removeEventListener("keydown", handleKeyDown, true);
-	}, [isOpen, handleKeyDown]);
+	useOverlayScope({
+		id: "confirm-dialog",
+		open: isOpen,
+		answers: { back: onCancel },
+	});
 
 	// Whoever opened the dialog gets the focus back when it closes. Without this
 	// a cancelled confirmation drops focus to the body, and the control the user

package/src/components/dialog.tsx

@@ -1,5 +1,6 @@
-import { type ReactNode, useCallback, useEffect, useRef } from "react";
+import { type ReactNode, useEffect, useRef } from "react";
 import { cn } from "../lib/cn.js";
+import { useOverlayScope } from "../lib/overlay-scope.js";
 import { DialogBackdrop } from "./dialog-backdrop.js";
 
 export interface DialogProps {
@@ -27,27 +28,7 @@ export function Dialog({
 }: DialogProps) {
 	const dialogRef = useRef<HTMLDivElement>(null);
 
-	const handleKeyDown = useCallback(
-		(e: KeyboardEvent) => {
-			if (e.key !== "Escape") return;
-			// A control inside the dialog can own Escape while it has something of
-			// its own to close — an open suggestion list. Escape closes that first;
-			// the next Escape closes the dialog.
-			const focused = document.activeElement;
-			if (focused instanceof Element && focused.closest("[data-escape-owner]"))
-				return;
-			e.preventDefault();
-			e.stopImmediatePropagation();
-			onClose();
-		},
-		[onClose],
-	);
-
-	useEffect(() => {
-		if (!open) return;
-		window.addEventListener("keydown", handleKeyDown, true);
-		return () => window.removeEventListener("keydown", handleKeyDown, true);
-	}, [open, handleKeyDown]);
+	useOverlayScope({ id: "dialog", open, answers: { back: onClose } });
 
 	useEffect(() => {
 		if (!open) return;

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

@@ -0,0 +1,135 @@
+/**
+ * Escape on an open overlay closes the overlay and nothing else (#958).
+ *
+ * The window-level triage layer maps Escape to `back`, which closes the
+ * conversation or the list underneath; each of these surfaces used to let the
+ * press reach it, so one keystroke dismissed two things. They share one scoping
+ * mechanism now, and the reading here is the same for all of them: a listener on
+ * `window` never sees the key the overlay answered.
+ */
+import "@remit/test-dom";
+import assert from "node:assert/strict";
+import { afterEach, beforeEach, describe, it } from "node:test";
+import { act, createElement, type ReactNode } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { ConfirmDialog } from "./confirm-dialog.js";
+import { Dialog } from "./dialog.js";
+import { PopoverMenu } from "./popover-menu.js";
+import { SlidePanel, type SlidePanelProps } from "./slide-panel.js";
+
+let root: Root;
+let container: HTMLElement;
+let seen: string[];
+let listener: (event: KeyboardEvent) => void;
+
+beforeEach(() => {
+	container = document.getElementById("root") as unknown as HTMLElement;
+	container.innerHTML = "";
+	root = createRoot(container);
+	seen = [];
+	listener = (event) => seen.push(event.key);
+	window.addEventListener("keydown", listener);
+});
+
+afterEach(() => {
+	window.removeEventListener("keydown", listener);
+	act(() => root.unmount());
+});
+
+const render = (element: ReactNode) => {
+	act(() => root.render(element));
+};
+
+const pressEscape = () => {
+	act(() => {
+		document.body.dispatchEvent(
+			new window.KeyboardEvent("keydown", { key: "Escape", bubbles: true }),
+		);
+	});
+};
+
+/** What the overlay under test did with the press, and what leaked past it. */
+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("SlidePanel closes and swallows the key", () => {
+		let closed = 0;
+		render(
+			createElement(
+				SlidePanel,
+				// createElement never folds the children argument into the props
+				// type, so a component with required children needs the cast.
+				{
+					isOpen: true,
+					onClose: () => {
+						closed++;
+					},
+					title: "Add Account",
+				} as SlidePanelProps,
+				"panel body",
+			),
+		);
+
+		pressEscape();
+
+		assertScoped(closed);
+	});
+
+	it("Dialog closes and swallows the key", () => {
+		let closed = 0;
+		render(
+			createElement(
+				Dialog,
+				{ open: true, onClose: () => closed++, title: "Folders" },
+				"dialog body",
+			),
+		);
+
+		pressEscape();
+
+		assertScoped(closed);
+	});
+
+	it("ConfirmDialog closes and swallows the key", () => {
+		let closed = 0;
+		render(
+			createElement(ConfirmDialog, {
+				isOpen: true,
+				title: "Delete 3 messages?",
+				confirmLabel: "Delete",
+				onConfirm: () => undefined,
+				onCancel: () => closed++,
+			}),
+		);
+
+		pressEscape();
+
+		assertScoped(closed);
+	});
+
+	it("PopoverMenu closes and swallows the key", () => {
+		render(
+			createElement(PopoverMenu, {
+				triggerLabel: "More actions",
+				items: [
+					{ key: "read", label: "Mark as read", onSelect: () => undefined },
+				],
+			}),
+		);
+		const trigger = container.querySelector("button") as HTMLButtonElement;
+		act(() => trigger.click());
+		assert.equal(trigger.getAttribute("aria-expanded"), "true");
+
+		pressEscape();
+
+		assert.equal(
+			trigger.getAttribute("aria-expanded"),
+			"false",
+			"the menu did not close itself",
+		);
+		assert.deepEqual(seen, [], "the layer behind the menu saw the same press");
+	});
+});

package/src/components/popover-menu.tsx

@@ -9,6 +9,7 @@ import {
 } from "react";
 import { createPortal } from "react-dom";
 import { cn } from "../lib/cn.js";
+import { useOverlayScope } from "../lib/overlay-scope.js";
 import { Button } from "./button.js";
 
 /** Viewport-relative bounding box of whatever a menu opens against. */
@@ -293,6 +294,12 @@ export function PopoverMenu({
 	const containerRef = useRef<HTMLDivElement>(null);
 	const panelRef = useRef<HTMLDivElement>(null);
 
+	useOverlayScope({
+		id: "popover-menu",
+		open,
+		answers: { back: () => setOpen(false) },
+	});
+
 	useEffect(() => {
 		if (!open) return;
 		const onPointer = (event: MouseEvent) => {
@@ -304,15 +311,8 @@ export function PopoverMenu({
 				return;
 			setOpen(false);
 		};
-		const onKey = (event: KeyboardEvent) => {
-			if (event.key === "Escape") setOpen(false);
-		};
 		document.addEventListener("mousedown", onPointer);
-		document.addEventListener("keydown", onKey);
-		return () => {
-			document.removeEventListener("mousedown", onPointer);
-			document.removeEventListener("keydown", onKey);
-		};
+		return () => document.removeEventListener("mousedown", onPointer);
 	}, [open]);
 
 	if (items.length === 0 && !children) return null;

package/src/components/rich-text-correction-menu.tsx

@@ -1,6 +1,7 @@
 import { BookPlus, EyeOff } from "lucide-react";
 import { useEffect, useRef } from "react";
 import { DESKTOP_MEDIA_QUERY } from "../lib/layout-breakpoints.js";
+import { useOverlayScope } from "../lib/overlay-scope.js";
 import { useRovingFocus } from "../lib/roving-focus.js";
 import { useMatchMedia } from "../lib/use-match-media.js";
 import { BottomSheet } from "./bottom-sheet.js";
@@ -135,33 +136,29 @@ export const RichTextCorrectionMenu = ({
 		panelRef.current?.focus();
 	}, []);
 
+	// Escape and every other shortcut go through the shared overlay stack, which
+	// dismisses the menu and leaves nothing for the layer behind it: the panel's
+	// own `onKeyDown` only fires while the panel actually holds focus, and a focus
+	// call that lands a beat later than the browser is ready for is not something
+	// to depend on. The phone branch rides `BottomSheet`'s scope instead.
+	useOverlayScope({
+		id: "correction-menu",
+		open: desktop,
+		answers: { back: () => onDismiss(true) },
+	});
+
 	// A press rather than a click, and a pointer press rather than a mouse one:
 	// the tap that opened this menu is followed by the browser's compatibility
 	// mouse events, which a `mousedown` listener reads as a press somewhere else
 	// and closes the menu on the way up.
-	//
-	// Escape is caught here too, at the document rather than the panel: the
-	// panel takes focus on mount so the panel's own `onKeyDown` ordinarily
-	// gets there first and this one never fires (its `stopPropagation` keeps
-	// the keydown from reaching here), but a focus call that lands a beat
-	// later than the browser is ready for is not something to depend on —
-	// this is what actually closes the menu when that happens.
 	useEffect(() => {
 		if (!desktop) return;
 		const onPointer = (event: Event) => {
 			if (panelRef.current?.contains(event.target as Node)) return;
 			onDismiss(false);
 		};
-		const onDocumentKeyDown = (event: KeyboardEvent) => {
-			if (event.key !== "Escape") return;
-			onDismiss(true);
-		};
 		document.addEventListener("pointerdown", onPointer);
-		document.addEventListener("keydown", onDocumentKeyDown);
-		return () => {
-			document.removeEventListener("pointerdown", onPointer);
-			document.removeEventListener("keydown", onDocumentKeyDown);
-		};
+		return () => document.removeEventListener("pointerdown", onPointer);
 	}, [desktop, onDismiss]);
 
 	/**

package/src/components/search-chip-input.tsx

@@ -1,6 +1,7 @@
 import { Search, X } from "lucide-react";
 import { useCallback, useEffect, useId, useRef, useState } from "react";
 import { cn } from "../lib/cn.js";
+import { resolveAgainstOverlays } from "../lib/overlay-scope.js";
 import type { ComboboxProps } from "../lib/use-suggest-list.js";
 import {
 	type ChipFocusTarget,
@@ -323,6 +324,10 @@ export const SearchChipInput = ({
 				return;
 			}
 			if (isEditableTarget(event.target)) return;
+			// The field is behind whatever is on top of it: an open overlay either
+			// answers the key or contains it, and focusing a field under a modal is
+			// neither (#959).
+			if (resolveAgainstOverlays("focusSearch")) return;
 			event.preventDefault();
 			inputRef.current?.focus();
 		};

package/src/components/self-update-progress-overlay.tsx

@@ -1,6 +1,7 @@
 import { AlertOctagon, Check, Loader2 } from "lucide-react";
 import { type RefObject, useEffect, useRef } from "react";
 import { cn } from "../lib/cn.js";
+import { useOverlayScope } from "../lib/overlay-scope.js";
 import { Button } from "./button.js";
 import {
 	type UpdatePhase,
@@ -76,6 +77,9 @@ export function SelfUpdateProgressOverlay({
 }: SelfUpdateProgressOverlayProps) {
 	const ref = useRef<HTMLDivElement>(null);
 	useBlockingFocus(ref);
+	// Nothing to answer: the update is running and there is no way out of it, so
+	// every shortcut is contained rather than acting on a mailbox that is gone.
+	useOverlayScope({ id: "self-update", open: true });
 	const activeIndex = phaseOrder.indexOf(phase);
 
 	return (

package/src/components/slide-panel.tsx

@@ -1,6 +1,7 @@
 import { X } from "lucide-react";
-import { type ReactNode, useEffect } from "react";
+import type { ReactNode } from "react";
 import { cn } from "../lib/cn.js";
+import { useOverlayScope } from "../lib/overlay-scope.js";
 
 /* ------------------------------------------------------------------ */
 /* SlidePanel: right-edge slide-over for a focused sub-task (editing   */
@@ -28,15 +29,13 @@ export function SlidePanel({
 	footer,
 }: SlidePanelProps) {
 	// Escape closes the panel from anywhere inside it, which is what a dialog
-	// owes the keyboard. The scrim is a pointer affordance only.
-	useEffect(() => {
-		if (!isOpen) return;
-		const onKeyDown = (event: KeyboardEvent) => {
-			if (event.key === "Escape") onClose();
-		};
-		document.addEventListener("keydown", onKeyDown);
-		return () => document.removeEventListener("keydown", onKeyDown);
-	}, [isOpen, onClose]);
+	// owes the keyboard, and nothing behind it sees the press. The scrim is a
+	// pointer affordance only.
+	useOverlayScope({
+		id: "slide-panel",
+		open: isOpen,
+		answers: { back: onClose },
+	});
 
 	return (
 		<>

package/src/index.ts

@@ -908,6 +908,13 @@ export {
 	DESKTOP_MEDIA_QUERY,
 	DESKTOP_MIN_WIDTH,
 } from "./lib/layout-breakpoints.js";
+export {
+	type OverlayAnswers,
+	type OverlayScopeOptions,
+	overlayStack,
+	resolveAgainstOverlays,
+	useOverlayScope,
+} from "./lib/overlay-scope.js";
 export {
 	derivePropertyClauses,
 	normalizeSubject,

package/src/lib/overlay-scope.test.ts

@@ -0,0 +1,314 @@
+/**
+ * The overlay stack, from the outside: what a window-level listener under an
+ * open overlay is allowed to see (#958), and what a triage layer under one is
+ * allowed to run (#959).
+ */
+import "@remit/test-dom";
+import assert from "node:assert/strict";
+import { afterEach, beforeEach, describe, it } from "node:test";
+import { act, createElement, type ReactNode } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import {
+	type OverlayAnswers,
+	overlayStack,
+	resolveAgainstOverlays,
+	useOverlayScope,
+} from "./overlay-scope.js";
+import { useTriageKeyboard } from "./use-triage-keyboard.js";
+
+let root: Root;
+let seen: string[];
+let listener: (event: KeyboardEvent) => void;
+
+beforeEach(() => {
+	const container = document.getElementById("root") as unknown as HTMLElement;
+	container.innerHTML = "";
+	root = createRoot(container);
+	seen = [];
+	listener = (event) => seen.push(event.key);
+	window.addEventListener("keydown", listener);
+});
+
+afterEach(() => {
+	window.removeEventListener("keydown", listener);
+	act(() => root.unmount());
+});
+
+const press = (key: string, from: EventTarget = document.body) => {
+	act(() => {
+		from.dispatchEvent(
+			new window.KeyboardEvent("keydown", { key, bubbles: true }),
+		);
+	});
+};
+
+const field = (id: string): HTMLInputElement =>
+	document.getElementById(id) as HTMLInputElement;
+
+function Scope({
+	id,
+	open,
+	answers,
+	children,
+}: {
+	id: string;
+	open: boolean;
+	answers?: OverlayAnswers;
+	children?: ReactNode;
+}) {
+	useOverlayScope({ id, open, answers });
+	return children ?? null;
+}
+
+const render = (element: ReactNode) => {
+	act(() => root.render(element));
+};
+
+describe("an overlay on the stack", () => {
+	it("answers Escape itself and leaves nothing for the window to see", () => {
+		const dismissed: string[] = [];
+		render(
+			createElement(Scope, {
+				id: "sheet",
+				open: true,
+				answers: { back: () => dismissed.push("sheet") },
+			}),
+		);
+
+		press("Escape");
+
+		assert.deepEqual(dismissed, ["sheet"]);
+		assert.deepEqual(
+			seen,
+			[],
+			"the layer behind the overlay saw the same press",
+		);
+	});
+
+	it("hands the key back once it closes", () => {
+		render(createElement(Scope, { id: "sheet", open: true, answers: {} }));
+		render(createElement(Scope, { id: "sheet", open: false, answers: {} }));
+
+		press("Escape");
+
+		assert.deepEqual(seen, ["Escape"]);
+	});
+
+	// Both open in one render, which is the case mount order gets wrong: React
+	// runs the inner overlay's effects first, so registration order would put the
+	// drawer on top of the confirmation it contains.
+	it("is answered by the innermost overlay, however the two came to be open", () => {
+		const dismissed: string[] = [];
+		const stack = () =>
+			createElement(Scope, {
+				id: "drawer",
+				open: true,
+				answers: { back: () => dismissed.push("drawer") },
+				// biome-ignore lint/correctness/noChildrenProp: no JSX in a `.ts` test
+				children: createElement(Scope, {
+					id: "confirm",
+					open: true,
+					answers: { back: () => dismissed.push("confirm") },
+				}),
+			});
+
+		render(stack());
+		press("Escape");
+		assert.deepEqual(
+			dismissed,
+			["confirm"],
+			"the drawer under the confirmation answered for it",
+		);
+
+		assert.deepEqual(
+			overlayStack().map((frame) => frame.id),
+			["drawer", "confirm"],
+			"the stack is not ordered outside-in",
+		);
+	});
+
+	it("says what it answers without leaving the stack to say it", () => {
+		const rung: string[] = [];
+		const scope = (serving: boolean) =>
+			createElement(Scope, {
+				id: "drawer",
+				open: true,
+				answers: serving
+					? {
+							back: () => rung.push("back"),
+							toggleIntelligence: () => rung.push("toggleIntelligence"),
+						}
+					: { back: () => rung.push("back") },
+				// biome-ignore lint/correctness/noChildrenProp: no JSX in a `.ts` test
+				children: createElement(Scope, {
+					id: "confirm",
+					open: true,
+					answers: { back: () => rung.push("confirm") },
+				}),
+			});
+
+		render(scope(false));
+		render(scope(true));
+
+		press("Escape");
+
+		assert.deepEqual(
+			rung,
+			["confirm"],
+			"changing what the drawer answers moved it above the confirmation",
+		);
+	});
+
+	it("keeps serving the key that opened it, and nothing else", () => {
+		const rung: string[] = [];
+		render(
+			createElement(Scope, {
+				id: "drawer",
+				open: true,
+				answers: {
+					back: () => rung.push("back"),
+					toggleIntelligence: () => rung.push("toggleIntelligence"),
+				},
+			}),
+		);
+
+		press("i");
+		press("j");
+
+		assert.deepEqual(rung, ["toggleIntelligence"]);
+		// Only what the drawer answered is swallowed. A key it does not serve is
+		// left to travel; what stops it is the triage layer declining to run it.
+		assert.deepEqual(seen, ["j"], "the drawer ate a key it never answered");
+	});
+
+	it("is not answered by a key typed into a field inside it", () => {
+		const rung: string[] = [];
+		render(
+			createElement(Scope, {
+				id: "drawer",
+				open: true,
+				answers: {
+					back: () => rung.push("back"),
+					toggleIntelligence: () => rung.push("toggleIntelligence"),
+				},
+				// biome-ignore lint/correctness/noChildrenProp: no JSX in a `.ts` test
+				children: createElement("input", { id: "typing" }),
+			}),
+		);
+
+		press("i", field("typing"));
+
+		assert.deepEqual(
+			rung,
+			[],
+			"a letter typed into the field closed the drawer",
+		);
+	});
+
+	it("yields Escape to a control inside it that owns one", () => {
+		const dismissed: string[] = [];
+		render(
+			createElement(Scope, {
+				id: "sheet",
+				open: true,
+				answers: { back: () => dismissed.push("sheet") },
+				// biome-ignore lint/correctness/noChildrenProp: no JSX in a `.ts` test
+				children: createElement("input", {
+					"data-escape-owner": "",
+					id: "suggesting",
+				}),
+			}),
+		);
+		(document.getElementById("suggesting") as HTMLInputElement).focus();
+
+		press("Escape");
+
+		assert.deepEqual(dismissed, [], "the overlay took Escape from the field");
+	});
+});
+
+describe("what the surfaces under an overlay may act on", () => {
+	it("contains an action the overlay does not serve", () => {
+		render(createElement(Scope, { id: "sheet", open: true, answers: {} }));
+
+		assert.equal(resolveAgainstOverlays("compose")?.outcome, "contained");
+	});
+
+	it("resolves to nothing at all with no overlay up", () => {
+		assert.equal(resolveAgainstOverlays("compose"), null);
+	});
+
+	it("leaves c and i typed into a field under an overlay inert (#959)", () => {
+		const ran: string[] = [];
+		function Layer() {
+			useTriageKeyboard({
+				handlers: {
+					compose: () => ran.push("compose"),
+					toggleIntelligence: () => ran.push("toggleIntelligence"),
+				},
+			});
+			return createElement(Scope, {
+				id: "sheet",
+				open: true,
+				answers: { back: () => undefined },
+				// biome-ignore lint/correctness/noChildrenProp: no JSX in a `.ts` test
+				children: createElement("input", { id: "typing" }),
+			});
+		}
+
+		render(createElement(Layer));
+
+		press("c", field("typing"));
+		press("i", field("typing"));
+
+		assert.deepEqual(
+			ran,
+			[],
+			"typing under an overlay reached the layer below",
+		);
+	});
+
+	it("drops a g prefix rather than arming one behind the overlay", () => {
+		const went: string[] = [];
+		function Layer({ modal }: { modal: boolean }) {
+			useTriageKeyboard({ handlers: { goBrief: () => went.push("goBrief") } });
+			return createElement(Scope, {
+				id: "sheet",
+				open: modal,
+				answers: { back: () => undefined },
+			});
+		}
+
+		// `g` over the modal must not leave a prefix behind for the `b` that
+		// follows it, which lands after the overlay has gone.
+		render(createElement(Layer, { modal: true }));
+		press("g");
+		render(createElement(Layer, { modal: false }));
+		press("b");
+		assert.deepEqual(went, [], "a sequence completed across the modal");
+
+		press("g");
+		press("b");
+		assert.deepEqual(went, ["goBrief"], "g stayed dead after the modal closed");
+	});
+
+	it("leaves a triage layer's compose inert under a modal (#959)", () => {
+		const composed: string[] = [];
+		function Layer({ modal }: { modal: boolean }) {
+			useTriageKeyboard({ handlers: { compose: () => composed.push("c") } });
+			return createElement(Scope, {
+				id: "confirm",
+				open: modal,
+				answers: { back: () => undefined },
+			});
+		}
+
+		render(createElement(Layer, { modal: true }));
+		press("c");
+		assert.deepEqual(composed, [], "c opened compose from under the modal");
+
+		render(createElement(Layer, { modal: false }));
+		press("c");
+		assert.deepEqual(composed, ["c"], "c stayed dead after the modal closed");
+	});
+});

package/src/lib/overlay-scope.ts

@@ -0,0 +1,205 @@
+/**
+ * The live overlay stack — the runtime half of the shortcut tree's leaf.
+ *
+ * `shortcut-tree` already states the rule: the top overlay frame either answers
+ * an action or contains it, and a key pressed over an overlay never reaches the
+ * surface behind it. Nothing enforced that at runtime, so every overlay grew its
+ * own answer — a capture-phase window listener here, a document-phase
+ * `stopPropagation` there, a `blocksKeyboard` flag threaded up through a pane —
+ * and the surfaces that grew none let Escape close the conversation underneath
+ * (#958) while `c` opened compose out from under a modal (#959).
+ *
+ * A mounted overlay declares itself here for as long as it is on screen, with
+ * what it answers for, and the rest follows from that one declaration:
+ *
+ * - What the top frame answers is run by one listener, shared by every overlay.
+ *   It sits on `window` in the capture phase, ahead of the triage layers and of
+ *   every other window listener the app binds, and swallows the key it ran —
+ *   Escape for a dismissal, and `i` for the drawer that key opened. A control
+ *   inside an overlay with something of its own to close marks itself
+ *   `[data-escape-owner]` and keeps Escape while it holds focus.
+ * - Everything else is contained rather than swallowed: `useTriageKeyboard`
+ *   resolves through {@link resolveAgainstOverlays} and declines to run a handler
+ *   the top frame does not serve, so the key is inert instead of racing.
+ *
+ * An overlay that answers nothing — the selection wizard, which has its own Back
+ * and Close and wants Escape to do neither — declares no answers and still
+ * contains the keyboard while it is up.
+ *
+ * The stack is ordered by where each overlay sits in the React tree, taken once
+ * at its first render: an overlay is above every overlay it renders inside. That
+ * is the invariant a nested pair needs — a confirmation raised from inside a
+ * drawer is the one Escape reaches — and it holds however the two came to be
+ * open, including a remount that mounts both in one commit. Registration order
+ * cannot state it: React runs a child's effects before its parent's, so
+ * registering on mount puts the inner overlay underneath the one containing it.
+ *
+ * The stack is module state rather than a React context on purpose: a window
+ * listener is global, so the register it answers from is too, and an overlay
+ * rendered through a portal or mounted in a Storybook story needs no provider
+ * above it to be seen.
+ */
+import { useEffect, useRef, useState } from "react";
+import type { TriageAction } from "./keymap.js";
+import {
+	dispatchKey,
+	isControlTarget,
+	isEditableTarget,
+} from "./keymap-dispatch.js";
+import {
+	type OverlayFrame,
+	type Resolution,
+	resolveOverlays,
+} from "./shortcut-tree.js";
+
+/** What an overlay answers, keyed by the action it answers. */
+export type OverlayAnswers = Partial<Record<TriageAction, () => void>>;
+
+interface ScopeEntry {
+	id: string;
+	/** Position in the React tree, ascending outward-in. See the module note. */
+	depth: number;
+	run: () => OverlayAnswers;
+}
+
+const ESCAPE_OWNER_SELECTOR = "[data-escape-owner]";
+
+let entries: ScopeEntry[] = [];
+
+/** Handed out by `useState` during render, so parents are numbered before children. */
+let renderedOverlays = 0;
+const nextDepth = (): number => ++renderedOverlays;
+
+const byDepth = (a: ScopeEntry, b: ScopeEntry): number => a.depth - b.depth;
+
+/**
+ * The frames on screen, root first — the tree's `overlays`.
+ *
+ * Built on demand rather than stored, so an overlay that gains or loses an
+ * answer while it is open says so without leaving the stack and rejoining it at
+ * the top.
+ */
+export function overlayStack(): readonly OverlayFrame[] {
+	return [...entries].sort(byDepth).map((entry) => ({
+		id: entry.id,
+		handles: Object.entries(entry.run())
+			.filter(([, answer]) => answer)
+			.map(([action]) => action as TriageAction),
+	}));
+}
+
+/** The innermost overlay on screen — the leaf that answers first. */
+function topEntry(): ScopeEntry | undefined {
+	let top: ScopeEntry | undefined;
+	for (const entry of entries) {
+		if (!top || entry.depth > top.depth) top = entry;
+	}
+	return top;
+}
+
+/**
+ * How the open overlays answer this action, or null when none is up. A layer
+ * with a window-level keyboard consults this before running a handler of its
+ * own: any answer at all means the action belongs to the overlay.
+ */
+export function resolveAgainstOverlays(
+	action: TriageAction,
+): Resolution | null {
+	return resolveOverlays(action, overlayStack());
+}
+
+/**
+ * What this keystroke means to an overlay. Escape reaches one from anywhere
+ * inside it, a focused field included — unless a control in there has its own
+ * thing to close, which takes the press and leaves the next one for the overlay.
+ * Every other key goes through the ordinary dispatch, so `i` typed into a field
+ * inside a drawer is a letter and not a dismissal. A `g …` sequence is never an
+ * overlay's to answer, so the prefix state is not carried here.
+ */
+function overlayAction(event: KeyboardEvent): TriageAction | null {
+	if (event.key === "Escape") {
+		const focused = document.activeElement;
+		if (focused instanceof Element && focused.closest(ESCAPE_OWNER_SELECTOR)) {
+			return null;
+		}
+		return "back";
+	}
+	return dispatchKey(
+		{
+			key: event.key,
+			shiftKey: event.shiftKey,
+			metaKey: event.metaKey,
+			ctrlKey: event.ctrlKey,
+			altKey: event.altKey,
+			inEditable: isEditableTarget(event.target),
+			onControl: isControlTarget(event.target),
+		},
+		null,
+	).action;
+}
+
+function onOverlayKey(event: KeyboardEvent): void {
+	const top = topEntry();
+	if (!top) return;
+	const action = overlayAction(event);
+	if (!action) return;
+	const answer = top.run()[action];
+	if (!answer) return;
+	event.preventDefault();
+	event.stopImmediatePropagation();
+	answer();
+}
+
+function setEntries(next: ScopeEntry[]): void {
+	const wasEmpty = entries.length === 0;
+	entries = next;
+	if (wasEmpty === (next.length === 0)) return;
+	if (next.length > 0) {
+		window.addEventListener("keydown", onOverlayKey, true);
+		return;
+	}
+	window.removeEventListener("keydown", onOverlayKey, true);
+}
+
+export interface OverlayScopeOptions {
+	/** Names the frame in the stack; only has to tell it from its neighbours. */
+	id: string;
+	/** On screen. A closed overlay leaves the stack and contains nothing. */
+	open: boolean;
+	/**
+	 * What this overlay answers, run by the shared listener before any layer
+	 * underneath sees the key. `back` is Escape, and dismissing is what a modal,
+	 * a drawer and a menu all want it to mean. Every action outside the table is
+	 * contained: inert for the surfaces underneath, never forwarded.
+	 */
+	answers?: OverlayAnswers;
+}
+
+/**
+ * Put this overlay on the stack while it is open. One call replaces a
+ * hand-rolled Escape listener, and hands the rest of the keyboard back to the
+ * surfaces underneath only once the overlay is gone.
+ */
+export function useOverlayScope({
+	id,
+	open,
+	answers = {},
+}: OverlayScopeOptions): void {
+	// Read at keystroke time, so neither a re-rendered answer nor a changed set
+	// of them re-registers the frame.
+	const answersRef = useRef(answers);
+	answersRef.current = answers;
+
+	// Numbered during the first render, where React is still going parent before
+	// child — the one moment nesting is legible from inside a hook.
+	const [depth] = useState(nextDepth);
+
+	useEffect(() => {
+		if (!open) return;
+		const entry: ScopeEntry = { id, depth, run: () => answersRef.current };
+		setEntries([...entries, entry]);
+		return () => {
+			setEntries(entries.filter((candidate) => candidate !== entry));
+		};
+	}, [id, open, depth]);
+}

package/src/lib/shortcut-tree.ts

@@ -315,6 +315,27 @@ function isRegistered(
 	return registered[level]?.includes(action) === true;
 }
 
+/**
+ * The overlay stack's own verdict, independent of everything below it: the top
+ * frame answers the action or contains it, and null means no overlay is up.
+ *
+ * Exported because the runtime stack (`overlay-scope`) needs the same rule from
+ * a keydown listener, where the rest of the tree is not built. One rule, one
+ * place: an overlay that contains a key for the resolver contains it for the
+ * live keyboard too.
+ */
+export function resolveOverlays(
+	action: TriageAction,
+	overlays: readonly OverlayFrame[],
+): Resolution | null {
+	const frame = overlays.at(-1);
+	if (!frame) return null;
+	if (!frame.handles.includes(action)) {
+		return { outcome: "contained", by: { kind: "overlay", frame } };
+	}
+	return { outcome: "act", target: { kind: "overlay", frame } };
+}
+
 /**
  * Resolve an action against the tree. Pure: no DOM, no router, no side effects.
  *
@@ -334,13 +355,8 @@ export function resolveShortcut(
 	tree: ShortcutTree,
 	registered: RegisteredActions,
 ): Resolution {
-	const frame = tree.overlays.at(-1);
-	if (frame) {
-		if (!frame.handles.includes(action)) {
-			return { outcome: "contained", by: { kind: "overlay", frame } };
-		}
-		return { outcome: "act", target: { kind: "overlay", frame } };
-	}
+	const overlaid = resolveOverlays(action, tree.overlays);
+	if (overlaid) return overlaid;
 
 	const field = tree.editing;
 	if (field) {

package/src/lib/use-triage-keyboard.ts

@@ -6,6 +6,7 @@ import {
 	isEditableTarget,
 	type SequencePrefix,
 } from "./keymap-dispatch.js";
+import { overlayStack, resolveAgainstOverlays } from "./overlay-scope.js";
 
 interface UseTriageKeyboardOptions {
 	handlers: TriageHandlers;
@@ -47,6 +48,11 @@ interface UseTriageKeyboardOptions {
  * conversation views. They bind disjoint keys; only the list's competing
  * listener was removed.
  *
+ * An open overlay pre-empts the whole layer. Every mounted modal, drawer and
+ * menu declares itself through `overlay-scope`, and each action is resolved
+ * against that stack before a handler runs, so no layer acts through a surface
+ * the reader has on top of it.
+ *
  * Per-action targeting (focused row vs selection) and the actual mutations live
  * in the handlers the caller passes in — this hook only dispatches.
  */
@@ -87,6 +93,17 @@ export function useTriageKeyboard({
 				prefixRef.current,
 			);
 
+			// An overlay is the leaf of the shortcut tree: while one is on screen it
+			// answers what it serves — through `overlay-scope`'s own listener, which
+			// has already run and swallowed the key — and contains the rest. The
+			// pending prefix is contained with it: a `g` pressed over a modal must
+			// not arm a sequence whose second key lands on the surface behind it.
+			if (overlayStack().length > 0) {
+				clearPrefixTimer();
+				prefixRef.current = null;
+				return;
+			}
+
 			// Update the pending prefix and (re)arm / clear its reset timer.
 			clearPrefixTimer();
 			prefixRef.current = result.nextPrefix;
@@ -99,6 +116,10 @@ export function useTriageKeyboard({
 
 			if (result.action === null) return;
 
+			// The same rule, per action: a contained key is left undefaulted, because
+			// it was never ours to consume.
+			if (resolveAgainstOverlays(result.action) !== null) return;
+
 			const handler = handlersRef.current[result.action];
 			if (!handler) return;