@remit/web-client 0.0.274 → 0.0.275

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/web-client",
-  "version": "0.0.274",
+  "version": "0.0.275",
   "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/hooks/useInitialSyncProgress.render.test.ts

@@ -55,6 +55,7 @@ const status = (
 		phase: "syncing",
 		messagesSynced: mailbox.synced,
 		messagesTotal: mailbox.total,
+		highWaterMarkUid: mailbox.synced,
 	})),
 });
 

package/src/lib/mail-freshness.test.ts

@@ -3,17 +3,23 @@ import { describe, test } from "node:test";
 import type { RemitImapMailboxSyncProgress } from "@remit/api-http-client/types.gen.ts";
 import type { NavMailboxRole } from "@remit/ui";
 import type { ResultFolderIndex } from "@/lib/result-folder";
-import { grownMailboxIds, hasGrown, totalsFrom } from "./mail-freshness.js";
+import {
+	grownMailboxIds,
+	hasGrown,
+	highWaterMarksFrom,
+} from "./mail-freshness.js";
 
 const mailbox = (
 	mailboxId: string,
 	messagesTotal: number,
+	highWaterMarkUid: number,
 ): RemitImapMailboxSyncProgress => ({
 	mailboxId,
 	fullPath: mailboxId,
 	phase: "complete",
 	messagesTotal,
 	messagesSynced: messagesTotal,
+	highWaterMarkUid,
 });
 
 const roles = (
@@ -25,30 +31,24 @@ const roles = (
 
 describe("hasGrown", () => {
 	test("false when nothing changed", () => {
-		const baseline = new Map([["mb-1", 10]]);
-		const current = new Map([["mb-1", 10]]);
+		const baseline = new Map([["mb-1", 100]]);
+		const current = new Map([["mb-1", 100]]);
 		assert.equal(hasGrown(baseline, current), false);
 	});
 
-	test("true when a mailbox's total increased", () => {
-		const baseline = new Map([["mb-1", 10]]);
-		const current = new Map([["mb-1", 11]]);
+	test("true when a mailbox took a UID above the highest one seen", () => {
+		const baseline = new Map([["mb-1", 100]]);
+		const current = new Map([["mb-1", 101]]);
 		assert.equal(hasGrown(baseline, current), true);
 	});
 
-	test("false when a mailbox's total dropped (reads, deletes) — not an arrival", () => {
-		const baseline = new Map([["mb-1", 10]]);
-		const current = new Map([["mb-1", 9]]);
-		assert.equal(hasGrown(baseline, current), false);
-	});
-
 	test("a mailbox missing from the baseline counts from zero", () => {
 		const baseline = new Map<string, number>();
 		const current = new Map([["mb-1", 1]]);
 		assert.equal(hasGrown(baseline, current), true);
 	});
 
-	test("a mailbox with zero new messages is not growth", () => {
+	test("a mailbox that has never taken a message is not growth", () => {
 		const baseline = new Map<string, number>();
 		const current = new Map([["mb-1", 0]]);
 		assert.equal(hasGrown(baseline, current), false);
@@ -56,59 +56,78 @@ describe("hasGrown", () => {
 
 	test("one mailbox growing is enough even if others are unchanged", () => {
 		const baseline = new Map([
-			["mb-1", 10],
-			["mb-2", 5],
+			["mb-1", 100],
+			["mb-2", 50],
 		]);
 		const current = new Map([
-			["mb-1", 10],
-			["mb-2", 6],
+			["mb-1", 100],
+			["mb-2", 51],
 		]);
 		assert.equal(hasGrown(baseline, current), true);
 	});
 });
 
-describe("totalsFrom", () => {
+describe("highWaterMarksFrom", () => {
 	test("keeps a mailbox with no resolved role (a custom folder)", () => {
-		const totals = totalsFrom([mailbox("mb-custom", 5)], roles({}));
-		assert.deepEqual([...totals], [["mb-custom", 5]]);
+		const marks = highWaterMarksFrom([mailbox("mb-custom", 5, 42)], roles({}));
+		assert.deepEqual([...marks], [["mb-custom", 42]]);
 	});
 
 	test("keeps Inbox and Junk — both are places new mail actually arrives", () => {
-		const totals = totalsFrom(
-			[mailbox("mb-inbox", 5), mailbox("mb-junk", 2)],
+		const marks = highWaterMarksFrom(
+			[mailbox("mb-inbox", 5, 42), mailbox("mb-junk", 2, 7)],
 			roles({ "mb-inbox": "inbox", "mb-junk": "junk" }),
 		);
-		assert.deepEqual(new Set(totals.keys()), new Set(["mb-inbox", "mb-junk"]));
+		assert.deepEqual(new Set(marks.keys()), new Set(["mb-inbox", "mb-junk"]));
 	});
 
 	for (const role of ["sent", "drafts", "trash", "archive"] as const) {
-		test(`drops ${role} — its own total growing is the user's doing, not an arrival`, () => {
-			const totals = totalsFrom([mailbox("mb-1", 5)], roles({ "mb-1": role }));
-			assert.equal(totals.has("mb-1"), false);
+		test(`drops ${role} — its own new messages are the user's doing, not an arrival`, () => {
+			const marks = highWaterMarksFrom(
+				[mailbox("mb-1", 5, 42)],
+				roles({ "mb-1": role }),
+			);
+			assert.equal(marks.has("mb-1"), false);
 		});
 	}
 
-	test("a delete (Inbox shrinks, Trash grows) never reads as growth once Trash is excluded", () => {
+	test("a delete (Inbox shrinks, Trash grows) never reads as an arrival", () => {
 		const folders = roles({ "mb-inbox": "inbox", "mb-trash": "trash" });
-		const baseline = totalsFrom(
-			[mailbox("mb-inbox", 10), mailbox("mb-trash", 3)],
+		const baseline = highWaterMarksFrom(
+			[mailbox("mb-inbox", 10, 100), mailbox("mb-trash", 3, 20)],
 			folders,
 		);
-		const afterDelete = totalsFrom(
-			[mailbox("mb-inbox", 9), mailbox("mb-trash", 4)],
+		const afterDelete = highWaterMarksFrom(
+			[mailbox("mb-inbox", 9, 100), mailbox("mb-trash", 4, 21)],
 			folders,
 		);
 		assert.equal(hasGrown(baseline, afterDelete), false);
 	});
 
-	test("real new mail in Inbox still reads as growth alongside an unrelated delete", () => {
+	// Issue #771: the arrival and the departure land in the same sync round, so
+	// the Inbox total nets to zero and the count-based reading saw nothing. The
+	// arrival is a UID above the highest one seen, and that is what surfaces it.
+	test("an arrival alongside a departure surfaces, though the total is unchanged", () => {
+		const folders = roles({ "mb-inbox": "inbox", "mb-trash": "trash" });
+		const baseline = highWaterMarksFrom(
+			[mailbox("mb-inbox", 10, 100), mailbox("mb-trash", 3, 20)],
+			folders,
+		);
+		const afterArrivalAndDeparture = highWaterMarksFrom(
+			[mailbox("mb-inbox", 10, 101), mailbox("mb-trash", 4, 21)],
+			folders,
+		);
+		assert.equal(hasGrown(baseline, afterArrivalAndDeparture), true);
+	});
+
+	test("real new mail in Inbox still reads as an arrival alongside an unrelated delete", () => {
 		const folders = roles({ "mb-inbox": "inbox", "mb-trash": "trash" });
-		const baseline = totalsFrom(
-			[mailbox("mb-inbox", 10), mailbox("mb-trash", 3)],
+		const baseline = highWaterMarksFrom(
+			[mailbox("mb-inbox", 10, 100), mailbox("mb-trash", 3, 20)],
 			folders,
 		);
-		const afterArrivalAndDelete = totalsFrom(
-			[mailbox("mb-inbox", 11), mailbox("mb-trash", 4)],
+		const afterArrivalAndDelete = highWaterMarksFrom(
+			[mailbox("mb-inbox", 11, 101), mailbox("mb-trash", 4, 21)],
 			folders,
 		);
 		assert.equal(hasGrown(baseline, afterArrivalAndDelete), true);
@@ -118,16 +137,16 @@ describe("totalsFrom", () => {
 describe("grownMailboxIds", () => {
 	// The invalidation half of the same reading: which folders' listings are
 	// now behind the server, so an open tab reloads exactly those.
-	test("names only the mailboxes whose totals moved up", () => {
+	test("names only the mailboxes that took a higher UID", () => {
 		const baseline = new Map([
-			["mb-1", 10],
-			["mb-2", 4],
-			["mb-3", 7],
+			["mb-1", 100],
+			["mb-2", 40],
+			["mb-3", 70],
 		]);
 		const current = new Map([
-			["mb-1", 12],
-			["mb-2", 4],
-			["mb-3", 6],
+			["mb-1", 120],
+			["mb-2", 40],
+			["mb-3", 70],
 		]);
 
 		assert.deepEqual(grownMailboxIds(baseline, current), ["mb-1"]);
@@ -140,7 +159,7 @@ describe("grownMailboxIds", () => {
 	});
 
 	test("is empty when nothing moved", () => {
-		const totals = new Map([["mb-1", 10]]);
-		assert.deepEqual(grownMailboxIds(totals, new Map(totals)), []);
+		const marks = new Map([["mb-1", 100]]);
+		assert.deepEqual(grownMailboxIds(marks, new Map(marks)), []);
 	});
 });

package/src/lib/mail-freshness.tsx

@@ -29,9 +29,9 @@ import {
 export const FRESHNESS_POLL_MS = 60_000;
 
 /**
- * Roles whose own total growing is the user's doing, not an arrival: sending
- * grows Sent, deleting or archiving grows Trash/Archive, and a Drafts count is
- * autosaves. Counting any of these as "new mail" would light the dot on a
+ * Roles whose own new messages are the user's doing, not an arrival: sending
+ * appends to Sent, deleting or archiving appends to Trash/Archive, and a Draft
+ * is an autosave. Counting any of these as "new mail" would light the dot on a
  * message the user just moved themselves. Junk is kept in — spam is still an
  * arrival, just an unwanted one — and a mailbox with no resolved role (a
  * custom folder, or one a filter files mail into directly) is never excluded.
@@ -43,43 +43,51 @@ const EXCLUDED_GROWTH_ROLES: ReadonlySet<NavMailboxRole> = new Set([
 	"archive",
 ]);
 
-type MailboxTotals = ReadonlyMap<string, number>;
+/**
+ * Each watched mailbox's highest UID. A total cannot answer "did mail arrive":
+ * a message landing in the round that another one leaves nets to zero, so the
+ * arrival was invisible (#771). The read model widens that window, because a
+ * local delete does not decrement the stored count — only the next sync does,
+ * and that same sync carries the arrival. The highest UID only moves up, so it
+ * names the arrival on its own.
+ */
+type MailboxHighWaterMarks = ReadonlyMap<string, number>;
 
-export const totalsFrom = (
+export const highWaterMarksFrom = (
 	mailboxes: readonly RemitImapMailboxSyncProgress[],
 	resultFolderIndex: ResultFolderIndex,
-): MailboxTotals => {
-	const totals = new Map<string, number>();
+): MailboxHighWaterMarks => {
+	const marks = new Map<string, number>();
 	for (const mailbox of mailboxes) {
 		const role = resultFolderIndex.get(mailbox.mailboxId)?.role;
 		if (role && EXCLUDED_GROWTH_ROLES.has(role)) continue;
-		totals.set(mailbox.mailboxId, mailbox.messagesTotal);
+		marks.set(mailbox.mailboxId, mailbox.highWaterMarkUid);
 	}
-	return totals;
+	return marks;
 };
 
 /**
- * Which mailboxes' totals grew since the baseline. Pure so the "did mail
- * arrive" call is unit-testable without a DOM or a QueryClient. A mailbox
- * missing from the baseline (new folder, first-ever reading) counts from zero
- * rather than being skipped, so mail landing in a folder created since the last
- * look still counts as an arrival.
+ * Which mailboxes took a UID above the highest one in the baseline. Pure so the
+ * "did mail arrive" call is unit-testable without a DOM or a QueryClient. A
+ * mailbox missing from the baseline (new folder, first-ever reading) counts
+ * from zero rather than being skipped, so mail landing in a folder created
+ * since the last look still counts as an arrival.
  */
 export const grownMailboxIds = (
-	baseline: MailboxTotals,
-	current: MailboxTotals,
+	baseline: MailboxHighWaterMarks,
+	current: MailboxHighWaterMarks,
 ): string[] => {
 	const grown: string[] = [];
-	for (const [mailboxId, total] of current) {
-		if (total > (baseline.get(mailboxId) ?? 0)) grown.push(mailboxId);
+	for (const [mailboxId, uid] of current) {
+		if (uid > (baseline.get(mailboxId) ?? 0)) grown.push(mailboxId);
 	}
 	return grown;
 };
 
-/** Whether any mailbox grew at all — the dot's own question. */
+/** Whether any mailbox took a new message at all — the dot's own question. */
 export const hasGrown = (
-	baseline: MailboxTotals,
-	current: MailboxTotals,
+	baseline: MailboxHighWaterMarks,
+	current: MailboxHighWaterMarks,
 ): boolean => grownMailboxIds(baseline, current).length > 0;
 
 interface MailFreshnessContextValue {
@@ -116,10 +124,10 @@ interface MailFreshnessProviderProps {
  * 4). The flag is sticky until acknowledged: it lights the dot on whichever
  * `RefreshButton` reads this context and stays lit until a refresh clears it.
  *
- * A tick that sees a folder's total move also invalidates that folder's thread
- * listing. It reorders nothing and asks the mail server for nothing — the
- * message is already on our side, so an open list showing it is a cache read,
- * not IMAP work. The dot is still the account-level signal.
+ * A tick that sees a folder take a new highest UID also invalidates that
+ * folder's thread listing. It reorders nothing and asks the mail server for
+ * nothing — the message is already on our side, so an open list showing it is a
+ * cache read, not IMAP work. The dot is still the account-level signal.
  */
 export function MailFreshnessProvider({
 	accountIds,
@@ -127,12 +135,12 @@ export function MailFreshnessProvider({
 }: MailFreshnessProviderProps) {
 	const queryClient = useQueryClient();
 	const { resultFolderIndex } = useMailContext();
-	const baselineRef = useRef(new Map<string, MailboxTotals>());
+	const baselineRef = useRef(new Map<string, MailboxHighWaterMarks>());
 	const seededRef = useRef(new Set<string>());
 	// The previous tick's reading, distinct from the dot's baseline: the dot's
 	// baseline is sticky until acknowledged, so comparing against it would
 	// re-invalidate on every tick for as long as the dot stays lit.
-	const previousTotalsRef = useRef(new Map<string, MailboxTotals>());
+	const previousMarksRef = useRef(new Map<string, MailboxHighWaterMarks>());
 	const [newMail, setNewMail] = useState<ReadonlySet<string>>(new Set());
 
 	const queries = useQueries({
@@ -153,14 +161,17 @@ export function MailFreshnessProvider({
 		accountIds.forEach((accountId, index) => {
 			const data = queries[index]?.data;
 			if (!data) return;
-			const current = totalsFrom(data.mailboxes ?? [], resultFolderIndex);
+			const current = highWaterMarksFrom(
+				data.mailboxes ?? [],
+				resultFolderIndex,
+			);
 
 			// Mail that has already landed on the server costs nothing more to
-			// show, so a folder whose total moved since the last tick reloads
+			// show, so a folder that took a UID above the last tick's reloads
 			// its listing here. That caps how stale an open tab's list can get
 			// at this poll's own interval, without a single extra IMAP round.
-			const previous = previousTotalsRef.current.get(accountId);
-			previousTotalsRef.current.set(accountId, current);
+			const previous = previousMarksRef.current.get(accountId);
+			previousMarksRef.current.set(accountId, current);
 			if (previous) {
 				const grown = grownMailboxIds(previous, current);
 				if (grown.length > 0) {
@@ -208,7 +219,7 @@ export function MailFreshnessProvider({
 					| undefined;
 				baselineRef.current.set(
 					accountId,
-					totalsFrom(data?.mailboxes ?? [], resultFolderIndex),
+					highWaterMarksFrom(data?.mailboxes ?? [], resultFolderIndex),
 				);
 				seededRef.current.add(accountId);
 			}