@remit/web-client 0.0.131 → 0.0.133

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/web-client",
-  "version": "0.0.131",
+  "version": "0.0.133",
   "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/IntelligencePane.render.test.ts

@@ -0,0 +1,134 @@
+/**
+ * The spam quick action stayed clickable throughout its own request (issue
+ * #648 review): the server dedupes message ids only within a single call, so
+ * two clicks fired two separate HTTP requests. For the undo direction this
+ * produced a wrong message — concurrent `notSpam` #2 reads
+ * `originalMailboxId` before #1 clears it, waits on #1's restore move, and
+ * can throw `MoveNotSettledError` on an undo that already succeeded. Wires
+ * the real `useReportSpam` hook to the real `IntelligencePanel` (the shape
+ * `IntelligencePane.tsx`'s `WiredPanel` uses) and clicks the real button
+ * twice to prove the fix: disabled while pending blocks the second request
+ * at the DOM level, not just in the hook.
+ */
+
+import assert from "node:assert/strict";
+import { afterEach, describe, it } from "node:test";
+import type { IntelligenceData } from "@remit/ui";
+import { IntelligencePanel } from "@remit/ui";
+import { createElement } from "react";
+import { useReportSpam } from "@/hooks/useReportSpam";
+import { createDomHarness, type DomHarness } from "@/test-support/dom";
+import { type HttpMock, mockFetch } from "@/test-support/http";
+
+const baseData: IntelligenceData = {
+	sender: {
+		name: "Alex Rivera",
+		email: "alex@example.com",
+		trust: "wellknown",
+		firstSeenLabel: "Jan 2025",
+	},
+	authenticity: {
+		verdict: "aligned",
+		fromDomain: "example.com",
+		dkimDomain: "example.com",
+		summary: "This message was signed by example.com.",
+	},
+	category: { value: "Personal" },
+	similar: [],
+};
+
+const ReportHarness = () => {
+	const { reportSpam, isReporting } = useReportSpam({ mailboxId: "mbx-inbox" });
+	return createElement(IntelligencePanel, {
+		data: baseData,
+		actions: { onReportSpam: () => reportSpam(["msg-1"]) },
+		reportSpamPending: isReporting,
+	});
+};
+
+const UndoHarness = () => {
+	const { notSpam, isRestoring } = useReportSpam({ mailboxId: "mbx-junk" });
+	return createElement(IntelligencePanel, {
+		data: baseData,
+		actions: { onNotSpam: () => notSpam(["msg-1"]) },
+		notSpamPending: isRestoring,
+	});
+};
+
+let harness: DomHarness | undefined;
+let http: HttpMock;
+
+const waitFor = async (
+	predicate: () => boolean,
+	timeoutMs = 2000,
+): Promise<void> => {
+	if (!harness) throw new Error("nothing mounted");
+	const deadline = Date.now() + timeoutMs;
+	while (!predicate()) {
+		if (Date.now() > deadline) {
+			throw new Error(
+				`waitFor: condition never became true within ${timeoutMs}ms`,
+			);
+		}
+		await harness.flush();
+		await harness.wait(5);
+	}
+};
+
+afterEach(() => {
+	harness?.close();
+	harness = undefined;
+	http.restore();
+});
+
+describe("the spam quick action disables itself for the duration of its own request (#648 review)", () => {
+	it("report direction: a second click while the report is in flight sends only one request", async () => {
+		let resolveRequest: (() => void) | undefined;
+		http = mockFetch(
+			() =>
+				new Promise((resolve) => {
+					resolveRequest = () => resolve({ successCount: 1, failureCount: 0 });
+				}),
+		);
+		harness = createDomHarness();
+		harness.renderApp(createElement(ReportHarness));
+
+		const button = harness.byText("button", "Report spam") as HTMLButtonElement;
+		harness.click(button);
+		await waitFor(() => button.textContent === "Reporting…");
+
+		assert.equal(button.disabled, true, "a control mid-request must disable");
+		harness.click(button);
+
+		assert.ok(resolveRequest, "the request never reached the mock");
+		resolveRequest?.();
+		await waitFor(() => button.textContent === "Report spam");
+
+		assert.equal(http.to("/messages/report-spam").length, 1);
+	});
+
+	it("undo direction: a second click while the undo is in flight sends only one request", async () => {
+		let resolveRequest: (() => void) | undefined;
+		http = mockFetch(
+			() =>
+				new Promise((resolve) => {
+					resolveRequest = () => resolve({ successCount: 1, failureCount: 0 });
+				}),
+		);
+		harness = createDomHarness();
+		harness.renderApp(createElement(UndoHarness));
+
+		const button = harness.byText("button", "Not spam") as HTMLButtonElement;
+		harness.click(button);
+		await waitFor(() => button.textContent === "Undoing…");
+
+		assert.equal(button.disabled, true, "a control mid-request must disable");
+		harness.click(button);
+
+		assert.ok(resolveRequest, "the request never reached the mock");
+		resolveRequest?.();
+		await waitFor(() => button.textContent === "Not spam");
+
+		assert.equal(http.to("/messages/not-spam").length, 1);
+	});
+});

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/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/hooks/useReportSpam.escalation.test.ts

@@ -0,0 +1,135 @@
+/**
+ * Closes the seam the existing #648-review tests each cover half of.
+ * `useReportSpam.integration.test.ts` builds a synthetic mutation via
+ * `mutationCache.build()` and never mounts the hook; `useReportSpam.render.
+ * test.ts` mounts the hook but under `createDomHarness`'s default
+ * `QueryClient`, which carries no global cache handlers. Neither exercises the
+ * JOIN: the real `useMutation` calls in `useReportSpam.ts`, under a
+ * `QueryClient` wired with the real `QueryCache`/`MutationCache` handlers from
+ * `lib/query-error-handler.ts` the way `shell/index.tsx` builds it, wrapped in
+ * the real `ErrorBannerProvider`. Deleting `meta: { softError: true }` from
+ * the real hook passes both existing tests — that is the bug that shipped
+ * twice and passed CI both times.
+ */
+
+import assert from "node:assert/strict";
+import { afterEach, describe, it } from "node:test";
+import { MutationCache, QueryCache, QueryClient } from "@tanstack/react-query";
+import { createElement, Fragment } from "react";
+import { FatalErrorOverlay } from "../components/ui/FatalErrorOverlay";
+import { __resetFatalError, subscribeFatalError } from "../lib/fatal-error";
+import {
+	handleMutationCacheError,
+	handleQueryCacheError,
+} from "../lib/query-error-handler";
+import { createDomHarness, type DomHarness } from "../test-support/dom";
+import { type HttpMock, httpError, mockFetch } from "../test-support/http";
+import { useReportSpam } from "./useReportSpam";
+
+let harness: DomHarness | undefined;
+let http: HttpMock;
+
+const mountHook = <T>(useHook: () => T): (() => T) => {
+	let value: T | undefined;
+	const Probe = () => {
+		value = useHook();
+		return null;
+	};
+	const queryClient = new QueryClient({
+		queryCache: new QueryCache({ onError: handleQueryCacheError }),
+		mutationCache: new MutationCache({ onError: handleMutationCacheError }),
+		defaultOptions: { mutations: { retry: false } },
+	});
+	harness = createDomHarness({ queryClient });
+	harness.renderApp(
+		createElement(
+			Fragment,
+			null,
+			createElement(FatalErrorOverlay),
+			createElement(Probe),
+		),
+	);
+	return () => {
+		if (value === undefined) throw new Error("hook did not render");
+		return value;
+	};
+};
+
+/** See `useReportSpam.render.test.ts` — the chain from a resolved fetch to a re-render crosses enough async boundaries that a fixed microtask count reads as flaky under load. */
+const waitFor = async (
+	predicate: () => boolean,
+	timeoutMs = 2000,
+): Promise<void> => {
+	if (!harness) throw new Error("nothing mounted");
+	const deadline = Date.now() + timeoutMs;
+	while (!predicate()) {
+		if (Date.now() > deadline) {
+			throw new Error(
+				`waitFor: condition never became true within ${timeoutMs}ms`,
+			);
+		}
+		await harness.flush();
+		await harness.wait(5);
+	}
+};
+
+const bannerAlerts = () =>
+	harness?.queryAll('[aria-label="Notifications"] [role="alert"]') ?? [];
+
+const fatalOverlay = () =>
+	harness?.query('[data-testid="fatal-error-overlay"]') ?? null;
+
+afterEach(() => {
+	harness?.close();
+	harness = undefined;
+	http.restore();
+	__resetFatalError();
+});
+
+describe("useReportSpam under the real global cache handlers (#648 review, the join both existing tests missed)", () => {
+	it("a per-message report failure banners once and never mounts the fatal overlay — report direction", async () => {
+		const fatalsSeen: string[] = [];
+		subscribeFatalError((fatal) => fatalsSeen.push(fatal.message));
+		http = mockFetch(() => ({ failureCount: 1 }));
+		const hook = mountHook(() => useReportSpam({ mailboxId: "mbx-inbox" }));
+
+		hook().reportSpam(["msg-1"]);
+		await waitFor(() => bannerAlerts().length > 0);
+
+		assert.equal(
+			fatalOverlay() !== null,
+			false,
+			"the fatal overlay must not mount",
+		);
+		assert.deepEqual(fatalsSeen, [], "no fatal error must be raised");
+		assert.equal(bannerAlerts().length, 1, "exactly one banner");
+	});
+
+	it("a per-message undo failure banners once and never mounts the fatal overlay — undo direction", async () => {
+		const fatalsSeen: string[] = [];
+		subscribeFatalError((fatal) => fatalsSeen.push(fatal.message));
+		http = mockFetch(() => ({ failureCount: 1 }));
+		const hook = mountHook(() => useReportSpam({ mailboxId: "mbx-junk" }));
+
+		hook().notSpam(["msg-1"]);
+		await waitFor(() => bannerAlerts().length > 0);
+
+		assert.equal(
+			fatalOverlay() !== null,
+			false,
+			"the fatal overlay must not mount",
+		);
+		assert.deepEqual(fatalsSeen, [], "no fatal error must be raised");
+		assert.equal(bannerAlerts().length, 1, "exactly one banner");
+	});
+
+	it("a genuine 500 from the same endpoint still escalates — meta.softError must not swallow the 5xx class", async () => {
+		http = mockFetch(() => httpError(500, "spam service is down"));
+		const hook = mountHook(() => useReportSpam({ mailboxId: "mbx-inbox" }));
+
+		hook().reportSpam(["msg-1"]);
+		await waitFor(() => fatalOverlay() !== null);
+
+		assert.ok(fatalOverlay(), "a 5xx must still reach the fatal overlay");
+	});
+});

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 };
+};

package/src/test-support/dom.ts

@@ -46,6 +46,14 @@ export interface DomOptions {
 	/** Screen posture `matchMedia` answers against — jsdom has no device. */
 	orientation?: "portrait" | "landscape";
 	pointer?: "coarse" | "fine";
+	/**
+	 * Use this `QueryClient` instead of the harness's default retry-disabled
+	 * one — e.g. one wired with the real `QueryCache`/`MutationCache` error
+	 * handlers from `lib/query-error-handler.ts`, the way `shell/index.tsx`
+	 * builds it, so a test can exercise the real global escalation path
+	 * instead of just the per-mutation `onError`.
+	 */
+	queryClient?: QueryClient;
 }
 
 export const createDomHarness = (options: DomOptions = {}): DomHarness => {
@@ -64,12 +72,14 @@ export const createDomHarness = (options: DomOptions = {}): DomHarness => {
 	let root: Root | undefined = createRoot(container);
 	// No retries: a test asserting a failure should not have to wait out a
 	// backoff before it can see one.
-	const queryClient = new QueryClient({
-		defaultOptions: {
-			queries: { retry: false },
-			mutations: { retry: false },
-		},
-	});
+	const queryClient =
+		options.queryClient ??
+		new QueryClient({
+			defaultOptions: {
+				queries: { retry: false },
+				mutations: { retry: false },
+			},
+		});
 
 	const requireRoot = (): Root => {
 		if (!root) throw new Error("harness already unmounted");

package/src/hooks/useReportSpam.integration.test.ts

@@ -1,93 +0,0 @@
-/**
- * Integration: prove a per-message report-spam/not-spam failure resolves to a
- * banner, never the full-screen fatal overlay, through the REAL global
- * `MutationCache` wiring (`lib/query-error-handler.ts`, wired on the
- * `QueryClient` in `shell/index.tsx`) — not just `ErrorBannerProvider`'s own
- * `isAlwaysFatal` check.
- *
- * That distinction is the whole point of this file. `ErrorBannerProvider.
- * pushError` refuses to banner an always-fatal error, but every mutation
- * ALSO reports to the MutationCache's global `onError`, independent of
- * whatever the per-mutation `onError` did — and `shouldEscalate` (what the
- * global handler calls) escalates by DEFAULT for any non-5xx that didn't opt
- * out via `meta.softError`. A test that only checked `isAlwaysFatal` passed
- * while the real app crashed to the fatal overlay on the same error: this is
- * exactly `query-escalation.integration.test.ts`'s pattern, applied to
- * `useReportSpam`'s own mutation shape (mutationFn + meta), because that is
- * the seam the earlier fix went through unexercised.
- */
-
-import assert from "node:assert/strict";
-import { afterEach, describe, it } from "node:test";
-import { MutationCache, QueryCache, QueryClient } from "@tanstack/react-query";
-import { __resetFatalError, subscribeFatalError } from "../lib/fatal-error";
-import {
-	handleMutationCacheError,
-	handleQueryCacheError,
-} from "../lib/query-error-handler";
-import { throwOnBulkFailure } from "./useReportSpam.js";
-
-afterEach(() => {
-	__resetFatalError();
-});
-
-const makeClient = () =>
-	new QueryClient({
-		queryCache: new QueryCache({ onError: handleQueryCacheError }),
-		mutationCache: new MutationCache({ onError: handleMutationCacheError }),
-		defaultOptions: { mutations: { retry: false } },
-	});
-
-/** The exact shape a failed report-spam/not-spam call resolves to on the wire (200, not a rejection) — see `throwOnBulkFailure`. */
-const failedBulkResult = () => ({
-	successCount: 0,
-	failureCount: 1,
-	failures: [
-		{
-			messageId: "9m2k7x4vqz1jd0tn3wf8b6y5c",
-			reason:
-				"Message 9m2k7x4vqz1jd0tn3wf8b6y5c's move to Junk has not settled yet; try again in a moment.",
-		},
-	],
-});
-
-describe("useReportSpam's mutations under the real MutationCache (#648 review)", () => {
-	it("with meta.softError, a per-message failure does NOT escalate to the fatal overlay (regression)", async () => {
-		const seen: string[] = [];
-		subscribeFatalError((fatal) => seen.push(fatal.message));
-		const client = makeClient();
-
-		const mutation = client.getMutationCache().build(client, {
-			mutationFn: async () => {
-				throwOnBulkFailure(failedBulkResult());
-			},
-			meta: { softError: true },
-		});
-		await mutation.execute(undefined).catch(() => {});
-
-		assert.deepEqual(
-			seen,
-			[],
-			"a designed, retryable per-message failure must not reach the fatal overlay",
-		);
-	});
-
-	it("without meta.softError, the same failure DOES escalate — proving the opt-out is load-bearing, not a no-op", async () => {
-		const seen: string[] = [];
-		subscribeFatalError((fatal) => seen.push(fatal.message));
-		const client = makeClient();
-
-		const mutation = client.getMutationCache().build(client, {
-			mutationFn: async () => {
-				throwOnBulkFailure(failedBulkResult());
-			},
-		});
-		await mutation.execute(undefined).catch(() => {});
-
-		assert.equal(
-			seen.length,
-			1,
-			"this asserts the failure mode the fix removes — a non-5xx with no softError opt-out escalates by default",
-		);
-	});
-});