@remit/web-client 0.0.63 → 0.0.64

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/web-client",
-  "version": "0.0.63",
+  "version": "0.0.64",
   "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/MessageList.tsx

@@ -474,6 +474,19 @@ export const MessageList = ({
 	// handled the click (caller should preventDefault and skip navigation);
 	// false for a plain click (caller lets the Link navigate).
 	const orderedIds = useMemo(() => threads.map((t) => t.messageId), [threads]);
+
+	// Sender addresses of the checked rows, for the organize widen's literal
+	// fallback when this deployment ships no vector pipeline (the sheet matches
+	// all mail from these senders). Read off the already-loaded thread rows, so
+	// no extra round-trip; the widen hook dedupes.
+	const selectedSenders = useMemo(() => {
+		const emails: string[] = [];
+		for (const thread of threads) {
+			if (!selectedIds.has(thread.messageId)) continue;
+			if (thread.fromEmail) emails.push(thread.fromEmail);
+		}
+		return emails;
+	}, [threads, selectedIds]);
 	const handleRowSelect = useCallback(
 		(messageId: string, modifiers: SelectionModifiers): boolean => {
 			if (modifiers.shiftKey) {
@@ -1256,6 +1269,7 @@ export const MessageList = ({
 				accountId={accountId}
 				mailboxId={mailboxId}
 				selectedMessageIds={Array.from(selectedIds)}
+				selectedSenders={selectedSenders}
 				junkMailboxId={junkMailboxId}
 				onClose={() => {
 					setMobileOrganizeEntry(null);
@@ -1497,6 +1511,7 @@ export const MessageList = ({
 					accountId={accountId}
 					mailboxId={mailboxId}
 					selectedMessageIds={Array.from(selectedIds)}
+					selectedSenders={selectedSenders}
 					onClose={() => setOrganizeOpen(false)}
 				/>
 			)}

package/src/components/mail/organize/MobileOrganizeFlow.render.test.ts

@@ -25,6 +25,7 @@ const render = (entry: OrganizeEntry) =>
 					accountId: "acc-1",
 					mailboxId: "mbx-inbox",
 					selectedMessageIds: ["msg-1", "msg-2"],
+					selectedSenders: ["npm@github.com"],
 					onClose: () => undefined,
 				}),
 			),

package/src/components/mail/organize/MobileOrganizeFlow.tsx

@@ -3,7 +3,7 @@ import { BottomSheet, Button } from "@remit/ui";
 import { useQuery } from "@tanstack/react-query";
 import { Loader2 } from "lucide-react";
 import { useEffect, useMemo, useState } from "react";
-import { useOrganizePreview } from "@/hooks/useOrganizePreview";
+import { useOrganizeWiden } from "@/hooks/useOrganizeWiden";
 import { getMailboxDisplayName } from "@/lib/folder-roles";
 import { buildMoveTargets } from "@/lib/move-targets";
 import {
@@ -20,6 +20,11 @@ interface MobileOrganizeFlowProps {
 	accountId: string;
 	mailboxId: string;
 	selectedMessageIds: string[];
+	/**
+	 * Sender addresses of the selected messages, driving the literal fallback on
+	 * a deployment without the vector pipeline (semantic-capability.ts).
+	 */
+	selectedSenders: string[];
 	junkMailboxId?: string;
 	/** Close the flow and return to the list — dismiss, "Not now", and Done all use it. */
 	onClose: () => void;
@@ -50,6 +55,7 @@ export function MobileOrganizeFlow({
 	accountId,
 	mailboxId,
 	selectedMessageIds,
+	selectedSenders,
 	junkMailboxId,
 	onClose,
 }: MobileOrganizeFlowProps) {
@@ -60,15 +66,16 @@ export function MobileOrganizeFlow({
 		preview,
 		matchedCount,
 		semanticUnavailable,
+		senders,
+		matchPredicate,
 		isPending,
 		isError,
 		error,
-	} = useOrganizePreview(accountId);
+	} = useOrganizeWiden(accountId, anchorMessageId, selectedSenders);
 
 	useEffect(() => {
-		if (!anchorMessageId) return;
-		preview({ anchorMessageId, matchOperator: "And", literalClauses: [] });
-	}, [anchorMessageId, preview]);
+		preview();
+	}, [preview]);
 
 	const { data: mailboxesData } = useQuery({
 		...mailboxOperationsListMailboxesOptions({ path: { accountId } }),
@@ -122,12 +129,13 @@ export function MobileOrganizeFlow({
 					accountId={accountId}
 					mailboxId={mailboxId}
 					selectedMessageIds={selectedMessageIds}
-					anchorMessageId={anchorMessageId}
+					matchPredicate={matchPredicate}
 					matchedCount={stage.matchedCount}
 					initialScope={seed?.scope}
 					seedMailboxId={seed?.moveMailboxId}
 					fallback={stage.fallback}
 					semanticUnavailable={semanticUnavailable}
+					senders={senders}
 					onClose={onClose}
 				/>
 			)}

package/src/components/mail/organize/OrganizeDialog.render.test.ts

@@ -20,6 +20,7 @@ const render = (open: boolean) =>
 				accountId: "acc-1",
 				mailboxId: "mbx-inbox",
 				selectedMessageIds: ["msg-1", "msg-2"],
+				selectedSenders: ["npm@github.com"],
 				onClose: () => undefined,
 			}),
 		) as never,

package/src/components/mail/organize/OrganizeDialog.tsx

@@ -1,7 +1,7 @@
 import { Button, Dialog } from "@remit/ui";
 import { Loader2 } from "lucide-react";
 import { useEffect } from "react";
-import { useOrganizePreview } from "@/hooks/useOrganizePreview";
+import { useOrganizeWiden } from "@/hooks/useOrganizeWiden";
 import { OrganizePanel } from "./OrganizePanel";
 
 interface OrganizeDialogProps {
@@ -9,6 +9,11 @@ interface OrganizeDialogProps {
 	accountId: string;
 	mailboxId: string;
 	selectedMessageIds: string[];
+	/**
+	 * Sender addresses of the selected messages, driving the literal fallback on
+	 * a deployment without the vector pipeline (semantic-capability.ts).
+	 */
+	selectedSenders: string[];
 	onClose: () => void;
 }
 
@@ -23,6 +28,7 @@ export function OrganizeDialog({
 	accountId,
 	mailboxId,
 	selectedMessageIds,
+	selectedSenders,
 	onClose,
 }: OrganizeDialogProps) {
 	const anchorMessageId = selectedMessageIds[0];
@@ -31,19 +37,17 @@ export function OrganizeDialog({
 		reset,
 		matchedCount,
 		semanticUnavailable,
+		senders,
+		matchPredicate,
 		isPending,
 		isError,
 		error,
-	} = useOrganizePreview(accountId);
+	} = useOrganizeWiden(accountId, anchorMessageId, selectedSenders);
 
 	useEffect(() => {
-		if (!open || !anchorMessageId) return;
-		preview({
-			anchorMessageId,
-			matchOperator: "And",
-			literalClauses: [],
-		});
-	}, [open, anchorMessageId, preview]);
+		if (!open) return;
+		preview();
+	}, [open, preview]);
 
 	const handleClose = () => {
 		reset();
@@ -80,9 +84,10 @@ export function OrganizeDialog({
 					accountId={accountId}
 					mailboxId={mailboxId}
 					selectedMessageIds={selectedMessageIds}
-					anchorMessageId={anchorMessageId}
+					matchPredicate={matchPredicate}
 					matchedCount={matchedCount}
 					semanticUnavailable={semanticUnavailable}
+					senders={senders}
 					onClose={handleClose}
 				/>
 			)}

package/src/components/mail/organize/OrganizePanel.progress.test.ts

@@ -0,0 +1,113 @@
+/**
+ * The back-apply progress copy. On a deployment without the vector pipeline the
+ * "all like these" job moves the sender-matched set, so the in-progress line must
+ * state the sender semantics — never "similar mail" (#250's honesty
+ * requirement). The semantic path keeps the "similar mail" wording.
+ */
+
+import assert from "node:assert/strict";
+import { afterEach, describe, it } from "node:test";
+import { mailboxOperationsListMailboxesQueryKey } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import { createElement } from "react";
+import type { OrganizeMatchPredicate } from "../../../lib/organize/sender-fallback";
+import { createDomHarness, type DomHarness } from "../../../test-support/dom";
+import { makeMailbox } from "../../../test-support/fixtures";
+import { type HttpMock, mockFetch } from "../../../test-support/http";
+import { OrganizePanel } from "./OrganizePanel";
+
+let harness: DomHarness | undefined;
+let http: HttpMock | undefined;
+
+afterEach(() => {
+	harness?.close();
+	harness = undefined;
+	http?.restore();
+	http = undefined;
+});
+
+const ACCOUNT_ID = "acc-1";
+
+const MAILBOXES = [
+	makeMailbox({ mailboxId: "mbx-inbox", fullPath: "INBOX" }),
+	makeMailbox({ mailboxId: "mbx-archive", fullPath: "Archive" }),
+];
+
+const SEMANTIC_PREDICATE: OrganizeMatchPredicate = {
+	anchorMessageId: "msg-1",
+	matchOperator: "And",
+	literalClauses: [],
+};
+
+const SENDER_PREDICATE: OrganizeMatchPredicate = {
+	matchOperator: "Or",
+	literalClauses: [{ field: "From", value: "npm@github.com" }],
+};
+
+const mount = (
+	props: Partial<Parameters<typeof OrganizePanel>[0]>,
+): DomHarness => {
+	http = mockFetch((call) => {
+		if (call.path.endsWith("/organize") && call.method === "POST") {
+			return { organizeJobId: "job-1", state: "Processing" };
+		}
+		if (call.path.endsWith("/organize/job-1") && call.method === "GET") {
+			return {
+				organizeJobId: "job-1",
+				state: "Processing",
+				matchedCount: 128,
+				appliedCount: 0,
+				failedCount: 0,
+			};
+		}
+		return {};
+	});
+	harness = createDomHarness();
+	harness.queryClient.setQueryData(
+		mailboxOperationsListMailboxesQueryKey({ path: { accountId: ACCOUNT_ID } }),
+		{ items: MAILBOXES },
+	);
+	harness.renderApp(
+		createElement(OrganizePanel, {
+			accountId: ACCOUNT_ID,
+			mailboxId: "mbx-inbox",
+			selectedMessageIds: ["msg-1", "msg-2"],
+			matchPredicate: SEMANTIC_PREDICATE,
+			matchedCount: 128,
+			seedMailboxId: "mbx-archive",
+			onClose: () => undefined,
+			...props,
+		}),
+	);
+	return harness;
+};
+
+async function startJob(dom: DomHarness): Promise<void> {
+	dom.click(dom.byText("button", "Organize"));
+	for (let attempt = 0; attempt < 20; attempt += 1) {
+		await dom.flush();
+		if (/Organizing/.test(dom.text())) return;
+		await dom.wait(1);
+	}
+}
+
+describe("OrganizePanel back-apply progress copy", () => {
+	it("states the sender semantics while organizing in the sender fallback", async () => {
+		const dom = mount({
+			matchPredicate: SENDER_PREDICATE,
+			semanticUnavailable: true,
+			senders: ["npm@github.com"],
+		});
+		await startJob(dom);
+
+		assert.match(dom.text(), /Organizing mail from these senders/);
+		assert.doesNotMatch(dom.text(), /Organizing similar mail/);
+	});
+
+	it("keeps the similar-mail wording on the semantic path", async () => {
+		const dom = mount({});
+		await startJob(dom);
+
+		assert.match(dom.text(), /Organizing similar mail/);
+		assert.doesNotMatch(dom.text(), /from these senders/);
+	});
+});

package/src/components/mail/organize/OrganizePanel.render.test.ts

@@ -26,7 +26,11 @@ const render = (overrides: Partial<Parameters<typeof OrganizePanel>[0]> = {}) =>
 					accountId: "acc-1",
 					mailboxId: "mbx-inbox",
 					selectedMessageIds: ["msg-1", "msg-2"],
-					anchorMessageId: "msg-1",
+					matchPredicate: {
+						anchorMessageId: "msg-1",
+						matchOperator: "And",
+						literalClauses: [],
+					},
 					matchedCount: 47,
 					onClose: () => undefined,
 					...overrides,
@@ -62,12 +66,38 @@ describe("OrganizePanel", () => {
 		assert.match(html, /organizing just your 2 selected/);
 	});
 
-	it("names the missing vector pipeline and organizes just the selection when the widen is unavailable (#226/#201)", () => {
+	it("names the missing vector pipeline and organizes just the selection when the widen is unavailable and no senders are known (#226/#201)", () => {
 		const html = render({ matchedCount: 0, semanticUnavailable: true });
 		assert.match(html, /available on this server/);
 		assert.match(html, /organizing just your 2 selected/);
 	});
 
+	it("names the senders and states it is matching all mail from them when the widen fell back (no vector pipeline)", () => {
+		const html = render({
+			matchedCount: 128,
+			semanticUnavailable: true,
+			senders: ["npm@github.com", "notifications@github.com"],
+			matchPredicate: {
+				matchOperator: "Or",
+				literalClauses: [
+					{ field: "From", value: "npm@github.com" },
+					{ field: "From", value: "notifications@github.com" },
+				],
+			},
+		});
+		assert.match(html, /matching all mail from/);
+		assert.match(html, /npm@github\.com/);
+		assert.match(html, /notifications@github\.com/);
+		assert.match(html, /128 matches/);
+		// Never claims the matched set is semantically similar (only denies that
+		// similar-mail matching is available).
+		assert.doesNotMatch(html, /similar message/i);
+		assert.doesNotMatch(html, /similar ones found/i);
+		// The sender fallback is a real widen: the scopes reach it, so the
+		// default scope is "all like these", not "just these".
+		assert.match(html, /All like these/);
+	});
+
 	it("pre-selects the seeded scope (a 'Something else' shortcut seeds the sentence)", () => {
 		const html = render({ initialScope: "standing" });
 		// The standing scope's "Always keep" phrasing only renders when it is active.

package/src/components/mail/organize/OrganizePanel.tsx

@@ -13,17 +13,25 @@ import {
 	commitButtonLabel,
 	commitDisabledReason,
 	scopeActionCount,
+	senderFallbackSummary,
 } from "@/lib/organize/organize-copy";
 import type {
 	OrganizeDraft,
 	OrganizeScope,
 } from "@/lib/organize/organize-model";
+import type { OrganizeMatchPredicate } from "@/lib/organize/sender-fallback";
 
 interface OrganizePanelProps {
 	accountId: string;
 	mailboxId: string;
 	selectedMessageIds: string[];
-	anchorMessageId: string;
+	/**
+	 * The predicate the widen previewed — the semantic anchor, or the
+	 * sender-derived literal clauses when the vector pipeline is absent. Every
+	 * commit scope carries exactly this, so the previewed set equals the set the
+	 * scope acts on.
+	 */
+	matchPredicate: OrganizeMatchPredicate;
 	/** Similar messages the widen preview matched. */
 	matchedCount: number;
 	/**
@@ -44,10 +52,17 @@ interface OrganizePanelProps {
 	fallback?: boolean;
 	/**
 	 * The server ran no semantic widen because this deployment ships no vector
-	 * pipeline. Like {@link fallback} it organizes just the selection, but the
-	 * heading names the real reason rather than "no similar found".
+	 * pipeline. With senders to match on ({@link senders}) the widen fell back to
+	 * matching all mail from those senders; with none it organizes just the
+	 * selection. Either way the heading names the real reason, never "similar".
 	 */
 	semanticUnavailable?: boolean;
+	/**
+	 * Distinct sender addresses driving the sender fallback. Non-empty only when
+	 * {@link semanticUnavailable} and the fallback produced a literal match set;
+	 * named in the heading and folder line so the copy states the real semantics.
+	 */
+	senders?: string[];
 	onClose: () => void;
 }
 
@@ -78,17 +93,22 @@ export function OrganizePanel({
 	accountId,
 	mailboxId,
 	selectedMessageIds,
-	anchorMessageId,
+	matchPredicate,
 	matchedCount,
 	initialScope,
 	seedMailboxId,
 	fallback = false,
 	semanticUnavailable = false,
+	senders = [],
 	onClose,
 }: OrganizePanelProps) {
+	// The vector pipeline is absent but the selection has senders to match on:
+	// the widen fell back to sender matching, which produces a real widened set
+	// the commit scopes reach — unlike a missing or empty widen.
+	const senderFallback = semanticUnavailable && senders.length > 0;
 	// A missing widen and an empty widen both organize just the selection; only
-	// the heading distinguishes them.
-	const noWiden = fallback || semanticUnavailable;
+	// the heading distinguishes them. The sender fallback is a real widen.
+	const noWiden = (fallback || semanticUnavailable) && !senderFallback;
 	const [scope, setScope] = useState<OrganizeScope>(
 		initialScope ?? (noWiden ? "just-these" : "all-like-these"),
 	);
@@ -113,14 +133,12 @@ export function OrganizePanel({
 
 	const draft: OrganizeDraft = useMemo(
 		() => ({
-			anchorMessageId,
-			matchOperator: "And",
-			literalClauses: [],
+			...matchPredicate,
 			moveMailboxId: moveMailboxId || undefined,
 			expiresAt:
 				scope === "temporary" ? pickedDateToExpiresAt(pickedDate) : undefined,
 		}),
-		[anchorMessageId, moveMailboxId, scope, pickedDate],
+		[matchPredicate, moveMailboxId, scope, pickedDate],
 	);
 
 	const { moveMessages } = useMoveMessages({ mailboxId, accountId });
@@ -161,6 +179,7 @@ export function OrganizePanel({
 			<JobProgress
 				progress={organizeJob.progress}
 				isDone={organizeJob.isDone}
+				senderFallback={senderFallback}
 				onClose={onClose}
 			/>
 		);
@@ -188,13 +207,17 @@ export function OrganizePanel({
 			<div className="border-b border-line px-5 py-3">
 				<h2 className="text-sm font-semibold text-fg">Organize</h2>
 				<p className="mt-0.5 text-xs text-fg-muted">
-					{semanticUnavailable
-						? `Finding similar mail isn't available on this server — organizing just your ${selectionCount} selected.`
-						: fallback
-							? `No similar messages found — organizing just your ${selectionCount} selected.`
-							: `${matchedCount} similar message${matchedCount === 1 ? "" : "s"} found${
-									selectionCount > 0 ? ` from ${selectionCount} selected` : ""
-								}.`}
+					{senderFallback
+						? `${senderFallbackSummary(senders)} ${matchedCount} match${
+								matchedCount === 1 ? "" : "es"
+							}.`
+						: semanticUnavailable
+							? `Finding similar mail isn't available on this server — organizing just your ${selectionCount} selected.`
+							: fallback
+								? `No similar messages found — organizing just your ${selectionCount} selected.`
+								: `${matchedCount} similar message${matchedCount === 1 ? "" : "s"} found${
+										selectionCount > 0 ? ` from ${selectionCount} selected` : ""
+									}.`}
 				</p>
 			</div>
 
@@ -205,7 +228,12 @@ export function OrganizePanel({
 							<span className="font-semibold text-fg">Always keep </span>
 						)}
 						{scope === "standing" ? "" : "Keep "}
-						{scope === "just-these" ? "these" : "emails like these"} in
+						{scope === "just-these"
+							? "these"
+							: senderFallback
+								? "mail from these senders"
+								: "emails like these"}{" "}
+						in
 					</p>
 					<Select
 						aria-label="Destination folder"
@@ -232,6 +260,10 @@ export function OrganizePanel({
 				<section className="space-y-1.5">
 					{SCOPE_OPTIONS.map((option) => {
 						const active = scope === option.id;
+						const caption =
+							senderFallback && option.id === "all-like-these"
+								? "including others from these senders"
+								: option.caption;
 						return (
 							<button
 								key={option.id}
@@ -263,7 +295,7 @@ export function OrganizePanel({
 										{option.label}
 									</span>
 									<span className="block text-xs text-fg-subtle">
-										{option.caption}
+										{caption}
 									</span>
 								</span>
 							</button>
@@ -330,10 +362,12 @@ export function OrganizePanel({
 function JobProgress({
 	progress,
 	isDone,
+	senderFallback,
 	onClose,
 }: {
 	progress: ReturnType<typeof useOrganizeJob>["progress"];
 	isDone: boolean;
+	senderFallback: boolean;
 	onClose: () => void;
 }) {
 	const failed = progress.state === "Failed";
@@ -350,7 +384,11 @@ function JobProgress({
 			)}
 
 			{!isDone && (
-				<p className="text-sm font-medium text-fg">Organizing similar mail…</p>
+				<p className="text-sm font-medium text-fg">
+					{senderFallback
+						? "Organizing mail from these senders…"
+						: "Organizing similar mail…"}
+				</p>
 			)}
 
 			{isDone && !failed && (

package/src/components/mail/organize/smart-organize.stories.tsx

@@ -117,7 +117,11 @@ export const Organize: Story = {
 				accountId={ACCOUNT_ID}
 				mailboxId="mbx-inbox"
 				selectedMessageIds={["msg-1", "msg-2", "msg-3"]}
-				anchorMessageId="msg-1"
+				matchPredicate={{
+					anchorMessageId: "msg-1",
+					matchOperator: "And",
+					literalClauses: [],
+				}}
 				matchedCount={47}
 				onClose={() => undefined}
 			/>
@@ -137,7 +141,11 @@ export const FromSearch: Story = {
 				accountId={ACCOUNT_ID}
 				mailboxId="mbx-inbox"
 				selectedMessageIds={["msg-1"]}
-				anchorMessageId="msg-1"
+				matchPredicate={{
+					anchorMessageId: "msg-1",
+					matchOperator: "And",
+					literalClauses: [],
+				}}
 				matchedCount={412}
 				seedMailboxId="mbx-archive"
 				onClose={() => undefined}
@@ -155,7 +163,11 @@ export const AlwaysRule: Story = {
 				accountId={ACCOUNT_ID}
 				mailboxId="mbx-inbox"
 				selectedMessageIds={["msg-1", "msg-2"]}
-				anchorMessageId="msg-1"
+				matchPredicate={{
+					anchorMessageId: "msg-1",
+					matchOperator: "And",
+					literalClauses: [],
+				}}
 				matchedCount={47}
 				initialScope="standing"
 				seedMailboxId="mbx-travel"
@@ -174,7 +186,11 @@ export const NoSimilarFound: Story = {
 				accountId={ACCOUNT_ID}
 				mailboxId="mbx-inbox"
 				selectedMessageIds={["msg-1", "msg-2"]}
-				anchorMessageId="msg-1"
+				matchPredicate={{
+					anchorMessageId: "msg-1",
+					matchOperator: "And",
+					literalClauses: [],
+				}}
 				matchedCount={0}
 				fallback
 				onClose={() => undefined}
@@ -196,7 +212,11 @@ export const SemanticUnavailable: Story = {
 				accountId={ACCOUNT_ID}
 				mailboxId="mbx-inbox"
 				selectedMessageIds={["msg-1", "msg-2"]}
-				anchorMessageId="msg-1"
+				matchPredicate={{
+					anchorMessageId: "msg-1",
+					matchOperator: "And",
+					literalClauses: [],
+				}}
 				matchedCount={0}
 				semanticUnavailable
 				onClose={() => undefined}
@@ -205,6 +225,75 @@ export const SemanticUnavailable: Story = {
 	),
 };
 
+/**
+ * No vector pipeline, but the selection has senders to match on — the widen
+ * fell back to matching all mail from those senders. The heading names the
+ * senders and states the real semantics, and every commit scope (including the
+ * standing filter) carries the sender `From` clauses, so it reaches the widened
+ * set and keeps working on future mail.
+ */
+export const SenderFallback: Story = {
+	name: "Sender Fallback",
+	render: () => (
+		<SheetStage>
+			<OrganizePanel
+				accountId={ACCOUNT_ID}
+				mailboxId="mbx-inbox"
+				selectedMessageIds={["msg-1", "msg-2"]}
+				matchPredicate={{
+					matchOperator: "Or",
+					literalClauses: [
+						{ field: "From", value: "npm@github.com" },
+						{ field: "From", value: "notifications@github.com" },
+					],
+				}}
+				matchedCount={128}
+				semanticUnavailable
+				senders={["npm@github.com", "notifications@github.com"]}
+				onClose={() => undefined}
+			/>
+		</SheetStage>
+	),
+};
+
+/**
+ * The sender fallback with a standing rule pre-selected — the "Always keep mail
+ * from these senders" sentence, the filter that will match future mail at index
+ * time.
+ */
+export const SenderFallbackStanding: Story = {
+	name: "Sender Fallback (standing)",
+	render: () => (
+		<SheetStage>
+			<OrganizePanel
+				accountId={ACCOUNT_ID}
+				mailboxId="mbx-inbox"
+				selectedMessageIds={["msg-1", "msg-2", "msg-3", "msg-4"]}
+				matchPredicate={{
+					matchOperator: "Or",
+					literalClauses: [
+						{ field: "From", value: "npm@github.com" },
+						{ field: "From", value: "notifications@github.com" },
+						{ field: "From", value: "noreply@medium.com" },
+						{ field: "From", value: "digest@substack.com" },
+					],
+				}}
+				matchedCount={412}
+				semanticUnavailable
+				senders={[
+					"npm@github.com",
+					"notifications@github.com",
+					"noreply@medium.com",
+					"digest@substack.com",
+				]}
+				initialScope="standing"
+				seedMailboxId="mbx-archive"
+				onClose={() => undefined}
+			/>
+		</SheetStage>
+	),
+};
+
 /** The "Something else" fallback: shortcuts derived from folders + an input. */
 export const SomethingElse: Story = {
 	render: () => (

package/src/hooks/useOrganizeWiden.test.ts

@@ -0,0 +1,151 @@
+/**
+ * The widen step's two-phase preview. On a semantic-capable deployment it runs
+ * the anchor preview once and stops. On a deployment that reports
+ * `semanticUnavailable` (no vector pipeline — semantic-capability.ts) it
+ * re-previews with sender-derived literal clauses — one `From` clause per
+ * distinct sender, combined with `Or`, no anchor — and reports the literal match
+ * count, so every commit scope acts on the sender-matched set.
+ */
+
+import assert from "node:assert/strict";
+import { afterEach, describe, it } from "node:test";
+import { createElement, useEffect } from "react";
+import { createDomHarness, type DomHarness } from "../test-support/dom";
+import { type HttpMock, mockFetch } from "../test-support/http";
+import { useOrganizeWiden } from "./useOrganizeWiden";
+
+let harness: DomHarness | undefined;
+let http: HttpMock | undefined;
+
+afterEach(() => {
+	harness?.close();
+	harness = undefined;
+	http?.restore();
+	http = undefined;
+});
+
+type Widen = ReturnType<typeof useOrganizeWiden>;
+type Responder = Parameters<typeof mockFetch>[0];
+
+const PREVIEW_PATH = "/organize/preview";
+
+const mount = (senders: string[], responder: Responder) => {
+	http = mockFetch(responder);
+	harness = createDomHarness();
+	const holder: { current: Widen | undefined } = { current: undefined };
+	function Probe() {
+		const widen = useOrganizeWiden("acc-1", "msg-1", senders);
+		holder.current = widen;
+		const { preview } = widen;
+		useEffect(() => {
+			preview();
+		}, [preview]);
+		return null;
+	}
+	harness.renderApp(createElement(Probe));
+	return holder;
+};
+
+async function settle(minCalls: number): Promise<void> {
+	const dom = harness;
+	const mock = http;
+	if (!dom || !mock) throw new Error("not mounted");
+	for (let attempt = 0; attempt < 40; attempt += 1) {
+		await dom.flush();
+		if (mock.to(PREVIEW_PATH).length >= minCalls) {
+			await dom.flush();
+			await dom.wait(1);
+			await dom.flush();
+			return;
+		}
+		await dom.wait(1);
+	}
+}
+
+describe("useOrganizeWiden — semantic-capable deployment", () => {
+	it("previews the anchor once and reports the semantic match, no fallback", async () => {
+		const holder = mount([], () => ({
+			matchedCount: 42,
+			messageIds: ["a", "b"],
+			semanticUnavailable: false,
+		}));
+		await settle(1);
+
+		assert.equal(http?.to(PREVIEW_PATH).length, 1);
+		const [call] = http?.to(PREVIEW_PATH) ?? [];
+		assert.equal(call.body?.anchorMessageId, "msg-1");
+		assert.deepEqual(call.body?.literalClauses, []);
+
+		const widen = holder.current;
+		assert.equal(widen?.matchedCount, 42);
+		assert.equal(widen?.semanticUnavailable, false);
+		assert.equal(widen?.senderFallback, false);
+		assert.deepEqual(widen?.matchPredicate, {
+			anchorMessageId: "msg-1",
+			matchOperator: "And",
+			literalClauses: [],
+		});
+	});
+});
+
+describe("useOrganizeWiden — no vector pipeline, senders present", () => {
+	it("re-previews with distinct sender From clauses combined with Or and no anchor", async () => {
+		const holder = mount(
+			["npm@github.com", "npm@github.com", "a@x.com"],
+			(call) =>
+				call.body?.anchorMessageId
+					? { matchedCount: 0, messageIds: [], semanticUnavailable: true }
+					: {
+							matchedCount: 128,
+							messageIds: ["m"],
+							semanticUnavailable: false,
+						},
+		);
+		await settle(2);
+
+		const calls = http?.to(PREVIEW_PATH) ?? [];
+		assert.equal(calls.length, 2);
+		// The second preview is the literal fallback: no anchor, Or, distinct
+		// sender From clauses.
+		const second = calls[1];
+		assert.equal(second.body?.anchorMessageId, undefined);
+		assert.equal(second.body?.matchOperator, "Or");
+		assert.deepEqual(second.body?.literalClauses, [
+			{ field: "From", value: "npm@github.com" },
+			{ field: "From", value: "a@x.com" },
+		]);
+
+		const widen = holder.current;
+		assert.equal(widen?.matchedCount, 128);
+		assert.equal(widen?.semanticUnavailable, true);
+		assert.equal(widen?.senderFallback, true);
+		assert.deepEqual(widen?.senders, ["npm@github.com", "a@x.com"]);
+		assert.deepEqual(widen?.matchPredicate, {
+			matchOperator: "Or",
+			literalClauses: [
+				{ field: "From", value: "npm@github.com" },
+				{ field: "From", value: "a@x.com" },
+			],
+		});
+	});
+});
+
+describe("useOrganizeWiden — no vector pipeline, no senders", () => {
+	it("does not re-preview and stays capability-absent with the anchor predicate", async () => {
+		const holder = mount([], () => ({
+			matchedCount: 0,
+			messageIds: [],
+			semanticUnavailable: true,
+		}));
+		await settle(1);
+		// Give any spurious second preview a chance to fire before asserting none did.
+		await harness?.flush();
+
+		assert.equal(http?.to(PREVIEW_PATH).length, 1);
+		const widen = holder.current;
+		assert.equal(widen?.semanticUnavailable, true);
+		assert.equal(widen?.senderFallback, false);
+		assert.deepEqual(widen?.senders, []);
+		assert.equal(widen?.matchPredicate.anchorMessageId, "msg-1");
+	});
+});

package/src/hooks/useOrganizeWiden.ts

@@ -0,0 +1,104 @@
+import { organizeOperationsPreviewOrganizeMutation } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import { useMutation } from "@tanstack/react-query";
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { buildOrganizeInput } from "@/lib/organize/organize-model";
+import {
+	buildSenderFallbackDraft,
+	deriveSenderClauses,
+	distinctSenders,
+	type OrganizeMatchPredicate,
+} from "@/lib/organize/sender-fallback";
+
+/**
+ * "Select similar messages" (the widen step) with a sender-derived fallback for
+ * deployments without the vector pipeline.
+ *
+ * The first preview runs the semantic anchor (POST /organize/preview). When the
+ * server reports `semanticUnavailable` — no vector pipeline on this deployment
+ * (semantic-capability.ts) — the widen re-previews with the literal vocabulary
+ * that matches vector-free: one `From` clause per distinct sender in the
+ * selection, combined with `Or`, no anchor. The counts shown, the one-time
+ * back-apply, and any standing filter then all carry that same literal
+ * predicate, so the previewed set equals the set every commit scope acts on.
+ *
+ * A semantic-capable deployment never fires the second preview and keeps exactly
+ * the anchor behaviour.
+ */
+export const useOrganizeWiden = (
+	accountId: string | undefined,
+	anchorMessageId: string | undefined,
+	senders: readonly string[],
+) => {
+	const mutation = useMutation(organizeOperationsPreviewOrganizeMutation());
+	const { mutate, reset: mutationReset } = mutation;
+	const [fellBack, setFellBack] = useState(false);
+
+	const distinct = useMemo(() => distinctSenders(senders), [senders]);
+
+	const preview = useCallback(() => {
+		if (!accountId || !anchorMessageId) return;
+		setFellBack(false);
+		mutate({
+			path: { accountId },
+			body: buildOrganizeInput({
+				anchorMessageId,
+				matchOperator: "And",
+				literalClauses: [],
+			}),
+		});
+	}, [accountId, anchorMessageId, mutate]);
+
+	const reset = useCallback(() => {
+		setFellBack(false);
+		mutationReset();
+	}, [mutationReset]);
+
+	const data = mutation.data;
+	// The first preview came back capability-absent and there are senders to
+	// match on: re-preview with the literal clauses before showing any count, so
+	// the count the user sees is the sender-match count, never a flash of the
+	// empty semantic result.
+	const willFallBack =
+		data?.semanticUnavailable === true && !fellBack && distinct.length > 0;
+
+	useEffect(() => {
+		if (!willFallBack || !accountId) return;
+		setFellBack(true);
+		mutate({
+			path: { accountId },
+			body: buildOrganizeInput(buildSenderFallbackDraft(distinct)),
+		});
+	}, [willFallBack, accountId, distinct, mutate]);
+
+	// The literal re-preview has no anchor, so its response reports
+	// `semanticUnavailable: false`; `fellBack` is what remembers the capability
+	// was absent once the fallback has run.
+	const capabilityAbsent = fellBack || (data?.semanticUnavailable ?? false);
+	const isPending = mutation.isPending || willFallBack;
+
+	const matchPredicate: OrganizeMatchPredicate = fellBack
+		? { matchOperator: "Or", literalClauses: deriveSenderClauses(distinct) }
+		: {
+				...(anchorMessageId ? { anchorMessageId } : {}),
+				matchOperator: "And",
+				literalClauses: [],
+			};
+
+	return {
+		preview,
+		reset,
+		matchedCount: isPending ? undefined : data?.matchedCount,
+		messageIds: isPending ? undefined : data?.messageIds,
+		// The deployment ships no vector pipeline — the widen matched on senders
+		// (or, with no senders, on nothing) rather than semantic similarity.
+		semanticUnavailable: capabilityAbsent,
+		// The widen fell back to sender matching and produced a usable literal
+		// match set: the commit scopes reach it, and the copy names the senders.
+		senderFallback: fellBack,
+		senders: distinct,
+		matchPredicate,
+		isPending,
+		isError: mutation.isError,
+		error: mutation.error,
+	};
+};

package/src/lib/organize/organize-copy.test.ts

@@ -3,7 +3,9 @@ import { describe, it } from "node:test";
 import {
 	commitButtonLabel,
 	commitDisabledReason,
+	formatSenderList,
 	scopeActionCount,
+	senderFallbackSummary,
 } from "./organize-copy";
 import type { OrganizeDraft } from "./organize-model";
 
@@ -91,3 +93,42 @@ describe("scopeActionCount", () => {
 		assert.equal(scopeActionCount("standing", 3, 48), 48);
 	});
 });
+
+describe("formatSenderList", () => {
+	it("names a single sender bare", () => {
+		assert.equal(formatSenderList(["npm@github.com"]), "npm@github.com");
+	});
+
+	it("joins a couple with 'and'", () => {
+		assert.equal(
+			formatSenderList(["a@x.com", "b@y.com"]),
+			"a@x.com and b@y.com",
+		);
+	});
+
+	it("lists up to three in full", () => {
+		assert.equal(
+			formatSenderList(["a@x.com", "b@y.com", "c@z.com"]),
+			"a@x.com, b@y.com and c@z.com",
+		);
+	});
+
+	it("truncates past three, summing the rest", () => {
+		assert.equal(
+			formatSenderList(["a@x.com", "b@y.com", "c@z.com", "d@w.com"]),
+			"a@x.com, b@y.com, c@z.com and 1 other",
+		);
+		assert.equal(
+			formatSenderList(["a@x.com", "b@y.com", "c@z.com", "d@w.com", "e@v.com"]),
+			"a@x.com, b@y.com, c@z.com and 2 others",
+		);
+	});
+});
+
+describe("senderFallbackSummary", () => {
+	it("states it is matching all mail from the senders, never 'similar'", () => {
+		const summary = senderFallbackSummary(["npm@github.com"]);
+		assert.match(summary, /isn't available on this server/);
+		assert.match(summary, /matching all mail from npm@github\.com instead/);
+	});
+});

package/src/lib/organize/organize-copy.ts

@@ -59,3 +59,32 @@ export const scopeActionCount = (
 	selectionCount: number,
 	matchedCount: number,
 ): number => (scope === "just-these" ? selectionCount : matchedCount);
+
+/** How many sender addresses are named before the rest are summed as "N others". */
+const MAX_SENDERS_SHOWN = 3;
+
+/**
+ * The sender addresses read out in prose: all of them when there are a few, or
+ * the first {@link MAX_SENDERS_SHOWN} and a count of the rest so a long selection
+ * stays legible in the sheet.
+ */
+export const formatSenderList = (senders: readonly string[]): string => {
+	if (senders.length === 0) return "these senders";
+	if (senders.length === 1) return senders[0];
+	if (senders.length <= MAX_SENDERS_SHOWN) {
+		return `${senders.slice(0, -1).join(", ")} and ${senders[senders.length - 1]}`;
+	}
+	const shown = senders.slice(0, MAX_SENDERS_SHOWN);
+	const rest = senders.length - MAX_SENDERS_SHOWN;
+	return `${shown.join(", ")} and ${rest} other${rest === 1 ? "" : "s"}`;
+};
+
+/**
+ * The heading when the widen fell back to sender matching (no vector pipeline on
+ * this server). States the actual semantics — matching every mail from these
+ * senders — and never claims semantic similarity.
+ */
+export const senderFallbackSummary = (senders: readonly string[]): string =>
+	`Similar-mail matching isn't available on this server — matching all mail from ${formatSenderList(
+		senders,
+	)} instead.`;

package/src/lib/organize/sender-fallback.test.ts

@@ -0,0 +1,56 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import {
+	buildSenderFallbackDraft,
+	deriveSenderClauses,
+	distinctSenders,
+} from "./sender-fallback";
+
+describe("distinctSenders", () => {
+	it("drops empties and blanks, trimming what remains", () => {
+		assert.deepEqual(
+			distinctSenders(["  npm@github.com ", "", "   ", "a@x.com"]),
+			["npm@github.com", "a@x.com"],
+		);
+	});
+
+	it("de-duplicates case-insensitively, keeping first-seen casing and order", () => {
+		assert.deepEqual(
+			distinctSenders([
+				"NPM@github.com",
+				"a@x.com",
+				"npm@GITHUB.com",
+				"a@x.com",
+			]),
+			["NPM@github.com", "a@x.com"],
+		);
+	});
+});
+
+describe("deriveSenderClauses", () => {
+	it("emits one From clause per distinct sender", () => {
+		assert.deepEqual(
+			deriveSenderClauses(["npm@github.com", "npm@github.com", "a@x.com"]),
+			[
+				{ field: "From", value: "npm@github.com" },
+				{ field: "From", value: "a@x.com" },
+			],
+		);
+	});
+
+	it("is empty when no sender survives", () => {
+		assert.deepEqual(deriveSenderClauses(["", "  "]), []);
+	});
+});
+
+describe("buildSenderFallbackDraft", () => {
+	it("combines the sender clauses with Or and carries no anchor", () => {
+		const draft = buildSenderFallbackDraft(["npm@github.com", "a@x.com"]);
+		assert.equal(draft.matchOperator, "Or");
+		assert.equal(draft.anchorMessageId, undefined);
+		assert.deepEqual(draft.literalClauses, [
+			{ field: "From", value: "npm@github.com" },
+			{ field: "From", value: "a@x.com" },
+		]);
+	});
+});

package/src/lib/organize/sender-fallback.ts

@@ -0,0 +1,64 @@
+import type {
+	RemitImapFilterClause,
+	RemitImapOrganizeInput,
+} from "@remit/api-http-client/types.gen.ts";
+import type { OrganizeDraft } from "./organize-model";
+
+/**
+ * The widen fallback for a deployment that ships no vector pipeline (self-host
+ * sqlite — semantic-capability.ts). The semantic anchor matches nothing there,
+ * so a widen degrades to the literal vocabulary RFC 031 already matches
+ * vector-free: one `From` clause per distinct sender in the selection, combined
+ * with `Or`, no anchor. The same predicate matches at index time (RFC 034), so a
+ * standing filter built from it keeps working on future mail.
+ */
+
+/**
+ * Distinct sender addresses from the selection, trimmed, empties dropped, and
+ * de-duplicated case-insensitively while preserving first-seen casing and order.
+ */
+export const distinctSenders = (senders: readonly string[]): string[] => {
+	const seen = new Set<string>();
+	const out: string[] = [];
+	for (const raw of senders) {
+		const value = raw.trim();
+		if (value === "") continue;
+		const key = value.toLowerCase();
+		if (seen.has(key)) continue;
+		seen.add(key);
+		out.push(value);
+	}
+	return out;
+};
+
+/**
+ * One `From` literal clause per distinct sender address. A `From` clause matches
+ * the sender address or display name (match.ts `clauseMatches`), so the address
+ * is the precise, stable key.
+ */
+export const deriveSenderClauses = (
+	senders: readonly string[],
+): RemitImapFilterClause[] =>
+	distinctSenders(senders).map((value) => ({ field: "From", value }));
+
+/**
+ * The literal predicate that stands in for the semantic anchor: the sender `From`
+ * clauses combined with `Or` and no anchor. The preview, the one-time back-apply,
+ * and the standing filter all carry exactly this.
+ */
+export const buildSenderFallbackDraft = (
+	senders: readonly string[],
+): OrganizeDraft => ({
+	matchOperator: "Or",
+	literalClauses: deriveSenderClauses(senders),
+});
+
+/**
+ * The predicate the widen previewed, handed to the organize sentence so the set
+ * it previews equals the set every commit scope acts on. Either the semantic
+ * anchor or the sender-derived literal fallback, never both.
+ */
+export type OrganizeMatchPredicate = Pick<
+	RemitImapOrganizeInput,
+	"anchorMessageId" | "matchOperator" | "literalClauses"
+>;

package/src/hooks/useOrganizePreview.ts

@@ -1,43 +0,0 @@
-import { organizeOperationsPreviewOrganizeMutation } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
-import { useMutation } from "@tanstack/react-query";
-import { useCallback } from "react";
-import {
-	buildOrganizeInput,
-	type OrganizeDraft,
-} from "@/lib/organize/organize-model";
-
-/**
- * "Select similar messages" (the widen step). Runs the read-only matcher once
- * server-side (POST /organize/preview) and returns the messages the same
- * predicate would apply an action to — the previewed set equals the set a job
- * with the same input would apply to. This is the only corpus-wide query the
- * flow makes; there is no client-side pagination over messages.
- */
-export const useOrganizePreview = (accountId: string | undefined) => {
-	const mutation = useMutation(organizeOperationsPreviewOrganizeMutation());
-	const { mutate } = mutation;
-
-	const preview = useCallback(
-		(draft: OrganizeDraft) => {
-			if (!accountId) return;
-			mutate({
-				path: { accountId },
-				body: buildOrganizeInput(draft),
-			});
-		},
-		[accountId, mutate],
-	);
-
-	return {
-		preview,
-		reset: mutation.reset,
-		matchedCount: mutation.data?.matchedCount,
-		messageIds: mutation.data?.messageIds,
-		// True when the server ran no semantic widen because this deployment
-		// ships no vector pipeline — the matched set is literal-only (or empty).
-		semanticUnavailable: mutation.data?.semanticUnavailable ?? false,
-		isPending: mutation.isPending,
-		isError: mutation.isError,
-		error: mutation.error,
-	};
-};