@remit/web-client 0.0.74 → 0.0.76

package/package.json

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

package/src/components/mail/MoveToTrigger.tsx

@@ -130,8 +130,8 @@ export const MoveToTrigger = ({
 	);
 
 	const handleCreateFolder = useCallback(
-		async (name: string): Promise<MoveMailboxOption> => {
-			const folder = await createFolder(name);
+		async (name: string, signal?: AbortSignal): Promise<MoveMailboxOption> => {
+			const folder = await createFolder(name, signal);
 			return { id: folder.id, label: folder.label };
 		},
 		[createFolder],

package/src/components/settings/DeleteFolderDialog.tsx

@@ -103,8 +103,9 @@ export function DeleteFolderDialog({
 
 	const handleCreateFolder = async (
 		name: string,
+		signal?: AbortSignal,
 	): Promise<MoveMailboxOption> => {
-		const created = await createFolder(name);
+		const created = await createFolder(name, signal);
 		return { id: created.id, label: created.label };
 	};
 

package/src/components/settings/FilterEditor.render.test.ts

@@ -60,12 +60,17 @@ const filterFixture = (
 
 type Responder = (call: HttpCall) => unknown;
 
-/** Fields whose presence in a patch bumps `ruleChangedAt` (RFC 034 Decision 3.2). */
-const PREDICATE_OR_ACTION = [
+/**
+ * Fields whose presence in a patch bumps `ruleChangedAt` (RFC 034 Decision
+ * 3.2, reader #266).
+ */
+const RULE_ASSERTION_FIELDS = [
 	"matchOperator",
 	"literalClauses",
 	"actionLabelId",
 	"actionMailboxId",
+	"scope",
+	"expiresAt",
 ];
 
 /**
@@ -84,7 +89,7 @@ const backend = (
 		}
 		if (call.path.endsWith("/filters/f-1") && call.method === "PATCH") {
 			const body = call.body ?? {};
-			const bumped = PREDICATE_OR_ACTION.some((field) => field in body);
+			const bumped = RULE_ASSERTION_FIELDS.some((field) => field in body);
 			return {
 				...filter,
 				...body,
@@ -254,12 +259,12 @@ describe("FilterEditor — degraded semantic filter (RFC 038 D4)", () => {
 			dom.query('[aria-label="Remove the similar-mail widen"]'),
 			null,
 		);
-		assert.match(dom.text(), /set when a filter is created/i);
+		assert.match(dom.text(), /similar-mail match is fixed to the message/i);
 	});
 });
 
-describe("FilterEditor — scope and expiry are read-only (reader #266)", () => {
-	it("shows an until-a-date filter's scope statically, with no scope or date control", async () => {
+describe("FilterEditor — scope and expiry are editable (reader #266)", () => {
+	it("keeps the scope toggle and date input live, minus the once option", async () => {
 		const dom = mount(
 			filterFixture({
 				scope: "Temporary",
@@ -268,14 +273,56 @@ describe("FilterEditor — scope and expiry are read-only (reader #266)", () =>
 		);
 		await settlePreview(dom);
 
-		// The live scope segmented control and the date input are gone — a
-		// scope/date change cannot be persisted, so it is never offered.
-		assert.equal(dom.query('input[name="rule-scope"]'), null);
-		assert.equal(dom.query('[aria-label="Expiry date"]'), null);
-		assert.match(dom.text(), /Until 2027-09-01/);
-		assert.match(dom.text(), /set when a filter is created/i);
+		assert.ok(dom.query('input[name="rule-scope"]'));
+		assert.ok(dom.byLabel("Expiry date"));
+		assert.doesNotMatch(dom.text(), /Just once/);
 
-		// The name stays editable.
+		// The name stays editable too.
 		assert.ok(dom.byLabel("Rule name"));
 	});
+
+	it("moves a standing filter to until-a-date, patches scope and expiresAt, and offers the re-apply", async () => {
+		const dom = mount(filterFixture());
+		await settlePreview(dom);
+
+		dom.click(dom.byText("label", "Until a date"));
+		dom.type(dom.byLabel("Expiry date"), "2027-09-01");
+		await dom.flush();
+
+		dom.click(primaryButton(dom, "Save until then"));
+		await dom.flush();
+
+		const patch = patchCalls();
+		assert.equal(patch.length, 1);
+		assert.equal(patch[0].body?.scope, "Temporary");
+		assert.match(String(patch[0].body?.expiresAt ?? ""), /^2027-09-01T/);
+		// The predicate/action and the name are untouched, so neither travels.
+		assert.equal("matchOperator" in (patch[0].body ?? {}), false);
+		assert.equal("name" in (patch[0].body ?? {}), false);
+
+		// A scope/expiry change is a rule reassertion too — it offers the
+		// re-apply exactly like a predicate/action change does.
+		assert.match(dom.text(), /Move existing mail/);
+	});
+
+	it("moves an until-a-date filter back to standing and clears the expiry", async () => {
+		const dom = mount(
+			filterFixture({
+				scope: "Temporary",
+				expiresAt: "2027-09-01T23:59:59+00:00",
+			}),
+		);
+		await settlePreview(dom);
+
+		dom.click(dom.byText("label", "Keep doing this"));
+		await dom.flush();
+
+		dom.click(primaryButton(dom, "Save rule"));
+		await dom.flush();
+
+		const patch = patchCalls();
+		assert.equal(patch.length, 1);
+		assert.equal(patch[0].body?.scope, "Standing");
+		assert.equal("expiresAt" in (patch[0].body ?? {}), false);
+	});
 });

package/src/components/settings/FilterEditor.tsx

@@ -8,6 +8,7 @@ import {
 	type FolderOption,
 	type MatchOperator,
 	previewCountSummary,
+	type RuleScope,
 } from "@remit/ui";
 import { CheckCircle2, Loader2 } from "lucide-react";
 import { useMemo, useRef, useState } from "react";
@@ -19,6 +20,7 @@ import {
 	buildUpdateFilterInput,
 	filterToRule,
 	ruleChangesPredicateOrAction,
+	ruleChangesScopeOrExpiry,
 } from "@/lib/organize/filter-edit-model";
 import {
 	normalizeClauseValue,
@@ -43,11 +45,14 @@ interface FilterEditorProps {
 /**
  * Editing a standing filter in the same chip editor the Organize surface uses
  * (RFC 038 D6). The row's persisted rule opens in the editor — clauses, match
- * operator, move action, scope, and the semantic anchor as a widen chip. Saving
- * a predicate or action change bumps `ruleChangedAt` and offers, never runs, a
- * re-back-apply over existing mail; a cosmetic rename does neither (RFC 034
- * Decision 3.2). The re-apply carries exactly the previewed predicate and is
- * held behind the same settled-count commit gate as creation.
+ * operator, move action, scope, expiry, and the semantic anchor as a widen
+ * chip. Saving a predicate, action, scope, or expiry change bumps
+ * `ruleChangedAt` and offers, never runs, a re-back-apply over existing mail;
+ * a cosmetic rename does neither (RFC 034 Decision 3.2, reader #266). The
+ * re-apply carries exactly the previewed predicate and is held behind the
+ * same settled-count commit gate as creation. The anchor stays fixed at
+ * creation regardless — repointing it would silently change what the filter
+ * matches, which deserves a new filter instead.
  */
 export function FilterEditor({
 	accountId,
@@ -142,14 +147,26 @@ export function FilterEditor({
 	const changeName = (name: string) =>
 		setRule((current) => ({ ...current, name }));
 
+	const changeScope = (scope: RuleScope) =>
+		setRule((current) => ({
+			...current,
+			scope,
+			until: scope === "until" ? current.until : undefined,
+		}));
+
+	const changeUntil = (until: string) =>
+		setRule((current) => ({ ...current, until }));
+
 	const commit = () => {
-		const predicateChanged = ruleChangesPredicateOrAction(rule, original);
+		const rulesChanged =
+			ruleChangesPredicateOrAction(rule, original) ||
+			ruleChangesScopeOrExpiry(rule, original);
 		const body = buildUpdateFilterInput(rule, original);
 		if (Object.keys(body).length === 0) {
 			onClose();
 			return;
 		}
-		setOfferReapply(predicateChanged);
+		setOfferReapply(rulesChanged);
 		update.updateFilter(body);
 	};
 
@@ -188,13 +205,15 @@ export function FilterEditor({
 			rule={rule}
 			folders={folders}
 			preview={preview}
-			// The update endpoint carries no anchor, so a widen can be neither added
-			// nor removed here: the "…and similar" add is never offered, and the
-			// existing chip is display-only (no onRemoveWiden). `semanticUnavailable`
-			// only drives the chip's inactive styling via `filterToRule`.
+			// The update endpoint carries no anchor field at all (reader #266), so a
+			// widen can be neither added nor removed here: the "…and similar" add is
+			// never offered, and the existing chip is display-only (no
+			// onRemoveWiden — anchorLocked enforces that regardless).
+			// `semanticUnavailable` only drives the chip's inactive styling via
+			// `filterToRule`.
 			semanticAvailable={false}
 			clauseFields={SUPPORTED_CLAUSE_FIELDS}
-			lifecycleLocked
+			anchorLocked
 			clauseEdit={clauseEdit}
 			onStartAddClause={startAddClause}
 			onStartEditClause={startEditClause}
@@ -207,6 +226,8 @@ export function FilterEditor({
 			onChangeMove={changeMove}
 			onCreateFolder={createFolder}
 			onChangeName={changeName}
+			onChangeScope={changeScope}
+			onChangeUntil={changeUntil}
 			onCommit={commit}
 			onCancel={onClose}
 		/>

package/src/hooks/useCreateMailbox.render.test.ts

@@ -1,9 +1,11 @@
 /**
- * useCreateMailbox.createFolder — the shared create seam the kit surfaces call.
- * It validates the typed name against the account's current folders with the
- * same IMAP-aware rules the settings form uses, and rejects with the
- * human-readable reason before any request. The mailbox list is seeded into the
- * query cache the hook reads, so validation runs against real paths.
+ * useCreateMailbox.createFolder — the shared create seam the kit surfaces call
+ * for a dependent write. It validates the typed name against the account's
+ * current folders with the same IMAP-aware rules the settings form uses, rejects
+ * with the human-readable reason before any request, then waits for the mail
+ * server to confirm the folder before resolving — so a filter or a move never
+ * binds to a still-pending row. The mailbox list is seeded into the query cache
+ * the hook reads, so validation runs against real paths.
  */
 
 import assert from "node:assert/strict";
@@ -13,8 +15,10 @@ import type {
 	MailboxOperationsListMailboxesResponse,
 	RemitImapMailboxResponse,
 } from "@remit/api-http-client/types.gen.ts";
+import { MailboxSyncStatus } from "@remit/domain-enums";
 import type { FolderOption } from "@remit/ui";
 import { act, createElement } from "react";
+import { MAILBOX_SYNC_FAILED_MESSAGE } from "../lib/mailbox-sync-wait";
 import { createDomHarness, type DomHarness } from "../test-support/dom";
 import { type HttpMock, mockFetch } from "../test-support/http";
 import { useCreateMailbox } from "./useCreateMailbox";
@@ -23,7 +27,9 @@ const ACCOUNT = "acc-1";
 
 let harness: DomHarness | undefined;
 let http: HttpMock | undefined;
-let createFolder: ((name: string) => Promise<FolderOption>) | undefined;
+let createFolder:
+	| ((name: string, signal?: AbortSignal) => Promise<FolderOption>)
+	| undefined;
 
 afterEach(() => {
 	harness?.close();
@@ -49,13 +55,23 @@ function Probe() {
 	return null;
 }
 
-const mount = (items: RemitImapMailboxResponse[]) => {
+const mount = (
+	items: RemitImapMailboxResponse[],
+	createdSyncStatus: RemitImapMailboxResponse["syncStatus"] = MailboxSyncStatus.synced,
+) => {
+	const created: RemitImapMailboxResponse[] = [];
 	http = mockFetch((call) => {
 		if (call.method === "POST") {
 			const body = call.body as { fullPath: string };
+			created.push({
+				mailboxId: `mbx-${body.fullPath}`,
+				accountId: ACCOUNT,
+				fullPath: body.fullPath,
+				syncStatus: createdSyncStatus,
+			} as RemitImapMailboxResponse);
 			return { mailboxId: `mbx-${body.fullPath}`, fullPath: body.fullPath };
 		}
-		return { items };
+		return { items: [...items, ...created] };
 	});
 	harness = createDomHarness();
 	harness.queryClient.setQueryData<MailboxOperationsListMailboxesResponse>(
@@ -114,7 +130,7 @@ describe("useCreateMailbox.createFolder validation", () => {
 		assert.equal(postCount(), 0);
 	});
 
-	it("passes a valid name through to the create request and maps the result", async () => {
+	it("passes a valid name through and resolves once the folder is confirmed synced", async () => {
 		mount([mailbox("INBOX", "/")]);
 		let result: FolderOption | undefined;
 		await act(async () => {
@@ -126,6 +142,90 @@ describe("useCreateMailbox.createFolder validation", () => {
 			fullPath: "Taxes",
 			namespaceType: "personal",
 		});
+		// It polled the list after the create to confirm the folder before resolving.
+		const gets = (http?.calls ?? []).filter((call) => call.method === "GET");
+		assert.ok(gets.length >= 1, "polls the mailbox list for confirmation");
 		assert.equal(result?.label, "Taxes");
 	});
+
+	it("rejects — no folder to bind a dependent write to — when the create is reported failed", async () => {
+		mount([mailbox("INBOX", "/")], MailboxSyncStatus.failed);
+		let caught: unknown;
+		await act(async () => {
+			caught = await createFolder?.("Taxes").then(
+				() => undefined,
+				(error: unknown) => error,
+			);
+		});
+		assert.ok(caught instanceof Error);
+		assert.equal(caught.message, MAILBOX_SYNC_FAILED_MESSAGE);
+	});
+
+	it("retry resumes the wait on the folder it already made — no second create, no 'already exists'", async () => {
+		// The created folder is reported failed on the first attempt, then synced.
+		let status: RemitImapMailboxResponse["syncStatus"] =
+			MailboxSyncStatus.failed;
+		const created: RemitImapMailboxResponse[] = [];
+		http = mockFetch((call) => {
+			if (call.method === "POST") {
+				const body = call.body as { fullPath: string };
+				created.push({
+					mailboxId: `mbx-${body.fullPath}`,
+					accountId: ACCOUNT,
+					fullPath: body.fullPath,
+				} as RemitImapMailboxResponse);
+				return { mailboxId: `mbx-${body.fullPath}`, fullPath: body.fullPath };
+			}
+			return {
+				items: [
+					mailbox("INBOX", "/"),
+					...created.map((entry) => ({ ...entry, syncStatus: status })),
+				],
+			};
+		});
+		harness = createDomHarness();
+		harness.queryClient.setQueryData<MailboxOperationsListMailboxesResponse>(
+			mailboxOperationsListMailboxesQueryKey({ path: { accountId: ACCOUNT } }),
+			{ items: [mailbox("INBOX", "/")] },
+		);
+		harness.renderApp(createElement(Probe));
+
+		let first: unknown;
+		await act(async () => {
+			first = await createFolder?.("Taxes").then(
+				() => undefined,
+				(error: unknown) => error,
+			);
+		});
+		assert.ok(first instanceof Error);
+		assert.equal(first.message, MAILBOX_SYNC_FAILED_MESSAGE);
+
+		// The server confirms; the user presses "Create folder" again, same name.
+		status = MailboxSyncStatus.synced;
+		let result: FolderOption | undefined;
+		await act(async () => {
+			result = await createFolder?.("Taxes");
+		});
+		assert.equal(result?.label, "Taxes");
+
+		// Exactly one create across both attempts — the retry resumed, it did not
+		// re-validate (which would throw "already exists") or re-POST.
+		const posts = (http?.calls ?? []).filter((call) => call.method === "POST");
+		assert.equal(posts.length, 1);
+	});
+
+	it("abort stops the wait so a folder that confirms later never resolves", async () => {
+		mount([mailbox("INBOX", "/")], MailboxSyncStatus.pending);
+		const controller = new AbortController();
+		let caught: unknown;
+		await act(async () => {
+			const promise = createFolder?.("Taxes", controller.signal);
+			controller.abort();
+			caught = await promise?.then(
+				() => undefined,
+				(error: unknown) => error,
+			);
+		});
+		assert.equal((caught as { name?: string })?.name, "AbortError");
+	});
 });

package/src/hooks/useCreateMailbox.ts

@@ -5,21 +5,40 @@ import {
 } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
 import type { FolderOption } from "@remit/ui";
 import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
-import { useCallback } from "react";
+import { useCallback, useRef } from "react";
 import { getMailboxDisplayName } from "@/lib/folder-roles";
+import { waitForMailboxSynced } from "@/lib/mailbox-sync-wait";
 import { composeFolderPath, validateNewFolderName } from "@/lib/new-folder";
 
 /**
  * Creates a mailbox for an account and refreshes the folder list on success.
  * The backend creates the row with a pending sync status and queues the IMAP
- * create, so the folder is usable as a move destination immediately.
+ * create.
  *
- * `createFolder` takes a leaf name, validates it against the account's current
- * folders with the same IMAP-aware rules the settings form uses (non-empty, no
- * hierarchy delimiter, no collision — INBOX case-insensitive), and rejects with
- * the human-readable reason before any request. The kit surfaces that pick the
- * result render that rejection inline. `mutation` is exposed for callers that
- * drive their own form state and error surface.
+ * `createFolder` is the seam for dependent writes: a folder created so a filter
+ * can move mail into it, or so a move can land mail there. It takes a leaf name,
+ * validates it against the account's current folders with the same IMAP-aware
+ * rules the settings form uses (non-empty, no hierarchy delimiter, no collision —
+ * INBOX case-insensitive), and rejects with the human-readable reason before any
+ * request. It then WAITS for the mail server to confirm the folder before
+ * resolving — a folder is not a valid target until it exists on the server, and
+ * binding a filter or a move to a still-pending row races the folder into
+ * existence and cannot report a create that fails. It resolves with the confirmed
+ * folder (carrying the path the server normalized to), rejects with a distinct
+ * message when the create fails or never confirms, and the kit surfaces that
+ * render either the "Creating folder…" wait or the failure inline.
+ *
+ * Retry is a resume, not a re-create: a create that timed out or failed leaves
+ * the row already made, so pressing "Create folder" again calls `createFolder`
+ * with the same name — which resumes the wait on the mailboxId it already made
+ * rather than re-validating (the pending row would collide as "already exists")
+ * and re-POSTing. The mailboxId is carried per-name until the folder confirms.
+ *
+ * `createFolder` takes an `AbortSignal` the surface aborts on unmount/cancel/
+ * close, so a folder that confirms after the surface is gone resolves nothing.
+ *
+ * `mutation` is exposed for callers that drive their own form state and want the
+ * optimistic, non-waiting create (the standalone settings create).
  */
 export function useCreateMailbox(accountId: string) {
 	const queryClient = useQueryClient();
@@ -39,26 +58,48 @@ export function useCreateMailbox(accountId: string) {
 		},
 	});
 
+	// fullPath -> mailboxId for a folder created but not yet confirmed, so a retry
+	// resumes the wait on it instead of re-creating. Cleared once it confirms.
+	const pendingByPath = useRef(new Map<string, string>());
+
 	const createFolder = useCallback(
-		async (name: string): Promise<FolderOption> => {
-			const items = data?.items ?? [];
-			const delimiter = items[0]?.hierarchyDelimiter ?? "/";
-			const problem = validateNewFolderName({
-				name,
-				delimiter,
-				existingPaths: items.map((item) => item.fullPath),
-			});
-			if (problem) throw new Error(problem);
-			const mailbox = await mutation.mutateAsync({
-				path: { accountId },
-				body: { fullPath: composeFolderPath(name), namespaceType: "personal" },
+		async (name: string, signal?: AbortSignal): Promise<FolderOption> => {
+			const fullPath = composeFolderPath(name);
+			let mailboxId = pendingByPath.current.get(fullPath);
+			if (!mailboxId) {
+				const items = data?.items ?? [];
+				const delimiter = items[0]?.hierarchyDelimiter ?? "/";
+				const problem = validateNewFolderName({
+					name,
+					delimiter,
+					existingPaths: items.map((item) => item.fullPath),
+				});
+				if (problem) throw new Error(problem);
+				const mailbox = await mutation.mutateAsync({
+					path: { accountId },
+					body: { fullPath, namespaceType: "personal" },
+				});
+				mailboxId = mailbox.mailboxId;
+				pendingByPath.current.set(fullPath, mailboxId);
+			}
+			const confirmed = await waitForMailboxSynced({
+				mailboxId,
+				signal,
+				fetchMailboxes: async () => {
+					const response = await queryClient.fetchQuery({
+						...mailboxOperationsListMailboxesOptions({ path: { accountId } }),
+						staleTime: 0,
+					});
+					return response.items ?? [];
+				},
 			});
+			pendingByPath.current.delete(fullPath);
 			return {
-				id: mailbox.mailboxId,
-				label: getMailboxDisplayName(mailbox.fullPath),
+				id: confirmed.mailboxId,
+				label: getMailboxDisplayName(confirmed.fullPath),
 			};
 		},
-		[mutation, accountId, data],
+		[mutation, accountId, data, queryClient],
 	);
 
 	return { createFolder, mutation };

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

@@ -0,0 +1,186 @@
+/**
+ * waitForMailboxSynced — the gate a dependent write (a filter, a move) holds
+ * behind while a freshly-created folder is confirmed on the mail server. It
+ * resolves only on `synced`, rejects distinctly on `failed` and on timeout, and
+ * keeps polling while the row is still `pending` or not yet listed.
+ */
+
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { MailboxSyncStatus } from "@remit/domain-enums";
+import {
+	MAILBOX_SYNC_FAILED_MESSAGE,
+	MAILBOX_SYNC_TIMEOUT_MESSAGE,
+	type MailboxSyncSignal,
+	waitForMailboxSynced,
+} from "./mailbox-sync-wait.js";
+
+const row = (
+	mailboxId: string,
+	syncStatus?: MailboxSyncSignal["syncStatus"],
+	extra: Record<string, unknown> = {},
+): MailboxSyncSignal & Record<string, unknown> => ({
+	mailboxId,
+	syncStatus,
+	...extra,
+});
+
+const noDelay = () => Promise.resolve();
+
+describe("waitForMailboxSynced", () => {
+	it("resolves with the confirmed row once it reaches synced", async () => {
+		const responses = [
+			[row("mbx-1", MailboxSyncStatus.pending)],
+			[row("mbx-1", MailboxSyncStatus.pending)],
+			[row("mbx-1", MailboxSyncStatus.synced, { fullPath: "Server/Receipts" })],
+		];
+		let call = 0;
+		const result = await waitForMailboxSynced({
+			mailboxId: "mbx-1",
+			fetchMailboxes: async () => responses[call++],
+			delay: noDelay,
+		});
+		assert.equal(result.syncStatus, MailboxSyncStatus.synced);
+		assert.equal(
+			(result as Record<string, unknown>).fullPath,
+			"Server/Receipts",
+		);
+		assert.equal(call, 3);
+	});
+
+	it("keeps polling while the row is not yet listed", async () => {
+		const responses = [
+			[] as MailboxSyncSignal[],
+			[row("other", MailboxSyncStatus.synced)],
+			[row("mbx-1", MailboxSyncStatus.synced)],
+		];
+		let call = 0;
+		const result = await waitForMailboxSynced({
+			mailboxId: "mbx-1",
+			fetchMailboxes: async () => responses[call++],
+			delay: noDelay,
+		});
+		assert.equal(result.mailboxId, "mbx-1");
+		assert.equal(call, 3);
+	});
+
+	it("rejects with the failure message when the create is reported failed", async () => {
+		await assert.rejects(
+			waitForMailboxSynced({
+				mailboxId: "mbx-1",
+				fetchMailboxes: async () => [row("mbx-1", MailboxSyncStatus.failed)],
+				delay: noDelay,
+			}),
+			(error: unknown) =>
+				error instanceof Error && error.message === MAILBOX_SYNC_FAILED_MESSAGE,
+		);
+	});
+
+	it("rejects with the timeout message when the row never confirms", async () => {
+		let clock = 0;
+		let fetches = 0;
+		await assert.rejects(
+			waitForMailboxSynced({
+				mailboxId: "mbx-1",
+				fetchMailboxes: async () => {
+					fetches += 1;
+					return [row("mbx-1", MailboxSyncStatus.pending)];
+				},
+				timeoutMs: 30_000,
+				pollIntervalMs: 1_000,
+				now: () => clock,
+				delay: async (ms) => {
+					clock += ms;
+				},
+			}),
+			(error: unknown) =>
+				error instanceof Error &&
+				error.message === MAILBOX_SYNC_TIMEOUT_MESSAGE,
+		);
+		assert.ok(fetches > 1, "polls more than once before timing out");
+	});
+
+	it("does not treat failed as timeout even past the deadline", async () => {
+		let clock = 100_000;
+		await assert.rejects(
+			waitForMailboxSynced({
+				mailboxId: "mbx-1",
+				fetchMailboxes: async () => [row("mbx-1", MailboxSyncStatus.failed)],
+				timeoutMs: 1,
+				now: () => clock++,
+				delay: noDelay,
+			}),
+			(error: unknown) =>
+				error instanceof Error && error.message === MAILBOX_SYNC_FAILED_MESSAGE,
+		);
+	});
+
+	const isAbort = (error: unknown): boolean =>
+		typeof error === "object" &&
+		error !== null &&
+		(error as { name?: unknown }).name === "AbortError";
+
+	it("rejects without polling when the signal is already aborted", async () => {
+		const controller = new AbortController();
+		controller.abort();
+		let fetches = 0;
+		await assert.rejects(
+			waitForMailboxSynced({
+				mailboxId: "mbx-1",
+				signal: controller.signal,
+				fetchMailboxes: async () => {
+					fetches += 1;
+					return [row("mbx-1", MailboxSyncStatus.pending)];
+				},
+				delay: noDelay,
+			}),
+			isAbort,
+		);
+		assert.equal(fetches, 0);
+	});
+
+	it("stops polling and rejects when the signal aborts mid-wait", async () => {
+		const controller = new AbortController();
+		let fetches = 0;
+		await assert.rejects(
+			waitForMailboxSynced({
+				mailboxId: "mbx-1",
+				signal: controller.signal,
+				fetchMailboxes: async () => {
+					fetches += 1;
+					if (fetches === 2) controller.abort();
+					return [row("mbx-1", MailboxSyncStatus.pending)];
+				},
+				delay: noDelay,
+			}),
+			isAbort,
+		);
+		assert.equal(fetches, 2);
+	});
+
+	it("resolves across the real timer delay between polls", async () => {
+		const responses = [
+			[row("mbx-1", MailboxSyncStatus.pending)],
+			[row("mbx-1", MailboxSyncStatus.synced)],
+		];
+		let call = 0;
+		const result = await waitForMailboxSynced({
+			mailboxId: "mbx-1",
+			pollIntervalMs: 1,
+			fetchMailboxes: async () => responses[call++],
+		});
+		assert.equal(result.syncStatus, MailboxSyncStatus.synced);
+	});
+
+	it("aborts an in-progress real timer delay", async () => {
+		const controller = new AbortController();
+		const pending = waitForMailboxSynced({
+			mailboxId: "mbx-1",
+			signal: controller.signal,
+			pollIntervalMs: 10_000,
+			fetchMailboxes: async () => [row("mbx-1", MailboxSyncStatus.pending)],
+		});
+		setTimeout(() => controller.abort(), 5);
+		await assert.rejects(pending, isAbort);
+	});
+});

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

@@ -0,0 +1,98 @@
+import { MailboxSyncStatus } from "@remit/domain-enums";
+
+type MailboxSyncStatusValue =
+	(typeof MailboxSyncStatus)[keyof typeof MailboxSyncStatus];
+
+/**
+ * A folder created for a dependent write — a filter that will move mail into it,
+ * or a move that lands mail there — is not usable the instant the create is
+ * queued: the row exists locally with `syncStatus: pending`, and the folder does
+ * not exist on the mail server until the imap-worker confirms the create and
+ * flips it to `synced`. Binding the dependent write to a `pending` row races the
+ * folder into existence across separate FIFO queues and cannot report a create
+ * that fails. This waits for the confirmation before the dependent write runs.
+ *
+ * The standalone create (a folder made in settings with no dependent write) does
+ * not use this — it may stay optimistic. The wait is only for the dependent case.
+ *
+ * The wait honours an `AbortSignal`: the surface that started the create passes
+ * one and aborts it on unmount/cancel/close, so a folder that confirms after the
+ * surface is gone never resolves and never fires the dependent bind or move.
+ */
+
+/** The read fields the wait needs off a mailbox row. */
+export interface MailboxSyncSignal {
+	mailboxId: string;
+	syncStatus?: MailboxSyncStatusValue;
+}
+
+export interface WaitForMailboxSyncedOptions<T extends MailboxSyncSignal> {
+	/** Reads the current mailbox rows; called once per poll (forces a fresh read). */
+	fetchMailboxes: () => Promise<readonly T[]>;
+	/** The row to wait on. */
+	mailboxId: string;
+	/** Aborts the wait; a late confirmation after abort resolves nothing. */
+	signal?: AbortSignal;
+	/** How long to wait for confirmation before giving up. */
+	timeoutMs?: number;
+	/** Gap between polls. */
+	pollIntervalMs?: number;
+	/** Injectable clock/sleep for tests. */
+	delay?: (ms: number, signal?: AbortSignal) => Promise<void>;
+	now?: () => number;
+}
+
+export const MAILBOX_SYNC_TIMEOUT_MS = 30_000;
+export const MAILBOX_SYNC_POLL_INTERVAL_MS = 1_000;
+
+export const MAILBOX_SYNC_FAILED_MESSAGE =
+	"The folder couldn't be created on the mail server. Please try again.";
+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> =>
+	new Promise((resolve, reject) => {
+		if (signal?.aborted) {
+			reject(signal.reason);
+			return;
+		}
+		const timer = setTimeout(() => {
+			signal?.removeEventListener("abort", onAbort);
+			resolve();
+		}, ms);
+		const onAbort = () => {
+			clearTimeout(timer);
+			reject(signal?.reason);
+		};
+		signal?.addEventListener("abort", onAbort, { once: true });
+	});
+
+/**
+ * Resolve with the mailbox row once its `syncStatus` reaches `synced` — the
+ * server-confirmed row, carrying the path the server normalized the create to.
+ * Reject with a failure message when the create is reported `failed`, with a
+ * distinct timeout message when it never confirms within `timeoutMs`, and with
+ * the signal's reason (an `AbortError`) when `signal` aborts. A row that is still
+ * `pending` (or not yet in the list) keeps the poll running.
+ */
+export async function waitForMailboxSynced<T extends MailboxSyncSignal>({
+	fetchMailboxes,
+	mailboxId,
+	signal,
+	timeoutMs = MAILBOX_SYNC_TIMEOUT_MS,
+	pollIntervalMs = MAILBOX_SYNC_POLL_INTERVAL_MS,
+	delay = defaultDelay,
+	now = Date.now,
+}: WaitForMailboxSyncedOptions<T>): Promise<T> {
+	const deadline = now() + timeoutMs;
+	for (;;) {
+		signal?.throwIfAborted();
+		const mailboxes = await fetchMailboxes();
+		const mailbox = mailboxes.find((entry) => entry.mailboxId === mailboxId);
+		if (mailbox?.syncStatus === MailboxSyncStatus.synced) return mailbox;
+		if (mailbox?.syncStatus === MailboxSyncStatus.failed)
+			throw new Error(MAILBOX_SYNC_FAILED_MESSAGE);
+		if (now() >= deadline) throw new Error(MAILBOX_SYNC_TIMEOUT_MESSAGE);
+		await delay(pollIntervalMs, signal);
+	}
+}

package/src/lib/organize/filter-edit-model.test.ts

@@ -7,6 +7,7 @@ import {
 	expiresAtToPickedDate,
 	filterToRule,
 	ruleChangesPredicateOrAction,
+	ruleChangesScopeOrExpiry,
 } from "./filter-edit-model";
 
 const filter = (
@@ -132,6 +133,48 @@ describe("ruleChangesPredicateOrAction", () => {
 	});
 });
 
+describe("ruleChangesScopeOrExpiry (reader #266)", () => {
+	const base = filterToRule(filter());
+
+	it("is false for an identical rule and for a rename only", () => {
+		assert.equal(ruleChangesScopeOrExpiry(base, base), false);
+		assert.equal(
+			ruleChangesScopeOrExpiry({ ...base, name: "New name" }, base),
+			false,
+		);
+	});
+
+	it("is true when scope moves to until-a-date", () => {
+		assert.equal(
+			ruleChangesScopeOrExpiry(
+				{ ...base, scope: "until", until: "2027-01-01" },
+				base,
+			),
+			true,
+		);
+	});
+
+	it("is true when only the until date changes", () => {
+		const untilBase = filterToRule(
+			filter({ scope: "Temporary", expiresAt: "2027-01-01T23:59:59+00:00" }),
+		);
+		assert.equal(
+			ruleChangesScopeOrExpiry(
+				{ ...untilBase, until: "2027-06-01" },
+				untilBase,
+			),
+			true,
+		);
+	});
+
+	it("is false when moving between standing and once-equivalent scopes with no until set", () => {
+		assert.equal(
+			ruleChangesScopeOrExpiry({ ...base, scope: "standing" }, base),
+			false,
+		);
+	});
+});
+
 describe("buildUpdateFilterInput", () => {
 	const original = filterToRule(filter());
 
@@ -172,4 +215,47 @@ describe("buildUpdateFilterInput", () => {
 	it("is empty when nothing changed", () => {
 		assert.deepEqual(buildUpdateFilterInput(original, original), {});
 	});
+
+	it("sends scope Temporary and a derived expiresAt when moving to until-a-date (reader #266)", () => {
+		const changed: FilterRule = {
+			...original,
+			scope: "until",
+			until: "2027-03-04",
+		};
+		const body = buildUpdateFilterInput(changed, original);
+		assert.equal(body.scope, "Temporary");
+		assert.match(body.expiresAt ?? "", /^2027-03-04T/);
+		assert.equal("matchOperator" in body, false);
+		assert.equal("name" in body, false);
+	});
+
+	it("sends scope Standing with no expiresAt when moving off a Temporary filter", () => {
+		const temporaryOriginal = filterToRule(
+			filter({ scope: "Temporary", expiresAt: "2027-01-01T23:59:59+00:00" }),
+		);
+		const changed: FilterRule = { ...temporaryOriginal, scope: "standing" };
+		const body = buildUpdateFilterInput(changed, temporaryOriginal);
+		assert.equal(body.scope, "Standing");
+		assert.equal("expiresAt" in body, false);
+	});
+
+	it("sends scope and the new expiresAt when only the date changes", () => {
+		const temporaryOriginal = filterToRule(
+			filter({ scope: "Temporary", expiresAt: "2027-01-01T23:59:59+00:00" }),
+		);
+		const changed: FilterRule = { ...temporaryOriginal, until: "2027-06-01" };
+		const body = buildUpdateFilterInput(changed, temporaryOriginal);
+		assert.equal(body.scope, "Temporary");
+		assert.match(body.expiresAt ?? "", /^2027-06-01T/);
+	});
+
+	it("carries no anchor field — the editor never has one to send (reader #266)", () => {
+		const changed: FilterRule = {
+			...original,
+			scope: "until",
+			until: "2027-03-04",
+		};
+		const body = buildUpdateFilterInput(changed, original);
+		assert.equal("anchorMessageId" in body, false);
+	});
 });

package/src/lib/organize/filter-edit-model.ts

@@ -3,6 +3,7 @@ import type {
 	RemitImapUpdateFilterInput,
 } from "@remit/api-http-client/types.gen.ts";
 import type { FilterRule, RuleClause } from "@remit/ui";
+import { pickedDateToExpiresAt } from "./filter-status";
 import { NO_ACTION } from "./organize-model";
 
 /**
@@ -79,13 +80,34 @@ export const ruleChangesPredicateOrAction = (
 	original: FilterRule,
 ): boolean => predicateActionKey(rule) !== predicateActionKey(original);
 
+const scopeExpiryKey = (rule: FilterRule): string =>
+	JSON.stringify({
+		scope: rule.scope === "until" ? "until" : "standing",
+		until: rule.scope === "until" ? (rule.until ?? "") : "",
+	});
+
+/**
+ * Whether the edited rule changes scope (standing ↔ until-a-date) or the date
+ * itself, versus the one it was loaded from (reader #266). Scope and expiry
+ * are mutable on an existing filter, unlike the anchor, and a change here
+ * bumps `ruleChangedAt` the same way a predicate/action change does — moving a
+ * lapsed filter back to Standing (or extending its date) is the same kind of
+ * "the user just reasserted this rule" moment, and re-offers the back-apply so
+ * mail delivered while the filter sat inactive can be caught up.
+ */
+export const ruleChangesScopeOrExpiry = (
+	rule: FilterRule,
+	original: FilterRule,
+): boolean => scopeExpiryKey(rule) !== scopeExpiryKey(original);
+
 /**
  * The PATCH body for an edited filter. A cosmetic rename sends `{ name }` only,
- * so the server's `changesPredicateOrAction` guard leaves `ruleChangedAt`
+ * so the server's `changesRuleAssertion` guard leaves `ruleChangedAt`
  * untouched (RFC 034 Decision 3.2). A predicate or action change sends the
- * operator, clauses, and move target, which bumps `ruleChangedAt`. Fields the
- * editor never touches — the label action, the immutable scope/expiry — are
- * absent from the patch, so the partial update preserves them.
+ * operator, clauses, and move target; a scope or expiry change sends `scope`
+ * and, for the `until` scope, `expiresAt` (reader #266) — either bumps
+ * `ruleChangedAt`. The label action and the anchor are never in the editor's
+ * gift, so they never enter the patch; the partial update preserves them.
  */
 export const buildUpdateFilterInput = (
 	rule: FilterRule,
@@ -102,5 +124,11 @@ export const buildUpdateFilterInput = (
 		}));
 		body.actionMailboxId = rule.moveMailboxId ?? NO_ACTION;
 	}
+	if (ruleChangesScopeOrExpiry(rule, original)) {
+		body.scope = rule.scope === "until" ? "Temporary" : "Standing";
+		if (rule.scope === "until") {
+			body.expiresAt = pickedDateToExpiresAt(rule.until ?? "");
+		}
+	}
 	return body;
 };