@remit/ui 0.0.123 → 0.0.125

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/ui",
-  "version": "0.0.123",
+  "version": "0.0.125",
   "type": "module",
   "files": [
     "src"

package/src/components/selection-wizard.render.test.ts

@@ -7,6 +7,7 @@ import {
 	matchDoorsFor,
 	stepBlockedReason,
 	stepsFor,
+	wizardScopeFor,
 } from "../lib/wizard-steps.js";
 import {
 	type RuleClause,
@@ -413,6 +414,27 @@ describe("FolderStepBody", () => {
 		);
 		assert.match(text(html), /Tap a folder to open it/);
 	});
+
+	it("states the restriction the selection actually carries (#525)", () => {
+		// Told to pick a single account, a selection already inside one account has
+		// nothing to act on and the flow dead-ends here.
+		const spansFolders = renderToString(
+			createElement(FolderStepBody, {
+				...folderProps,
+				restriction: wizardScopeFor("acc-personal", "spansFolders").destination,
+			}),
+		);
+		assert.match(text(spansFolders), /within one folder/);
+		assert.doesNotMatch(text(spansFolders), /single account/);
+
+		const spansAccounts = renderToString(
+			createElement(FolderStepBody, {
+				...folderProps,
+				restriction: wizardScopeFor(undefined, "spansAccounts").destination,
+			}),
+		);
+		assert.match(text(spansAccounts), /single account/);
+	});
 });
 
 describe("RuleStepBody", () => {

package/src/components/selection-wizard.tsx

@@ -636,9 +636,10 @@ export interface FolderStepProps {
 	/** The account's hierarchy separator, which the tree nests on. */
 	delimiter?: string;
 	/**
-	 * Why there is no folder list to choose from — a selection spanning accounts
-	 * has no single account whose folders these could be (#477 5.5). Said here
-	 * rather than left as an empty picker.
+	 * Why no destination can be chosen — the selection spans more accounts, or
+	 * more folders, than a move can take (#477 5.5, #525). In the words of the
+	 * scope it actually spans, so the instruction is one the user can follow. Said
+	 * here rather than left as an empty picker.
 	 */
 	restriction?: string;
 }
@@ -692,9 +693,10 @@ export interface RuleStepProps {
 	onScopeChange: (scope: RuleScope) => void;
 	onUntilChange: (until: string) => void;
 	/**
-	 * Why the two persisting scopes cannot be reached from here — a selection
-	 * spanning accounts has no single account to create the rule for (#477 5.5).
-	 * They stay pressable and say this; the one-off scope is unaffected.
+	 * Why the two persisting scopes cannot be reached from here — the selection
+	 * spans more accounts, or more folders, than a rule can take (#477 5.5, #525),
+	 * in the words of the scope it actually spans. They stay pressable and say
+	 * this; the one-off scope is unaffected.
 	 */
 	restriction?: string;
 }

package/src/index.ts

@@ -989,6 +989,8 @@ export {
 	clauseWords,
 	crossAccountDestinationReason,
 	crossAccountRuleReason,
+	crossFolderDestinationReason,
+	crossFolderRuleReason,
 	ESCALATED_MATCH_HINT,
 	ESCALATED_REVIEW_WARNING,
 	ESCALATED_SCOPE_FALLBACK,
@@ -1006,6 +1008,7 @@ export {
 	type RunState,
 	runCopy,
 	type SampleEmptyReason,
+	type SelectionRestriction,
 	type StepId,
 	sampleEmptyCopy,
 	stepBlockedReason,
@@ -1018,4 +1021,6 @@ export {
 	verbCopy,
 	type WizardAnswers,
 	type WizardDraft,
+	type WizardScope,
+	wizardScopeFor,
 } from "./lib/wizard-steps.js";

package/src/lib/keymap.test.ts

@@ -1,6 +1,7 @@
 import assert from "node:assert";
 import { describe, test } from "node:test";
 import {
+	ALL_TRIAGE_ACTIONS,
 	KEY_HINT_GROUPS,
 	keysForAction,
 	shortcutHintForAction,
@@ -70,6 +71,12 @@ describe("keymap module", () => {
 		assert.strictEqual(describes("↑"), "Focus the message above");
 	});
 
+	test("every action the app can produce has a displayed binding", () => {
+		for (const action of ALL_TRIAGE_ACTIONS) {
+			assert.ok(keysForAction(action), `${action} has keys`);
+		}
+	});
+
 	test("every hint's action is a non-empty key list", () => {
 		for (const group of KEY_HINT_GROUPS) {
 			for (const hint of group.hints) {

package/src/lib/keymap.ts

@@ -48,6 +48,51 @@ export type TriageAction =
 	| "goFlagged"
 	| "goSettings";
 
+/**
+ * Presence table for {@link TriageAction}. `Record<TriageAction, true>` is what
+ * makes it exhaustive: adding a member to the union without adding it here is a
+ * type error, so anything that must reason about *every* action — the shortcut
+ * tree's completeness tests, the help overlay's audit — has a runtime list that
+ * cannot silently fall behind the type.
+ */
+const TRIAGE_ACTION_PRESENCE: Record<TriageAction, true> = {
+	focusNext: true,
+	focusPrevious: true,
+	focusFirst: true,
+	focusLast: true,
+	openFocused: true,
+	back: true,
+	toggleSelect: true,
+	extendSelectDown: true,
+	extendSelectUp: true,
+	selectAll: true,
+	reply: true,
+	replyAll: true,
+	forward: true,
+	delete: true,
+	toggleStar: true,
+	toggleRead: true,
+	muteSender: true,
+	blockSender: true,
+	vipSender: true,
+	markJunk: true,
+	toggleIntelligence: true,
+	toggleDensity: true,
+	focusSearch: true,
+	compose: true,
+	help: true,
+	goBrief: true,
+	goInbox: true,
+	goSent: true,
+	goFlagged: true,
+	goSettings: true,
+};
+
+/** Every action the app can produce, in declaration order. */
+export const ALL_TRIAGE_ACTIONS: readonly TriageAction[] = Object.keys(
+	TRIAGE_ACTION_PRESENCE,
+) as TriageAction[];
+
 /** Map of action → handler. Omitted actions are inert (no-op). */
 export type TriageHandlers = Partial<Record<TriageAction, () => void>>;
 

package/src/lib/shortcut-tree.test.ts

@@ -0,0 +1,438 @@
+import assert from "node:assert";
+import { describe, test } from "node:test";
+import { ALL_TRIAGE_ACTIONS, type TriageAction } from "./keymap.js";
+import {
+	type BlockedReason,
+	type DetailSurface,
+	type EditingField,
+	type ListNode,
+	type MailList,
+	NODE_ACTIONS,
+	type OverlayFrame,
+	type RegisteredActions,
+	type Resolution,
+	resolveShortcut,
+	type ShortcutTree,
+} from "./shortcut-tree.js";
+
+const brief: MailList = { kind: "brief" };
+const inbox: MailList = { kind: "mailbox", mailboxId: "a", role: "inbox" };
+const sent: MailList = { kind: "mailbox", mailboxId: "b", role: "sent" };
+const archive: MailList = { kind: "mailbox", mailboxId: "c", role: "other" };
+
+const thread: DetailSurface = {
+	kind: "thread",
+	threadId: "t1",
+	messageId: null,
+};
+const draft: DetailSurface = { kind: "compose", draftId: null };
+
+const aim = { threadId: "t1", messageId: null };
+
+const listOnly = (partial: Partial<ListNode> = {}): ListNode => ({
+	list: brief,
+	pane: { layout: "list-only" },
+	aim: null,
+	selection: [],
+	...partial,
+});
+
+const split = (
+	surface: DetailSurface,
+	partial: Partial<ListNode> = {},
+): ListNode => ({
+	...listOnly({ aim, ...partial }),
+	pane: { layout: "split", detail: { surface } },
+});
+
+const detailOnly = (
+	surface: DetailSurface,
+	partial: Partial<ListNode> = {},
+): ListNode => ({
+	...listOnly({ aim, ...partial }),
+	pane: { layout: "detail-only", detail: { surface } },
+});
+
+const tree = (partial: Partial<ShortcutTree> = {}): ShortcutTree => ({
+	overlays: [],
+	editing: null,
+	settling: null,
+	mail: { list: listOnly() },
+	...partial,
+});
+
+const on = (list: ListNode): ShortcutTree => tree({ mail: { list } });
+
+const settings = (): ShortcutTree => tree({ mail: null });
+
+const everywhere: RegisteredActions = {
+	app: ALL_TRIAGE_ACTIONS,
+	mail: ALL_TRIAGE_ACTIONS,
+	list: ALL_TRIAGE_ACTIONS,
+	detail: ALL_TRIAGE_ACTIONS,
+};
+
+const acted = (result: Resolution): string => {
+	if (result.outcome !== "act") {
+		assert.fail(`expected act, got ${result.outcome}`);
+	}
+	if (result.target.kind === "level") return result.target.level;
+	if (result.target.kind === "overlay") {
+		return `overlay:${result.target.frame.id}`;
+	}
+	return `editing:${result.target.field.id}`;
+};
+
+const containedBy = (result: Resolution): string => {
+	if (result.outcome !== "contained") {
+		assert.fail(`expected contained, got ${result.outcome}`);
+	}
+	if (result.by.kind === "overlay") return `overlay:${result.by.frame.id}`;
+	return `editing:${result.by.field.id}`;
+};
+
+const blockedFor = (result: Resolution): string => {
+	if (result.outcome !== "blocked") {
+		assert.fail(`expected blocked, got ${result.outcome}`);
+	}
+	return result.reason;
+};
+
+describe("shortcut tree", () => {
+	test("every declared action is one the keymap can produce", () => {
+		const known = new Set<string>(ALL_TRIAGE_ACTIONS);
+		for (const rules of Object.values(NODE_ACTIONS)) {
+			for (const declared of rules) {
+				assert.ok(known.has(declared.action), `${declared.action} is known`);
+			}
+		}
+	});
+
+	test("every keymap action is declared somewhere in the tree", () => {
+		const declared = new Set<string>(
+			Object.values(NODE_ACTIONS).flatMap((rules) =>
+				rules.map((entry) => entry.action),
+			),
+		);
+		for (const action of ALL_TRIAGE_ACTIONS) {
+			assert.ok(declared.has(action), `${action} is declared`);
+		}
+	});
+
+	test("the top overlay frame answers, and pre-empts every level", () => {
+		const overlays: OverlayFrame[] = [
+			{ id: "sheet", handles: ["back"] },
+			{ id: "confirm", handles: ["back", "reply"] },
+		];
+		const withOverlay = tree({ overlays });
+		assert.strictEqual(
+			acted(resolveShortcut("back", withOverlay, {})),
+			"overlay:confirm",
+		);
+		assert.strictEqual(
+			acted(resolveShortcut("reply", withOverlay, everywhere)),
+			"overlay:confirm",
+		);
+	});
+
+	test("an overlay contains what it does not handle", () => {
+		const withOverlay = tree({
+			overlays: [{ id: "confirm", handles: ["back"] }],
+		});
+		assert.strictEqual(
+			containedBy(resolveShortcut("selectAll", withOverlay, everywhere)),
+			"overlay:confirm",
+		);
+		assert.strictEqual(
+			containedBy(resolveShortcut("focusSearch", withOverlay, everywhere)),
+			"overlay:confirm",
+		);
+	});
+
+	test("an editing field answers or contains, and pre-empts the levels", () => {
+		const editing: EditingField = { id: "search", handles: ["back"] };
+		const typing = tree({ editing });
+		assert.strictEqual(
+			acted(resolveShortcut("back", typing, everywhere)),
+			"editing:search",
+		);
+		assert.strictEqual(
+			containedBy(resolveShortcut("focusNext", typing, everywhere)),
+			"editing:search",
+		);
+	});
+
+	test("an overlay outranks an editing field", () => {
+		const both = tree({
+			overlays: [{ id: "compose-modal", handles: ["back"] }],
+			editing: { id: "subject", handles: ["back"] },
+		});
+		assert.strictEqual(
+			acted(resolveShortcut("back", both, {})),
+			"overlay:compose-modal",
+		);
+	});
+
+	test("settling blocks everything, and names its scope", () => {
+		for (const action of ALL_TRIAGE_ACTIONS) {
+			assert.strictEqual(
+				blockedFor(
+					resolveShortcut(action, tree({ settling: "app" }), everywhere),
+				),
+				"settling",
+			);
+		}
+		assert.strictEqual(
+			blockedFor(
+				resolveShortcut("reply", tree({ settling: "list" }), everywhere),
+			),
+			"list-settling",
+		);
+	});
+
+	test("focusNext walks to the list when the list shares the screen", () => {
+		const desktop = on(split(thread));
+		assert.strictEqual(
+			acted(resolveShortcut("focusNext", desktop, everywhere)),
+			"list",
+		);
+		assert.strictEqual(
+			acted(resolveShortcut("focusPrevious", desktop, everywhere)),
+			"list",
+		);
+	});
+
+	test("focusNext stops at the detail when the detail owns the screen", () => {
+		const phone = on(detailOnly(thread));
+		assert.strictEqual(
+			acted(resolveShortcut("focusNext", phone, everywhere)),
+			"detail",
+		);
+		assert.strictEqual(
+			acted(resolveShortcut("focusPrevious", phone, everywhere)),
+			"detail",
+		);
+	});
+
+	test("a level that serves an action but registers no handler is skipped", () => {
+		const phone = on(detailOnly(thread));
+		assert.strictEqual(
+			acted(resolveShortcut("reply", phone, { list: ["reply"] })),
+			"list",
+		);
+		assert.strictEqual(
+			acted(
+				resolveShortcut("reply", phone, { detail: ["reply"], list: ["reply"] }),
+			),
+			"detail",
+		);
+	});
+
+	test("an action no level serves is unbound, requirements or not", () => {
+		assert.strictEqual(
+			resolveShortcut("compose", tree(), {}).outcome,
+			"unbound",
+		);
+		assert.strictEqual(
+			resolveShortcut("muteSender", tree(), {}).outcome,
+			"unbound",
+		);
+		assert.strictEqual(
+			resolveShortcut("toggleSelect", on(detailOnly(thread)), {}).outcome,
+			"unbound",
+		);
+	});
+
+	test("an unmet requirement only speaks when the level serves the action", () => {
+		const unaimed = on(listOnly());
+		assert.strictEqual(
+			resolveShortcut("muteSender", unaimed, {}).outcome,
+			"unbound",
+		);
+		assert.strictEqual(
+			blockedFor(
+				resolveShortcut("muteSender", unaimed, { list: ["muteSender"] }),
+			),
+			"not-aimed",
+		);
+	});
+
+	test("the root-most served level's reason is the one reported", () => {
+		const composing = on(split(draft, { aim: null }));
+		assert.strictEqual(
+			blockedFor(
+				resolveShortcut("reply", composing, {
+					detail: ["reply"],
+					list: ["reply"],
+				}),
+			),
+			"not-aimed",
+		);
+	});
+
+	test("back closes a compose detail, which is not a thread", () => {
+		const composing = on(detailOnly(draft));
+		assert.strictEqual(
+			acted(resolveShortcut("back", composing, everywhere)),
+			"detail",
+		);
+		assert.strictEqual(
+			blockedFor(resolveShortcut("reply", composing, { detail: ["reply"] })),
+			"no-thread",
+		);
+	});
+
+	test("back clears a selection on the list", () => {
+		assert.strictEqual(
+			blockedFor(resolveShortcut("back", on(listOnly()), everywhere)),
+			"no-selection",
+		);
+		assert.strictEqual(
+			acted(
+				resolveShortcut(
+					"back",
+					on(listOnly({ selection: ["m1"] })),
+					everywhere,
+				),
+			),
+			"list",
+		);
+	});
+
+	test("a phone thread reports geometry, not a fault", () => {
+		const phone = on(detailOnly(thread));
+		for (const action of [
+			"toggleSelect",
+			"selectAll",
+			"toggleDensity",
+			"openFocused",
+			"focusFirst",
+			"focusLast",
+		] as TriageAction[]) {
+			assert.strictEqual(
+				blockedFor(resolveShortcut(action, phone, everywhere)),
+				"list-off-screen",
+			);
+		}
+	});
+
+	test("go-to keys know where they already are", () => {
+		assert.strictEqual(
+			blockedFor(resolveShortcut("goBrief", on(listOnly()), everywhere)),
+			"already-there",
+		);
+		assert.strictEqual(
+			blockedFor(
+				resolveShortcut(
+					"goFlagged",
+					on(listOnly({ list: { kind: "flagged" } })),
+					everywhere,
+				),
+			),
+			"already-there",
+		);
+		assert.strictEqual(
+			blockedFor(
+				resolveShortcut("goInbox", on(listOnly({ list: inbox })), everywhere),
+			),
+			"already-there",
+		);
+		assert.strictEqual(
+			blockedFor(
+				resolveShortcut("goSent", on(listOnly({ list: sent })), everywhere),
+			),
+			"already-there",
+		);
+	});
+
+	test("a mailbox with no role is somewhere else entirely", () => {
+		const other = on(listOnly({ list: archive }));
+		assert.strictEqual(
+			acted(resolveShortcut("goInbox", other, everywhere)),
+			"app",
+		);
+		assert.strictEqual(
+			acted(resolveShortcut("goSent", other, everywhere)),
+			"app",
+		);
+		assert.strictEqual(
+			acted(resolveShortcut("goBrief", other, everywhere)),
+			"app",
+		);
+	});
+
+	test("a go-to key outside any list is not already-there", () => {
+		const noList = tree({ mail: { list: null } });
+		assert.strictEqual(
+			acted(resolveShortcut("goBrief", noList, everywhere)),
+			"app",
+		);
+		assert.strictEqual(
+			acted(resolveShortcut("goBrief", settings(), everywhere)),
+			"app",
+		);
+	});
+
+	test("help and the go-to family answer on a screen with no mail node", () => {
+		const globals: TriageAction[] = [
+			"help",
+			"goBrief",
+			"goFlagged",
+			"goInbox",
+			"goSent",
+			"goSettings",
+		];
+		for (const action of globals) {
+			assert.strictEqual(
+				acted(resolveShortcut(action, settings(), everywhere)),
+				"app",
+			);
+		}
+	});
+
+	test("the mail surface's own keys are dead where there is no mail", () => {
+		const mailOnly: TriageAction[] = [
+			"compose",
+			"focusSearch",
+			"toggleIntelligence",
+		];
+		for (const action of mailOnly) {
+			assert.strictEqual(
+				resolveShortcut(action, settings(), everywhere).outcome,
+				"unbound",
+			);
+			assert.strictEqual(
+				acted(resolveShortcut(action, tree(), everywhere)),
+				"mail",
+			);
+		}
+	});
+
+	test("every blocked reason is reachable", () => {
+		const scenarios: Record<BlockedReason, () => Resolution> = {
+			settling: () =>
+				resolveShortcut("help", tree({ settling: "app" }), everywhere),
+			"list-settling": () =>
+				resolveShortcut("help", tree({ settling: "list" }), everywhere),
+			"list-off-screen": () =>
+				resolveShortcut("toggleSelect", on(detailOnly(thread)), {
+					list: ["toggleSelect"],
+				}),
+			"list-shown": () =>
+				resolveShortcut("focusNext", on(split(thread)), {
+					detail: ["focusNext"],
+				}),
+			"not-aimed": () =>
+				resolveShortcut("toggleStar", on(listOnly()), { list: ["toggleStar"] }),
+			"no-selection": () =>
+				resolveShortcut("back", on(listOnly()), { list: ["back"] }),
+			"no-thread": () =>
+				resolveShortcut("reply", on(detailOnly(draft)), { detail: ["reply"] }),
+			"already-there": () =>
+				resolveShortcut("goBrief", on(listOnly()), { app: ["goBrief"] }),
+		};
+		for (const [reason, scenario] of Object.entries(scenarios)) {
+			assert.strictEqual(blockedFor(scenario()), reason);
+		}
+	});
+});

package/src/lib/shortcut-tree.ts

@@ -0,0 +1,373 @@
+import type { TriageAction } from "./keymap.js";
+
+/**
+ * Pure resolver for the shortcut tree (#713, stage 1).
+ *
+ * `keymap-dispatch` decides *which* action a keystroke means. This module
+ * decides *who answers it*: given the app's current shape, an action runs at one
+ * level of the tree, is contained by an overlay or a field, is blocked for a
+ * named reason, or is unbound.
+ *
+ * A node is a level, never a branch value. There are four — `app`, `mail`,
+ * `list`, `detail` — plus two owners that pre-empt them: an overlay stack and
+ * an editing field. Which list you are on, which detail surface is open and
+ * which panes are on screen are *values* carried by those nodes, so the verb set
+ * of a level is declared once and a precondition discriminates the cases.
+ * Resolution walks leaf-to-root and the first served level wins, which is what
+ * makes `j` mean "next message in the thread" on a phone and "next row" on a
+ * desktop without either surface knowing the other exists.
+ *
+ * Nothing here touches React, the DOM or the router: the caller supplies the
+ * tree and the handler registry, and maps an outcome to whatever the user
+ * should see and to whether the keystroke is consumed.
+ */
+
+/** The four levels of the tree, root first. */
+export type ShortcutLevel = "app" | "mail" | "list" | "detail";
+
+/**
+ * What a mailbox is *for*. The go-to keys name the inbox and the sent folder
+ * without knowing any id, so the role travels with the list and stays a value
+ * the resolver can compare.
+ */
+export type MailboxRole = "inbox" | "sent" | "other";
+
+/** The list being browsed — the first segment under `/mail`. */
+export type MailList =
+	| { kind: "brief" }
+	| { kind: "flagged" }
+	| { kind: "outbox" }
+	| { kind: "mailbox"; mailboxId: string; role: MailboxRole };
+
+/** Where a go-to key would take you. */
+export type GoToDestination = "brief" | "flagged" | "inbox" | "sent";
+
+/** The detail surface open under the list. */
+export type DetailSurface =
+	| { kind: "thread"; threadId: string; messageId: string | null }
+	| { kind: "compose"; draftId: string | null };
+
+/** What the message verbs act on: the focused row, or the open thread. */
+export interface Aim {
+	threadId: string;
+	messageId: string | null;
+}
+
+export interface DetailNode {
+	surface: DetailSurface;
+}
+
+/**
+ * Which panes the list holds. One value rather than a visibility flag beside an
+ * optional detail, so "neither pane on screen" cannot be built: a hidden list
+ * always means the detail has taken the screen.
+ */
+export type ListPane =
+	| { layout: "list-only" }
+	| { layout: "split"; detail: DetailNode }
+	| { layout: "detail-only"; detail: DetailNode };
+
+export interface ListNode {
+	list: MailList;
+	pane: ListPane;
+	aim: Aim | null;
+	/** Ids of the selected rows; the resolver reads its size, not a flag. */
+	selection: readonly string[];
+}
+
+export interface MailNode {
+	list: ListNode | null;
+}
+
+/**
+ * A modal, sheet or menu. The stack's top frame is the leaf of the tree: it
+ * either answers the action or contains it, and never leaks a key to the
+ * surface behind it.
+ */
+export interface OverlayFrame {
+	id: string;
+	handles: readonly TriageAction[];
+}
+
+/** A focused editable surface. Same containment rule as an overlay frame. */
+export interface EditingField {
+	id: string;
+	handles: readonly TriageAction[];
+}
+
+/**
+ * What is mid-transition. `"app"` is a navigation in flight, `"list"` a list
+ * still loading; both block every action until they land, so a key pressed
+ * during a transition can never act on the surface it was not aimed at.
+ */
+export type SettlingScope = "app" | "list";
+
+export interface ShortcutTree {
+	overlays: readonly OverlayFrame[];
+	editing: EditingField | null;
+	settling: SettlingScope | null;
+	mail: MailNode | null;
+}
+
+/** The facts a rule can require of the tree. */
+export type ShortcutFlag = "listVisible" | "aimed" | "selection" | "threadOpen";
+
+/**
+ * A precondition on a rule. A bare flag must hold; `{ not: "listVisible" }` is
+ * the one negation the tree needs, and it is what gives the detail its own
+ * navigation when the list is off screen; `listIsNot` is how a go-to action
+ * declares that it is already where it would take you.
+ */
+export type Requirement =
+	| ShortcutFlag
+	| { not: "listVisible" }
+	| { listIsNot: GoToDestination };
+
+export interface ActionRule {
+	action: TriageAction;
+	requires: readonly Requirement[];
+}
+
+/**
+ * Why a level that serves this action did not run it. Every reason is reachable
+ * and every reason is the caller's to phrase: `list-off-screen` is ordinary
+ * phone geometry and says nothing, while `not-aimed` and `no-selection` are
+ * worth telling the user about.
+ */
+export type BlockedReason =
+	| "settling"
+	| "list-settling"
+	| "list-off-screen"
+	| "list-shown"
+	| "not-aimed"
+	| "no-selection"
+	| "no-thread"
+	| "already-there";
+
+/** Who runs the action. */
+export type ActTarget =
+	| { kind: "overlay"; frame: OverlayFrame }
+	| { kind: "editing"; field: EditingField }
+	| { kind: "level"; level: ShortcutLevel };
+
+/** Who swallowed the action without running it. */
+export type ContainTarget =
+	| { kind: "overlay"; frame: OverlayFrame }
+	| { kind: "editing"; field: EditingField };
+
+/**
+ * `contained` and `unbound` are not the same silence. A contained key belongs to
+ * the overlay or the field that swallowed it and must not reach the page behind
+ * it; an unbound key was never ours, so the browser keeps it.
+ */
+export type Resolution =
+	| { outcome: "act"; target: ActTarget }
+	| { outcome: "contained"; by: ContainTarget }
+	| { outcome: "blocked"; reason: BlockedReason }
+	| { outcome: "unbound" };
+
+/** Which actions a host serves, per level. */
+export type RegisteredActions = Readonly<
+	Partial<Record<ShortcutLevel, readonly TriageAction[]>>
+>;
+
+const LIST_VERBS: readonly TriageAction[] = [
+	"reply",
+	"replyAll",
+	"forward",
+	"delete",
+	"toggleStar",
+	"toggleRead",
+	"muteSender",
+	"blockSender",
+	"vipSender",
+	"markJunk",
+];
+
+const LIST_NAVIGATION: readonly TriageAction[] = [
+	"focusNext",
+	"focusPrevious",
+	"focusFirst",
+	"focusLast",
+	"openFocused",
+	"toggleSelect",
+	"extendSelectDown",
+	"extendSelectUp",
+	"selectAll",
+	"toggleDensity",
+];
+
+const rule = (
+	action: TriageAction,
+	...requires: Requirement[]
+): ActionRule => ({ action, requires });
+
+/**
+ * Every action the app answers, declared at the level that owns it. An action
+ * may appear at more than one level; the leaf-most rule whose level serves it
+ * and whose requirements hold wins.
+ *
+ * Help and the go-to family sit at `app` on purpose: `?` and `g …` are how you
+ * leave a screen, so they must answer on settings, where there is no `mail`
+ * node at all. Compose, search and the intelligence rail act on the mail
+ * surface and stay at `mail`, where they are correctly dead on settings.
+ * `goSettings` carries no `listIsNot` because settings is not a list; "already
+ * on settings" is not expressible in a tree rooted at the mail address.
+ */
+export const NODE_ACTIONS: Record<ShortcutLevel, readonly ActionRule[]> = {
+	app: [
+		rule("help"),
+		rule("goBrief", { listIsNot: "brief" }),
+		rule("goFlagged", { listIsNot: "flagged" }),
+		rule("goInbox", { listIsNot: "inbox" }),
+		rule("goSent", { listIsNot: "sent" }),
+		rule("goSettings"),
+	],
+	mail: [rule("compose"), rule("focusSearch"), rule("toggleIntelligence")],
+	list: [
+		...LIST_NAVIGATION.map((action) => rule(action, "listVisible")),
+		...LIST_VERBS.map((action) => rule(action, "aimed")),
+		rule("back", "selection"),
+	],
+	detail: [
+		rule("focusNext", "threadOpen", { not: "listVisible" }),
+		rule("focusPrevious", "threadOpen", { not: "listVisible" }),
+		rule("reply", "threadOpen"),
+		rule("replyAll", "threadOpen"),
+		rule("forward", "threadOpen"),
+		rule("back"),
+	],
+};
+
+const UNMET_REASON: Record<ShortcutFlag, BlockedReason> = {
+	listVisible: "list-off-screen",
+	aimed: "not-aimed",
+	selection: "no-selection",
+	threadOpen: "no-thread",
+};
+
+function listNode(tree: ShortcutTree): ListNode | null {
+	return tree.mail?.list ?? null;
+}
+
+function detailNode(list: ListNode): DetailNode | null {
+	return list.pane.layout === "list-only" ? null : list.pane.detail;
+}
+
+function holds(flag: ShortcutFlag, tree: ShortcutTree): boolean {
+	const list = listNode(tree);
+	if (!list) return false;
+	if (flag === "listVisible") return list.pane.layout !== "detail-only";
+	if (flag === "aimed") return list.aim !== null;
+	if (flag === "selection") return list.selection.length > 0;
+	return detailNode(list)?.surface.kind === "thread";
+}
+
+function isAt(list: MailList, destination: GoToDestination): boolean {
+	if (list.kind === "mailbox") {
+		return destination === list.role;
+	}
+	return list.kind === destination;
+}
+
+function unmet(
+	requirement: Requirement,
+	tree: ShortcutTree,
+): BlockedReason | null {
+	if (typeof requirement === "string") {
+		return holds(requirement, tree) ? null : UNMET_REASON[requirement];
+	}
+	if ("not" in requirement) {
+		return holds(requirement.not, tree) ? "list-shown" : null;
+	}
+	const list = listNode(tree);
+	if (!list) return null;
+	return isAt(list.list, requirement.listIsNot) ? "already-there" : null;
+}
+
+function firstUnmet(
+	requires: readonly Requirement[],
+	tree: ShortcutTree,
+): BlockedReason | null {
+	for (const requirement of requires) {
+		const reason = unmet(requirement, tree);
+		if (reason) return reason;
+	}
+	return null;
+}
+
+/** The levels present in this tree, leaf first. */
+function activeLevels(tree: ShortcutTree): ShortcutLevel[] {
+	const list = listNode(tree);
+	const levels: ShortcutLevel[] = [];
+	if (list && detailNode(list)) levels.push("detail");
+	if (list) levels.push("list");
+	if (tree.mail) levels.push("mail");
+	levels.push("app");
+	return levels;
+}
+
+function isRegistered(
+	registered: RegisteredActions,
+	level: ShortcutLevel,
+	action: TriageAction,
+): boolean {
+	return registered[level]?.includes(action) === true;
+}
+
+/**
+ * Resolve an action against the tree. Pure: no DOM, no router, no side effects.
+ *
+ * The overlay stack and the editing field are leaves that pre-empt the level
+ * chain entirely. Otherwise the walk runs leaf-to-root over the levels that
+ * *serve* this action: the first one whose requirements hold acts, and a level
+ * that declares the action but registers no handler is skipped as if it were not
+ * there. A level nobody serves never contributes a reason, so an action a screen
+ * does not offer stays silent instead of explaining itself.
+ *
+ * When no served level can run it, the root-most reason is reported: the
+ * leaf-most failure is usually the geometry the user did not choose, while the
+ * one above it is the thing they can act on.
+ */
+export function resolveShortcut(
+	action: TriageAction,
+	tree: ShortcutTree,
+	registered: RegisteredActions,
+): Resolution {
+	const frame = tree.overlays.at(-1);
+	if (frame) {
+		if (!frame.handles.includes(action)) {
+			return { outcome: "contained", by: { kind: "overlay", frame } };
+		}
+		return { outcome: "act", target: { kind: "overlay", frame } };
+	}
+
+	const field = tree.editing;
+	if (field) {
+		if (!field.handles.includes(action)) {
+			return { outcome: "contained", by: { kind: "editing", field } };
+		}
+		return { outcome: "act", target: { kind: "editing", field } };
+	}
+
+	if (tree.settling) {
+		const reason = tree.settling === "list" ? "list-settling" : "settling";
+		return { outcome: "blocked", reason };
+	}
+
+	let blockedOn: BlockedReason | null = null;
+	for (const level of activeLevels(tree)) {
+		for (const candidate of NODE_ACTIONS[level]) {
+			if (candidate.action !== action) continue;
+			if (!isRegistered(registered, level, action)) continue;
+			const reason = firstUnmet(candidate.requires, tree);
+			if (!reason) {
+				return { outcome: "act", target: { kind: "level", level } };
+			}
+			blockedOn = reason;
+		}
+	}
+
+	if (blockedOn) return { outcome: "blocked", reason: blockedOn };
+	return { outcome: "unbound" };
+}

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

@@ -10,6 +10,8 @@ import {
 	clauseSentence,
 	clauseWords,
 	crossAccountMatchReason,
+	crossFolderDestinationReason,
+	crossFolderRuleReason,
 	ESCALATED_MATCH_HINT,
 	ESCALATED_REVIEW_WARNING,
 	escalatedMatchLabel,
@@ -32,6 +34,7 @@ import {
 	type Verb,
 	verbCopy,
 	type WizardDraft,
+	wizardScopeFor,
 } from "./wizard-steps.js";
 
 const VERBS: Verb[] = ["delete", "move", "junk", "markRead", "organize"];
@@ -858,3 +861,50 @@ describe("the match as words", () => {
 		);
 	});
 });
+
+/**
+ * A selection spanning folders of one account was told to pick a single account
+ * (#525) — an instruction a user holding one account's mail cannot follow, so
+ * the flow dead-ended on the folder step with nowhere to go.
+ */
+describe("the restriction a selection walks the wizard with", () => {
+	it("tells a selection spanning folders about folders, not accounts", () => {
+		const scope = wizardScopeFor("acc-personal", "spansFolders");
+		assert.equal(scope.destination, crossFolderDestinationReason);
+		assert.equal(scope.rule, crossFolderRuleReason);
+		assert.match(scope.destination ?? "", /within one folder/);
+		assert.doesNotMatch(scope.destination ?? "", /account/);
+		assert.doesNotMatch(scope.rule ?? "", /account/);
+	});
+
+	it("keeps the account a folder-spanning selection has", () => {
+		// The widened doors are counted through a preview that account answers, so
+		// there is nothing to withhold them for.
+		const scope = wizardScopeFor("acc-personal", "spansFolders");
+		assert.equal(scope.accountId, "acc-personal");
+		assert.deepEqual(
+			[...matchDoorsFor(scope.accountId)],
+			["selected", "similar", "properties"],
+		);
+	});
+
+	it("tells a selection spanning accounts about accounts", () => {
+		const scope = wizardScopeFor(undefined, "spansAccounts");
+		assert.equal(scope.accountId, undefined);
+		assert.match(scope.destination ?? "", /within one account/);
+		assert.match(scope.rule ?? "", /within one account/);
+		assert.deepEqual([...matchDoorsFor(scope.accountId)], ["selected"]);
+	});
+
+	it("restricts a selection with no account whatever it was handed", () => {
+		const scope = wizardScopeFor(undefined, undefined);
+		assert.match(scope.destination ?? "", /within one account/);
+		assert.match(scope.rule ?? "", /within one account/);
+	});
+
+	it("restricts nothing when one account and one folder answer for it", () => {
+		assert.deepEqual(wizardScopeFor("acc-personal", undefined), {
+			accountId: "acc-personal",
+		});
+	});
+});

package/src/lib/wizard-steps.ts

@@ -232,6 +232,74 @@ export const crossAccountDestinationReason =
 export const crossAccountMatchReason =
 	"Matching beyond the messages you picked only works within one account — clear the selection, or pick messages from a single account.";
 
+/**
+ * Why a selection spanning folders of one account cannot become a rule (#525).
+ * The account is settled and the source folder is not, so the restriction the
+ * wizard states is the folder one — telling a single-account selection to pick
+ * one account is an instruction it cannot follow.
+ */
+export const crossFolderRuleReason =
+	"A rule only works within one folder — clear the selection, or pick messages from a single folder.";
+
+/** The same restriction on the step that asks for a folder. */
+export const crossFolderDestinationReason =
+	"A destination only works within one folder — clear the selection, or pick messages from a single folder.";
+
+/**
+ * Which scope a selection spans more of than the wizard's folder-scoped steps
+ * can take. The surface that resolved the selection knows which one it is, so it
+ * hands the case over rather than a flag both cases collapse into.
+ */
+export type SelectionRestriction = "spansAccounts" | "spansFolders";
+
+const RESTRICTION_COPY: Record<
+	SelectionRestriction,
+	{ rule: string; destination: string }
+> = {
+	spansAccounts: {
+		rule: crossAccountRuleReason,
+		destination: crossAccountDestinationReason,
+	},
+	spansFolders: {
+		rule: crossFolderRuleReason,
+		destination: crossFolderDestinationReason,
+	},
+};
+
+/** What a restricted selection leaves the wizard's account-scoped steps to work with. */
+export interface WizardScope {
+	/**
+	 * The account a filter, a folder create and a widened door's preview all
+	 * belong to. Absent only when the selection has no single account — a
+	 * selection spanning folders of one account keeps it, so its widened doors
+	 * have something to count against.
+	 */
+	accountId?: string;
+	/** What the rule step states, when the selection cannot reach a saved scope. */
+	rule?: string;
+	/** What the folder step states, when the selection cannot reach a destination. */
+	destination?: string;
+}
+
+/**
+ * The scope a selection walks the wizard with. A selection with no single
+ * account is account-restricted whatever it was handed, since the account is
+ * what the filter, the folder create and the preview all hang off.
+ */
+export const wizardScopeFor = (
+	accountId: string | undefined,
+	restriction: SelectionRestriction | undefined,
+): WizardScope => {
+	const applied = accountId === undefined ? "spansAccounts" : restriction;
+	if (!applied) return { accountId };
+	const copy = RESTRICTION_COPY[applied];
+	return {
+		accountId: applied === "spansAccounts" ? undefined : accountId,
+		rule: copy.rule,
+		destination: copy.destination,
+	};
+};
+
 /**
  * The doors the match step offers. Withholding the two widened ones is what
  * keeps a selection spanning accounts off a review that waits on a count nobody