@remit/web-client 0.0.56 → 0.0.57

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/web-client",
-  "version": "0.0.56",
+  "version": "0.0.57",
   "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

@@ -53,6 +53,7 @@ import {
 } from "@/lib/selection-sheet-mode";
 import { cn } from "@/lib/utils";
 import { MoveToTrigger } from "./MoveToTrigger";
+import { MobileOrganizeFlow } from "./organize/MobileOrganizeFlow";
 import { OrganizeDialog } from "./organize/OrganizeDialog";
 import { SelectionToolbar } from "./SelectionToolbar";
 import { SwipeableMessageRow } from "./SwipeableMessageRow";
@@ -221,6 +222,12 @@ export const MessageList = ({
 	const navigate = useNavigate();
 	const isDesktop = useIsDesktop();
 	const [organizeOpen, setOrganizeOpen] = useState(false);
+	// Mobile only: which selection-sheet entry opened the guided organize flow
+	// (`null` when closed). Desktop uses `organizeOpen` + `OrganizeDialog`
+	// instead — a sheet is a touch pattern (issue #211).
+	const [mobileOrganizeEntry, setMobileOrganizeEntry] = useState<
+		"select-similar" | "something-else" | null
+	>(null);
 	const isSearching = !!searchQuery?.trim();
 
 	// Roving focus cursor (#429): the keyboard "where am I" pointer, distinct
@@ -275,6 +282,13 @@ export const MessageList = ({
 	// it back to the count, and across that render the two disagree.
 	const isMultiSelectMode = deriveIsMultiSelectMode(selectedCount, isDesktop);
 
+	// When the selection empties — cancel, a completed action, a mailbox switch —
+	// the guided organize entry must reset too, so a later re-selection doesn't
+	// reopen the flow on a stale entry (issue #211).
+	useEffect(() => {
+		if (selectedCount === 0) setMobileOrganizeEntry(null);
+	}, [selectedCount]);
+
 	// Pending delete, awaiting confirmation. `null` means the dialog is closed.
 	// `source: "ids"` snapshots the concrete ids at request time so a selection
 	// change behind the dialog can't retarget the delete — every keyboard/desktop
@@ -1227,6 +1241,24 @@ export const MessageList = ({
 			/>
 		) : undefined;
 
+	// The guided organize flow (issue #211) overlays the same positioned pane
+	// ancestor as the sheet, so it is rendered from the sheet slot. The sheet
+	// stays mounted underneath as the flow's dimmed backdrop.
+	const mobileOrganizeFlow =
+		mobileOrganizeEntry && accountId && !isDesktop && selectedCount > 0 ? (
+			<MobileOrganizeFlow
+				entry={mobileOrganizeEntry}
+				accountId={accountId}
+				mailboxId={mailboxId}
+				selectedMessageIds={Array.from(selectedIds)}
+				junkMailboxId={junkMailboxId}
+				onClose={() => {
+					setMobileOrganizeEntry(null);
+					exitSelection();
+				}}
+			/>
+		) : undefined;
+
 	const mobileSelectionSheet = showMobileSheet ? (
 		<SelectionSheet
 			count={mobileCount}
@@ -1239,8 +1271,12 @@ export const MessageList = ({
 					: undefined
 			}
 			onMarkRead={handleMarkAsRead}
-			onSelectSimilar={accountId ? () => setOrganizeOpen(true) : undefined}
-			onSomethingElse={accountId ? () => setOrganizeOpen(true) : undefined}
+			onSelectSimilar={
+				accountId ? () => setMobileOrganizeEntry("select-similar") : undefined
+			}
+			onSomethingElse={
+				accountId ? () => setMobileOrganizeEntry("something-else") : undefined
+			}
 			moveSlot={mobileMoveSlot}
 			isBusy={mobileIsBusy}
 			selectAll={mobileSelectAll}
@@ -1258,6 +1294,16 @@ export const MessageList = ({
 		/>
 	) : undefined;
 
+	// Both mobile overlays share the pane's positioned ancestor via the sheet
+	// slot: the peeking sheet, and the guided organize flow above it.
+	const mobileSelectionSurface =
+		mobileSelectionSheet || mobileOrganizeFlow ? (
+			<>
+				{mobileSelectionSheet}
+				{mobileOrganizeFlow}
+			</>
+		) : undefined;
+
 	const activeSelectionBar = desktopSelectionBar;
 
 	// Roving tabindex: exactly one row is in the tab order, so Tab moves focus
@@ -1401,7 +1447,7 @@ export const MessageList = ({
 				isDesktop={isDesktop}
 				hideHeader={hideHeader}
 				selectionBar={activeSelectionBar}
-				selectionSheet={mobileSelectionSheet}
+				selectionSheet={mobileSelectionSurface}
 				listBody={listState === "ready" ? virtualBody : undefined}
 			/>
 			<ConfirmDialog

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

@@ -0,0 +1,45 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import React, { createElement } from "react";
+import { renderToString } from "react-dom/server";
+import { ErrorBannerProvider } from "@/components/ui/ErrorBannerProvider";
+import type { OrganizeEntry } from "@/lib/organize/mobile-organize-flow";
+import { MobileOrganizeFlow } from "./MobileOrganizeFlow";
+
+// The node test loader transpiles remit-ui's `.tsx` with the classic JSX
+// runtime, which references a global `React`. Vite uses the automatic runtime,
+// so this shim only exists for the SSR test harness.
+(globalThis as { React?: typeof React }).React = React;
+
+const render = (entry: OrganizeEntry) =>
+	renderToString(
+		createElement(
+			QueryClientProvider,
+			{ client: new QueryClient() },
+			createElement(
+				ErrorBannerProvider,
+				null,
+				createElement(MobileOrganizeFlow, {
+					entry,
+					accountId: "acc-1",
+					mailboxId: "mbx-inbox",
+					selectedMessageIds: ["msg-1", "msg-2"],
+					onClose: () => undefined,
+				}),
+			),
+		) as never,
+	);
+
+describe("MobileOrganizeFlow", () => {
+	it("select-similar opens on the widening state before the preview resolves", () => {
+		const html = render("select-similar");
+		assert.match(html, /Finding similar messages/);
+	});
+
+	it("something-else opens on the shortcuts + plain-language input", () => {
+		const html = render("something-else");
+		assert.match(html, /What should Remit do\?/);
+		assert.match(html, /Tell Remit what to do/);
+	});
+});

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

@@ -0,0 +1,138 @@
+import { mailboxOperationsListMailboxesOptions } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+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 { getMailboxDisplayName } from "@/lib/folder-roles";
+import { buildMoveTargets } from "@/lib/move-targets";
+import {
+	type OrganizeEntry,
+	type OrganizeSeed,
+	type PreviewStatus,
+	resolveOrganizeStage,
+} from "@/lib/organize/mobile-organize-flow";
+import { OrganizePanel } from "./OrganizePanel";
+import { SomethingElsePanel } from "./SomethingElsePanel";
+
+interface MobileOrganizeFlowProps {
+	entry: OrganizeEntry;
+	accountId: string;
+	mailboxId: string;
+	selectedMessageIds: string[];
+	junkMailboxId?: string;
+	/** Close the flow and return to the list — dismiss, "Not now", and Done all use it. */
+	onClose: () => void;
+}
+
+const previewStatusOf = (
+	isError: boolean,
+	isPending: boolean,
+	matchedCount: number | undefined,
+): PreviewStatus => {
+	if (isError) return "error";
+	if (isPending) return "pending";
+	return matchedCount !== undefined ? "success" : "idle";
+};
+
+/**
+ * The guided select-similar → organize flow, the mobile home for organizing
+ * (issue #211). Entered from the selection sheet, it widens the selection once
+ * with the read-only matcher (POST /organize/preview), shows a brief widening
+ * state, and renders the organize sentence inside a bottom sheet on that
+ * widened set — the same {@link OrganizePanel} the desktop dialog uses, so the
+ * two never drift. "Something else" collects a folder/scope seed first; a widen
+ * that matches nothing falls back to organizing the selection. Desktop keeps
+ * its `OrganizeDialog` — this is the touch surface only.
+ */
+export function MobileOrganizeFlow({
+	entry,
+	accountId,
+	mailboxId,
+	selectedMessageIds,
+	junkMailboxId,
+	onClose,
+}: MobileOrganizeFlowProps) {
+	const anchorMessageId = selectedMessageIds[0];
+	const [seed, setSeed] = useState<OrganizeSeed | undefined>();
+
+	const { preview, matchedCount, isPending, isError, error } =
+		useOrganizePreview(accountId);
+
+	useEffect(() => {
+		if (!anchorMessageId) return;
+		preview({ anchorMessageId, matchOperator: "And", literalClauses: [] });
+	}, [anchorMessageId, preview]);
+
+	const { data: mailboxesData } = useQuery({
+		...mailboxOperationsListMailboxesOptions({ path: { accountId } }),
+		staleTime: Number.POSITIVE_INFINITY,
+	});
+
+	const folderOptions = useMemo(
+		() =>
+			buildMoveTargets(mailboxesData?.items ?? []).map((mailbox) => ({
+				id: mailbox.mailboxId,
+				label: getMailboxDisplayName(mailbox.fullPath),
+			})),
+		[mailboxesData?.items],
+	);
+
+	const stage = resolveOrganizeStage({
+		entry,
+		hasSeed: seed !== undefined,
+		previewStatus: previewStatusOf(isError, isPending, matchedCount),
+		matchedCount,
+	});
+
+	return (
+		<BottomSheet open onClose={onClose} dismissLabel="Dismiss organize">
+			{stage.kind === "something-else" && (
+				<SomethingElsePanel
+					folderOptions={folderOptions}
+					junkMailboxId={junkMailboxId}
+					onSeed={setSeed}
+				/>
+			)}
+
+			{stage.kind === "widening" && <WideningState />}
+
+			{stage.kind === "error" && (
+				<div className="flex flex-col items-center gap-3 px-5 py-10 text-center">
+					<p className="text-sm font-medium text-danger">
+						Couldn't find similar messages
+					</p>
+					<p className="max-w-xs text-xs text-fg-muted">
+						{error instanceof Error ? error.message : "Please try again."}
+					</p>
+					<Button variant="ghost" onClick={onClose} className="mt-2">
+						Close
+					</Button>
+				</div>
+			)}
+
+			{stage.kind === "organize" && (
+				<OrganizePanel
+					accountId={accountId}
+					mailboxId={mailboxId}
+					selectedMessageIds={selectedMessageIds}
+					anchorMessageId={anchorMessageId}
+					matchedCount={stage.matchedCount}
+					initialScope={seed?.scope}
+					seedMailboxId={seed?.moveMailboxId}
+					fallback={stage.fallback}
+					onClose={onClose}
+				/>
+			)}
+		</BottomSheet>
+	);
+}
+
+function WideningState() {
+	return (
+		<div className="flex flex-col items-center gap-3 px-5 py-10 text-center">
+			<Loader2 className="size-8 animate-spin text-accent-2" />
+			<p className="text-sm font-medium text-fg">Finding similar messages…</p>
+		</div>
+	);
+}

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

@@ -14,7 +14,7 @@ import { OrganizePanel } from "./OrganizePanel";
 // so this shim only exists for the SSR test harness.
 (globalThis as { React?: typeof React }).React = React;
 
-const render = () =>
+const render = (overrides: Partial<Parameters<typeof OrganizePanel>[0]> = {}) =>
 	renderToString(
 		createElement(
 			QueryClientProvider,
@@ -29,6 +29,7 @@ const render = () =>
 					anchorMessageId: "msg-1",
 					matchedCount: 47,
 					onClose: () => undefined,
+					...overrides,
 				}),
 			),
 		) as never,
@@ -54,6 +55,18 @@ describe("OrganizePanel", () => {
 		assert.match(html, /These and new mail like this/);
 		assert.match(html, /Until a date/);
 	});
+
+	it("says it is organizing just the selection when the widen matched nothing (#211 — no dead end)", () => {
+		const html = render({ matchedCount: 0, fallback: true });
+		assert.match(html, /No similar messages found/);
+		assert.match(html, /organizing just your 2 selected/);
+	});
+
+	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.
+		assert.match(html, /Always keep/);
+	});
 });
 
 // The commit button's `disabled` prop is

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

@@ -26,6 +26,22 @@ interface OrganizePanelProps {
 	anchorMessageId: string;
 	/** Similar messages the widen preview matched. */
 	matchedCount: number;
+	/**
+	 * Which scope is selected on open. Defaults to `all-like-these`; the
+	 * zero-match fallback and a "Something else" seed override it.
+	 */
+	initialScope?: OrganizeScope;
+	/**
+	 * Destination folder to pre-select — a "Something else" shortcut or a
+	 * plain-language input seeds this (issue #211).
+	 */
+	seedMailboxId?: string;
+	/**
+	 * The widen matched nothing, so the sentence organizes just the selection
+	 * rather than dead-ending. Changes the heading and defaults the scope to
+	 * `just-these`.
+	 */
+	fallback?: boolean;
 	onClose: () => void;
 }
 
@@ -58,10 +74,17 @@ export function OrganizePanel({
 	selectedMessageIds,
 	anchorMessageId,
 	matchedCount,
+	initialScope,
+	seedMailboxId,
+	fallback = false,
 	onClose,
 }: OrganizePanelProps) {
-	const [scope, setScope] = useState<OrganizeScope>("all-like-these");
-	const [moveMailboxId, setMoveMailboxId] = useState<string>("");
+	const [scope, setScope] = useState<OrganizeScope>(
+		initialScope ?? (fallback ? "just-these" : "all-like-these"),
+	);
+	const [moveMailboxId, setMoveMailboxId] = useState<string>(
+		seedMailboxId ?? "",
+	);
 	const [name, setName] = useState("");
 	const [pickedDate, setPickedDate] = useState("");
 
@@ -155,8 +178,11 @@ 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">
-					{matchedCount} similar message{matchedCount === 1 ? "" : "s"} found
-					{selectionCount > 0 ? ` from ${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>
 

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

@@ -0,0 +1,54 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import React, { createElement } from "react";
+import { renderToString } from "react-dom/server";
+import type { OrganizeSeed } from "@/lib/organize/mobile-organize-flow";
+import { type FolderOption, SomethingElsePanel } from "./SomethingElsePanel";
+
+// The node test loader transpiles remit-ui's `.tsx` with the classic JSX
+// runtime, which references a global `React`. Vite uses the automatic runtime,
+// so this shim only exists for the SSR test harness.
+(globalThis as { React?: typeof React }).React = React;
+
+const FOLDERS: FolderOption[] = [
+	{ id: "mbx-inbox", label: "Inbox" },
+	{ id: "mbx-archive", label: "Archive" },
+	{ id: "mbx-junk", label: "Spam" },
+];
+
+const render = (
+	folderOptions: FolderOption[] = FOLDERS,
+	junkMailboxId?: string,
+) =>
+	renderToString(
+		createElement(SomethingElsePanel, {
+			folderOptions,
+			junkMailboxId,
+			onSeed: (_seed: OrganizeSeed) => undefined,
+		}) as never,
+	);
+
+describe("SomethingElsePanel", () => {
+	it("shows the plain-language prompt and input", () => {
+		const html = render();
+		assert.match(html, /What should Remit do\?/);
+		assert.match(html, /Tell Remit what to do/);
+	});
+
+	it("derives shortcuts from the account's real folders", () => {
+		const html = render();
+		assert.match(html, /Always keep in Inbox/);
+		assert.match(html, /File in Archive/);
+	});
+
+	it("offers the appointed Junk mailbox by its own label", () => {
+		const html = render(FOLDERS, "mbx-junk");
+		assert.match(html, /Move to Spam/);
+	});
+
+	it("offers no folder shortcuts when the account has none", () => {
+		const html = render([]);
+		assert.doesNotMatch(html, /Always keep in Inbox/);
+		assert.doesNotMatch(html, /File in Archive/);
+	});
+});

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

@@ -0,0 +1,159 @@
+import { Button, Input } from "@remit/ui";
+import { ArrowUp } from "lucide-react";
+import { useMemo, useState } from "react";
+import type { OrganizeSeed } from "@/lib/organize/mobile-organize-flow";
+
+export interface FolderOption {
+	id: string;
+	label: string;
+}
+
+interface SomethingElsePanelProps {
+	/** The account's move destinations, the same set the sentence's folder picker uses. */
+	folderOptions: FolderOption[];
+	/** The appointed Junk mailbox, offered as a shortcut when present. */
+	junkMailboxId?: string;
+	/** Chosen shortcut or parsed input — seeds the organize sentence's folder/scope. */
+	onSeed: (seed: OrganizeSeed) => void;
+}
+
+interface Shortcut {
+	id: string;
+	label: string;
+	seed: OrganizeSeed;
+}
+
+const findFolder = (
+	folderOptions: FolderOption[],
+	label: string,
+): FolderOption | undefined =>
+	folderOptions.find((folder) => folder.label.toLowerCase() === label);
+
+/**
+ * Shortcuts are derived from the account's real folders — there is no
+ * suggestion endpoint, so the panel offers the moves it can actually commit:
+ * keep it in the Inbox as a standing rule, file it in Archive, or send it to
+ * the appointed Junk mailbox. Each seeds the organize sentence; the user still
+ * confirms the scope.
+ */
+const buildShortcuts = (
+	folderOptions: FolderOption[],
+	junkMailboxId: string | undefined,
+): Shortcut[] => {
+	const shortcuts: Shortcut[] = [];
+	const inbox = findFolder(folderOptions, "inbox");
+	if (inbox) {
+		shortcuts.push({
+			id: "keep-inbox",
+			label: "Always keep in Inbox",
+			seed: { moveMailboxId: inbox.id, scope: "standing" },
+		});
+	}
+	const archive = findFolder(folderOptions, "archive");
+	if (archive) {
+		shortcuts.push({
+			id: "file-archive",
+			label: "File in Archive",
+			seed: { moveMailboxId: archive.id },
+		});
+	}
+	const junk = junkMailboxId
+		? folderOptions.find((folder) => folder.id === junkMailboxId)
+		: undefined;
+	if (junk) {
+		shortcuts.push({
+			id: "move-junk",
+			label: `Move to ${junk.label}`,
+			seed: { moveMailboxId: junk.id },
+		});
+	}
+	return shortcuts;
+};
+
+/**
+ * Reads a plain-language instruction into a seed without an NLP endpoint: it
+ * matches the typed words against the account's own folder names and reads an
+ * "always"/"keep" phrasing as the standing scope. Whatever it can't resolve to
+ * a folder still opens the sentence, where the picker is one tap away — never a
+ * dead end.
+ */
+const parseInstruction = (
+	text: string,
+	folderOptions: FolderOption[],
+): OrganizeSeed => {
+	const lower = text.toLowerCase();
+	const folder = folderOptions.find((option) =>
+		lower.includes(option.label.toLowerCase()),
+	);
+	const standing = /\b(always|keep|future|from now)\b/.test(lower);
+	return {
+		moveMailboxId: folder?.id,
+		scope: standing ? "standing" : undefined,
+	};
+};
+
+/**
+ * The "Something else" fallback (issue #211): smart shortcuts plus a
+ * plain-language input, both of which seed the organize sentence's folder and
+ * scope. Presentational — the flow owns the folder data and what a seed does.
+ */
+export function SomethingElsePanel({
+	folderOptions,
+	junkMailboxId,
+	onSeed,
+}: SomethingElsePanelProps) {
+	const [text, setText] = useState("");
+	const shortcuts = useMemo(
+		() => buildShortcuts(folderOptions, junkMailboxId),
+		[folderOptions, junkMailboxId],
+	);
+
+	const submit = () => {
+		const trimmed = text.trim();
+		if (!trimmed) return;
+		onSeed(parseInstruction(trimmed, folderOptions));
+	};
+
+	return (
+		<div className="flex min-h-0 flex-col">
+			<div className="border-b border-line px-5 py-3">
+				<h2 className="text-sm font-semibold text-fg">What should Remit do?</h2>
+				<p className="mt-0.5 text-xs text-fg-muted">
+					Pick a shortcut or say it in your own words.
+				</p>
+			</div>
+
+			<div className="min-h-0 flex-1 space-y-2 overflow-y-auto px-5 py-4">
+				{shortcuts.map((shortcut) => (
+					<Button
+						key={shortcut.id}
+						variant="secondary"
+						onClick={() => onSeed(shortcut.seed)}
+						className="h-12 w-full justify-start px-4"
+					>
+						{shortcut.label}
+					</Button>
+				))}
+			</div>
+
+			<div className="flex items-center gap-2 border-t border-line px-5 py-3">
+				<Input
+					value={text}
+					onChange={(event) => setText(event.target.value)}
+					onKeyDown={(event) => event.key === "Enter" && submit()}
+					placeholder="Tell Remit what to do…"
+					aria-label="Tell Remit what to do"
+					className="flex-1"
+				/>
+				<Button
+					variant="primary"
+					aria-label="Send"
+					onClick={submit}
+					disabled={!text.trim()}
+					icon={<ArrowUp className="size-4" />}
+					className="size-9 shrink-0 px-0"
+				/>
+			</div>
+		</div>
+	);
+}

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

@@ -0,0 +1,197 @@
+import { mailboxOperationsListMailboxesQueryKey } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import type { RemitImapMailboxResponse } from "@remit/api-http-client/types.gen.ts";
+import { BottomSheet } from "@remit/ui";
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import type { ReactNode } from "react";
+import { ErrorBannerProvider } from "@/components/ui/ErrorBannerProvider";
+import { OrganizePanel } from "./OrganizePanel";
+import type { FolderOption } from "./SomethingElsePanel";
+import { SomethingElsePanel } from "./SomethingElsePanel";
+
+/**
+ * `Flows/Smart Organize` — the guided select-similar → organize flow (issue
+ * #211), rendered from the real web-client components, not a prototype copy:
+ * the same {@link OrganizePanel} the desktop dialog and the mobile sheet use,
+ * and the same {@link SomethingElsePanel} the flow seeds from. The prototype's
+ * interactive `Inbox` / `Walkthrough` stories live alongside these in the
+ * workbench; these show each in-sheet panel in isolation so they can't drift
+ * from what ships.
+ */
+
+const ACCOUNT_ID = "acc-1";
+
+const makeMailbox = (
+	mailboxId: string,
+	fullPath: string,
+): RemitImapMailboxResponse => ({
+	mailboxId,
+	accountId: ACCOUNT_ID,
+	namespaceType: "personal",
+	namespacePrefix: "",
+	hierarchyDelimiter: "/",
+	fullPath,
+	messageCount: 0,
+	unseenCount: 0,
+	deletedCount: 0,
+	lastSyncUid: 0,
+	highWaterMarkUid: 0,
+	lastMessageSyncAt: 0,
+	createdAt: 0,
+	updatedAt: 0,
+});
+
+const MAILBOXES: RemitImapMailboxResponse[] = [
+	makeMailbox("mbx-inbox", "INBOX"),
+	makeMailbox("mbx-archive", "Archive"),
+	makeMailbox("mbx-receipts", "Receipts"),
+	makeMailbox("mbx-travel", "Travel"),
+	makeMailbox("mbx-junk", "Junk"),
+];
+
+const FOLDER_OPTIONS: FolderOption[] = [
+	{ id: "mbx-inbox", label: "Inbox" },
+	{ id: "mbx-archive", label: "Archive" },
+	{ id: "mbx-receipts", label: "Receipts" },
+	{ id: "mbx-junk", label: "Junk" },
+];
+
+/**
+ * A QueryClient pre-seeded with the account's mailboxes, so the sentence's
+ * folder picker renders its real options without a network round-trip.
+ */
+function seededClient(): QueryClient {
+	const client = new QueryClient({
+		defaultOptions: { queries: { retry: false } },
+	});
+	client.setQueryData(
+		mailboxOperationsListMailboxesQueryKey({ path: { accountId: ACCOUNT_ID } }),
+		{ items: MAILBOXES },
+	);
+	return client;
+}
+
+/** Phone frame + a bottom sheet holding the panel, mirroring the mobile home. */
+function SheetStage({ children }: { children: ReactNode }) {
+	return (
+		<QueryClientProvider client={seededClient()}>
+			<ErrorBannerProvider>
+				<div className="relative mx-auto h-dvh w-full shrink-0 overflow-hidden bg-surface sm:my-6 sm:h-[760px] sm:w-[390px] sm:rounded-[2rem] sm:border sm:border-line sm:shadow-sm">
+					<div className="divide-y divide-line opacity-50">
+						{Array.from({ length: 8 }).map((_, index) => (
+							<div
+								// biome-ignore lint/suspicious/noArrayIndexKey: static backdrop skeleton, no ids
+								key={index}
+								className="flex items-start gap-3 px-row-inset py-2.5"
+							>
+								<div className="mt-0.5 size-7 shrink-0 rounded-full bg-surface-sunken" />
+								<div className="min-w-0 flex-1 space-y-1">
+									<div className="h-2.5 w-1/3 rounded bg-surface-sunken" />
+									<div className="h-2 w-2/3 rounded bg-surface-sunken" />
+								</div>
+							</div>
+						))}
+					</div>
+					<BottomSheet open onClose={() => undefined}>
+						{children}
+					</BottomSheet>
+				</div>
+			</ErrorBannerProvider>
+		</QueryClientProvider>
+	);
+}
+
+const meta: Meta = {
+	title: "Flows/Smart Organize",
+	parameters: { layout: "fullscreen" },
+};
+export default meta;
+
+type Story = StoryObj;
+
+/** The organize sentence on a widened selection — folder picker + four scopes. */
+export const Organize: Story = {
+	render: () => (
+		<SheetStage>
+			<OrganizePanel
+				accountId={ACCOUNT_ID}
+				mailboxId="mbx-inbox"
+				selectedMessageIds={["msg-1", "msg-2", "msg-3"]}
+				anchorMessageId="msg-1"
+				matchedCount={47}
+				onClose={() => undefined}
+			/>
+		</SheetStage>
+	),
+};
+
+/**
+ * A larger widen — the same sentence over a broad match set, as when the anchor
+ * is a common sender.
+ */
+export const FromSearch: Story = {
+	name: "From Search",
+	render: () => (
+		<SheetStage>
+			<OrganizePanel
+				accountId={ACCOUNT_ID}
+				mailboxId="mbx-inbox"
+				selectedMessageIds={["msg-1"]}
+				anchorMessageId="msg-1"
+				matchedCount={412}
+				seedMailboxId="mbx-archive"
+				onClose={() => undefined}
+			/>
+		</SheetStage>
+	),
+};
+
+/** The standing scope pre-selected — the "Always keep…" sentence + filter name. */
+export const AlwaysRule: Story = {
+	name: "Always Rule",
+	render: () => (
+		<SheetStage>
+			<OrganizePanel
+				accountId={ACCOUNT_ID}
+				mailboxId="mbx-inbox"
+				selectedMessageIds={["msg-1", "msg-2"]}
+				anchorMessageId="msg-1"
+				matchedCount={47}
+				initialScope="standing"
+				seedMailboxId="mbx-travel"
+				onClose={() => undefined}
+			/>
+		</SheetStage>
+	),
+};
+
+/** The widen matched nothing — the sentence organizes just the selection. */
+export const NoSimilarFound: Story = {
+	name: "No Similar Found",
+	render: () => (
+		<SheetStage>
+			<OrganizePanel
+				accountId={ACCOUNT_ID}
+				mailboxId="mbx-inbox"
+				selectedMessageIds={["msg-1", "msg-2"]}
+				anchorMessageId="msg-1"
+				matchedCount={0}
+				fallback
+				onClose={() => undefined}
+			/>
+		</SheetStage>
+	),
+};
+
+/** The "Something else" fallback: shortcuts derived from folders + an input. */
+export const SomethingElse: Story = {
+	render: () => (
+		<SheetStage>
+			<SomethingElsePanel
+				folderOptions={FOLDER_OPTIONS}
+				junkMailboxId="mbx-junk"
+				onSeed={() => undefined}
+			/>
+		</SheetStage>
+	),
+};

package/src/lib/organize/mobile-organize-flow.test.ts

@@ -0,0 +1,96 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import {
+	type OrganizeStageInput,
+	resolveOrganizeStage,
+} from "./mobile-organize-flow";
+
+const base: OrganizeStageInput = {
+	entry: "select-similar",
+	hasSeed: true,
+	previewStatus: "idle",
+	matchedCount: undefined,
+};
+
+describe("resolveOrganizeStage — the guided mobile flow's state machine", () => {
+	it("select-similar shows the widening state before the preview resolves", () => {
+		assert.deepEqual(resolveOrganizeStage({ ...base, previewStatus: "idle" }), {
+			kind: "widening",
+		});
+		assert.deepEqual(
+			resolveOrganizeStage({ ...base, previewStatus: "pending" }),
+			{ kind: "widening" },
+		);
+	});
+
+	it("opens the organize sentence on the widened set once the preview matches", () => {
+		assert.deepEqual(
+			resolveOrganizeStage({
+				...base,
+				previewStatus: "success",
+				matchedCount: 47,
+			}),
+			{ kind: "organize", matchedCount: 47, fallback: false },
+		);
+	});
+
+	it("falls back to organizing the selection when the widen matches nothing — no dead end", () => {
+		assert.deepEqual(
+			resolveOrganizeStage({
+				...base,
+				previewStatus: "success",
+				matchedCount: 0,
+			}),
+			{ kind: "organize", matchedCount: 0, fallback: true },
+		);
+		// A success with an undefined count is treated as zero, not a crash.
+		assert.deepEqual(
+			resolveOrganizeStage({
+				...base,
+				previewStatus: "success",
+				matchedCount: undefined,
+			}),
+			{ kind: "organize", matchedCount: 0, fallback: true },
+		);
+	});
+
+	it("surfaces the error branch when the widen fails", () => {
+		assert.deepEqual(
+			resolveOrganizeStage({ ...base, previewStatus: "error" }),
+			{ kind: "error" },
+		);
+	});
+
+	it("something-else shows the shortcuts + input until a seed is chosen", () => {
+		assert.deepEqual(
+			resolveOrganizeStage({
+				entry: "something-else",
+				hasSeed: false,
+				previewStatus: "success",
+				matchedCount: 47,
+			}),
+			{ kind: "something-else" },
+		);
+	});
+
+	it("something-else widens after the seed, then opens the seeded sentence", () => {
+		assert.deepEqual(
+			resolveOrganizeStage({
+				entry: "something-else",
+				hasSeed: true,
+				previewStatus: "pending",
+				matchedCount: undefined,
+			}),
+			{ kind: "widening" },
+		);
+		assert.deepEqual(
+			resolveOrganizeStage({
+				entry: "something-else",
+				hasSeed: true,
+				previewStatus: "success",
+				matchedCount: 12,
+			}),
+			{ kind: "organize", matchedCount: 12, fallback: false },
+		);
+	});
+});

package/src/lib/organize/mobile-organize-flow.ts

@@ -0,0 +1,73 @@
+import type { OrganizeScope } from "./organize-model";
+
+/**
+ * How the guided mobile flow was entered from the selection sheet:
+ *
+ * - `select-similar` — widen straight into the organize sentence.
+ * - `something-else` — collect a folder/scope seed from shortcuts or a
+ *   plain-language input first, then widen into the seeded sentence.
+ */
+export type OrganizeEntry = "select-similar" | "something-else";
+
+/** The read-only widen preview's lifecycle (POST /organize/preview). */
+export type PreviewStatus = "idle" | "pending" | "success" | "error";
+
+/** A folder/scope the "Something else" panel pre-fills the sentence with. */
+export interface OrganizeSeed {
+	moveMailboxId?: string;
+	scope?: OrganizeScope;
+}
+
+/**
+ * The stage the guided flow renders, resolved from the entry, whether a
+ * "Something else" seed has been chosen yet, and where the widen preview is:
+ *
+ * - `something-else` — the shortcuts + input, shown until a seed is picked.
+ * - `widening` — the brief widening state between the tap and the sentence.
+ * - `error` — the widen failed; a dead end only in the sense that it offers a
+ *   close, never a broken sentence.
+ * - `organize` — the committed sentence, on the widened set. `fallback` is true
+ *   when the widen matched nothing, so the sentence organizes just the
+ *   selection instead of a dead end (issue #211).
+ */
+export type OrganizeStage =
+	| { kind: "something-else" }
+	| { kind: "widening" }
+	| { kind: "error" }
+	| { kind: "organize"; matchedCount: number; fallback: boolean };
+
+export interface OrganizeStageInput {
+	entry: OrganizeEntry;
+	/** "Something else" only: whether the user has chosen a seed yet. */
+	hasSeed: boolean;
+	previewStatus: PreviewStatus;
+	/** The widen's matched total; defined once `previewStatus` is `success`. */
+	matchedCount: number | undefined;
+}
+
+/**
+ * The pure state machine behind the guided organize sheet:
+ * `idle → widening → organize` for select-similar, with a `something-else`
+ * seeding step in front for that entry, an `error` branch when the widen
+ * fails, and the zero-match `fallback` that keeps the organize sentence usable
+ * on the selection alone. Kept pure so every transition is testable without a
+ * DOM, React Query, or a network — the component only reads the stage back.
+ */
+export const resolveOrganizeStage = ({
+	entry,
+	hasSeed,
+	previewStatus,
+	matchedCount,
+}: OrganizeStageInput): OrganizeStage => {
+	if (entry === "something-else" && !hasSeed) {
+		return { kind: "something-else" };
+	}
+	if (previewStatus === "error") {
+		return { kind: "error" };
+	}
+	if (previewStatus !== "success") {
+		return { kind: "widening" };
+	}
+	const matched = matchedCount ?? 0;
+	return { kind: "organize", matchedCount: matched, fallback: matched === 0 };
+};