@remit/web-client 0.0.195 → 0.0.196

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/web-client",
-  "version": "0.0.195",
+  "version": "0.0.196",
   "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/settings/DeleteFolderDialog.render.test.ts

@@ -64,6 +64,7 @@ i18n.use(initReactI18next).init({
 
 let container: HTMLElement;
 let root: Root;
+let queryClient: QueryClient;
 const originalFetch = globalThis.fetch;
 
 interface FetchCall {
@@ -71,7 +72,7 @@ interface FetchCall {
 	method: string;
 	body: string;
 }
-type FetchRoute = (call: FetchCall) => Response;
+type FetchRoute = (call: FetchCall) => Response | Promise<Response>;
 let route: FetchRoute = () => new Response("{}", { status: 200 });
 
 const json = (body: unknown): Response =>
@@ -80,6 +81,31 @@ const json = (body: unknown): Response =>
 		headers: { "Content-Type": "application/json" },
 	});
 
+/**
+ * `GET /sync/status`, the read the empty-folder delete waits on. `lastSyncedAt`
+ * only advances once `POST /sync` has been answered, so a count read before the
+ * trigger is distinguishable from one a triggered round wrote.
+ */
+const syncStatus = (
+	counts: Readonly<Record<string, number>>,
+	rounds: number,
+) => ({
+	accountId: "acc-1",
+	syncPhase: "complete",
+	mailboxes: mailboxes.map((box) => ({
+		mailboxId: box.mailboxId,
+		fullPath: box.fullPath,
+		phase: "complete",
+		messagesTotal: counts[box.mailboxId] ?? box.messageCount,
+		messagesSynced: 0,
+		lastSyncedAt: 1000 + rounds,
+	})),
+});
+
+const isSyncStatus = (url: string): boolean => url.includes("/sync/status");
+const isSyncTrigger = (url: string, method: string): boolean =>
+	method === "POST" && url.endsWith("/sync");
+
 const threadItems = (ids: readonly string[]) => ({
 	items: ids.map((id) => ({
 		threadMessageId: `t-${id}`,
@@ -95,16 +121,22 @@ beforeEach(() => {
 	container = document.createElement("div");
 	document.body.appendChild(container);
 	root = createRoot(container);
+	queryClient = new QueryClient({
+		defaultOptions: { queries: { retry: false }, mutations: { retry: false } },
+	});
 	globalThis.fetch = (async (input: RequestInfo | URL) => {
 		const request = input as Request;
 		const body = request.method === "GET" ? "" : await request.clone().text();
-		return route({ url: request.url, method: request.method, body });
+		return await route({ url: request.url, method: request.method, body });
 	}) as typeof fetch;
 });
 
 afterEach(() => {
 	act(() => root.unmount());
 	container.remove();
+	// Drops the cached queries with their gc timers, which otherwise hold the
+	// test process open for their full gcTime.
+	queryClient.clear();
 	globalThis.fetch = originalFetch;
 });
 
@@ -122,7 +154,7 @@ const render = (props: {
 				{ i18n },
 				createElement(
 					QueryClientProvider,
-					{ client: new QueryClient() },
+					{ client: queryClient },
 					createElement(DeleteFolderDialog, {
 						open: props.open,
 						accountId: "acc-1",
@@ -353,9 +385,17 @@ describe("DeleteFolderDialog", () => {
 
 	it("deletes an empty folder and closes on success", async () => {
 		let closed = false;
-		route = ({ method }) => {
+		let rounds = 0;
+		let triggered = 0;
+		route = ({ url, method }) => {
 			if (method === "DELETE") return new Response(null, { status: 204 });
-			return new Response("{}", { status: 200 });
+			if (isSyncStatus(url)) return json(syncStatus({}, rounds));
+			if (isSyncTrigger(url, method)) {
+				triggered += 1;
+				rounds += 1;
+				return json({ triggered: true, message: "ok" });
+			}
+			return json({ items: mailboxes });
 		};
 		render({
 			open: true,
@@ -368,9 +408,184 @@ describe("DeleteFolderDialog", () => {
 			buttonByText(/^Delete folder$/)?.click();
 		});
 		await flush();
+		assert.equal(triggered, 1, "the delete asks the server for a sync round");
 		assert.equal(closed, true);
 	});
 
+	it("refuses to delete a folder the server says still holds mail", async () => {
+		let deleted = false;
+		let closed = false;
+		let rounds = 0;
+		route = ({ url, method }) => {
+			if (method === "DELETE") {
+				deleted = true;
+				return new Response(null, { status: 204 });
+			}
+			// Mail landed in Empty since its last sync round, so the count the
+			// round reports contradicts the zero the dialog opened on.
+			if (isSyncStatus(url)) return json(syncStatus({ empty: 2 }, rounds));
+			if (isSyncTrigger(url, method)) {
+				rounds += 1;
+				return json({ triggered: true, message: "ok" });
+			}
+			return json({ items: mailboxes });
+		};
+		render({
+			open: true,
+			folder: mailboxes[2] as RemitImapMailboxResponse,
+			onClose: () => {
+				closed = true;
+			},
+		});
+		assert.match(container.textContent ?? "", /empty and will be removed/);
+		await act(async () => {
+			buttonByText(/^Delete folder$/)?.click();
+		});
+		await flush();
+		assert.equal(deleted, false, "a fresh count above zero blocks the delete");
+		assert.equal(closed, false, "the dialog stays open on the mail it found");
+		assert.match(container.textContent ?? "", /This folder is not empty/);
+		assert.match(container.textContent ?? "", /reports 2 emails/);
+		assert.match(container.textContent ?? "", /holds 2 emails/);
+		assert.ok(
+			buttonByText(/Move them to another folder/),
+			"the non-empty flow takes over",
+		);
+	});
+
+	it("refuses the delete when the count cannot be read", async () => {
+		let deleted = false;
+		route = ({ url, method }) => {
+			if (method === "DELETE") {
+				deleted = true;
+				return new Response(null, { status: 204 });
+			}
+			if (isSyncStatus(url))
+				return new Response(JSON.stringify({ detail: "server exploded" }), {
+					status: 500,
+					headers: { "Content-Type": "application/json" },
+				});
+			if (isSyncTrigger(url, method))
+				return json({ triggered: true, message: "ok" });
+			return json({ items: mailboxes });
+		};
+		render({ open: true, folder: mailboxes[2] as RemitImapMailboxResponse });
+		await act(async () => {
+			buttonByText(/^Delete folder$/)?.click();
+		});
+		await flush();
+		assert.equal(deleted, false, "an unreadable count is not an empty folder");
+		assert.ok(
+			buttonByText(/^Close$/),
+			"the failure is stated, not swallowed into a delete",
+		);
+	});
+
+	it("does not delete when the dialog is closed mid-check", async () => {
+		let deleted = false;
+		let closed = false;
+		let rounds = 0;
+		let releaseStatus: (() => void) | undefined;
+		route = ({ url, method }) => {
+			if (method === "DELETE") {
+				deleted = true;
+				return new Response(null, { status: 204 });
+			}
+			if (isSyncStatus(url)) {
+				const answer = json(syncStatus({}, rounds));
+				if (rounds === 0) return answer;
+				// The round has landed but the answer is still in flight; the user
+				// gets to cancel before it arrives.
+				return new Promise<Response>((resolve) => {
+					releaseStatus = () => resolve(answer);
+				});
+			}
+			if (isSyncTrigger(url, method)) {
+				rounds += 1;
+				return json({ triggered: true, message: "ok" });
+			}
+			return json({ items: mailboxes });
+		};
+		render({
+			open: true,
+			folder: mailboxes[2] as RemitImapMailboxResponse,
+			onClose: () => {
+				closed = true;
+			},
+		});
+		await act(async () => {
+			buttonByText(/^Delete folder$/)?.click();
+		});
+		await flush();
+		assert.ok(releaseStatus, "the check is waiting on the server");
+		await act(async () => {
+			container
+				.querySelector<HTMLButtonElement>('button[aria-label="Cancel"]')
+				?.click();
+		});
+		await act(async () => {
+			releaseStatus?.();
+		});
+		await flush();
+		assert.equal(closed, true, "the cancel closes the dialog");
+		assert.equal(deleted, false, "a cancelled check never reaches the delete");
+	});
+
+	it("asks whether to keep waiting, and resumes without a second round", async () => {
+		let deleted = false;
+		let reported = false;
+		let triggered = 0;
+		route = ({ url, method }) => {
+			if (method === "DELETE") {
+				deleted = true;
+				return new Response(null, { status: 204 });
+			}
+			if (isSyncStatus(url)) return json(syncStatus({}, reported ? 1 : 0));
+			if (isSyncTrigger(url, method)) {
+				triggered += 1;
+				return json({ triggered: true, message: "ok" });
+			}
+			return json({ items: mailboxes });
+		};
+		render({ open: true, folder: mailboxes[2] as RemitImapMailboxResponse });
+
+		// A sync fans the whole account out, so the folder's round can land long
+		// after the trigger. Run the clock forward instead of waiting on it.
+		const realNow = Date.now;
+		let fake = realNow();
+		// Past the segment in one step, so the stall is reached without a poll
+		// sleeping through it.
+		Date.now = () => {
+			fake += 200_000;
+			return fake;
+		};
+		try {
+			await act(async () => {
+				buttonByText(/^Delete folder$/)?.click();
+			});
+			await flush();
+		} finally {
+			Date.now = realNow;
+			// The reads taken under the fake clock cached a future timestamp, which
+			// reads as fresh once the real clock is back; drop them so the resumed
+			// wait talks to the server again.
+			queryClient.clear();
+		}
+
+		assert.equal(triggered, 1, "one round is asked for");
+		assert.equal(deleted, false, "an unreported folder is not deleted");
+		assert.match(container.textContent ?? "", /hasn't reported back/);
+		assert.ok(buttonByText(/^Keep waiting$/), "the wait is the user's call");
+
+		reported = true;
+		await act(async () => {
+			buttonByText(/^Keep waiting$/)?.click();
+		});
+		await flush();
+		assert.equal(triggered, 1, "resuming asks for no second round");
+		assert.equal(deleted, true, "the reported count settles the delete");
+	});
+
 	it("moves the mail in batches then deletes the emptied folder", async () => {
 		let closed = false;
 		let moved: string[] = [];

package/src/components/settings/DeleteFolderDialog.tsx

@@ -14,7 +14,11 @@ import { useCallback, useEffect, useMemo, useState } from "react";
 import { useCreateMailbox } from "@/hooks/useCreateMailbox";
 import { useDeleteFolder } from "@/hooks/useDeleteFolder";
 import { useFolderLabelTranslator } from "@/hooks/useFolderLabelTranslator";
-import { initialStage, moveProgressLabel } from "@/lib/delete-folder";
+import {
+	elapsedLabel,
+	initialStage,
+	moveProgressLabel,
+} from "@/lib/delete-folder";
 import { buildMailboxRoleMap, labelForMailbox } from "@/lib/folder-roles";
 import { buildMoveOptions } from "@/lib/move-options";
 
@@ -37,11 +41,14 @@ const emailCount = (count: number): string =>
 	`${count} ${count === 1 ? "email" : "emails"}`;
 
 /**
- * Per-folder delete wizard. An empty folder is a single destructive confirm; a
- * folder with mail first asks what happens to the messages — delete them with
- * the folder, or move them elsewhere (batched, with visible progress) before
- * the now-empty folder is removed. Closing mid-move keeps already-moved mail
- * moved; re-opening enumerates what's left and continues.
+ * Per-folder delete wizard. An empty folder is a single destructive confirm,
+ * settled against a sync round asked for on the spot rather than the folder's
+ * last synced count — a wait the user can watch, keep, or cancel, and which
+ * deletes nothing until the server answers; a folder with mail asks what
+ * happens to the messages first — delete them with the folder, or move them
+ * elsewhere (batched, with visible progress) before the now-empty folder is
+ * removed. Closing mid-move keeps
+ * already-moved mail moved; re-opening enumerates what's left and continues.
  */
 export function DeleteFolderDialog({
 	open,
@@ -54,6 +61,7 @@ export function DeleteFolderDialog({
 	const [stage, setStage] = useState<FateStage>(() =>
 		initialStage(folder.messageCount),
 	);
+	const [arrivedSinceSync, setArrivedSinceSync] = useState<number>();
 	const [destinationId, setDestinationId] = useState<string>();
 	const { createFolderIn } = useCreateMailbox(accountId);
 	const translator = useFolderLabelTranslator();
@@ -61,7 +69,9 @@ export function DeleteFolderDialog({
 		phase,
 		progress,
 		errorMessage,
+		checkStartedAt,
 		deleteMailbox,
+		deleteIfEmpty,
 		moveThenDelete,
 		cancel,
 		reset,
@@ -70,12 +80,30 @@ export function DeleteFolderDialog({
 		mailboxId: folder.mailboxId,
 		onDeleted: onClose,
 	});
+	const [checkElapsed, setCheckElapsed] = useState("0:00");
+
+	// The check has no progress to report — only that it is still waiting — so
+	// the wait itself is what the surface shows, ticking, for as long as it runs.
+	const waiting = phase === "checking" || phase === "check-stalled";
+	useEffect(() => {
+		if (!waiting || checkStartedAt === undefined) return;
+		const update = () =>
+			setCheckElapsed(elapsedLabel(Date.now() - checkStartedAt));
+		update();
+		const timer = setInterval(update, 1000);
+		return () => clearInterval(timer);
+	}, [waiting, checkStartedAt]);
 
+	// Opening the dialog stages it; a count arriving later deliberately does not.
+	// The refusal below invalidates the folder list on purpose, and re-staging on
+	// the count that refetch brings back would wipe the refusal off the screen.
+	// biome-ignore lint/correctness/useExhaustiveDependencies: folder.messageCount is read at open and must not re-run this.
 	useEffect(() => {
 		if (!open) return;
 		setStage(initialStage(folder.messageCount));
+		setArrivedSinceSync(undefined);
 		reset();
-	}, [open, folder.messageCount, reset]);
+	}, [open, reset]);
 
 	useEffect(() => {
 		if (!open) return;
@@ -89,6 +117,13 @@ export function DeleteFolderDialog({
 		onClose();
 	}, [cancel, onClose]);
 
+	const handleDeleteEmpty = useCallback(async () => {
+		const outcome = await deleteIfEmpty();
+		if (outcome.status !== "blocked") return;
+		setArrivedSinceSync(outcome.messageCount);
+		setStage("choose-fate");
+	}, [deleteIfEmpty]);
+
 	const destinations = useMemo<FolderTreeNode[]>(
 		() =>
 			buildMoveOptions({
@@ -117,6 +152,7 @@ export function DeleteFolderDialog({
 	if (!open) return null;
 
 	const title = `Delete ${name}`;
+	const messageCount = arrivedSinceSync ?? folder.messageCount;
 
 	const body = (() => {
 		if (phase === "moving") {
@@ -131,6 +167,42 @@ export function DeleteFolderDialog({
 			);
 		}
 
+		if (phase === "checking") {
+			return (
+				<div className="flex flex-col items-center gap-3 px-5 py-10 text-center">
+					<Loader2 className="size-8 animate-spin text-accent-2" />
+					<p className="text-sm font-medium text-fg">
+						Checking the folder on the mail server…
+					</p>
+					<p className="text-xs text-fg-muted" role="status" aria-live="polite">
+						{`Waiting ${checkElapsed}. Nothing is deleted until the server answers.`}
+					</p>
+				</div>
+			);
+		}
+
+		if (phase === "check-stalled") {
+			return (
+				<div className="space-y-4 px-5 py-4">
+					<Banner tone="warning" variant="soft">
+						{`The mail server hasn't reported back on this folder yet — ${checkElapsed} so far. Nothing has been deleted.`}
+					</Banner>
+					<p className="text-xs text-fg-muted">
+						A sync covers the whole account, so a busy mailbox can take a while
+						to come round to this folder.
+					</p>
+					<div className="flex justify-end gap-2">
+						<Button variant="secondary" size="sm" onClick={handleClose}>
+							Cancel
+						</Button>
+						<Button size="sm" onClick={() => handleDeleteEmpty()}>
+							Keep waiting
+						</Button>
+					</div>
+				</div>
+			);
+		}
+
 		if (phase === "deleting" || phase === "done") {
 			return (
 				<div className="flex flex-col items-center gap-3 px-5 py-10 text-center">
@@ -178,7 +250,7 @@ export function DeleteFolderDialog({
 							variant="danger"
 							size="sm"
 							icon={<Trash2 className="size-3.5" />}
-							onClick={() => deleteMailbox()}
+							onClick={() => handleDeleteEmpty()}
 						>
 							Delete folder
 						</Button>
@@ -191,9 +263,14 @@ export function DeleteFolderDialog({
 			return (
 				<>
 					<div className="space-y-3 px-5 py-4 text-sm text-fg-muted">
+						{arrivedSinceSync !== undefined && (
+							<Banner tone="warning" variant="soft">
+								{`This folder is not empty: the mail server reports ${emailCount(arrivedSinceSync)} in it. Nothing was deleted.`}
+							</Banner>
+						)}
 						<p>
 							<strong className="text-fg">{name}</strong> holds{" "}
-							{emailCount(folder.messageCount)}. What should happen to them?
+							{emailCount(messageCount)}. What should happen to them?
 						</p>
 						<div className="space-y-2">
 							<button
@@ -244,8 +321,8 @@ export function DeleteFolderDialog({
 					<div className="space-y-3 px-5 py-4 text-sm text-fg-muted">
 						<p>
 							Delete <strong className="text-fg">{name}</strong> and its{" "}
-							{emailCount(folder.messageCount)}? The messages are removed from
-							the server with the folder and can't be recovered.
+							{emailCount(messageCount)}? The messages are removed from the
+							server with the folder and can't be recovered.
 						</p>
 					</div>
 					<footer className="flex items-center justify-end gap-2 border-t border-line px-5 py-3">
@@ -272,7 +349,7 @@ export function DeleteFolderDialog({
 		return (
 			<div className="flex h-[26rem] flex-col">
 				<p className="px-5 pt-4 text-sm text-fg-muted">
-					Move the {emailCount(folder.messageCount)} in{" "}
+					Move the {emailCount(messageCount)} in{" "}
 					<strong className="text-fg">{name}</strong> to:
 				</p>
 				<div className="flex min-h-0 flex-1 overflow-hidden">
@@ -301,7 +378,7 @@ export function DeleteFolderDialog({
 							className="h-11 w-full font-semibold"
 						>
 							<span className="truncate">
-								{`Move ${emailCount(folder.messageCount)} to ${destination.label}`}
+								{`Move ${emailCount(messageCount)} to ${destination.label}`}
 							</span>
 						</Button>
 					</footer>

package/src/hooks/useDeleteFolder.ts

@@ -1,11 +1,13 @@
 import {
 	configOperationsGetConfigQueryKey,
 	mailboxOperationsListMailboxesQueryKey,
+	syncOperationsGetSyncStatusOptions,
 } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
 import {
 	mailboxDetailOperationsDeleteMailbox,
 	mailboxOperationsListMailboxes,
 	messageBulkOperationsMoveMessages,
+	syncOperationsTriggerSync,
 	threadOperationsListThreads,
 } from "@remit/api-http-client/sdk.gen.ts";
 import { useQueryClient } from "@tanstack/react-query";
@@ -17,6 +19,12 @@ import {
 	MOVE_BATCH_SIZE,
 	type MoveProgress,
 } from "@/lib/delete-folder";
+import {
+	awaitFreshMailboxCount,
+	type FreshCountOutcome,
+	type MailboxCountReading,
+	mailboxSyncStamp,
+} from "@/lib/fresh-mailbox-count";
 
 const PAGE_CAP = 50;
 
@@ -101,11 +109,25 @@ const liveMessageCount = async (
 
 export type DeleteFolderPhase =
 	| "idle"
+	| "checking"
+	| "check-stalled"
 	| "moving"
 	| "deleting"
 	| "done"
 	| "error";
 
+/**
+ * What a delete-as-empty did. `blocked` carries the count that stopped it;
+ * `pending` means the server has not reported yet and the user decides whether
+ * to wait on; `failed` means nothing was established. Neither is ever treated
+ * as empty.
+ */
+export type EmptyDeleteOutcome =
+	| { status: "deleted" }
+	| { status: "blocked"; messageCount: number }
+	| { status: "pending" }
+	| { status: "failed" };
+
 interface UseDeleteFolderOptions {
 	accountId: string;
 	mailboxId: string;
@@ -121,7 +143,11 @@ export function useDeleteFolder({
 	const [phase, setPhase] = useState<DeleteFolderPhase>("idle");
 	const [progress, setProgress] = useState<MoveProgress | null>(null);
 	const [errorMessage, setErrorMessage] = useState<string>();
+	const [checkStartedAt, setCheckStartedAt] = useState<number>();
 	const abortRef = useRef<AbortController | null>(null);
+	/** The folder's sync stamp before the round was asked for; set while a check
+	 * is running or paused, so resuming it re-uses the same baseline. */
+	const sinceRef = useRef<number | undefined>(undefined);
 
 	const invalidate = useCallback(() => {
 		queryClient.invalidateQueries({
@@ -163,6 +189,88 @@ export function useDeleteFolder({
 		[accountId, mailboxId],
 	);
 
+	const readMailboxSyncStatus = useCallback(
+		(): Promise<readonly MailboxCountReading[]> =>
+			queryClient
+				.fetchQuery({
+					...syncOperationsGetSyncStatusOptions({ path: { accountId } }),
+					staleTime: 0,
+				})
+				.then((data) => data.mailboxes ?? []),
+		[queryClient, accountId],
+	);
+
+	/**
+	 * Delete a folder the user was told is empty. Every count the client holds is
+	 * the last sync round's, so this waits (R2 of the IMAP mutation rules) for a
+	 * round asked for here to report on the folder, and deletes only on the count
+	 * that round read. A read failure or a folder gone from the account refuses
+	 * the delete: not knowing what a folder holds is never permission.
+	 *
+	 * The round can take minutes — it fans the whole account out behind INBOX —
+	 * so the wait runs in segments. A segment that ends unreported returns
+	 * `pending` and the user decides; calling again resumes the same wait against
+	 * the same baseline, and never asks for a second round.
+	 */
+	const deleteIfEmpty = useCallback(async (): Promise<EmptyDeleteOutcome> => {
+		const controller = new AbortController();
+		abortRef.current = controller;
+		const { signal } = controller;
+		setPhase("checking");
+		setErrorMessage(undefined);
+
+		const resuming = sinceRef.current !== undefined;
+		const counted = await attempt(
+			(async (): Promise<FreshCountOutcome> => {
+				if (!resuming) {
+					signal.throwIfAborted();
+					sinceRef.current = mailboxSyncStamp(
+						await readMailboxSyncStatus(),
+						mailboxId,
+					);
+					signal.throwIfAborted();
+					setCheckStartedAt(Date.now());
+					await syncOperationsTriggerSync({
+						path: { accountId },
+						throwOnError: true,
+					});
+				}
+				return awaitFreshMailboxCount({
+					readMailboxes: readMailboxSyncStatus,
+					mailboxId,
+					since: sinceRef.current ?? 0,
+					signal,
+				});
+			})(),
+		);
+
+		if (signal.aborted) {
+			// The dialog is closing or the user cancelled; leave nothing running
+			// and no phase for a later caller to inherit.
+			setPhase("idle");
+			sinceRef.current = undefined;
+			return { status: "failed" };
+		}
+		if (!counted.ok) {
+			sinceRef.current = undefined;
+			setErrorMessage(counted.error);
+			setPhase("error");
+			return { status: "failed" };
+		}
+		if (counted.value.status === "pending") {
+			setPhase("check-stalled");
+			return { status: "pending" };
+		}
+		sinceRef.current = undefined;
+		if (counted.value.messageCount > 0) {
+			setPhase("idle");
+			invalidate();
+			return { status: "blocked", messageCount: counted.value.messageCount };
+		}
+		await deleteMailbox();
+		return { status: "deleted" };
+	}, [accountId, mailboxId, readMailboxSyncStatus, deleteMailbox, invalidate]);
+
 	const cancel = useCallback(() => {
 		abortRef.current?.abort();
 	}, []);
@@ -250,16 +358,21 @@ export function useDeleteFolder({
 	const reset = useCallback(() => {
 		abortRef.current?.abort();
 		abortRef.current = null;
+		sinceRef.current = undefined;
 		setPhase("idle");
 		setProgress(null);
 		setErrorMessage(undefined);
+		setCheckStartedAt(undefined);
 	}, []);
 
 	return {
 		phase,
 		progress,
 		errorMessage,
+		/** When the running check asked for its round; the surface shows the wait. */
+		checkStartedAt,
 		deleteMailbox,
+		deleteIfEmpty,
 		moveThenDelete,
 		cancel,
 		reset,

package/src/lib/delete-folder.test.ts

@@ -3,6 +3,7 @@ import { describe, it } from "node:test";
 import {
 	advanceMove,
 	beginMove,
+	elapsedLabel,
 	excludeFolder,
 	type FolderNode,
 	failMove,
@@ -262,6 +263,19 @@ describe("move progress", () => {
 	});
 });
 
+describe("elapsedLabel", () => {
+	it("counts a wait in minutes and padded seconds", () => {
+		assert.equal(elapsedLabel(0), "0:00");
+		assert.equal(elapsedLabel(9_400), "0:09");
+		assert.equal(elapsedLabel(65_000), "1:05");
+		assert.equal(elapsedLabel(600_000), "10:00");
+	});
+
+	it("reads a backwards clock as no time at all", () => {
+		assert.equal(elapsedLabel(-5_000), "0:00");
+	});
+});
+
 describe("initialStage", () => {
 	it("opens on the empty confirm for a folder with no mail", () => {
 		assert.equal(initialStage(0), "confirm-empty");

package/src/lib/delete-folder.ts

@@ -172,6 +172,12 @@ export function moveProgressLabel(progress: MoveProgress): string {
 	return `Moved ${progress.moved} of ${progress.total}`;
 }
 
+/** How long a wait has run, as `m:ss` — clamped at zero so a clock skew reads as 0:00. */
+export function elapsedLabel(ms: number): string {
+	const seconds = Math.max(0, Math.floor(ms / 1000));
+	return `${Math.floor(seconds / 60)}:${String(seconds % 60).padStart(2, "0")}`;
+}
+
 /** Where the wizard opens: a straight confirm for an empty folder, otherwise the fate step. */
 export function initialStage(
 	messageCount: number,

package/src/lib/fresh-mailbox-count.test.ts

@@ -0,0 +1,145 @@
+/**
+ * awaitFreshMailboxCount — the gate a folder delete holds behind while the
+ * server is asked what the folder actually holds. It reports a count only from
+ * a round that stamped past the baseline, reports `pending` rather than a count
+ * when the segment runs out, and refuses outright on a folder the account does
+ * not list.
+ */
+
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import {
+	awaitFreshMailboxCount,
+	FRESH_COUNT_MISSING_MESSAGE,
+	type MailboxCountReading,
+	mailboxSyncStamp,
+} from "./fresh-mailbox-count.js";
+
+const reading = (
+	messagesTotal: number,
+	lastSyncedAt?: number,
+): MailboxCountReading => ({
+	mailboxId: "mbx-1",
+	messagesTotal,
+	lastSyncedAt,
+});
+
+const noDelay = () => Promise.resolve();
+
+/** A clock that jumps a minute per reading, so a segment expires in two polls. */
+const impatientClock = () => {
+	let clock = 0;
+	return () => {
+		clock += 60_000;
+		return clock;
+	};
+};
+
+describe("mailboxSyncStamp", () => {
+	it("reads the folder's stamp, and zero for a folder never synced", () => {
+		assert.equal(mailboxSyncStamp([reading(0, 100)], "mbx-1"), 100);
+		assert.equal(mailboxSyncStamp([reading(0)], "mbx-1"), 0);
+	});
+
+	it("refuses a folder the account does not list", () => {
+		assert.throws(() => mailboxSyncStamp([], "mbx-1"), {
+			message: FRESH_COUNT_MISSING_MESSAGE,
+		});
+	});
+});
+
+describe("awaitFreshMailboxCount", () => {
+	it("resolves with the count a round stamped past the baseline", async () => {
+		const responses = [[reading(0, 100)], [reading(0, 100)], [reading(3, 200)]];
+		let call = 0;
+		const outcome = await awaitFreshMailboxCount({
+			mailboxId: "mbx-1",
+			since: 100,
+			readMailboxes: async () => responses[call++] as MailboxCountReading[],
+			delay: noDelay,
+		});
+		assert.deepEqual(outcome, { status: "fresh", messageCount: 3 });
+		assert.equal(call, 3);
+	});
+
+	it("never reports a count from a round older than the baseline", async () => {
+		// The stamp stands still — the folder was never re-read, so the zero
+		// sitting in the row is exactly the stale count that must not be trusted.
+		const outcome = await awaitFreshMailboxCount({
+			mailboxId: "mbx-1",
+			since: 100,
+			readMailboxes: async () => [reading(0, 100)],
+			delay: noDelay,
+			now: impatientClock(),
+		});
+		assert.deepEqual(outcome, { status: "pending" });
+	});
+
+	it("resumes against the same baseline and then reports the count", async () => {
+		let stamp = 100;
+		const readMailboxes = async () => [reading(2, stamp)];
+		const first = await awaitFreshMailboxCount({
+			mailboxId: "mbx-1",
+			since: 100,
+			readMailboxes,
+			delay: noDelay,
+			now: impatientClock(),
+		});
+		assert.deepEqual(first, { status: "pending" });
+
+		stamp = 300;
+		const second = await awaitFreshMailboxCount({
+			mailboxId: "mbx-1",
+			since: 100,
+			readMailboxes,
+			delay: noDelay,
+			now: impatientClock(),
+		});
+		assert.deepEqual(second, { status: "fresh", messageCount: 2 });
+	});
+
+	it("refuses a folder the account no longer lists", async () => {
+		await assert.rejects(
+			awaitFreshMailboxCount({
+				mailboxId: "mbx-1",
+				since: 100,
+				readMailboxes: async () => [],
+				delay: noDelay,
+			}),
+			{ message: FRESH_COUNT_MISSING_MESSAGE },
+		);
+	});
+
+	it("propagates a failed read rather than counting it as zero", async () => {
+		await assert.rejects(
+			awaitFreshMailboxCount({
+				mailboxId: "mbx-1",
+				since: 100,
+				readMailboxes: async () => {
+					throw new Error("sync status 500");
+				},
+				delay: noDelay,
+			}),
+			{ message: "sync status 500" },
+		);
+	});
+
+	it("stops on abort and never reports a count", async () => {
+		const controller = new AbortController();
+		let call = 0;
+		controller.abort();
+		await assert.rejects(
+			awaitFreshMailboxCount({
+				mailboxId: "mbx-1",
+				since: 100,
+				readMailboxes: async () => {
+					call += 1;
+					return [reading(0, 200)];
+				},
+				signal: controller.signal,
+				delay: noDelay,
+			}),
+		);
+		assert.equal(call, 0, "an aborted wait reads nothing");
+	});
+});

package/src/lib/fresh-mailbox-count.ts

@@ -0,0 +1,114 @@
+import { abortableDelay } from "./mailbox-sync-wait";
+
+/**
+ * How many messages a folder holds *on the mail server*, rather than how many
+ * the last sync round left in the local row.
+ *
+ * Every count the client can read — the mailbox row's `messageCount`, and so
+ * the folder list and the sync-status projection over it — is whatever the last
+ * round wrote. Mail that arrived since is invisible in it, which is fine for a
+ * badge and fatal for a delete: `deleteMailbox` takes the folder's mail with it
+ * and IMAP has no undo.
+ *
+ * So the count is taken from a round asked for on the spot: trigger a sync,
+ * then wait for the folder's `lastSyncedAt` to advance past the stamp read
+ * before the trigger, and read the count that round wrote alongside it (every
+ * message-sync round writes both from the same IMAP STATUS).
+ *
+ * What the advancing stamp proves is that *some* round's write landed after the
+ * baseline read — not necessarily the round this triggered. A round already in
+ * flight can land first and satisfy the wait. That is accepted: its STATUS was
+ * taken within milliseconds of the baseline, and the error it can carry is a
+ * count from a moment too early, which either agrees with the trigger's round
+ * or reports mail the folder had and the delete then refuses. The mistake lands
+ * on the side of not deleting.
+ *
+ * Nothing here decides on a count read before the trigger, and every way out
+ * other than an advanced stamp throws or reports `pending`: a folder missing
+ * from the account, a failed read, an aborted wait. Uncertainty about what a
+ * folder holds is never permission to delete it.
+ */
+
+/** The read fields the wait needs off a sync-status entry. */
+export interface MailboxCountReading {
+	mailboxId: string;
+	messagesTotal: number;
+	lastSyncedAt?: number;
+}
+
+/** A count from a round that reported after the baseline, or no round yet. */
+export type FreshCountOutcome =
+	| { status: "fresh"; messageCount: number }
+	| { status: "pending" };
+
+export interface AwaitFreshMailboxCountOptions {
+	/** Reads every mailbox's sync-status entry; called once per poll. */
+	readMailboxes: () => Promise<readonly MailboxCountReading[]>;
+	/** The folder to count. */
+	mailboxId: string;
+	/** The folder's `lastSyncedAt` as read before the sync was triggered. */
+	since: number;
+	/** Aborts the wait; a round that lands afterwards resolves nothing. */
+	signal?: AbortSignal;
+	/** How long this stretch of waiting runs before reporting `pending`. */
+	segmentMs?: number;
+	pollIntervalMs?: number;
+	/** Injectable clock/sleep for tests. */
+	delay?: (ms: number, signal?: AbortSignal) => Promise<void>;
+	now?: () => number;
+}
+
+/**
+ * How long one stretch of waiting runs before handing the decision back to the
+ * user. An explicit sync fans the whole account out on one FIFO group with
+ * INBOX first, so a folder on a large account can sit behind minutes of other
+ * mailboxes: this is not long enough to conclude anything, only long enough
+ * that someone watching a spinner deserves to be asked whether to keep waiting.
+ */
+export const FRESH_COUNT_SEGMENT_MS = 120_000;
+export const FRESH_COUNT_POLL_INTERVAL_MS = 2_000;
+
+export const FRESH_COUNT_MISSING_MESSAGE =
+	"This folder is no longer in the account's folder list, so nothing was deleted.";
+
+const entryFor = (
+	mailboxes: readonly MailboxCountReading[],
+	mailboxId: string,
+): MailboxCountReading => {
+	const entry = mailboxes.find((mailbox) => mailbox.mailboxId === mailboxId);
+	if (!entry) throw new Error(FRESH_COUNT_MISSING_MESSAGE);
+	return entry;
+};
+
+/** The folder's last sync stamp, or a refusal when the account does not list it. */
+export const mailboxSyncStamp = (
+	mailboxes: readonly MailboxCountReading[],
+	mailboxId: string,
+): number => entryFor(mailboxes, mailboxId).lastSyncedAt ?? 0;
+
+/**
+ * Poll for one segment. Resolves `fresh` with the count once a round reports
+ * past `since`, `pending` when the segment runs out with the folder still
+ * unreported — the caller asks the user whether to wait on, and calling again
+ * with the same `since` resumes without triggering a second round.
+ */
+export async function awaitFreshMailboxCount({
+	readMailboxes,
+	mailboxId,
+	since,
+	signal,
+	segmentMs = FRESH_COUNT_SEGMENT_MS,
+	pollIntervalMs = FRESH_COUNT_POLL_INTERVAL_MS,
+	delay = abortableDelay,
+	now = Date.now,
+}: AwaitFreshMailboxCountOptions): Promise<FreshCountOutcome> {
+	const deadline = now() + segmentMs;
+	for (;;) {
+		signal?.throwIfAborted();
+		const entry = entryFor(await readMailboxes(), mailboxId);
+		if ((entry.lastSyncedAt ?? 0) > since)
+			return { status: "fresh", messageCount: entry.messagesTotal };
+		if (now() >= deadline) return { status: "pending" };
+		await delay(pollIntervalMs, signal);
+	}
+}

package/src/lib/mailbox-sync-wait.ts

@@ -50,7 +50,11 @@ export const MAILBOX_SYNC_FAILED_MESSAGE =
 export const MAILBOX_SYNC_TIMEOUT_MESSAGE =
 	"The folder was created but the mail server hasn't confirmed it yet, so nothing was attached to it. It's in your folder list — try again in a moment.";
 
-const defaultDelay = (ms: number, signal?: AbortSignal): Promise<void> =>
+/** `setTimeout` that rejects with the signal's reason instead of outliving it. */
+export const abortableDelay = (
+	ms: number,
+	signal?: AbortSignal,
+): Promise<void> =>
 	new Promise((resolve, reject) => {
 		if (signal?.aborted) {
 			reject(signal.reason);
@@ -81,7 +85,7 @@ export async function waitForMailboxSynced<T extends MailboxSyncSignal>({
 	signal,
 	timeoutMs = MAILBOX_SYNC_TIMEOUT_MS,
 	pollIntervalMs = MAILBOX_SYNC_POLL_INTERVAL_MS,
-	delay = defaultDelay,
+	delay = abortableDelay,
 	now = Date.now,
 }: WaitForMailboxSyncedOptions<T>): Promise<T> {
 	const deadline = now() + timeoutMs;