@remit/web-client 0.0.130 → 0.0.132

package/package.json

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

@@ -84,6 +84,7 @@ import {
 	toThreadRowData,
 } from "@/lib/brief";
 import { isServerError } from "@/lib/error-classifier";
+import { junkDestination } from "@/lib/junk-destination";
 import type { ListHeaderChrome } from "@/lib/list-header-chrome";
 import { useMailContext } from "@/lib/mail-context";
 import { useMailFreshness } from "@/lib/mail-freshness";
@@ -280,7 +281,7 @@ function BriefSelectionChrome({
 		[rows, selectedIds],
 	);
 
-	const canJunk = !!junkMailboxId && junkMailboxId !== scope.mailboxId;
+	const junkDestinationId = junkDestination(junkMailboxId, scope.mailboxId);
 
 	// One select-all for both surfaces: the desktop toolbar and the touch sheet
 	// offer the same control over the same rendered rows, so the verb a phone
@@ -316,7 +317,7 @@ function BriefSelectionChrome({
 			onDelete={() => wizard.start("delete")}
 			onMove={() => wizard.start("move")}
 			onOrganize={() => wizard.start("organize")}
-			onJunk={canJunk ? () => wizard.start("junk") : undefined}
+			onJunk={junkDestinationId ? () => wizard.start("junk") : undefined}
 			onMarkRead={() => wizard.start("markRead")}
 			overflowSlot={
 				scope.accountId &&

package/src/components/mail/MailboxPane.tsx

@@ -111,6 +111,7 @@ import {
 	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";
 import { isRescueCandidate } from "@/lib/rescue-candidates";
@@ -658,6 +659,7 @@ function MailboxPaneProvider({
 
 	const { junkMailboxId } = useJunkMailbox(mailboxAccountId);
 	const isSpamFolder = junkMailboxId != null && junkMailboxId === mailboxId;
+	const junkDestinationId = junkDestination(junkMailboxId, mailboxId);
 	const { candidates: rescueCandidates } = useRescueCandidates(
 		isSpamFolder ? junkMailboxId : undefined,
 	);
@@ -724,7 +726,7 @@ function MailboxPaneProvider({
 
 	const triageMarkJunk = useCallback(() => {
 		if (listCommandsRef.current?.requestVerb("junk")) return;
-		if (!junkMailboxId) return;
+		if (!junkDestinationId) return;
 		const ids = triageTargetMessageIds();
 		if (ids.length === 0) return;
 		recordRescueSentToJunk(telemetry, {
@@ -732,10 +734,10 @@ function MailboxPaneProvider({
 			senderTrust: focusedThread?.senderTrust ?? "unknown",
 			wasRescuable: focusedThread ? isRescueCandidate(focusedThread) : false,
 		});
-		triageMove(ids, junkMailboxId);
+		triageMove(ids, junkDestinationId);
 	}, [
 		listCommandsRef,
-		junkMailboxId,
+		junkDestinationId,
 		triageTargetMessageIds,
 		triageMove,
 		telemetry,

package/src/components/mail/MessageList.tsx

@@ -46,8 +46,10 @@ import {
 	escalationActionLabel,
 } from "@/lib/escalation-label";
 import { formatDeleteToTrashTitle, formatEmailDate } from "@/lib/format";
+import { junkDestination } from "@/lib/junk-destination";
 import { tabStopId } from "@/lib/list-focus";
 import { useListHeaderChrome } from "@/lib/list-header-chrome";
+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";
@@ -290,6 +292,7 @@ export const MessageList = ({
 	// The Junk quick action moves the selection to the account's appointed Junk
 	// mailbox — the message-flags API has no `$Junk` field, so "junk" is a move.
 	const { junkMailboxId } = useJunkMailbox(accountId);
+	const junkDestinationId = junkDestination(junkMailboxId, mailboxId);
 
 	// Selection state
 	const {
@@ -571,39 +574,50 @@ export const MessageList = ({
 		}
 	}, [orderedIds, selectAll]);
 
-	// A keyboard verb, routed the same way the bar routes its own. Over a
-	// selection every verb opens the wizard, so the keyboard cannot reach a bulk
-	// action the bar would have reviewed. Over a bare cursor only Delete is the
-	// list's, and it keeps the confirmation and the cursor hand-back.
+	// A keyboard verb, routed by `listVerbRequest` — the same routing the bar
+	// renders from, so a verb the bar withholds is not still reachable by
+	// shortcut. Over a selection every verb opens the wizard (#477 1.4), whatever
+	// the selection is: the ticked rows, a selection spanning accounts — the
+	// wizard is where that restriction is stated, on the step that needs one
+	// account (#477 5.5) — or the predicate the list escalated to, which the
+	// wizard names on its match step and counts on its review screen before
+	// anything is sent (#508).
 	const requestVerb = useCallback(
 		(verb: Verb): boolean => {
-			// The confirmation is already asking about a delete: the keypress belongs
-			// to it, and answering it is the Confirm button's job. Claiming the press
-			// here is what stops a second Delete from reaching an unconfirmed delete.
-			if (pendingDelete !== null) return true;
-			if (hasSelection) {
-				// Every verb on the bar opens the wizard (#477 1.4), whatever the
-				// selection is: the ticked rows, a selection spanning accounts — the
-				// wizard is where that restriction is stated, on the step that needs
-				// one account (#477 5.5) — or the predicate the list escalated to,
-				// which the wizard names on its match step and counts on its review
-				// screen before anything is sent (#508).
+			const request = listVerbRequest({
+				verb,
+				confirmingDelete: pendingDelete !== null,
+				hasSelection,
+				junkMailboxId,
+				currentMailboxId: mailboxId,
+				deletableMessageId: onDeleteMessages ? focusedMessageId : undefined,
+			});
+			if (request.kind === "openWizard") {
 				startWizard(verb);
 				return true;
 			}
-			if (verb !== "delete" || !onDeleteMessages || !focusedMessageId) {
-				return false;
+			if (request.kind === "confirmDelete") {
+				requestDelete([request.messageId]);
+				return true;
 			}
-			requestDelete([focusedMessageId]);
-			return true;
+			// A shortcut that does nothing at all is indistinguishable from one that
+			// is broken, so a verb this mailbox cannot take says why on the press.
+			if (request.kind === "unavailable") {
+				pushError({ severity: "warning", title: request.reason });
+				return true;
+			}
+			return request.kind === "withheld";
 		},
 		[
 			pendingDelete,
 			onDeleteMessages,
 			hasSelection,
+			junkMailboxId,
+			mailboxId,
 			startWizard,
 			focusedMessageId,
 			requestDelete,
+			pushError,
 		],
 	);
 
@@ -1178,11 +1192,7 @@ export const MessageList = ({
 			onDelete={() => startWizard("delete")}
 			onMove={() => startWizard("move")}
 			onOrganize={organizeSelection}
-			onJunk={
-				junkMailboxId && junkMailboxId !== mailboxId
-					? () => startWizard("junk")
-					: undefined
-			}
+			onJunk={junkDestinationId ? () => startWizard("junk") : undefined}
 			onMarkRead={() => startWizard("markRead")}
 			overflowSlot={
 				accountId && mailboxId && selectedCount > 0 && labels.length > 0 ? (

package/src/components/mail/SelectionWizardHost.run-exit.test.ts

@@ -45,7 +45,7 @@ describe("ending the run", () => {
 		assert.match(source, /onCancelRun: runInFlight \? stopRun : undefined/);
 		assert.match(
 			source,
-			/const runInFlight =\s*bulkRun !== undefined && bulkRun\.outcome === undefined;/,
+			/const runInFlight =\s*bulkRun !== undefined &&\s*bulkRun\.outcome === undefined &&\s*bulkRun\.failureReason === undefined;/,
 		);
 	});
 

package/src/components/mail/SelectionWizardHost.tsx

@@ -48,6 +48,7 @@ import { useOrganizeWiden } from "@/hooks/useOrganizeWiden";
 import { useRulePreview } from "@/hooks/useRulePreview";
 import { useSelectedSubjects } from "@/hooks/useSelectedSubjects";
 import type { BulkActionProgress, BulkRunOutcome } from "@/lib/bulk-actions";
+import { NO_JUNK_FOLDER_REASON } from "@/lib/junk-destination";
 import { useListHeaderChrome } from "@/lib/list-header-chrome";
 import { useMailContext } from "@/lib/mail-context";
 import { buildMoveOptions, folderDelimiter } from "@/lib/move-options";
@@ -174,6 +175,12 @@ interface RunSnapshot {
 	applied: number;
 	failed: number;
 	failures: readonly WizardMessage[];
+	/**
+	 * Why a commit never started, when the reason is one the same commit cannot
+	 * get past. Carried to the run screen, which states it and offers no retry
+	 * (#522).
+	 */
+	failureReason?: string;
 }
 
 const NOT_STARTED: RunSnapshot = {
@@ -222,21 +229,12 @@ const widenedRunsAsJob = (verb: Verb): boolean =>
  * The commit pressed with nowhere for the mail to go. A verb that files mail
  * needs a destination, and reaching the run screen without one is a failure the
  * screen states along with the way out of it — never a control that does
- * nothing.
+ * nothing, and never a retry that re-sends the same commit to the same absence.
  */
-const noDestinationOutcome = (
-	verb: Verb,
-	ids: readonly string[],
-): BulkRunOutcome => ({
-	done: 0,
-	failedIds: [...ids],
-	cancelled: false,
-	error: new Error(
-		verb === "junk"
-			? "This account has no Junk folder appointed, so there is nowhere to file these. Appoint one under Settings › Folders."
-			: "No destination was chosen, so there is nowhere to file these. Go back and pick a folder.",
-	),
-});
+const noDestinationReason = (verb: Verb): string =>
+	verb === "junk"
+		? NO_JUNK_FOLDER_REASON
+		: "No destination was chosen, so there is nowhere to file these. Go back and pick a folder.";
 
 /**
  * Where the wizard meets the app (#483). The steps and their bodies belong to
@@ -305,7 +303,8 @@ function SelectionWizardSession({
 		OrganizeScope | undefined
 	>(undefined);
 	const [bulkRun, setBulkRun] = useState<
-		{ matched: number; outcome?: BulkRunOutcome } | undefined
+		| { matched: number; outcome?: BulkRunOutcome; failureReason?: string }
+		| undefined
 	>(undefined);
 	// The predicate the create chains its pass to. Undefined when the rule cannot
 	// be back-applied — a `HasWords` clause the vector-free pass cannot evaluate —
@@ -589,7 +588,7 @@ function SelectionWizardSession({
 			if (!action) {
 				setBulkRun({
 					matched: ids.length,
-					outcome: noDestinationOutcome(verb, ids),
+					failureReason: noDestinationReason(verb),
 				});
 				return;
 			}
@@ -610,7 +609,7 @@ function SelectionWizardSession({
 		if (!action) {
 			setBulkRun({
 				matched: escalated.total,
-				outcome: noDestinationOutcome(verb, []),
+				failureReason: noDestinationReason(verb),
 			});
 			return;
 		}
@@ -747,7 +746,12 @@ function SelectionWizardSession({
 
 	const bulkSnapshot = useCallback((): RunSnapshot => {
 		if (!bulkRun) return NOT_STARTED;
-		const { matched, outcome } = bulkRun;
+		const { matched, outcome, failureReason } = bulkRun;
+		// Nothing was sent, and nothing about sending it again resolves what was
+		// missing — so the screen carries why rather than the generic ending (#522).
+		if (failureReason !== undefined) {
+			return { ...NOT_STARTED, state: "commitFailed", failureReason };
+		}
 		if (!outcome) {
 			const applied = runProgress?.done ?? 0;
 			// A predicate matches more by the time the run re-pages it than the count
@@ -867,7 +871,11 @@ function SelectionWizardSession({
 	// list's runner and a bounded selection by this wizard's own, so the stop
 	// follows whichever one is paging.
 	const { stop: stopBulk } = bulk;
-	const runInFlight = bulkRun !== undefined && bulkRun.outcome === undefined;
+	// A commit that never started has nothing paging and nothing to end.
+	const runInFlight =
+		bulkRun !== undefined &&
+		bulkRun.outcome === undefined &&
+		bulkRun.failureReason === undefined;
 	const stopRun = useCallback(() => {
 		if (escalated) {
 			escalated.stop();
@@ -1001,6 +1009,7 @@ function SelectionWizardSession({
 				applied: run.applied,
 				failedCount: run.failed,
 				failures: run.failures,
+				failureReason: run.failureReason,
 				onRetry: retry,
 				onDismiss: dismiss,
 				onCancelRun: runInFlight ? stopRun : undefined,

package/src/components/mail/SwipeableMessageRow.modifier-select.test.ts

@@ -0,0 +1,237 @@
+/**
+ * A modifier can only come from a real keyboard, so the touch row honours it at
+ * every width (#586).
+ *
+ * Below 1024px the list renders the swipe row, which reads a press as a pointer
+ * gesture and opens the message from the release. Shift and cmd have to reach
+ * selection before that gesture starts, or a half-screen window and a tablet
+ * with a keyboard can only ever open messages one at a time.
+ */
+
+import assert from "node:assert/strict";
+import { afterEach, describe, it } from "node:test";
+import type { RemitImapThreadMessageResponse } from "@remit/api-http-client/types.gen.ts";
+import type { SelectionModifiers } from "@remit/ui";
+import {
+	type AnyRouter,
+	createMemoryHistory,
+	createRootRoute,
+	createRoute,
+	createRouter,
+	RouterContextProvider,
+} from "@tanstack/react-router";
+import { createElement } from "react";
+import { createDomHarness, type DomHarness } from "../../test-support/dom";
+import { SwipeableMessageRow } from "./SwipeableMessageRow";
+
+const HALF_SCREEN_WIDTH = 900;
+
+let harness: DomHarness | undefined;
+
+afterEach(() => {
+	harness?.close();
+	harness = undefined;
+});
+
+const thread = {
+	threadMessageId: "tm-1",
+	threadId: "th-1",
+	messageId: "msg-1",
+	accountId: "acc-1",
+	accountConfigId: "acc-1",
+	mailboxId: "mbx-1",
+	subject: "Q3 planning notes",
+	fromName: "Alex Rivera",
+	fromEmail: "alex@example.com",
+	snippet: "Notes from the planning session.",
+	sentDate: 0,
+	isRead: false,
+	hasAttachment: false,
+	hasStars: false,
+	star: "None",
+	isDeleted: false,
+	senderTrust: "unknown",
+	createdAt: 0,
+	updatedAt: 0,
+} as unknown as RemitImapThreadMessageResponse;
+
+// The router reads `self` at construction; the shared jsdom globals stop at
+// `window`.
+(globalThis as { self?: typeof globalThis }).self ??= globalThis;
+
+const rootRoute = createRootRoute();
+const mailRoute = createRoute({
+	getParentRoute: () => rootRoute,
+	path: "/mail/$mailboxId",
+});
+
+interface Mounted {
+	row: HTMLElement;
+	router: AnyRouter;
+	selects: SelectionModifiers[];
+}
+
+const mountRow = (selectionTakesIt = true): Mounted => {
+	const selects: SelectionModifiers[] = [];
+	const router = createRouter({
+		routeTree: rootRoute.addChildren([mailRoute]),
+		history: createMemoryHistory({ initialEntries: ["/mail/mbx-1"] }),
+	}) as unknown as AnyRouter;
+	const created = createDomHarness({ viewportWidth: HALF_SCREEN_WIDTH });
+	harness = created;
+	created.render(
+		createElement(RouterContextProvider, {
+			router,
+			// biome-ignore lint/correctness/noChildrenProp: RouterContextProvider types `children` as a required prop, which createElement's rest-argument form does not satisfy
+			children: createElement(SwipeableMessageRow, {
+				thread,
+				mailboxId: "mbx-1",
+				isSelected: false,
+				isChecked: false,
+				onToggleCheck: () => undefined,
+				onRowSelect: (_id: string, modifiers: SelectionModifiers) => {
+					selects.push(modifiers);
+					return selectionTakesIt;
+				},
+				isMultiSelectMode: false,
+				onLongPress: () => undefined,
+				isDesktop: false,
+				onDelete: () => undefined,
+				onToggleRead: () => undefined,
+			}),
+		}),
+	);
+	const row = created.query("button[data-message-row]");
+	assert.ok(row, "the swipe row did not mount");
+	return { row, router, selects };
+};
+
+const press = (
+	row: Element,
+	modifiers: Partial<SelectionModifiers> = {},
+): PointerEvent => {
+	const event = new PointerEvent("pointerdown", {
+		bubbles: true,
+		cancelable: true,
+		pointerId: 1,
+		clientX: 10,
+		clientY: 10,
+		shiftKey: modifiers.shiftKey ?? false,
+		metaKey: modifiers.metaKey ?? false,
+		ctrlKey: modifiers.ctrlKey ?? false,
+	});
+	harness?.dispatch(row, event);
+	return event;
+};
+
+const release = (row: Element): void => {
+	harness?.dispatch(
+		row,
+		new PointerEvent("pointerup", { bubbles: true, pointerId: 1 }),
+	);
+};
+
+// A press whose default was taken still delivers a click, so the click has to
+// be consumed too rather than reaching selection a second time.
+const click = (
+	row: Element,
+	modifiers: Partial<SelectionModifiers> = {},
+): void =>
+	harness?.dispatch(
+		row,
+		new MouseEvent("click", {
+			bubbles: true,
+			cancelable: true,
+			shiftKey: modifiers.shiftKey ?? false,
+			metaKey: modifiers.metaKey ?? false,
+			ctrlKey: modifiers.ctrlKey ?? false,
+		}),
+	);
+
+const openedMessageId = (router: AnyRouter): string | undefined =>
+	(router.state.location.search as { selectedMessageId?: string })
+		.selectedMessageId;
+
+describe("SwipeableMessageRow — modifier selection below the desktop width", () => {
+	it("takes a shift-press for selection instead of opening the message", async () => {
+		const { row, router, selects } = mountRow();
+
+		const event = press(row, { shiftKey: true });
+		release(row);
+		await harness?.flush();
+
+		assert.deepEqual(selects, [
+			{ shiftKey: true, metaKey: false, ctrlKey: false },
+		]);
+		assert.equal(event.defaultPrevented, true);
+		assert.equal(openedMessageId(router), undefined);
+	});
+
+	it("takes a cmd-press for selection instead of opening the message", async () => {
+		const { row, router, selects } = mountRow();
+
+		press(row, { metaKey: true });
+		release(row);
+		click(row, { metaKey: true });
+		await harness?.flush();
+
+		assert.deepEqual(selects, [
+			{ shiftKey: false, metaKey: true, ctrlKey: false },
+		]);
+		assert.equal(openedMessageId(router), undefined);
+	});
+
+	it("drops the native text selection a shift-press would drag across rows", () => {
+		const { row } = mountRow();
+		const selection = harness?.window.getSelection();
+		assert.ok(selection, "jsdom exposes no selection");
+		const range = harness?.document.createRange();
+		assert.ok(range, "jsdom exposes no range");
+		range.selectNodeContents(row);
+		selection.removeAllRanges();
+		selection.addRange(range);
+
+		press(row, { shiftKey: true });
+
+		assert.equal(selection.rangeCount, 0);
+	});
+
+	it("suppresses the context menu a ctrl-press already spent on selection", () => {
+		const { row, selects } = mountRow();
+
+		press(row, { ctrlKey: true });
+		const menu = new MouseEvent("contextmenu", {
+			bubbles: true,
+			cancelable: true,
+			ctrlKey: true,
+		});
+		harness?.dispatch(row, menu);
+
+		assert.deepEqual(selects, [
+			{ shiftKey: false, metaKey: false, ctrlKey: true },
+		]);
+		assert.equal(menu.defaultPrevented, true);
+	});
+
+	it("opens on an unmodified tap", async () => {
+		const { row, router, selects } = mountRow();
+
+		press(row);
+		release(row);
+		click(row);
+		await harness?.flush();
+
+		assert.deepEqual(selects, []);
+		assert.equal(openedMessageId(router), "msg-1");
+	});
+
+	it("opens when selection declines the modified press", async () => {
+		const { row, router } = mountRow(false);
+
+		press(row, { metaKey: true });
+		release(row);
+		await harness?.flush();
+
+		assert.equal(openedMessageId(router), "msg-1");
+	});
+});

package/src/components/mail/SwipeableMessageRow.tsx

@@ -11,6 +11,7 @@ import { useCallback, useState } from "react";
 import { toDisplayCategory } from "@/lib/display-category";
 import { formatEmailDate } from "@/lib/format";
 import { MessageListItem } from "./MessageListItem";
+import { useModifierSelect } from "./useModifierSelect";
 
 interface MailboxLinkSearch {
 	selectedMessageId?: string;
@@ -111,6 +112,8 @@ export const SwipeableMessageRow = ({
 		});
 	}, [navigate, mailboxId, thread.messageId]);
 
+	const modifierSelect = useModifierSelect(thread.messageId, onRowSelect);
+
 	if (isDesktop || isMultiSelectMode) {
 		return (
 			<MessageListItem
@@ -131,18 +134,31 @@ export const SwipeableMessageRow = ({
 		);
 	}
 
+	// The swipe row reads the press as a pointer gesture, and it opens the message
+	// from the release — a `mousedown` handler on the row would already be behind
+	// it. Taking the modified press in the capture phase keeps it away from the
+	// gesture entirely, so a shift- or cmd-click selects instead of starting a
+	// swipe, a long press or an open.
 	return (
-		<SwipeableRow
-			thread={toThreadRowData(thread)}
-			selectionMode={false}
-			checked={false}
-			active={isSelected}
-			peek={peek}
-			onPeek={setPeek}
-			onToggleCheck={handleToggleCheck}
-			onLongPress={handleLongPress}
-			onOpen={handleOpen}
-			onAct={handleAct}
-		/>
+		// biome-ignore lint/a11y/noStaticElementInteractions: the wrapper only intercepts mouse modifiers ahead of the row's own gesture; the row beneath keeps the button semantics and the whole keyboard path
+		<div
+			role="presentation"
+			onPointerDownCapture={modifierSelect.onMouseDown}
+			onClickCapture={modifierSelect.claimClick}
+			onContextMenu={modifierSelect.onContextMenu}
+		>
+			<SwipeableRow
+				thread={toThreadRowData(thread)}
+				selectionMode={false}
+				checked={false}
+				active={isSelected}
+				peek={peek}
+				onPeek={setPeek}
+				onToggleCheck={handleToggleCheck}
+				onLongPress={handleLongPress}
+				onOpen={handleOpen}
+				onAct={handleAct}
+			/>
+		</div>
 	);
 };

package/src/components/mail/selection-verbs.test.ts

@@ -191,13 +191,20 @@ describe("every keyboard verb over a selection goes through the list", () => {
 		markJunk: "junk",
 	};
 
+	/**
+	 * How a list may answer a verb aimed at the bare cursor: with the shared
+	 * decision, whose rules are in `../../lib/list-verb-request.test.ts`, or
+	 * inline. Either way only Delete is the list's.
+	 */
+	const CURSOR_DELETE_ONLY = /listVerbRequest\(\{|if \(verb !== "delete"/;
+
 	for (const file of LISTS) {
 		it(`${file} publishes the one seam and claims a selection`, () => {
 			const source = read(file);
 			assert.match(source, /requestVerb,/);
 			assert.match(
 				source,
-				/if \(verb !== "delete"/,
+				CURSOR_DELETE_ONLY,
 				"only delete is the list's over a bare cursor",
 			);
 			assert.doesNotMatch(

package/src/lib/junk-destination.test.ts

@@ -0,0 +1,40 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import {
+	ALREADY_IN_JUNK_REASON,
+	junkDestination,
+	junkWithheldReason,
+	NO_JUNK_FOLDER_REASON,
+} from "./junk-destination";
+
+const JUNK = "mbx-junk";
+const INBOX = "mbx-inbox";
+
+describe("junkDestination", () => {
+	it("is the appointed folder when the mail is somewhere else", () => {
+		assert.equal(junkDestination(JUNK, INBOX), JUNK);
+	});
+
+	it("is nothing when the account appointed no Junk folder", () => {
+		assert.equal(junkDestination(undefined, INBOX), undefined);
+	});
+
+	it("is nothing when the mail is already in the Junk folder", () => {
+		assert.equal(junkDestination(JUNK, JUNK), undefined);
+	});
+});
+
+describe("junkWithheldReason", () => {
+	it("is nothing to say when the verb can act", () => {
+		assert.equal(junkWithheldReason(JUNK, INBOX), undefined);
+	});
+
+	it("names the setting that appoints a folder", () => {
+		assert.equal(junkWithheldReason(undefined, INBOX), NO_JUNK_FOLDER_REASON);
+		assert.match(NO_JUNK_FOLDER_REASON, /Settings › Folders/);
+	});
+
+	it("says the mail is already where the verb would put it", () => {
+		assert.equal(junkWithheldReason(JUNK, JUNK), ALREADY_IN_JUNK_REASON);
+	});
+});

package/src/lib/junk-destination.ts

@@ -0,0 +1,37 @@
+/**
+ * Where the Junk verb can file mail, and why it cannot when it cannot (#522).
+ * One reading, for every surface that offers the verb: the selection bar, the
+ * keyboard, the brief's own bar and the wizard's commit. A second derivation is
+ * what let the keyboard open a wizard on a verb the bar was withholding.
+ */
+
+export const NO_JUNK_FOLDER_REASON =
+	"This account has no Junk folder appointed, so there is nowhere to file these. Appoint one under Settings › Folders.";
+
+export const ALREADY_IN_JUNK_REASON =
+	"These are already in Junk, so there is nowhere to file them.";
+
+/**
+ * The account's appointed Junk folder, and nothing at all when the account has
+ * appointed none or when that folder is the one the mail is already in.
+ */
+export const junkDestination = (
+	junkMailboxId: string | undefined,
+	currentMailboxId: string | undefined,
+): string | undefined =>
+	junkMailboxId !== undefined && junkMailboxId !== currentMailboxId
+		? junkMailboxId
+		: undefined;
+
+/** Why the verb cannot be offered here, and nothing when it can. */
+export const junkWithheldReason = (
+	junkMailboxId: string | undefined,
+	currentMailboxId: string | undefined,
+): string | undefined => {
+	if (junkDestination(junkMailboxId, currentMailboxId) !== undefined) {
+		return undefined;
+	}
+	return junkMailboxId === undefined
+		? NO_JUNK_FOLDER_REASON
+		: ALREADY_IN_JUNK_REASON;
+};

package/src/lib/list-verb-request.test.ts

@@ -0,0 +1,124 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import type { Verb } from "@remit/ui";
+import {
+	ALREADY_IN_JUNK_REASON,
+	NO_JUNK_FOLDER_REASON,
+} from "./junk-destination";
+import { type ListVerbReading, listVerbRequest } from "./list-verb-request";
+
+const JUNK = "mbx-junk";
+const INBOX = "mbx-inbox";
+
+const reading = (over: Partial<ListVerbReading> = {}): ListVerbReading => ({
+	verb: "junk",
+	confirmingDelete: false,
+	hasSelection: true,
+	junkMailboxId: JUNK,
+	currentMailboxId: INBOX,
+	deletableMessageId: undefined,
+	...over,
+});
+
+const VERBS: Verb[] = ["delete", "move", "junk", "markRead", "organize"];
+
+describe("listVerbRequest", () => {
+	it("opens the wizard for every verb over a selection", () => {
+		for (const verb of VERBS) {
+			assert.deepEqual(
+				listVerbRequest(reading({ verb })),
+				{ kind: "openWizard" },
+				verb,
+			);
+		}
+	});
+
+	it("leaves a verb aimed at the bare cursor to the pane, except delete", () => {
+		for (const verb of VERBS.filter((each) => each !== "delete")) {
+			assert.deepEqual(
+				listVerbRequest(
+					reading({ verb, hasSelection: false, deletableMessageId: "m1" }),
+				),
+				{ kind: "declined" },
+				verb,
+			);
+		}
+		assert.deepEqual(
+			listVerbRequest(
+				reading({
+					verb: "delete",
+					hasSelection: false,
+					deletableMessageId: "m1",
+				}),
+			),
+			{ kind: "confirmDelete", messageId: "m1" },
+		);
+	});
+
+	it("declines a delete the surface cannot make", () => {
+		assert.deepEqual(
+			listVerbRequest(
+				reading({
+					verb: "delete",
+					hasSelection: false,
+					deletableMessageId: undefined,
+				}),
+			),
+			{ kind: "declined" },
+		);
+	});
+
+	it("claims a second delete rather than letting it past the confirmation", () => {
+		assert.deepEqual(
+			listVerbRequest(reading({ verb: "delete", confirmingDelete: true })),
+			{ kind: "withheld" },
+		);
+	});
+
+	/**
+	 * #522. The bar withholds Junk on exactly these two readings; the keyboard
+	 * used to claim the press regardless and open the wizard on a verb whose
+	 * commit then resolved no destination — ending on a Try again that re-sent the
+	 * identical commit forever.
+	 */
+	describe("Junk with nowhere to file into", () => {
+		it("is withheld over a selection when no Junk folder is appointed", () => {
+			assert.deepEqual(listVerbRequest(reading({ junkMailboxId: undefined })), {
+				kind: "unavailable",
+				reason: NO_JUNK_FOLDER_REASON,
+			});
+		});
+
+		it("is withheld over a selection inside the Junk folder itself", () => {
+			assert.deepEqual(listVerbRequest(reading({ currentMailboxId: JUNK })), {
+				kind: "unavailable",
+				reason: ALREADY_IN_JUNK_REASON,
+			});
+		});
+
+		it("is withheld over a bare cursor too, rather than falling to the pane", () => {
+			// Declining here hands the press to the pane, which moves the focused row
+			// into the folder it is already in and reports it as done.
+			assert.deepEqual(
+				listVerbRequest(
+					reading({
+						hasSelection: false,
+						currentMailboxId: JUNK,
+						deletableMessageId: "m1",
+					}),
+				),
+				{ kind: "unavailable", reason: ALREADY_IN_JUNK_REASON },
+			);
+		});
+
+		it("withholds nothing else on the same reading", () => {
+			for (const verb of VERBS.filter((each) => each !== "junk")) {
+				assert.deepEqual(
+					listVerbRequest(reading({ verb, junkMailboxId: undefined })),
+					{ kind: "openWizard" },
+					verb,
+				);
+			}
+		});
+	});
+});

package/src/lib/list-verb-request.ts

@@ -0,0 +1,62 @@
+/**
+ * What a message list does with a verb the keyboard aimed at it (#477 1.4,
+ * #508, #522). Pure, so the routing is testable without the DOM, the router and
+ * the data hooks a list wires together.
+ */
+
+import type { Verb } from "@remit/ui";
+import { junkWithheldReason } from "./junk-destination";
+
+/**
+ * - `openWizard` — the selection walks the wizard, which is where a bulk action
+ *   is reviewed before it reaches the mail server.
+ * - `confirmDelete` — the one verb a bare cursor keeps, with its confirmation.
+ * - `withheld` — the press belongs to what is already on screen: the delete
+ *   confirmation is asking, and answering it is the Confirm button's job.
+ * - `unavailable` — the verb cannot act on this mail from here, and this is why.
+ *   The list takes the press and says so, rather than leaving a shortcut that
+ *   silently does nothing.
+ * - `declined` — not the list's press, so the pane acts on the focused row.
+ */
+export type ListVerbRequest =
+	| { kind: "openWizard" }
+	| { kind: "confirmDelete"; messageId: string }
+	| { kind: "withheld" }
+	| { kind: "unavailable"; reason: string }
+	| { kind: "declined" };
+
+export interface ListVerbReading {
+	verb: Verb;
+	/** The delete confirmation is on screen. */
+	confirmingDelete: boolean;
+	hasSelection: boolean;
+	/** The account's appointed Junk folder, when it has appointed one. */
+	junkMailboxId: string | undefined;
+	/** The mailbox the rows are in, which the Junk destination cannot also be. */
+	currentMailboxId: string | undefined;
+	/** The row under the cursor, when this surface can delete it. */
+	deletableMessageId: string | undefined;
+}
+
+export const listVerbRequest = ({
+	verb,
+	confirmingDelete,
+	hasSelection,
+	junkMailboxId,
+	currentMailboxId,
+	deletableMessageId,
+}: ListVerbReading): ListVerbRequest => {
+	if (confirmingDelete) return { kind: "withheld" };
+	// Junk with nowhere to file into is kept off the keyboard exactly as the bar
+	// keeps it off the screen. Opening the wizard on it instead ends on a commit
+	// that resolves no destination, whatever is ticked (#522).
+	if (verb === "junk") {
+		const reason = junkWithheldReason(junkMailboxId, currentMailboxId);
+		if (reason !== undefined) return { kind: "unavailable", reason };
+	}
+	if (hasSelection) return { kind: "openWizard" };
+	if (verb !== "delete" || deletableMessageId === undefined) {
+		return { kind: "declined" };
+	}
+	return { kind: "confirmDelete", messageId: deletableMessageId };
+};