@remit/web-client 0.0.172 → 0.0.174

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/web-client",
-  "version": "0.0.172",
+  "version": "0.0.174",
   "type": "module",
   "description": "Remit web client, published as composable primitives — the app shell, auth shells, and runtime config. A distributor imports what it composes and bundles it.",
   "exports": {

package/src/components/compose/ComposeForm.tsx

@@ -40,6 +40,7 @@ import {
 import { useMessageBodyContent } from "../../hooks/useMessageBodyContent";
 import { useSaveDraft } from "../../hooks/useSaveDraft";
 import { useSignature } from "../../hooks/useSignature.js";
+import { softErrorMeta } from "../../lib/error-classifier";
 import { accountIsMissingSmtp } from "../settings/account-form-helpers.js";
 import { useErrorBanners } from "../ui/ErrorBannerProvider.js";
 import {
@@ -212,6 +213,17 @@ type SendReadiness =
 	| { status: "blocked"; reason: string }
 	| { status: "ready"; accountId: string };
 
+/**
+ * Naming To, not "a recipient". Sending goes through the draft, and a draft is
+ * created against `CreateOutboxMessageInput`, whose `@minItems(1)` is on
+ * `toAddresses` alone — so a message addressed only in Cc has a recipient and
+ * still cannot be sent from here, and being told to add one it can already see
+ * leaves it with nothing to do. The server's own send guard counts Cc and Bcc,
+ * because a Bcc-only envelope is real mail; it is answering whether the message
+ * has anywhere to go, which is not the question this one asks.
+ */
+const NO_TO_ADDRESS_MESSAGE = "Add a To address before sending.";
+
 const isFormEmpty = (
 	toAddresses: AddressEntry[],
 	ccAddresses: AddressEntry[],
@@ -536,7 +548,7 @@ export const ComposeForm = ({
 		[onDraftCreated],
 	);
 
-	const { saveStatus, saveError, saveDraft, saveImmediately, stopAutoSave } =
+	const { saveState, saveError, saveDraft, saveImmediately, stopAutoSave } =
 		useSaveDraft({
 			outboxMessageId,
 			onDraftCreated: adoptCreatedDraft,
@@ -555,12 +567,17 @@ export const ComposeForm = ({
 		});
 	}, [saveError, pushError]);
 
-	const sendMutation = useMutation(
-		outboxDetailOperationsSendOutboxMessageMutation(),
-	);
+	// A refused send is reported below, next to the message it did not send, and
+	// the composer stays up so the user can fix the address and press it again.
+	// A 5xx still escalates.
+	const sendMutation = useMutation({
+		...outboxDetailOperationsSendOutboxMessageMutation(),
+		meta: softErrorMeta,
+	});
 
 	const deleteMutation = useMutation({
 		...outboxDetailOperationsDeleteOutboxMessageMutation(),
+		meta: softErrorMeta,
 		onError: (error) => {
 			// Discard closes the dialog optimistically. A soft 4xx (409/404 the
 			// draft is already gone) must not pass silently as success — surface a
@@ -621,7 +638,7 @@ export const ComposeForm = ({
 			return { status: "blocked", reason: SMTP_MISSING_MESSAGE };
 		}
 		if (toAddresses.length === 0) {
-			return { status: "blocked", reason: "Add at least one recipient." };
+			return { status: "blocked", reason: NO_TO_ADDRESS_MESSAGE };
 		}
 		return { status: "ready", accountId: selectedAccountId };
 	}, [
@@ -864,7 +881,7 @@ export const ComposeForm = ({
 					onSend={attemptSend}
 					onBlocked={reportBlocked}
 					onDiscard={handleDiscard}
-					saveStatus={saveStatus}
+					save={saveState}
 				/>
 			}
 		>

package/src/components/compose/forward-autosave-is-not-fatal.render.test.ts

@@ -0,0 +1,357 @@
+/**
+ * Forward opens with a subject and a quote and deliberately no recipient. The
+ * autosave gate only skips a form that is blank everywhere, so the seeded
+ * subject used to fire a create — and a create carries `@minItems(1)` on
+ * `toAddresses`, so the server refused it 400. That refusal then went to the
+ * full-screen fatal page, which unmounts the composer and takes the message
+ * with it: the one failure mode a composer must never have.
+ *
+ * Both halves are held here. The invalid request is not made at all while the
+ * draft has no recipient to create it with — and the composer says so, because
+ * a message being held unsaved in silence is the same loss with the noise taken
+ * out. A write that does fail lands in a banner beside the message rather than
+ * over it. A 5xx and a 401 keep their own rules.
+ */
+
+import assert from "node:assert/strict";
+import { afterEach, describe, it } from "node:test";
+import type {
+	RemitImapAccountResponse,
+	RemitImapDescribeMessageResponse,
+} from "@remit/api-http-client/types.gen.ts";
+import { MutationCache, QueryCache, QueryClient } from "@tanstack/react-query";
+import {
+	type AnyRouter,
+	createMemoryHistory,
+	createRootRoute,
+	createRoute,
+	createRouter,
+	RouterContextProvider,
+} from "@tanstack/react-router";
+import { createElement, Fragment, useState } from "react";
+import { __resetFatalError } 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 { FatalErrorOverlay } from "../ui/FatalErrorOverlay";
+import { ComposeForm } from "./ComposeForm";
+import { ComposeProvider } from "./ComposeProvider";
+
+const ACCOUNT_ID = "acc-1";
+const OUTBOX_MESSAGE_ID = "ob-fwd";
+const AUTOSAVE_DEBOUNCE_MS = 2000;
+
+const account = {
+	accountId: ACCOUNT_ID,
+	email: "me@example.com",
+	smtpEnabled: true,
+} as unknown as RemitImapAccountResponse;
+
+const sourceMessage = {
+	message: { messageId: "msg-1" },
+	envelope: {
+		subject: "Lunch",
+		messageIdValue: "<m1@example.com>",
+		from: [{ normalizedEmail: "them@example.com", displayName: "Them" }],
+		replyTo: [],
+		to: [],
+		cc: [],
+	},
+	references: [],
+	bodyParts: [],
+} as unknown as RemitImapDescribeMessageResponse;
+
+const outboxEntry = () => ({
+	outboxMessageId: OUTBOX_MESSAGE_ID,
+	accountId: ACCOUNT_ID,
+	fromAddress: account.email,
+	toAddresses: ["them@example.com"],
+	ccAddresses: [],
+	bccAddresses: [],
+	references: [],
+	subject: "Fwd: Lunch",
+	textBody: "here you go",
+	status: "draft",
+});
+
+let harness: DomHarness | undefined;
+let http: HttpMock | undefined;
+
+afterEach(() => {
+	harness?.close();
+	harness = undefined;
+	http?.restore();
+	http = undefined;
+	__resetFatalError();
+});
+
+const creates = () =>
+	(http?.calls ?? []).filter(
+		(call) => call.method === "POST" && call.path.endsWith("/outbox"),
+	);
+
+const patches = () =>
+	(http?.calls ?? []).filter((call) => call.method === "PATCH");
+
+const sends = () =>
+	(http?.calls ?? []).filter((call) => call.path.endsWith("/send"));
+
+const fatalOverlay = () =>
+	harness?.query('[data-testid="fatal-error-overlay"]') ?? null;
+
+const bannerAlerts = () =>
+	harness?.queryAll('[aria-label="Notifications"] [role="alert"]') ?? [];
+
+// The draft the composer is on is its owner's to hand it — here, the test's.
+const Opened = ({ outboxMessageId }: { outboxMessageId?: string }) => {
+	const [draftId, setDraftId] = useState(outboxMessageId);
+
+	return createElement(ComposeForm, {
+		mode: "forward",
+		account,
+		sourceMessage,
+		outboxMessageId: draftId,
+		onDraftCreated: setDraftId,
+		onClose: () => {},
+	});
+};
+
+(globalThis as { self?: typeof globalThis }).self ??= globalThis;
+
+const rootRoute = createRootRoute();
+const mailboxRoute = createRoute({
+	getParentRoute: () => rootRoute,
+	path: "/mail/$mailboxId",
+	validateSearch: (search: Record<string, unknown>) => search,
+});
+
+const testRouter = (): AnyRouter =>
+	createRouter({
+		routeTree: rootRoute.addChildren([mailboxRoute]),
+		history: createMemoryHistory({ initialEntries: ["/mail/mbx-1"] }),
+	}) as unknown as AnyRouter;
+
+interface MountOptions {
+	/** The draft compose opens on, when the user is resuming one. */
+	outboxMessageId?: string;
+	/** The status every PATCH answers with, when it is to fail. */
+	patchStatus?: number;
+}
+
+/**
+ * The stub holds the constraint the API holds: a create with no recipient is
+ * refused, in the words the backend's schema validation uses.
+ */
+const mount = async (options: MountOptions = {}): Promise<void> => {
+	http = mockFetch(async (call) => {
+		if (call.path.endsWith("/config")) return { accounts: [account] };
+
+		if (call.method === "POST" && call.path.endsWith("/outbox")) {
+			const to = call.body?.toAddresses;
+			if (!Array.isArray(to) || to.length === 0) {
+				return httpError(
+					400,
+					"body/requestBody/toAddresses must NOT have fewer than 1 items",
+				);
+			}
+			return outboxEntry();
+		}
+
+		if (call.method === "PATCH") {
+			if (options.patchStatus) {
+				return httpError(options.patchStatus, "the draft moved on");
+			}
+			return outboxEntry();
+		}
+
+		return outboxEntry();
+	});
+
+	const queryClient = new QueryClient({
+		queryCache: new QueryCache({ onError: handleQueryCacheError }),
+		mutationCache: new MutationCache({ onError: handleMutationCacheError }),
+		defaultOptions: {
+			queries: { retry: false },
+			mutations: { retry: false },
+		},
+	});
+
+	harness = createDomHarness({ queryClient });
+	harness.renderApp(
+		createElement(
+			Fragment,
+			null,
+			createElement(FatalErrorOverlay),
+			createElement(RouterContextProvider, {
+				router: testRouter(),
+				// biome-ignore lint/correctness/noChildrenProp: RouterContextProvider types `children` as a required prop, which createElement's rest-argument form does not satisfy
+				children: createElement(
+					ComposeProvider,
+					null,
+					createElement(Opened, { outboxMessageId: options.outboxMessageId }),
+				),
+			}),
+		),
+	);
+	await harness.flush();
+	await harness.wait(50);
+};
+
+const subjectField = (): HTMLInputElement => {
+	const field = harness?.query<HTMLInputElement>("[data-subject-field]");
+	if (!field) throw new Error("the compose subject field is not mounted");
+	return field;
+};
+
+const recipientField = (): HTMLInputElement => {
+	const field = harness?.query<HTMLInputElement>("#address-field-To");
+	if (!field) throw new Error("the compose recipient field is not mounted");
+	return field;
+};
+
+const addRecipient = async (email: string): Promise<void> => {
+	harness?.type(recipientField(), email);
+	harness?.dispatch(
+		recipientField(),
+		new (
+			harness.window as unknown as { KeyboardEvent: typeof KeyboardEvent }
+		).KeyboardEvent("keydown", { key: "Enter", bubbles: true }),
+	);
+	await harness?.flush();
+};
+
+describe("a forwarded message and the draft it cannot create yet", () => {
+	it("attempts no create while the forward has no recipient", async () => {
+		await mount();
+
+		assert.equal(
+			subjectField().value,
+			"Fwd: Lunch",
+			"the forward seeded its subject, so the form is not blank",
+		);
+
+		await harness?.wait(AUTOSAVE_DEBOUNCE_MS + 300);
+
+		assert.equal(creates().length, 0, "no create was attempted");
+		assert.equal(fatalOverlay(), null, "the composer stayed on screen");
+		assert.equal(bannerAlerts().length, 0, "nothing was raised as a failure");
+	});
+
+	it("says the draft is not being saved, and what would make it save", async () => {
+		await mount();
+
+		harness?.type(subjectField(), "Fwd: Lunch and the three paragraphs after");
+		await harness?.flush();
+
+		const indicator = harness?.byText("output", "Not saved");
+		assert.match(
+			indicator?.textContent ?? "",
+			/add a To address/i,
+			"the composer names the field the create schema actually requires",
+		);
+
+		await addRecipient("them@example.com");
+		await harness?.wait(AUTOSAVE_DEBOUNCE_MS + 300);
+
+		assert.equal(creates().length, 1, "the held content was written");
+		assert.equal(
+			creates()[0]?.body?.subject,
+			"Fwd: Lunch and the three paragraphs after",
+			"including everything typed while it was held",
+		);
+		assert.match(harness?.text() ?? "", /Draft saved/);
+	});
+
+	it("creates the draft, with everything the forward seeded, once a recipient is there", async () => {
+		await mount();
+		await harness?.wait(AUTOSAVE_DEBOUNCE_MS + 300);
+
+		await addRecipient("them@example.com");
+		await harness?.wait(AUTOSAVE_DEBOUNCE_MS + 300);
+
+		const created = creates();
+		assert.equal(created.length, 1, "the draft was created once");
+		assert.deepEqual(created[0]?.body?.toAddresses, ["them@example.com"]);
+		assert.equal(created[0]?.body?.subject, "Fwd: Lunch");
+		assert.equal(fatalOverlay(), null, "the composer stayed on screen");
+	});
+
+	it("refuses to send a forward that has no recipient, and says why", async () => {
+		await mount();
+
+		const send = harness?.byText("button", "Send");
+		if (!send) throw new Error("the send button is not mounted");
+		harness?.click(send);
+		await harness?.flush();
+		await harness?.wait(100);
+
+		assert.match(harness?.text() ?? "", /Add a To address before sending/);
+		assert.equal(creates().length, 0, "nothing was created");
+		assert.equal(sends().length, 0, "nothing was sent");
+	});
+
+	it("drops the held sentence the moment the To address arrives", async () => {
+		await mount();
+
+		harness?.type(subjectField(), "Fwd: Lunch and the three paragraphs after");
+		await harness?.flush();
+		assert.match(harness?.text() ?? "", /Not saved/);
+
+		await addRecipient("them@example.com");
+
+		// Before the debounce, not after it: the sentence stopped being true the
+		// moment the address landed, and standing for another two seconds tells
+		// the user their draft is being dropped when it is on its way.
+		assert.doesNotMatch(
+			harness?.text() ?? "",
+			/Not saved/,
+			"a reason that no longer holds is off screen at once",
+		);
+	});
+});
+
+describe("a failed autosave and the message it is holding", () => {
+	it("banners a refused write and leaves the composer and its text alone", async () => {
+		await mount({ outboxMessageId: OUTBOX_MESSAGE_ID, patchStatus: 409 });
+
+		harness?.type(subjectField(), "Fwd: Lunch on Thursday");
+		await harness?.wait(AUTOSAVE_DEBOUNCE_MS + 300);
+
+		assert.ok(patches().length > 0, "the write was attempted");
+		assert.equal(
+			fatalOverlay(),
+			null,
+			"a refused autosave must not take the composer down",
+		);
+		assert.match(harness?.text() ?? "", /Couldn't save draft/);
+		assert.equal(
+			subjectField().value,
+			"Fwd: Lunch on Thursday",
+			"what was written is still on screen",
+		);
+	});
+
+	it("escalates a 401 — a dismissible banner is no way back in", async () => {
+		await mount({ outboxMessageId: OUTBOX_MESSAGE_ID, patchStatus: 401 });
+
+		harness?.type(subjectField(), "Fwd: Lunch on Thursday");
+		await harness?.wait(AUTOSAVE_DEBOUNCE_MS + 300);
+
+		assert.ok(
+			fatalOverlay(),
+			"a signed-out session must reach the page that signs back in",
+		);
+	});
+
+	it("still escalates a 5xx from the same write", async () => {
+		await mount({ outboxMessageId: OUTBOX_MESSAGE_ID, patchStatus: 500 });
+
+		harness?.type(subjectField(), "Fwd: Lunch on Thursday");
+		await harness?.wait(AUTOSAVE_DEBOUNCE_MS + 300);
+
+		assert.ok(fatalOverlay(), "our API answering 'I'm broken' is never soft");
+	});
+});

package/src/components/ui/ErrorBanner.stories.tsx

@@ -6,10 +6,10 @@ import { ErrorBanner } from "./ErrorBanner";
  * message list, so it is opaque and it names its own severity out loud rather
  * than leaving colour to carry the meaning.
  *
- * A failure the user cannot act on still gets an action link, prefilled, so
- * reporting it is one click instead of a form they have to assemble. The
- * hrefs below stand in for the real report URL, which the app builds from
- * build-time constants Storybook has no `define` for.
+ * Every error banner carries a prefilled report link, so reporting a failure
+ * the user cannot act on is one click instead of a form they have to
+ * assemble. The hrefs below stand in for the real report URL, which the app
+ * builds from build-time constants Storybook has no `define` for.
  */
 const meta: Meta<typeof ErrorBanner> = {
 	title: "Components/ErrorBanner",
@@ -27,21 +27,38 @@ type Story = StoryObj<typeof ErrorBanner>;
 const REPORT_URL =
 	"https://github.com/remit-mail/reader/issues/new?title=Spellcheck+stopped";
 
-/** A mutation that failed, with the reason underneath. */
+/** A mutation that failed, with the reason underneath and a way out. */
 export const Failed: Story = {
 	name: "Error",
 	args: {
 		severity: "error",
 		title: "Couldn't move message",
 		detail: "Connection reset by peer",
+		action: { label: "Report an issue", href: REPORT_URL },
 	},
 };
 
-/** Nothing more to say than the title. */
+/** Nothing more to say than the title — the report link still stands. */
 export const NoDetail: Story = {
 	args: {
 		severity: "error",
 		title: "Couldn't move message",
+		action: { label: "Report an issue", href: REPORT_URL },
+	},
+};
+
+/**
+ * Report spam failing because the account has nowhere to file it. The reason
+ * names the folder and the fix, so this one is actionable without the report
+ * link — which is offered anyway, because the user should not have to decide.
+ */
+export const NoJunkFolder: Story = {
+	args: {
+		severity: "error",
+		title: "Couldn't report this message as spam",
+		detail:
+			"This account has no Junk folder. Create one named Junk or Spam in your mail provider, then report this message again.",
+		action: { label: "Report an issue", href: REPORT_URL },
 	},
 };
 

package/src/components/ui/ErrorBannerProvider.tsx

@@ -6,6 +6,7 @@ import {
 	useMemo,
 	useState,
 } from "react";
+import { buildBugReportContext, buildGitHubIssueUrl } from "@/lib/bug-report";
 import { isAlwaysFatal } from "@/lib/error-classifier";
 import { reportFatalError } from "@/lib/fatal-error";
 import { ErrorBannerStack } from "./ErrorBannerStack.js";
@@ -13,6 +14,7 @@ import {
 	appendBanner,
 	buildEntry,
 	dismissBanner,
+	type ErrorBannerAction,
 	type ErrorBannerEntry,
 	type PushErrorInput,
 } from "./error-banners.js";
@@ -28,6 +30,37 @@ const ErrorBannerContext = createContext<ErrorBannerContextValue | undefined>(
 	undefined,
 );
 
+/**
+ * A way out of every failure banner. A soft failure is still a failure the
+ * user could not prevent and cannot diagnose, and a banner offering only
+ * "Dismiss" is a dead end — the fatal screen has carried a prefilled report
+ * since issue #55 and the soft surface never did. The report is seeded from
+ * the banner it belongs to, so it names the failure instead of asking the
+ * user to describe it, and it carries the same breadcrumbs — failing request,
+ * navigation, console — the fatal report does.
+ *
+ * A caller that already has a better way out keeps it, and a warning or an
+ * informational banner gets none: those are not failures to report.
+ */
+export const bannerWayOut = (
+	input: PushErrorInput,
+): ErrorBannerAction | undefined => {
+	if (input.action) return input.action;
+	if ((input.severity ?? "error") !== "error") return undefined;
+	return {
+		label: "Report an issue",
+		href: buildGitHubIssueUrl(
+			buildBugReportContext({
+				title: `Bug: ${input.title}`,
+				errorMessage: input.detail
+					? `${input.title} — ${input.detail}`
+					: input.title,
+				stack: input.error instanceof Error ? input.error.stack : undefined,
+			}),
+		),
+	};
+};
+
 const generateId = (): string => {
 	if (
 		typeof globalThis.crypto !== "undefined" &&
@@ -58,7 +91,11 @@ export const ErrorBannerProvider = ({ children }: { children: ReactNode }) => {
 		if (input.error != null && isAlwaysFatal(input.error)) {
 			return reportFatalError(input.error).correlationId;
 		}
-		const entry = buildEntry(input, generateId(), Date.now());
+		const entry = buildEntry(
+			{ ...input, action: bannerWayOut(input) },
+			generateId(),
+			Date.now(),
+		);
 		setErrors((current) => appendBanner(current, entry));
 		return entry.id;
 	}, []);

package/src/components/ui/banner-way-out.test.ts

@@ -0,0 +1,71 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { ApiError } from "@/lib/api";
+import { bannerWayOut } from "./ErrorBannerProvider";
+
+const issueBody = (href: string): string =>
+	new URL(href).searchParams.get("body") ?? "";
+
+const issueTitle = (href: string): string =>
+	new URL(href).searchParams.get("title") ?? "";
+
+describe("bannerWayOut — no failure banner is a dead end", () => {
+	it("offers a prefilled report on a failure the user cannot act on", () => {
+		// The spam report that failed on test.remit.email offered nothing but
+		// Dismiss: no reason, no fix, no way to report it.
+		const action = bannerWayOut({
+			title: "Couldn't report this message as spam",
+			detail: "This message could not be processed.",
+			error: new ApiError("This message could not be processed.", 422),
+		});
+
+		assert.equal(action?.label, "Report an issue");
+		assert.ok(
+			action?.href.startsWith(
+				"https://github.com/remit-mail/reader/issues/new?",
+			),
+		);
+		assert.match(
+			issueTitle(action.href),
+			/Couldn't report this message as spam/,
+		);
+		assert.match(
+			issueBody(action.href),
+			/Couldn't report this message as spam/,
+		);
+	});
+
+	it("carries the stack of the error that caused the banner", () => {
+		const error = new Error("Connection reset by peer");
+		const action = bannerWayOut({
+			title: "Couldn't move this message",
+			error,
+		});
+
+		assert.ok(action !== undefined);
+		assert.match(issueBody(action.href), /Stacktrace/);
+	});
+
+	it("keeps an action the call site already chose", () => {
+		const action = bannerWayOut({
+			title: "Spellcheck stopped",
+			action: { label: "Report this", href: "https://example.invalid/report" },
+		});
+
+		assert.deepEqual(action, {
+			label: "Report this",
+			href: "https://example.invalid/report",
+		});
+	});
+
+	it("offers none on a warning or a statement of fact", () => {
+		assert.equal(
+			bannerWayOut({ severity: "warning", title: "Draft saved locally" }),
+			undefined,
+		);
+		assert.equal(
+			bannerWayOut({ severity: "info", title: "Sync finished" }),
+			undefined,
+		);
+	});
+});

package/src/hooks/signed-out-poll-is-not-fatal.render.test.ts

@@ -0,0 +1,126 @@
+/**
+ * A 401 escalates over `meta.softError` only when someone is waiting on the
+ * answer. The self-update poll is the case that made that seam necessary: it is
+ * mounted at the app root and answers 401 by design for anyone whose session has
+ * lapsed, so escalating it put the full-screen fatal page over every screen in
+ * the app at load — including the sign-in the shell was already about to ask
+ * for.
+ *
+ * Held with the real caches wired to `lib/query-error-handler.ts`, because the
+ * seam is in what those two handlers pass and a classifier unit test cannot see
+ * a caller that never passed anything.
+ */
+
+import assert from "node:assert/strict";
+import { afterEach, describe, it } from "node:test";
+import {
+	MutationCache,
+	QueryCache,
+	QueryClient,
+	useMutation,
+} from "@tanstack/react-query";
+import { createElement, Fragment, useEffect } from "react";
+import { FatalErrorOverlay } from "../components/ui/FatalErrorOverlay";
+import { ApiError } from "../lib/api";
+import { softErrorMeta } from "../lib/error-classifier";
+import { __resetFatalError } 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 { SelfUpdateProvider } from "./use-system-update";
+
+let harness: DomHarness | undefined;
+let http: HttpMock | undefined;
+
+afterEach(() => {
+	harness?.close();
+	harness = undefined;
+	http?.restore();
+	http = undefined;
+	__resetFatalError();
+});
+
+const escalatingClient = (): QueryClient =>
+	new QueryClient({
+		queryCache: new QueryCache({ onError: handleQueryCacheError }),
+		mutationCache: new MutationCache({ onError: handleMutationCacheError }),
+		defaultOptions: {
+			queries: { retry: false },
+			mutations: { retry: false },
+		},
+	});
+
+const fatalOverlay = () =>
+	harness?.query('[data-testid="fatal-error-overlay"]') ?? null;
+
+/** A write nobody pressed a button for, refused for want of a session. */
+const SoftWrite = () => {
+	const mutation = useMutation({
+		mutationFn: async (): Promise<void> => {
+			throw new ApiError("signed out", 401);
+		},
+		meta: softErrorMeta,
+	});
+	const { mutate } = mutation;
+	useEffect(() => {
+		mutate();
+	}, [mutate]);
+	return null;
+};
+
+describe("a 401 and who was waiting on it", () => {
+	it("leaves the app standing when the root update poll is signed out", async () => {
+		http = mockFetch((call) => {
+			if (call.path.endsWith("/system/update")) {
+				return httpError(401, "session expired");
+			}
+			return {};
+		});
+
+		harness = createDomHarness({ queryClient: escalatingClient() });
+		harness.renderApp(
+			createElement(
+				Fragment,
+				null,
+				createElement(FatalErrorOverlay),
+				createElement(SelfUpdateProvider, null),
+			),
+		);
+		await harness.flush();
+		await harness.wait(50);
+		await harness.flush();
+
+		assert.ok(
+			http.to("/system/update").length > 0,
+			"the poll was made, so the 401 really was classified",
+		);
+		assert.equal(
+			fatalOverlay(),
+			null,
+			"a background poll's 401 must not take the whole app down",
+		);
+	});
+
+	it("still escalates a soft write's 401 — no banner signs anyone back in", async () => {
+		harness = createDomHarness({ queryClient: escalatingClient() });
+		harness.renderApp(
+			createElement(
+				Fragment,
+				null,
+				createElement(FatalErrorOverlay),
+				createElement(SoftWrite),
+			),
+		);
+		await harness.flush();
+		await harness.wait(50);
+		await harness.flush();
+
+		assert.ok(
+			fatalOverlay(),
+			"a signed-out session must reach the page that signs back in",
+		);
+	});
+});

package/src/hooks/useMarkAsRead.ts

@@ -9,6 +9,7 @@ import { useCallback, useEffect, useMemo, useRef } from "react";
 import { useErrorBanners } from "@/components/ui/ErrorBannerProvider";
 import { formatErrorDetail } from "@/components/ui/error-banners";
 import { runChunkedMutation } from "@/lib/bulk-actions";
+import { softErrorMeta } from "@/lib/error-classifier";
 import {
 	cancelThreadListQueries,
 	invalidateThreadListQueries,
@@ -138,8 +139,12 @@ export const useMarkAsRead = ({
 	const markedAsReadRef = useRef<Set<string>>(new Set());
 	const pendingRef = useRef<Set<string>>(new Set());
 
+	// Nobody asked for this write and nobody is waiting on it — it fires after a
+	// dwell on an open message. The rollback and the banner below are the whole
+	// of its failure, so a refusal must not take the screen down with it.
 	const { mutate: markAsRead } = useMutation({
 		...messageBulkOperationsUpdateFlagsMutation(),
+		meta: softErrorMeta,
 		onMutate: async (variables): Promise<MarkAsReadContext> => {
 			const messageIds = new Set(variables.body.messageIds ?? []);
 			const isRead = variables.body.isRead ?? true;

package/src/hooks/useRefreshControl.ts

@@ -32,8 +32,13 @@ const messageFor = (error: unknown): string =>
 		? error.message
 		: "Something went wrong";
 
+// The user pulled to refresh and is watching the spinner, so this is theirs to
+// be answered: a 401 here escalates over the soft meta rather than resolving
+// into a spinner that stops for no stated reason.
 const escalateIfFatal = (error: unknown): void => {
-	if (shouldEscalate(error, { softError: true })) reportFatalError(error);
+	if (shouldEscalate(error, { softError: true }, "user")) {
+		reportFatalError(error);
+	}
 };
 
 const maxLastSynced = (

package/src/hooks/useReportSpam.ts

@@ -51,7 +51,7 @@ interface UseReportSpamOptions {
  * despite a non-zero `failureCount`.
  */
 export const GENERIC_SPAM_ACTION_FAILURE =
-	"This message could not be processed. Please try again.";
+	"This message could not be processed. Please try again. If it keeps failing, report it.";
 
 /**
  * The server's designed failure text names the message by embedding its raw

package/src/hooks/useSaveDraft.ts

@@ -3,10 +3,10 @@ import {
 	outboxOperationsCreateOutboxMessageMutation,
 	outboxOperationsListOutboxMessagesOptions,
 } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import type { ComposeSaveState } from "@remit/ui";
 import { useMutation, useQueryClient } from "@tanstack/react-query";
 import { useCallback, useRef, useState } from "react";
-
-export type SaveStatus = "idle" | "saving" | "saved" | "error";
+import { softErrorMeta } from "../lib/error-classifier";
 
 export type ImmediateSave =
 	| { outcome: "saved"; outboxMessageId: string }
@@ -29,6 +29,44 @@ interface UseSaveDraftOptions {
 	onDraftCreated: (id: string) => void;
 }
 
+/**
+ * A draft with no To address yet has nothing the create endpoint will accept —
+ * `CreateOutboxMessageInput.toAddresses` carries `@minItems(1)`, so the request
+ * comes back 400. Cc and Bcc do not stand in for it; the constraint names
+ * `toAddresses` and nothing else. Forward opens in exactly that state, with a
+ * subject and a quote and no address, and it is a normal place to be while
+ * writing rather than a failure to report. The update endpoint has no such
+ * constraint, so only a draft that does not exist yet is held back.
+ *
+ * The send guard in `outbox-queue.ts` counts Cc and Bcc, and is right to: a
+ * Bcc-only envelope is real mail. It answers a different question — whether
+ * this message has anywhere to go — from this one, which is only whether the
+ * create schema will take it.
+ */
+const nothingToCreateYet = (
+	targetId: string | undefined,
+	data: DraftData,
+): boolean => targetId === undefined && data.toAddresses.length === 0;
+
+/**
+ * Held back, and naming what is actually missing. "A recipient" was a lie to
+ * anyone who had filled in Cc: they had one, and were being told to add what
+ * they could see on screen.
+ *
+ * Module scope, not a literal built in the render: this is set from inside the
+ * autosave effect, and a fresh object each time would be a new state on every
+ * render with the effect re-running on each of them.
+ */
+const NOT_SAVED_WITHOUT_A_TO_ADDRESS: ComposeSaveState = {
+	status: "unsaved",
+	reason: "Not saved — add a To address to keep this draft.",
+};
+
+const IDLE: ComposeSaveState = { status: "idle" };
+const SAVING: ComposeSaveState = { status: "saving" };
+const SAVED: ComposeSaveState = { status: "saved" };
+const SAVE_FAILED: ComposeSaveState = { status: "error" };
+
 const settled = (promise: Promise<unknown>): Promise<void> =>
 	promise.then(
 		() => undefined,
@@ -39,7 +77,7 @@ export const useSaveDraft = ({
 	outboxMessageId,
 	onDraftCreated,
 }: UseSaveDraftOptions) => {
-	const [saveStatus, setSaveStatus] = useState<SaveStatus>("idle");
+	const [saveState, setSaveState] = useState<ComposeSaveState>(IDLE);
 	const [saveError, setSaveError] = useState<unknown>(null);
 	const timerRef = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
 	const closedIdsRef = useRef<Set<string>>(new Set());
@@ -67,16 +105,21 @@ export const useSaveDraft = ({
 		if (leavingADocument && timerRef.current) clearTimeout(timerRef.current);
 	}
 
-	const createMutation = useMutation(
-		outboxOperationsCreateOutboxMessageMutation(),
-	);
-	const updateMutation = useMutation(
-		outboxDetailOperationsUpdateOutboxMessageMutation(),
-	);
+	// A write that fails belongs in the composer's banner beside the message it
+	// could not save, never on the full-screen page that unmounts the composer
+	// and the message with it. A 5xx still escalates.
+	const createMutation = useMutation({
+		...outboxOperationsCreateOutboxMessageMutation(),
+		meta: softErrorMeta,
+	});
+	const updateMutation = useMutation({
+		...outboxDetailOperationsUpdateOutboxMessageMutation(),
+		meta: softErrorMeta,
+	});
 
 	const executeSave = useCallback(
 		async (data: DraftData) => {
-			setSaveStatus("saving");
+			setSaveState(SAVING);
 			setSaveError(null);
 
 			const targetId = targetIdRef.current;
@@ -94,7 +137,7 @@ export const useSaveDraft = ({
 						references: data.references,
 					},
 				});
-				setSaveStatus("saved");
+				setSaveState(SAVED);
 				return result;
 			}
 
@@ -106,13 +149,18 @@ export const useSaveDraft = ({
 			});
 			targetIdRef.current = result.outboxMessageId;
 			onDraftCreated(result.outboxMessageId);
-			setSaveStatus("saved");
+			setSaveState(SAVED);
 			queryClient.invalidateQueries({
 				queryKey: outboxOperationsListOutboxMessagesOptions().queryKey,
 			});
 			return result;
 		},
-		[createMutation, updateMutation, onDraftCreated, queryClient],
+		[
+			createMutation.mutateAsync,
+			updateMutation.mutateAsync,
+			onDraftCreated,
+			queryClient,
+		],
 	);
 
 	// One entry takes one write at a time. Overlapping writes settle in whatever
@@ -131,6 +179,20 @@ export const useSaveDraft = ({
 	const saveDraft = useCallback(
 		(data: DraftData) => {
 			if (timerRef.current) clearTimeout(timerRef.current);
+			// Said now rather than two seconds from now: the composer is holding
+			// text nothing is going to persist, and the moment it starts holding it
+			// is the moment the user has to be able to see that.
+			if (nothingToCreateYet(targetIdRef.current, data)) {
+				setSaveState(NOT_SAVED_WITHOUT_A_TO_ADDRESS);
+				return;
+			}
+			// The sentence goes the moment its reason does, rather than standing
+			// for the two seconds until the write it is no longer true about
+			// lands. Only that sentence is cleared: a "Draft saved" from the
+			// previous write is still the truth about this document.
+			setSaveState((current) =>
+				current.status === "unsaved" ? IDLE : current,
+			);
 			timerRef.current = setTimeout(() => {
 				const targetId = targetIdRef.current;
 				if (targetId && closedIdsRef.current.has(targetId)) return;
@@ -139,7 +201,7 @@ export const useSaveDraft = ({
 				// through the global MutationCache.onError sink.
 				enqueueSave(data).catch((error: unknown) => {
 					setSaveError(error);
-					setSaveStatus("error");
+					setSaveState(SAVE_FAILED);
 				});
 			}, 2000);
 		},
@@ -161,7 +223,7 @@ export const useSaveDraft = ({
 					}),
 				)
 				.catch((error: unknown): ImmediateSave => {
-					setSaveStatus("error");
+					setSaveState(SAVE_FAILED);
 					return { outcome: "failed", error };
 				});
 		},
@@ -178,5 +240,5 @@ export const useSaveDraft = ({
 		if (closedOutboxMessageId) closedIdsRef.current.add(closedOutboxMessageId);
 	}, []);
 
-	return { saveStatus, saveError, saveDraft, saveImmediately, stopAutoSave };
+	return { saveState, saveError, saveDraft, saveImmediately, stopAutoSave };
 };

package/src/hooks/useStaleAccountSync.test.ts

@@ -221,6 +221,21 @@ describe("handleBackgroundSyncFailure", () => {
 		assert.equal(escalated, false);
 	});
 
+	test("a 401 on the background probe does NOT escalate", () => {
+		silenceWarn();
+		let escalated = false;
+		subscribeFatalError(() => {
+			escalated = true;
+		});
+
+		// The probe fires on mount and nobody is waiting on it. Escalating its
+		// 401 would put the full-screen page up on load for a lapsed session,
+		// ahead of the sign-in the shell is already about to ask for.
+		handleBackgroundSyncFailure("a-1", new ApiError("signed out", 401));
+
+		assert.equal(escalated, false);
+	});
+
 	test("a network blip on the background probe does NOT escalate", () => {
 		silenceWarn();
 		let escalated = false;

package/src/hooks/useStaleAccountSync.ts

@@ -140,13 +140,17 @@ export const __peekStaleAccountSyncGuard = (): ReadonlySet<string> =>
  * per-account guard so a later remount can retry, then log and move on. But a
  * 5xx is OUR API broken, and per the contract (#1059) that always escalates to
  * the full-screen overlay — even from a background trigger.
+ *
+ * Nobody is waiting on this one. It fires on mount, so escalating its 401 would
+ * put the full-screen page up on load for anyone whose session had lapsed,
+ * ahead of the sign-in the shell is already about to ask for.
  */
 export const handleBackgroundSyncFailure = (
 	accountId: string,
 	error: unknown,
 ): void => {
 	triggeredAccountIds.delete(accountId);
-	if (shouldEscalate(error, { softError: true })) {
+	if (shouldEscalate(error, { softError: true }, "nobody")) {
 		reportFatalError(error);
 		return;
 	}

package/src/lib/app-info.ts

@@ -2,10 +2,18 @@
  * Build-time constants injected by vite.config.ts via `define`.
  * __APP_SHA__ is the full git SHA (or "dev" in local builds without git).
  * __APP_BUILD_TIME__ is an ISO timestamp.
+ *
+ * Read through `typeof` because not every host that renders this app's
+ * components applies the `define` — Storybook's test runner mounts them
+ * without it — and a bare reference is a ReferenceError at module scope that
+ * takes the importing story down with it. An unknown build is the same
+ * "dev" the git-less local build already resolves to.
  */
 
-export const APP_SHA: string = __APP_SHA__;
-export const APP_BUILD_TIME: string = __APP_BUILD_TIME__;
+export const APP_SHA: string =
+	typeof __APP_SHA__ === "undefined" ? "dev" : __APP_SHA__;
+export const APP_BUILD_TIME: string =
+	typeof __APP_BUILD_TIME__ === "undefined" ? "unknown" : __APP_BUILD_TIME__;
 
 /** First 7 characters of the SHA, matching git's default short form. */
 export const APP_SHORT_SHA: string = APP_SHA.slice(0, 7);

package/src/lib/error-classifier.test.ts

@@ -278,4 +278,50 @@ describe("shouldEscalate (the fail-fast decision table — #1059)", () => {
 		assert.equal(shouldEscalate(bug), true);
 		assert.equal(shouldEscalate(bug, { softError: true }), true);
 	});
+
+	it("escalates a 401 on a write EVEN when the call site marked it soft (rule 4 wins)", () => {
+		assert.equal(
+			shouldEscalate(
+				new ApiError("signed out", 401),
+				{ softError: true },
+				"user",
+			),
+			true,
+			"a dismissible banner leaves the user signed out with no way back in",
+		);
+	});
+
+	it("leaves a soft 401 soft when nobody is waiting on the answer", () => {
+		assert.equal(
+			shouldEscalate(
+				new ApiError("signed out", 401),
+				{ softError: true },
+				"nobody",
+			),
+			false,
+			"a background poll's 401 must not put the fatal page over the whole app",
+		);
+	});
+
+	it("defaults to nobody waiting, so an unstated call site keeps a soft 401 soft", () => {
+		assert.equal(
+			shouldEscalate(new ApiError("signed out", 401), { softError: true }),
+			false,
+		);
+	});
+
+	it("escalates a 401 on a read that never opted out", () => {
+		assert.equal(
+			shouldEscalate(new ApiError("signed out", 401), undefined, "nobody"),
+			true,
+			"a read with no softError escalates on the default, waiting or not",
+		);
+	});
+
+	it("leaves a soft 403 soft — the call site can state that refusal in place", () => {
+		assert.equal(
+			shouldEscalate(new ApiError("not yours", 403), { softError: true }),
+			false,
+		);
+	});
 });

package/src/lib/error-classifier.ts

@@ -101,6 +101,37 @@ export const isClientBug = (error: unknown): boolean =>
 export const isAlwaysFatal = (error: unknown): boolean =>
 	isServerError(error) || isClientBug(error);
 
+/**
+ * The session is gone. Not 403: a handler answers 403 for a resource belonging
+ * to another account config, which is a refusal a call site can state where it
+ * stands. A 401 is the user signed out from under whatever they were doing.
+ */
+export const isUnauthenticated = (error: unknown): boolean =>
+	getErrorStatus(error) === 401;
+
+/**
+ * Who is waiting on this request's answer. One decision turns on it, and only
+ * one: whether a 401 overrides the call site's own `meta.softError`.
+ *
+ * "user" — the user did something and the app owes them the outcome. Every
+ * mutation is this, the debounced autosave included: it carries text that is on
+ * screen, and if it is refused for want of a session then so is the send behind
+ * it. No banner a call site can render signs anyone back in, so this is the one
+ * 4xx a call site may not keep to itself.
+ *
+ * "nobody" — a poll, a prefetch, a best-effort background trigger, an inline
+ * sub-resource with an error surface of its own. A 401 there is not news the
+ * app may take the whole screen for, and `meta.softError` decides as usual.
+ *
+ * Reads are "nobody" as a class, which is not the same as saying no read
+ * matters: a read the screen is actually waiting on has no `meta.softError` on
+ * it, so rule 1 escalates it anyway. The only reads this spares are the ones
+ * that already declared they own their failures — the update poll mounted at
+ * the app root, the message body with its own inline banner. Escalating those
+ * put the full-screen page over every screen in the app.
+ */
+export type Awaiting = "user" | "nobody";
+
 const isSoftErrorMeta = (meta: Record<string, unknown> | undefined): boolean =>
 	meta?.softError === true;
 
@@ -115,7 +146,12 @@ const isSoftErrorMeta = (meta: Record<string, unknown> | undefined): boolean =>
  *     answered "I'm broken"; that is never benign.
  *  3. A client-side exception ALWAYS escalates, on the same terms. It is our
  *     bug; there is nothing for the user to retry and nothing to dismiss.
- *  4. The ONLY soft (do-NOT-escalate) exemptions:
+ *  4. A 401 on a request the user is waiting on ALWAYS escalates, on the same
+ *     terms. Dismissing it leaves them signed out with no way back in, and a
+ *     send that keeps failing becomes a loop with no exit — `BetterAuthShell`
+ *     re-gates only when `useSession()` revalidates, which a banner never makes
+ *     happen. See `Awaiting` for what nobody waiting on it means.
+ *  5. The ONLY soft (do-NOT-escalate) exemptions:
  *     a. aborts / cancellations — never a failure;
  *     b. network/offline errors — environmental, recovered by React Query's
  *        reconnect/retry;
@@ -126,11 +162,29 @@ const isSoftErrorMeta = (meta: Record<string, unknown> | undefined): boolean =>
 export const shouldEscalate = (
 	error: unknown,
 	meta?: Record<string, unknown>,
+	awaiting: Awaiting = "nobody",
 ): boolean => {
 	if (isServerError(error)) return true;
 	if (isAbortError(error)) return false;
 	if (isNetworkError(error)) return false;
+	if (awaiting === "user" && isUnauthenticated(error)) return true;
 	if (isAlwaysFatal(error)) return true;
 	if (isSoftErrorMeta(meta)) return false;
 	return true;
 };
+
+/**
+ * The meta a call site sets to keep its own non-5xx failures off the
+ * full-screen fatal page, because it renders them itself — a banner, a retry,
+ * an empty state. Rules 2, 3 and 4 above still win: a 5xx, a client-side
+ * exception, and a 401 on something the user is waiting on, escalate regardless.
+ *
+ * Two classes of call site must always carry it. One is a request the user
+ * never asked for and is not waiting on — a debounced autosave, a
+ * dwell-triggered mark-as-read: a refusal there is not news worth stopping the
+ * app for. The other is any surface holding text the user has not finished
+ * writing. The fatal page unmounts the app, so escalating from a composer
+ * throws the message away and leaves nothing to retry, which is a worse outcome
+ * than the failure it reports.
+ */
+export const softErrorMeta: { softError: true } = { softError: true };

package/src/lib/query-error-handler.ts

@@ -10,6 +10,13 @@ import { reportFatalError } from "./fatal-error";
  * statusless network blips, and non-5xx errors a call site opted out of via
  * `meta.softError` stay soft.
  *
+ * The two caches differ on one thing, the `Awaiting` argument. A mutation is
+ * something the user did and is owed the outcome of, so a 401 there escalates
+ * over `meta.softError` — no banner signs anyone back in. A query is "nobody" as
+ * a class: the reads the screen is actually waiting on carry no `meta.softError`
+ * and escalate on the default anyway, so the only ones this spares are those
+ * that already declared they own their failures.
+ *
  * This is the v5 equivalent of `defaultOptions.queries.onError` /
  * `.mutations.onError` — v5 moved the global error hook onto the caches.
  */
@@ -17,7 +24,7 @@ export const handleQueryCacheError = (
 	error: Error,
 	query: Query<unknown, unknown, unknown>,
 ): void => {
-	if (shouldEscalate(error, query.meta)) {
+	if (shouldEscalate(error, query.meta, "nobody")) {
 		reportFatalError(error);
 	}
 };
@@ -28,7 +35,7 @@ export const handleMutationCacheError = (
 	_onMutateResult: unknown,
 	mutation: Mutation<unknown, unknown, unknown>,
 ): void => {
-	if (shouldEscalate(error, mutation.meta)) {
+	if (shouldEscalate(error, mutation.meta, "user")) {
 		reportFatalError(error);
 	}
 };