@remit/web-client 0.0.173 → 0.0.175

package/src/components/mail/intelligence-drawer.stories.tsx

@@ -4,20 +4,20 @@ import { ChevronLeft, Info } from "lucide-react";
 import { useState } from "react";
 import { expect, userEvent, within } from "storybook/test";
 import { Drawer } from "@/components/layout/Drawer";
-import { resolveRailOpen } from "@/lib/intelligence-pref";
-import { parseOpenPanels, retainOpenPanelsAtTier } from "@/routing";
+import { useIntelligenceDrawer } from "@/hooks/useIntelligenceDrawer";
 
 /**
- * The intelligence drawer below the desktop tier (#777).
+ * The intelligence drawer below the desktop tier (#777, #778).
  *
  * There is no fourth pane here: the rail is a full-screen drawer over the open
- * message, so it belongs to the thread it was opened for. The address is the
- * only place its open state lives, and a navigation drops it — otherwise a DKIM
- * mismatch on one message leaves the drawer covering every message opened
- * after it.
+ * message, so it belongs to the thread it was opened for and to nothing else.
+ * It is modal, so it opens only when the reader asks — a DKIM mismatch shows
+ * the banner and leaves the message alone. A drawer that opened itself would
+ * put a scrim over the message, and the reader's next tap would land on the
+ * scrim rather than on Back.
  *
- * Both rules are the app's own: the fragment goes through
- * `retainOpenPanelsAtTier`, and what is up is `resolveRailOpen`.
+ * The rule is the app's own: `useIntelligenceDrawer` is the hook the phone and
+ * mid-width panes both run on.
  */
 const meta: Meta = {
 	title: "Flows/Reading/Intelligence Drawer",
@@ -30,8 +30,6 @@ type Story = StoryObj;
 const PHONE_WIDTH = 390;
 const PHONE_HEIGHT = 720;
 
-const retainOnPhone = retainOpenPanelsAtTier(false);
-
 const intelligence: IntelligenceData = {
 	sender: {
 		name: "Mondial Relay",
@@ -77,23 +75,14 @@ const messages: readonly Message[] = [
 ];
 
 /**
- * The phone reader, driven by the address alone: `hash` is the whole state,
- * and every navigation writes it through the same helper the panes use.
+ * The phone reader. What is open is the thread on screen and, beside it, the
+ * drawer the reader asked for — held by `useIntelligenceDrawer` against that
+ * thread, so opening another one takes the drawer down with it.
  */
-const PhoneReader = ({ initialHash = "" }: { initialHash?: string }) => {
-	const [hash, setHash] = useState(initialHash);
+const PhoneReader = () => {
 	const [openId, setOpenId] = useState<string | undefined>(messages[0]?.id);
 	const open = messages.find((message) => message.id === openId);
-	const drawerOpen = resolveRailOpen({
-		panels: parseOpenPanels(hash),
-		prefersOpen: true,
-		isDesktop: false,
-		hasThread: open !== undefined,
-	});
-	const navigate = (nextId: string | undefined) => {
-		setHash(retainOnPhone(hash));
-		setOpenId(nextId);
-	};
+	const drawer = useIntelligenceDrawer(open?.id ?? null);
 
 	return (
 		<div className="flex flex-col gap-2">
@@ -113,7 +102,7 @@ const PhoneReader = ({ initialHash = "" }: { initialHash?: string }) => {
 							<button
 								type="button"
 								aria-label="Back"
-								onClick={() => navigate(undefined)}
+								onClick={() => setOpenId(undefined)}
 								className="inline-flex size-11 items-center justify-center rounded-md text-fg hover:bg-surface-raised"
 							>
 								<ChevronLeft className="size-5" />
@@ -124,7 +113,7 @@ const PhoneReader = ({ initialHash = "" }: { initialHash?: string }) => {
 							<button
 								type="button"
 								aria-label="Message details"
-								onClick={() => setHash("intelligence")}
+								onClick={drawer.toggle}
 								className="inline-flex size-11 items-center justify-center rounded-md text-fg hover:bg-surface-raised"
 							>
 								<Info className="size-5" />
@@ -141,7 +130,7 @@ const PhoneReader = ({ initialHash = "" }: { initialHash?: string }) => {
 							<li key={message.id}>
 								<button
 									type="button"
-									onClick={() => navigate(message.id)}
+									onClick={() => setOpenId(message.id)}
 									className="flex w-full flex-col items-start gap-0.5 border-b border-line px-4 py-3 text-left hover:bg-surface-raised"
 								>
 									<span className="text-sm font-semibold text-fg">
@@ -156,8 +145,8 @@ const PhoneReader = ({ initialHash = "" }: { initialHash?: string }) => {
 					</ul>
 				)}
 				<Drawer
-					isOpen={drawerOpen}
-					onClose={() => setHash("")}
+					isOpen={drawer.isOpen}
+					onClose={drawer.close}
 					ariaLabel="Message details"
 					side="right"
 				>
@@ -165,34 +154,58 @@ const PhoneReader = ({ initialHash = "" }: { initialHash?: string }) => {
 				</Drawer>
 			</div>
 			<p className="font-mono text-2xs text-fg-subtle">
-				{`/mail/inbox${open ? `/${open.id}` : ""}${hash ? `#${hash}` : ""}`}
+				{`/mail/inbox${open ? `/${open.id}` : ""}`}
 			</p>
 		</div>
 	);
 };
 
-/** A message with no drawer over it: the address names no panel. */
-export const Closed: Story = {
-	render: () => <PhoneReader />,
+/** The reader's own press on the details control. */
+const openDetails = async (canvasElement: HTMLElement): Promise<void> => {
+	await userEvent.click(
+		within(canvasElement).getByLabelText("Message details"),
+	);
 };
 
 /**
- * The drawer over the message it was opened for — here by a DKIM mismatch,
- * which opens it without being asked.
+ * The warned message as it opens: the banner's own wording, and nothing over
+ * it. A mismatch is what the panel explains, never a reason to cover the
+ * message with it — a scrim there takes the reader's next tap, Back included.
  */
+export const Closed: Story = {
+	render: () => <PhoneReader />,
+	play: async ({ canvasElement }) => {
+		const canvas = within(canvasElement);
+		await expect(canvas.queryByRole("dialog")).toBeNull();
+		await expect(canvas.getByLabelText("Back")).toBeVisible();
+	},
+};
+
+/** The drawer over the message it was opened for. */
 export const OpenOverThread: Story = {
-	render: () => <PhoneReader initialHash="intelligence" />,
+	render: () => <PhoneReader />,
+	play: async ({ canvasElement }) => {
+		await openDetails(canvasElement);
+		await expect(within(canvasElement).getByRole("dialog")).toBeVisible();
+	},
 };
 
 /**
- * The same drawer, then Back and another message. The fragment is dropped on
- * the way out, so the second message is not covered by a panel opened for the
- * first. Press Back with the drawer up to walk it.
+ * Dismissed, and gone for the next message too: the drawer is held against the
+ * thread it was opened for, so nothing carries it forward.
  */
-export const DroppedByNavigation: Story = {
-	render: () => <PhoneReader initialHash="intelligence" />,
+export const DismissedAndNotCarried: Story = {
+	render: () => <PhoneReader />,
 	play: async ({ canvasElement }) => {
 		const canvas = within(canvasElement);
+		await openDetails(canvasElement);
+		await expect(canvas.getByRole("dialog")).toBeVisible();
+
+		// The scrim carries the same name as the header's close button and comes
+		// first in the drawer, so the visible control is the second of the two.
+		await userEvent.click(canvas.getAllByLabelText("Close menu")[1]);
+		await expect(canvas.queryByRole("dialog")).toBeNull();
+
 		await userEvent.click(canvas.getByLabelText("Back"));
 		await userEvent.click(canvas.getByText("Standup moved to 10:15"));
 		await expect(canvas.queryByRole("dialog")).toBeNull();
@@ -204,5 +217,8 @@ export const DroppedByNavigation: Story = {
 export const OpenOverThreadDark: Story = {
 	name: "Open Over Thread (dark)",
 	parameters: { theme: "dark" },
-	render: () => <PhoneReader initialHash="intelligence" />,
+	render: () => <PhoneReader />,
+	play: async ({ canvasElement }) => {
+		await openDetails(canvasElement);
+	},
 };

package/src/hooks/intelligence-drawer.render.test.ts

@@ -0,0 +1,99 @@
+/**
+ * The intelligence drawer is modal, so what matters as much as opening it is
+ * that nothing else can. It belongs to the thread it was opened for: leaving
+ * that thread puts it away, and coming back to the same message opens it clear
+ * rather than under the scrim it was last left with (#778).
+ *
+ * The reachable case is a phone's system Back, which is a navigation like any
+ * other — the thread goes, and the drawer has to go with it for good.
+ */
+
+import assert from "node:assert/strict";
+import { afterEach, beforeEach, describe, it } from "node:test";
+import { createElement } from "react";
+import { createDomHarness, type DomHarness } from "../test-support/dom";
+import { useIntelligenceDrawer } from "./useIntelligenceDrawer";
+
+let dom: DomHarness;
+
+beforeEach(() => {
+	dom = createDomHarness();
+});
+
+afterEach(() => {
+	dom.close();
+});
+
+/** Reports what the drawer says, and offers the controls a reader has. */
+const Probe = ({ threadId }: { threadId: string | null }) => {
+	const drawer = useIntelligenceDrawer(threadId);
+	return createElement(
+		"div",
+		null,
+		createElement(
+			"span",
+			{ "data-state": "" },
+			drawer.isOpen ? "open" : "shut",
+		),
+		createElement("button", {
+			type: "button",
+			"data-open": "",
+			onClick: drawer.open,
+		}),
+		createElement("button", {
+			type: "button",
+			"data-toggle": "",
+			onClick: drawer.toggle,
+		}),
+	);
+};
+
+const state = (): string | undefined =>
+	dom.query("[data-state]")?.textContent ?? undefined;
+const press = (handle: string): void => {
+	const button = dom.query(`[${handle}]`);
+	if (!button) throw new Error(`no ${handle} control`);
+	dom.click(button);
+};
+
+describe("the intelligence drawer", () => {
+	it("opens only when it is asked to", () => {
+		dom.render(createElement(Probe, { threadId: "thread-a" }));
+		assert.equal(state(), "shut");
+
+		press("data-open");
+		assert.equal(state(), "open");
+	});
+
+	it("does not come back with the message it was opened over", () => {
+		dom.render(createElement(Probe, { threadId: "thread-a" }));
+		press("data-open");
+		assert.equal(state(), "open");
+
+		// System Back: the thread closes under it.
+		dom.render(createElement(Probe, { threadId: null }));
+		assert.equal(state(), "shut");
+
+		// And the same message again, which is where the scrim used to be waiting.
+		dom.render(createElement(Probe, { threadId: "thread-a" }));
+		assert.equal(state(), "shut");
+	});
+
+	it("stays behind when the reader moves to another thread", () => {
+		dom.render(createElement(Probe, { threadId: "thread-a" }));
+		press("data-open");
+		assert.equal(state(), "open");
+
+		dom.render(createElement(Probe, { threadId: "thread-b" }));
+		assert.equal(state(), "shut");
+	});
+
+	it("toggles shut again from the toolbar's control", () => {
+		dom.render(createElement(Probe, { threadId: "thread-a" }));
+		press("data-toggle");
+		assert.equal(state(), "open");
+
+		press("data-toggle");
+		assert.equal(state(), "shut");
+	});
+});

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/useIntelligenceDrawer.ts

@@ -0,0 +1,54 @@
+import { useCallback, useState } from "react";
+
+/**
+ * The intelligence drawer's own state, scoped to the thread it was opened for.
+ *
+ * The drawer is modal, so it opens only when it is asked for. `intelligenceOpen`
+ * is the rail's persisted preference and the DKIM auto-open sets it on every
+ * tier, so driving the drawer from it throws a scrim over a message the moment
+ * one is selected — and the reader's next tap lands on that scrim instead of the
+ * control they aimed at, Back to messages included. Naming the thread is also
+ * what closes it again when they move on: a bare flag would still be set when
+ * they came back.
+ */
+export interface IntelligenceDrawer {
+	/** Up only while the thread it was opened for is the one on screen. */
+	isOpen: boolean;
+	/** The banner's "Why?" — always an open, never a close. */
+	open: () => void;
+	close: () => void;
+	/** The toolbar's control. */
+	toggle: () => void;
+}
+
+export function useIntelligenceDrawer(
+	openThreadId: string | null,
+): IntelligenceDrawer {
+	const [drawerThreadId, setDrawerThreadId] = useState<string | null>(null);
+	// Leaving the thread puts the drawer away for good, rather than leaving it
+	// armed for the reader's return. Held state alone would reopen it: press
+	// system Back and come to the same message again and the scrim would be
+	// waiting, which is the defect this hook exists to end (#778).
+	//
+	// Adjusted during render, not in an effect: React re-runs the render before
+	// committing, so nothing paints with the stale thread. An effect would show
+	// one frame of an open drawer over the message first.
+	if (drawerThreadId !== null && drawerThreadId !== openThreadId) {
+		setDrawerThreadId(null);
+	}
+	// Derived rather than stored: moving to another thread closes it with no
+	// effect to run.
+	const isOpen = openThreadId !== null && drawerThreadId === openThreadId;
+
+	const close = useCallback(() => setDrawerThreadId(null), []);
+	const open = useCallback(
+		() => setDrawerThreadId(openThreadId),
+		[openThreadId],
+	);
+	const toggle = useCallback(
+		() => setDrawerThreadId(isOpen ? null : openThreadId),
+		[isOpen, openThreadId],
+	);
+
+	return { isOpen, open, close, toggle };
+}

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