@remit/web-client 0.0.91 → 0.0.92

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/web-client",
-  "version": "0.0.91",
+  "version": "0.0.92",
   "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.selection.test.ts

@@ -45,10 +45,17 @@ describe("MessageList selection mode", () => {
 	it("turns the back gesture into an exit, and only while selecting", () => {
 		assert.match(
 			source,
-			/shouldExitSelectionOnNavigate\(action, hasSelection\)/,
+			/shouldExitSelectionOnNavigate\(action, hasSelection, wizardStep\)/,
 		);
 		assert.match(source, /disabled: !hasSelection/);
 	});
+
+	it("leaves the back gesture to the wizard while the wizard is open", () => {
+		assert.match(
+			source,
+			/disabled: !hasSelection \|\| wizardStep !== undefined/,
+		);
+	});
 });
 
 /**

package/src/components/mail/MessageList.tsx

@@ -52,6 +52,7 @@ import {
 	shouldExitSelectionOnNavigate,
 } from "@/lib/selection-mode";
 import { cn } from "@/lib/utils";
+import { useWizardStepValue } from "@/lib/wizard-history";
 import { LabelApplyTrigger } from "./LabelApplyTrigger";
 import { MoveToTrigger } from "./MoveToTrigger";
 import { MobileOrganizeFlow } from "./organize/MobileOrganizeFlow";
@@ -232,6 +233,7 @@ export const MessageList = ({
 	const parentRef = useRef<HTMLDivElement>(null);
 	const navigate = useNavigate();
 	const isDesktop = useIsDesktop();
+	const wizardStep = useWizardStepValue();
 	const [organizeOpen, setOrganizeOpen] = useState(false);
 	// Mobile only: which selection-sheet entry opened the guided organize flow
 	// (`null` when closed). Desktop uses `organizeOpen` + `OrganizeDialog`
@@ -1060,12 +1062,14 @@ export const MessageList = ({
 	// — is never blocked, and the blocker is off entirely with nothing selected.
 	useBlocker({
 		shouldBlockFn: ({ action }) => {
-			if (!shouldExitSelectionOnNavigate(action, hasSelection)) return false;
+			if (!shouldExitSelectionOnNavigate(action, hasSelection, wizardStep)) {
+				return false;
+			}
 			exitSelection();
 			return true;
 		},
 		enableBeforeUnload: false,
-		disabled: !hasSelection,
+		disabled: !hasSelection || wizardStep !== undefined,
 	});
 
 	// Load more when scrolling near the bottom

package/src/components/mail/SelectionWizardHost.tsx

@@ -0,0 +1,191 @@
+import {
+	type ClauseDraft,
+	type ClauseEditState,
+	type MatchCount,
+	type MatchMode,
+	type RunState,
+	SelectionWizard,
+	type StepId,
+	stepBlockedReason,
+	stepIndex,
+	stepsFor,
+	type Verb,
+	type WizardDraft,
+	type WizardMessage,
+} from "@remit/ui";
+import { useCallback, useState } from "react";
+import { useWizardStep } from "@/lib/wizard-history";
+
+const OPENING_STEP: StepId = "match";
+const UNCOUNTED: MatchCount = { status: "uncounted" };
+const EMPTY_DRAFT: WizardDraft = { clauses: [], matchOperator: "all" };
+
+/** How the commit ended, once something commits it (#483). */
+export interface WizardOutcome {
+	state: RunState;
+	matched: number;
+	applied: number;
+	failures: readonly WizardMessage[];
+}
+
+/** Nothing has been sent anywhere, so nothing can have been done. */
+const NOTHING_COMMITTED: WizardOutcome = {
+	state: "commitFailed",
+	matched: 0,
+	applied: 0,
+	failures: [],
+};
+
+export interface SelectionWizardHostProps {
+	verb: Verb;
+	selectedCount: number;
+	outcome?: WizardOutcome;
+}
+
+export function SelectionWizardHost({
+	verb,
+	selectedCount,
+	outcome = NOTHING_COMMITTED,
+}: SelectionWizardHostProps) {
+	const { step, goToStep, goBack, closeWizard } = useWizardStep(OPENING_STEP);
+	const [mode, setMode] = useState<MatchMode>("selected");
+	const [draft, setDraft] = useState<WizardDraft>(EMPTY_DRAFT);
+	const [clauseEdit, setClauseEdit] = useState<ClauseEditState | undefined>(
+		undefined,
+	);
+	const [nudgedStep, setNudgedStep] = useState<StepId | undefined>(undefined);
+
+	const startAddClause = useCallback(() => {
+		setClauseEdit({ mode: "add", draft: { field: "From", value: "" } });
+	}, []);
+
+	const startEditClause = useCallback(
+		(clauseId: string) => {
+			const clause = draft.clauses.find((held) => held.id === clauseId);
+			if (!clause) return;
+			setClauseEdit({
+				mode: "edit",
+				clauseId,
+				draft: { field: clause.field, value: clause.value },
+			});
+		},
+		[draft.clauses],
+	);
+
+	const removeClause = useCallback((clauseId: string) => {
+		setDraft((held) => ({
+			...held,
+			clauses: held.clauses.filter((clause) => clause.id !== clauseId),
+		}));
+	}, []);
+
+	const changeClauseDraft = useCallback((next: ClauseDraft) => {
+		setClauseEdit((edit) => edit && { ...edit, draft: next });
+	}, []);
+
+	const submitClause = useCallback(() => {
+		setClauseEdit((edit) => {
+			if (!edit) return undefined;
+			setDraft((held) => ({
+				...held,
+				clauses: edit.clauseId
+					? held.clauses.map((clause) =>
+							clause.id === edit.clauseId
+								? { ...clause, ...edit.draft }
+								: clause,
+						)
+					: [...held.clauses, { id: crypto.randomUUID(), ...edit.draft }],
+			}));
+			return undefined;
+		});
+	}, []);
+
+	if (!step) return null;
+
+	const steps = stepsFor({ verb, mode, scope: draft.scope });
+	// The step the screens are on, which is the held one only while the answers
+	// still hold it. Reading the URL's step here and the resolved one on screen
+	// is how a footer comes to name a screen nobody is looking at.
+	const current = steps[stepIndex(steps, step)];
+	const blockedReason = stepBlockedReason(current, draft, UNCOUNTED);
+	const sample = {
+		messages: [],
+		count: UNCOUNTED,
+		label: "Messages this covers",
+	};
+
+	const advance = () => {
+		if (blockedReason) {
+			setNudgedStep(current);
+			return;
+		}
+		const next = steps[stepIndex(steps, current) + 1];
+		if (next) goToStep(next);
+	};
+
+	return (
+		<SelectionWizard
+			verb={verb}
+			steps={steps}
+			step={current}
+			blockedReason={blockedReason}
+			nudged={nudgedStep === current}
+			onBack={goBack}
+			onExit={() => closeWizard(steps, current)}
+			onContinue={advance}
+			onCommit={() => goToStep("run")}
+			match={{
+				selectedCount,
+				mode,
+				onModeChange: setMode,
+				onSemanticFallback: () => setMode("properties"),
+				sample,
+			}}
+			properties={{
+				clauses: draft.clauses,
+				matchOperator: draft.matchOperator,
+				onMatchOperatorChange: (matchOperator) =>
+					setDraft((held) => ({ ...held, matchOperator })),
+				clauseEdit,
+				onStartAddClause: startAddClause,
+				onStartEditClause: startEditClause,
+				onRemoveClause: removeClause,
+				onChangeDraft: changeClauseDraft,
+				onSubmitClause: submitClause,
+				onCancelClause: () => setClauseEdit(undefined),
+				sample,
+			}}
+			rule={{
+				draft,
+				onScopeChange: (scope) => setDraft((held) => ({ ...held, scope })),
+				onUntilChange: (until) => setDraft((held) => ({ ...held, until })),
+			}}
+			name={{
+				name: draft.name ?? "",
+				onNameChange: (name) => setDraft((held) => ({ ...held, name })),
+				nudged: nudgedStep === current,
+			}}
+			review={{
+				verb,
+				mode,
+				selectedCount,
+				clauses: draft.clauses,
+				matchOperator: draft.matchOperator,
+				scope: draft.scope,
+				until: draft.until,
+				ruleName: draft.name,
+				sample,
+			}}
+			run={{
+				state: outcome.state,
+				verb,
+				scope: draft.scope,
+				matched: outcome.matched,
+				applied: outcome.applied,
+				failures: outcome.failures,
+				onRetry: goBack,
+				onDismiss: () => closeWizard(steps, current),
+			}}
+		/>
+	);
+}

package/src/components/mail/ThreadListInteraction.tsx

@@ -36,6 +36,7 @@ import type { TriageContextUpdate } from "@/hooks/useTriageLayer";
 import { formatDeleteToTrashTitle } from "@/lib/format";
 import { tabStopId } from "@/lib/list-focus";
 import { useListHeaderChrome } from "@/lib/list-header-chrome";
+import { useMailContext } from "@/lib/mail-context";
 import type { MessageListCommands } from "./MessageList";
 import type { MessageRowSelection } from "./MessageRow";
 
@@ -186,6 +187,14 @@ export function ThreadListInteraction({
 		if (orderedIds.length > 0) toggleAll(orderedIds);
 	}, [orderedIds, toggleAll]);
 
+	// The selection wizard is mounted on the route, above this provider, and
+	// acts on these rows — so it reads the count from here rather than keeping
+	// one of its own (#477).
+	const { onSelectedCountChange } = useMailContext();
+	useEffect(() => {
+		onSelectedCountChange(selectedCount);
+	}, [selectedCount, onSelectedCountChange]);
+
 	// A row that leaves the list — a chip filter, a collapsed section, a
 	// completed delete — cannot stay selected. Survivors keep their selection.
 	const { intersectWith } = selection;

package/src/lib/mail-context.ts

@@ -54,6 +54,13 @@ export interface MailContextValue {
 	onToggleIntelligence: () => void;
 	/** Set the pane open/closed and persist the choice (desktop default-open). */
 	onSetIntelligenceOpen: (open: boolean) => void;
+	/**
+	 * How many rows the list has ticked. The selection is owned by the list, and
+	 * surfaces mounted beside it — the selection wizard (#477) — need the same
+	 * number the bar is counting rather than one of their own.
+	 */
+	selectedCount: number;
+	onSelectedCountChange: (count: number) => void;
 }
 
 export const MailContext = createContext<MailContextValue | null>(null);
@@ -78,6 +85,8 @@ export const useMailContext = (): MailContextValue => {
 			intelligenceOpen: false,
 			onToggleIntelligence: () => {},
 			onSetIntelligenceOpen: () => {},
+			selectedCount: 0,
+			onSelectedCountChange: () => {},
 		}
 	);
 };

package/src/lib/selection-mode.test.ts

@@ -28,17 +28,31 @@ describe("deriveIsMultiSelectMode", () => {
 
 describe("shouldExitSelectionOnNavigate", () => {
 	test("back while selecting exits selection instead of navigating", () => {
-		assert.equal(shouldExitSelectionOnNavigate("BACK", true), true);
+		assert.equal(shouldExitSelectionOnNavigate("BACK", true, undefined), true);
 	});
 
 	test("back with nothing selected is left alone", () => {
-		assert.equal(shouldExitSelectionOnNavigate("BACK", false), false);
+		assert.equal(
+			shouldExitSelectionOnNavigate("BACK", false, undefined),
+			false,
+		);
+	});
+
+	test("back inside the wizard pops a step instead of the selection", () => {
+		assert.equal(shouldExitSelectionOnNavigate("BACK", true, "match"), false);
+		assert.equal(shouldExitSelectionOnNavigate("BACK", true, "review"), false);
 	});
 
 	test("forward, push, replace and go are never blocked", () => {
-		assert.equal(shouldExitSelectionOnNavigate("FORWARD", true), false);
-		assert.equal(shouldExitSelectionOnNavigate("PUSH", true), false);
-		assert.equal(shouldExitSelectionOnNavigate("REPLACE", true), false);
-		assert.equal(shouldExitSelectionOnNavigate("GO", true), false);
+		assert.equal(
+			shouldExitSelectionOnNavigate("FORWARD", true, undefined),
+			false,
+		);
+		assert.equal(shouldExitSelectionOnNavigate("PUSH", true, undefined), false);
+		assert.equal(
+			shouldExitSelectionOnNavigate("REPLACE", true, undefined),
+			false,
+		);
+		assert.equal(shouldExitSelectionOnNavigate("GO", true, undefined), false);
 	});
 });

package/src/lib/selection-mode.ts

@@ -3,6 +3,8 @@
  * and 10). Pure so "one source of truth, one exit" is testable without a DOM.
  */
 
+import type { StepId } from "@remit/ui";
+
 /** The subset of `@tanstack/history`'s `HistoryAction` a blocker can see. */
 export type NavigationAction = "PUSH" | "REPLACE" | "FORWARD" | "BACK" | "GO";
 
@@ -22,8 +24,13 @@ export const deriveIsMultiSelectMode = (
  * Whether a history navigation should exit selection mode instead of leaving
  * the route. Only the back gesture is intercepted, so a navigation the app
  * itself starts (opening a message, switching mailboxes) is never blocked.
+ *
+ * While the selection wizard is open its own steps own the back gesture, and
+ * the selection is what the wizard is acting on — swallowing back there would
+ * clear the selection out from under the flow instead of popping a step.
  */
 export const shouldExitSelectionOnNavigate = (
 	action: NavigationAction,
 	hasSelection: boolean,
-): boolean => action === "BACK" && hasSelection;
+	wizardStep: StepId | undefined,
+): boolean => action === "BACK" && hasSelection && wizardStep === undefined;

package/src/lib/wizard-history.test.ts

@@ -0,0 +1,176 @@
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { describe, it } from "node:test";
+import { fileURLToPath } from "node:url";
+import {
+	backExits,
+	type MatchMode,
+	type RuleScope,
+	type StepId,
+	stepIndex,
+	stepsFor,
+	type Verb,
+	type WizardAnswers,
+} from "@remit/ui";
+import {
+	ownedHistoryEntries,
+	wizardStepFromParam,
+	wizardStepValue,
+} from "./wizard-history.js";
+
+const VERBS: readonly Verb[] = [
+	"delete",
+	"move",
+	"junk",
+	"markRead",
+	"organize",
+];
+const MODES: readonly MatchMode[] = ["selected", "similar", "properties"];
+const SCOPES: readonly (RuleScope | undefined)[] = [
+	undefined,
+	"once",
+	"standing",
+	"until",
+];
+
+const answerSets = (): WizardAnswers[] => {
+	const sets: WizardAnswers[] = [];
+	for (const verb of VERBS) {
+		for (const mode of MODES) {
+			for (const scope of SCOPES) {
+				for (const fromSearch of [false, true]) {
+					sets.push({ verb, mode, scope, fromSearch });
+				}
+			}
+		}
+	}
+	return sets;
+};
+
+const here = dirname(fileURLToPath(import.meta.url));
+const source = readFileSync(resolve(here, "wizard-history.ts"), "utf8");
+
+/** The steps up to and including the one an answer is given on. */
+const prefixThrough = (steps: readonly StepId[], step: StepId): StepId[] =>
+	steps.slice(0, steps.indexOf(step) + 1);
+
+/**
+ * The re-root runs inside a router, so the rule is enforced by reading the
+ * source — as `../components/mail/MessageList.selection.test.ts` does for its
+ * own component-level rules. What it pins is where the decision comes from: a
+ * step the app itself pushed must never be re-rooted, or the push that opens
+ * the wizard from a verb (#483) duplicates the entry underneath it and the
+ * first back after Cancel appears to do nothing.
+ */
+describe("re-rooting a wizard that was loaded into", () => {
+	it("decides from what the first render held, not from a flag", () => {
+		assert.match(source, /useRef\(step !== undefined\)/);
+		assert.match(
+			source,
+			/if \(!loadedHoldingStep\.current\) return;\s*\n\s*loadedHoldingStep\.current = false;/,
+		);
+	});
+
+	it("is never armed by a step the app pushed", () => {
+		const goToStep = source.slice(source.indexOf("const goToStep"));
+		assert.doesNotMatch(goToStep, /loadedHoldingStep/);
+	});
+
+	it("does not re-run when the step changes", () => {
+		assert.doesNotMatch(source, /\}, \[step, openingStep, navigate\]\)/);
+	});
+});
+
+describe("the wizard step in the URL", () => {
+	it("round-trips every step the wizard can reach", () => {
+		for (const answers of answerSets()) {
+			for (const step of stepsFor(answers)) {
+				assert.equal(wizardStepFromParam(step), step);
+			}
+		}
+	});
+
+	it("reads a value the wizard cannot be on as no step", () => {
+		for (const value of [undefined, "", "Match", "step-1", 2, null, {}]) {
+			assert.equal(wizardStepFromParam(value), undefined);
+		}
+	});
+
+	it("never fails validation, so a mistyped link still lands on the mail", () => {
+		for (const value of ["nope", "MATCH", "run ", 7, [], null, undefined]) {
+			const parsed = wizardStepValue.safeParse(value);
+			assert.ok(parsed.success);
+			assert.equal(parsed.data, undefined);
+		}
+		assert.equal(wizardStepValue.parse("review"), "review");
+	});
+});
+
+describe("the history entries the wizard owns", () => {
+	it("is one per step reached, on every shape of the list", () => {
+		for (const answers of answerSets()) {
+			const steps = stepsFor(answers);
+			steps.forEach((step, position) => {
+				assert.equal(ownedHistoryEntries(steps, step), position + 1);
+			});
+		}
+	});
+
+	it("cannot be moved by the match door, which is answered before it", () => {
+		for (const verb of VERBS) {
+			for (const scope of SCOPES) {
+				const prefixes = MODES.map((mode) =>
+					prefixThrough(stepsFor({ verb, mode, scope }), "match"),
+				);
+				for (const prefix of prefixes) {
+					assert.deepEqual(prefix, prefixes[0]);
+					for (const step of prefix) {
+						const counts = MODES.map((mode) =>
+							ownedHistoryEntries(stepsFor({ verb, mode, scope }), step),
+						);
+						assert.equal(new Set(counts).size, 1);
+					}
+				}
+			}
+		}
+	});
+
+	it("cannot be moved by the scope, which is answered before it", () => {
+		for (const mode of MODES) {
+			for (const fromSearch of [false, true]) {
+				const listFor = (scope: RuleScope | undefined) =>
+					stepsFor({ verb: "organize", mode, scope, fromSearch });
+				const prefixes = SCOPES.map((scope) =>
+					prefixThrough(listFor(scope), "rule"),
+				);
+				for (const prefix of prefixes) {
+					assert.deepEqual(prefix, prefixes[0]);
+					for (const step of prefix) {
+						const counts = SCOPES.map((scope) =>
+							ownedHistoryEntries(listFor(scope), step),
+						);
+						assert.equal(new Set(counts).size, 1);
+					}
+				}
+			}
+		}
+	});
+
+	it("rewinds the whole flow from the steps Back leaves on", () => {
+		for (const answers of answerSets()) {
+			const steps = stepsFor(answers);
+			assert.ok(backExits(steps, steps[0]));
+			assert.equal(ownedHistoryEntries(steps, steps[0]), 1);
+			const run = steps[steps.length - 1];
+			assert.ok(backExits(steps, run));
+			assert.equal(ownedHistoryEntries(steps, run), steps.length);
+		}
+	});
+
+	it("holds a step the answers dropped to the opening entry", () => {
+		const steps = stepsFor({ verb: "delete", mode: "selected" });
+		assert.equal(stepIndex(steps, "properties"), 0);
+		assert.equal(ownedHistoryEntries(steps, "properties"), 1);
+	});
+});

package/src/lib/wizard-history.ts

@@ -0,0 +1,116 @@
+/**
+ * The selection wizard's step in the URL, and the history entries it owns
+ * (#477 clause 1.6). TanStack Router owns history here: the step is a validated
+ * `wizard` search param on /mail, pushed with `navigate({ search })`, so
+ * `router.state.location` and `window.location` never disagree.
+ *
+ * The wizard is rooted on an entry that carries no step, so the entries it owns
+ * are the pushes that reached the current step: one for the opening step, one
+ * per advance. A document that loads straight into a step has no such root, and
+ * no answers behind the step either, so it is re-rooted at the opening step
+ * before anything else — otherwise the number of entries to rewind is a guess
+ * about a tab this code never saw.
+ *
+ * Which steps Back leaves the wizard from is `backExits` in the step model, and
+ * the shell reads it to route Back to exit rather than to a step. These are the
+ * two movements it routes between: `goBack` pops one entry, `closeWizard`
+ * rewinds every entry the wizard owns.
+ */
+
+import { type StepId, stepIndex } from "@remit/ui";
+import { useNavigate, useRouter, useSearch } from "@tanstack/react-router";
+import { useCallback, useEffect, useRef } from "react";
+import { z } from "zod";
+
+const stepId = z.enum([
+	"match",
+	"properties",
+	"folder",
+	"rule",
+	"name",
+	"review",
+	"run",
+]);
+
+export const wizardStepFromParam = (value: unknown): StepId | undefined => {
+	const parsed = stepId.safeParse(value);
+	return parsed.success ? parsed.data : undefined;
+};
+
+/**
+ * The route's `wizard` field. A value the wizard cannot be on reads as no step
+ * rather than as a validation failure, so a truncated or hand-typed link lands
+ * on the mail list instead of the router's error screen.
+ */
+export const wizardStepValue = z.unknown().transform(wizardStepFromParam);
+
+export const ownedHistoryEntries = (
+	steps: readonly StepId[],
+	step: StepId,
+): number => stepIndex(steps, step) + 1;
+
+export const useWizardStepValue = (): StepId | undefined =>
+	useSearch({ from: "/mail", select: (search) => search.wizard });
+
+export interface WizardStepNavigation {
+	step: StepId | undefined;
+	goToStep: (step: StepId) => void;
+	goBack: () => void;
+	closeWizard: (steps: readonly StepId[], step: StepId) => void;
+}
+
+export const useWizardStep = (openingStep: StepId): WizardStepNavigation => {
+	const router = useRouter();
+	const navigate = useNavigate();
+	const step = useWizardStepValue();
+	// Whether this document loaded already holding a step, which is the one
+	// entrance that leaves the wizard unrooted. A step the app itself pushed
+	// arrives rooted, so re-rooting it would duplicate the entry underneath it.
+	const loadedHoldingStep = useRef(step !== undefined);
+	const pushedTo = useRef<StepId | undefined>(undefined);
+
+	// Two taps on Continue land before the URL settles, and both would push the
+	// same step — leaving a back that appears to do nothing.
+	// biome-ignore lint/correctness/useExhaustiveDependencies: the guard is cleared because the step changed, which is only knowable from the dependency.
+	useEffect(() => {
+		pushedTo.current = undefined;
+	}, [step]);
+
+	useEffect(() => {
+		if (!loadedHoldingStep.current) return;
+		loadedHoldingStep.current = false;
+		void (async () => {
+			await navigate({
+				to: ".",
+				search: (prev) => ({ ...prev, wizard: undefined }),
+				replace: true,
+			});
+			await navigate({
+				to: ".",
+				search: (prev) => ({ ...prev, wizard: openingStep }),
+			});
+		})();
+	}, [openingStep, navigate]);
+
+	const goToStep = useCallback(
+		(next: StepId) => {
+			if (next === step || pushedTo.current === next) return;
+			pushedTo.current = next;
+			navigate({ to: ".", search: (prev) => ({ ...prev, wizard: next }) });
+		},
+		[navigate, step],
+	);
+
+	const goBack = useCallback(() => {
+		router.history.back();
+	}, [router]);
+
+	const closeWizard = useCallback(
+		(steps: readonly StepId[], current: StepId) => {
+			router.history.go(-ownedHistoryEntries(steps, current));
+		},
+		[router],
+	);
+
+	return { step, goToStep, goBack, closeWizard };
+};

package/src/routes/mail.tsx

@@ -21,6 +21,7 @@ import { FlaggedPane } from "@/components/mail/FlaggedPane";
 import { MailboxPane } from "@/components/mail/MailboxPane";
 import { MailNav } from "@/components/mail/MailNav";
 import { OutboxPane } from "@/components/mail/OutboxPane";
+import { SelectionWizardHost } from "@/components/mail/SelectionWizardHost";
 import { ErrorState } from "@/components/ui/ErrorState";
 import { KeyboardShortcutsModal } from "@/components/ui/KeyboardShortcutsModal";
 import { useDebouncedValue } from "@/hooks/useDebouncedValue";
@@ -43,6 +44,7 @@ import {
 	searchInputForView,
 	shouldMirrorQuery,
 } from "@/lib/search-view";
+import { wizardStepValue } from "@/lib/wizard-history";
 import "@/lib/client";
 
 // `MailContext` / `useMailContext` live in `@/lib/mail-context` so the provider
@@ -53,6 +55,9 @@ export { useMailContext } from "@/lib/mail-context";
 
 const mailSearchSchema = z.object({
 	q: z.string().optional(),
+	// The selection wizard's step (#477 clause 1.6). The router owns history, so
+	// the step is a validated search param rather than a raw pushState entry.
+	wizard: wizardStepValue,
 });
 
 export const Route = createFileRoute("/mail")({
@@ -92,6 +97,9 @@ function MailLayout() {
 	// collapse preference there (#782). DKIM-mismatch auto-open still fires on
 	// every tier. Explicit toggles persist the user's choice.
 	const [intelligenceOpen, setIntelligenceOpen] = useState(false);
+	// The list owns the selection; the wizard is mounted here, beside it, and
+	// counts the same rows the selection bar is counting.
+	const [selectedCount, setSelectedCount] = useState(0);
 	const handleSetIntelligenceOpen = useCallback((open: boolean) => {
 		setIntelligenceOpen(open);
 		writeIntelligencePref(open);
@@ -304,6 +312,8 @@ function MailLayout() {
 		intelligenceOpen,
 		onToggleIntelligence: handleToggleIntelligence,
 		onSetIntelligenceOpen: handleSetIntelligenceOpen,
+		selectedCount,
+		onSelectedCountChange: setSelectedCount,
 	};
 
 	// Single nav node: the kit renders it as a pane (≥1024px) or inside its
@@ -468,6 +478,7 @@ function MailLayout() {
 				isOpen={showShortcuts}
 				onClose={() => setShowShortcuts(false)}
 			/>
+			<SelectionWizardHost verb="organize" selectedCount={selectedCount} />
 			{/* Outlet is required for TanStack Router to activate child routes.
 			    Routes that manage their own rendering (brief, mailbox, outbox) return
 			    null from their component — the parent shell owns the layout. */}