@remit/web-client 0.0.186 → 0.0.188

package/package.json

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

@@ -72,7 +72,11 @@ import {
 import type { EscalationSearchQuery } from "@/hooks/useEscalatedActions";
 import { useIntelligenceData } from "@/hooks/useIntelligenceData";
 import { useIntelligenceDrawer } from "@/hooks/useIntelligenceDrawer";
-import { useIntelligenceSurface } from "@/hooks/useIntelligenceSurface";
+import {
+	type IntelligenceCommands,
+	useIntelligenceSurface,
+	usePublishIntelligenceCommands,
+} from "@/hooks/useIntelligenceSurface";
 import { useLayoutTier } from "@/hooks/useLayoutTier";
 import { useMailboxAccount } from "@/hooks/useMailboxAccount";
 import { useToggleReadFor } from "@/hooks/useMarkAsRead";
@@ -168,8 +172,14 @@ interface MailboxPaneContextValue {
 	 * when no category is selected.
 	 */
 	listFilter: MessageListFilter | undefined;
-	intelligenceOpen: boolean;
 	onToggleIntelligence: () => void;
+	/**
+	 * Where the mounted reading surface publishes the intelligence commands the
+	 * keyboard layer drives. The rail's width gate is the shell's own
+	 * measurement and this provider sits above the shell, so the surface that is
+	 * mounted answers for its own tier rather than this one guessing.
+	 */
+	intelligenceRef: RefObject<IntelligenceCommands | null>;
 	/**
 	 * Deselects the open message when it's the one a mutation just removed
 	 * from this mailbox's list — wired into every mutation that can take the
@@ -260,8 +270,7 @@ function MailboxPaneProvider({
 	const threadId = thread?.threadId;
 	const pointedAtMessageId = thread?.messageId;
 	const telemetry = useTelemetry();
-	const { accounts, searchQuery, intelligenceOpen, onToggleIntelligence } =
-		useMailContext();
+	const { accounts, searchQuery, onToggleIntelligence } = useMailContext();
 	const tokenContext = useSearchTokenContext();
 
 	const normalizedSearchQuery = normalizeSearchQuery(searchQuery);
@@ -499,6 +508,8 @@ function MailboxPaneProvider({
 			onAfterOptimisticRemove: handleDeselectIfRemoved,
 		});
 
+	const intelligenceRef = useRef<IntelligenceCommands | null>(null);
+
 	const triage = useTriageContext();
 	const {
 		listCommandsRef,
@@ -691,9 +702,14 @@ function MailboxPaneProvider({
 		updateFocusedSenderFlags({ vip: { value: next } });
 	}, [focusedAddressId, focusedAddress, updateFocusedSenderFlags]);
 
+	// Block sender lives in intelligence, so the key raises whichever surface
+	// this width has: the rail above 1280, the drawer below it. Reaching for
+	// `onToggleIntelligence` from here wrote `#intelligence` at every tier, and
+	// a panel the address names with no renderer behind it is a panel that opens
+	// nothing (`docs/architecture/url-state.md`, R6).
 	const triageBlock = useCallback(() => {
-		if (!intelligenceOpen) onToggleIntelligence();
-	}, [intelligenceOpen, onToggleIntelligence]);
+		intelligenceRef.current?.open();
+	}, []);
 
 	const goToRoute = useCallback(
 		(to: "/mail/brief" | "/mail/flagged" | "/settings") => {
@@ -736,10 +752,12 @@ function MailboxPaneProvider({
 			toggleStar: triageStar,
 			toggleRead: triageToggleRead,
 			muteSender: triageMute,
-			blockSender: triageBlock,
+			blockSender: selectedThread ? triageBlock : undefined,
 			vipSender: triageVip,
 			markJunk: triageMarkJunk,
-			toggleIntelligence: selectedThread ? onToggleIntelligence : undefined,
+			toggleIntelligence: selectedThread
+				? () => intelligenceRef.current?.toggle()
+				: undefined,
 			compose: openCompose,
 			goBrief: () => goToRoute("/mail/brief"),
 			goInbox: () => goToRoute("/mail/brief"),
@@ -783,8 +801,8 @@ function MailboxPaneProvider({
 		onToggleFilterAttribute,
 		onClearFilters,
 		listFilter,
-		intelligenceOpen,
 		onToggleIntelligence,
+		intelligenceRef,
 		handleDeselectIfRemoved,
 		// Escalation ("select all N matching") re-issues this predicate server-side
 		// and acts on every match, so it is only offered when the predicate IS the
@@ -1064,9 +1082,11 @@ function MailboxReading() {
 		onToolbarStar,
 		onToolbarMove,
 		handleDeselectIfRemoved,
+		intelligenceRef,
 	} = useMailboxPane();
 	const hasThread = Boolean(conversation);
 	const intelligence = useIntelligenceSurface(conversation?.threadId);
+	usePublishIntelligenceCommands(intelligenceRef, intelligence);
 
 	// The rail opens itself on a DKIM mismatch. It lives here, behind the rail's
 	// own width gate, because raising it writes `#intelligence` into the address
@@ -1182,8 +1202,14 @@ function MailboxPhone() {
 		nextThread,
 		previousThread,
 		handleDeselectIfRemoved,
+		intelligenceRef,
 	} = useMailboxPane();
+	// The drawer directly, not `useIntelligenceSurface`: this view is what the
+	// shell mounts where it has one pane, so there is no rail to choose between
+	// — and the rail's own width gate answers yes on a wide portrait tablet the
+	// shell still put here.
 	const drawer = useIntelligenceDrawer(conversation?.threadId ?? null);
+	usePublishIntelligenceCommands(intelligenceRef, drawer);
 
 	if (conversation) {
 		return (

package/src/components/mail/MessageActionMenu.tsx

@@ -2,7 +2,6 @@ import {
 	messageBulkOperationsUpdateFlagsMutation,
 	threadDetailOperationsListThreadMessagesQueryKey,
 } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
-import type { RemitImapThreadMessageResponse } from "@remit/api-http-client/types.gen.ts";
 import { useMutation, useQueryClient } from "@tanstack/react-query";
 import { useNavigate } from "@tanstack/react-router";
 import {
@@ -32,29 +31,13 @@ import {
 	patchThreadListQueries,
 	restoreThreadListQueries,
 	snapshotThreadListQueries,
-	type ThreadListSnapshotEntry,
+	type ThreadMessagesData,
+	type ThreadMutationContext,
 	threadListCacheKeys,
 } from "@/lib/thread-list-cache";
 import { useOpenThreadPath, useRetainOpenPanels } from "@/routing";
 import { MoveToTrigger } from "./MoveToTrigger";
 
-interface ThreadMessagesData {
-	items: RemitImapThreadMessageResponse[];
-	[key: string]: unknown;
-}
-
-interface SnapshotEntry<T> {
-	queryKey: readonly unknown[];
-	data: T;
-}
-
-interface MarkUnreadContext {
-	threadMessagesPrefix: readonly unknown[];
-	listPrefixes: ReadonlyArray<readonly unknown[]>;
-	previousThreadMessages: SnapshotEntry<ThreadMessagesData>[];
-	previousThreadsList: ThreadListSnapshotEntry[];
-}
-
 interface MessageActionMenuProps {
 	messageId: string;
 	threadId: string;
@@ -109,7 +92,7 @@ export const MessageActionMenu = ({
 
 	const { mutate: updateFlags, isPending: isUpdatingFlags } = useMutation({
 		...messageBulkOperationsUpdateFlagsMutation(),
-		onMutate: async (variables): Promise<MarkUnreadContext> => {
+		onMutate: async (variables): Promise<ThreadMutationContext> => {
 			const isReadNext = variables.body.isRead ?? true;
 			const targetIds = new Set(variables.body.messageIds ?? []);
 

package/src/components/mail/intelligence-shortcut-surface.render.test.ts

@@ -0,0 +1,343 @@
+/**
+ * The mailbox's intelligence keys act on the surface the width has (#840).
+ *
+ * `i` and `b` are registered by the pane provider, which sits above the shell
+ * and so cannot see the rail's own width gate. Both reached for the rail's
+ * toggle directly, and below 1280 that wrote `#intelligence` into the address
+ * with no rail mounted to render it — a panel the address names and nothing
+ * answers (`docs/architecture/url-state.md`, R6). The drawer is the surface at
+ * those widths, and it is what the toolbar's own control already used.
+ *
+ * Mounted in the real `AppShellSlotted` at all three tiers, with the `/mail`
+ * layout's binding between the fragment and the rail: which panes a width has
+ * is the shell's own answer here, and what the address holds is the router's.
+ */
+
+import assert from "node:assert/strict";
+import { afterEach, describe, it } from "node:test";
+import { AppShellSlotted } from "@remit/ui";
+import {
+	type AnyRouter,
+	createMemoryHistory,
+	createRootRoute,
+	createRoute,
+	createRouter,
+	Outlet,
+	RouterProvider,
+} from "@tanstack/react-router";
+import { createElement, type ReactNode, useCallback } from "react";
+import { ComposeProvider } from "@/components/compose/ComposeProvider";
+import { MailContext, type MailContextValue } from "@/lib/mail-context";
+import { EMPTY_RESULT_FOLDER_INDEX } from "@/lib/result-folder";
+import { useOpenPanels, useOpenThreadPath, useSetOpenPanels } from "@/routing";
+import {
+	createDomHarness,
+	type DomHarness,
+	type DomOptions,
+} from "@/test-support/dom";
+import { makeThreadMessage } from "@/test-support/fixtures";
+import { type HttpMock, mockFetch } from "@/test-support/http";
+import {
+	describedMessage,
+	intelligenceDrawer,
+	MESSAGE_ID,
+	settle,
+	THREAD_ID,
+} from "@/test-support/intelligence-surface";
+import { MailboxPane } from "./MailboxPane";
+
+/** Below the rail's 1280px gate, above the reading pane's 1024px one. */
+const TWO_PANE_WIDTH = 1100;
+/** Wide enough for the rail, which is where the fragment raises it. */
+const RAIL_WIDTH = 1400;
+/** One pane, where the list route mounts its phone view instead of the slots. */
+const PHONE_WIDTH = 420;
+
+const MAILBOX_ID = "mailbox-1";
+const MESSAGE_PATH = `/mail/${MAILBOX_ID}/${THREAD_ID}/${MESSAGE_ID}`;
+
+/**
+ * No DKIM mismatch: the auto-open raises the rail on its own where the rail
+ * fits, which would put `#intelligence` in the address before any key is
+ * pressed.
+ */
+const row = makeThreadMessage({
+	messageId: MESSAGE_ID,
+	threadId: THREAD_ID,
+	subject: "Your parcel could not be delivered",
+	fromName: "Mondial Relay",
+	fromEmail: "delivery.notice@gmail.example",
+});
+
+let harness: DomHarness | undefined;
+let http: HttpMock | undefined;
+
+afterEach(() => {
+	harness?.close();
+	harness = undefined;
+	http?.restore();
+	http = undefined;
+});
+
+// The router reads `self` at construction; the shared jsdom globals stop at
+// `window`.
+(globalThis as { self?: typeof globalThis }).self ??= globalThis;
+
+/**
+ * What `routes/mail.tsx` binds: the rail's open state is the fragment, and the
+ * toggle rewrites the fragment. The device preference is left out — nothing
+ * here is about the tier the address is silent on.
+ */
+function MailLayout({ children }: { children: ReactNode }) {
+	const openPanels = useOpenPanels();
+	const setOpenPanels = useSetOpenPanels();
+	const intelligenceOpen = openPanels.includes("intelligence");
+	const onToggleIntelligence = useCallback(() => {
+		setOpenPanels(intelligenceOpen ? [] : ["intelligence"]);
+	}, [intelligenceOpen, setOpenPanels]);
+
+	const value: MailContextValue = {
+		accounts: [],
+		mailboxNameIndex: new Map(),
+		accountNameIndex: new Map(),
+		resultFolderIndex: EMPTY_RESULT_FOLDER_INDEX,
+		searchQuery: "",
+		searchInput: "",
+		searchViewKey: "",
+		onSearchChange: () => {},
+		onSearchClear: () => {},
+		onSearchClearQuery: () => {},
+		intelligenceOpen,
+		onToggleIntelligence,
+	};
+	return createElement(MailContext.Provider, { value }, children);
+}
+
+/**
+ * The shell as `MailShell` mounts it: one pane carrying the phone view below
+ * the reading boundary, the slots above it, and the rail's visibility taken
+ * from the address the same way the layout takes it.
+ */
+function Shell({ width }: { width: number }) {
+	const intelligenceOpen = useOpenPanels().includes("intelligence");
+	if (width < 1024) {
+		return createElement(AppShellSlotted, {
+			initialWidth: width,
+			nav: null,
+			list: createElement(MailboxPane.Phone),
+		});
+	}
+	return createElement(AppShellSlotted, {
+		initialWidth: width,
+		nav: null,
+		list: null,
+		reading: createElement(MailboxPane.Reading),
+		intelligence: createElement(MailboxPane.Intelligence),
+		intelligenceOpen,
+	});
+}
+
+const testRouter = (width: number, href: string): AnyRouter => {
+	const rootRoute = createRootRoute({
+		component: () =>
+			createElement(
+				ComposeProvider,
+				null,
+				createElement(MailLayout, {
+					// biome-ignore lint/correctness/noChildrenProp: no JSX in a `.ts` test, and createElement's variadic children do not satisfy a required prop
+					children: createElement(Outlet),
+				}),
+			),
+	});
+	const mailRoute = createRoute({
+		getParentRoute: () => rootRoute,
+		path: "/mail",
+		validateSearch: (search: Record<string, unknown>) => search,
+		component: Outlet,
+	});
+	const mailboxRoute = createRoute({
+		getParentRoute: () => mailRoute,
+		path: "/$mailboxId",
+		component: () =>
+			createElement(MailboxPane, {
+				mailboxId: MAILBOX_ID,
+				thread: useOpenThreadPath(),
+				// biome-ignore lint/correctness/noChildrenProp: no JSX in a `.ts` test, and createElement's variadic children do not satisfy a required prop
+				children: createElement(Outlet),
+			}),
+	});
+	const threadRoute = createRoute({
+		getParentRoute: () => mailboxRoute,
+		path: "$threadId",
+		component: Outlet,
+	});
+	const messageRoute = createRoute({
+		getParentRoute: () => threadRoute,
+		path: "$messageId",
+		component: () => createElement(Shell, { width }),
+	});
+	const routeTree = rootRoute.addChildren([
+		mailRoute.addChildren([
+			mailboxRoute.addChildren([threadRoute.addChildren([messageRoute])]),
+		]),
+	]);
+	return createRouter({
+		routeTree,
+		history: createMemoryHistory({ initialEntries: [href] }),
+	}) as unknown as AnyRouter;
+};
+
+const mountAt = async (
+	width: number,
+	options: DomOptions = {},
+	href: string = MESSAGE_PATH,
+): Promise<[DomHarness, AnyRouter]> => {
+	http = mockFetch((call) => {
+		if (call.path.endsWith("/config")) return { accounts: [] };
+		if (call.path.endsWith(`/threads/${THREAD_ID}/messages`)) {
+			return { items: [row] };
+		}
+		if (call.path.includes("/messages/")) return describedMessage;
+		if (call.path.includes("/threads")) return { items: [row] };
+		return { items: [] };
+	});
+
+	const router = testRouter(width, href);
+	await router.load();
+	const mounted = createDomHarness({ viewportWidth: width, ...options });
+	harness = mounted;
+	mounted.renderApp(createElement(RouterProvider, { router }));
+	await settle(mounted);
+	return [mounted, router];
+};
+
+const press = async (mounted: DomHarness, key: string): Promise<void> => {
+	mounted.dispatch(
+		mounted.window,
+		new mounted.window.KeyboardEvent("keydown", { key, bubbles: true }),
+	);
+	await settle(mounted);
+};
+
+/**
+ * The rail: the intelligence panel mounted in the shell's own row rather than
+ * inside the drawer, which puts the same panel behind a scrim.
+ */
+const rail = (mounted: DomHarness): HTMLElement | null => {
+	const pane = mounted.query("aside");
+	if (!pane) return null;
+	return pane.closest('[role="dialog"]') ? null : pane;
+};
+
+describe("the intelligence keys reach the surface the width has (#840)", () => {
+	for (const [tier, width, options] of [
+		["between the reading pane and the rail", TWO_PANE_WIDTH, {}],
+		[
+			"on the phone",
+			PHONE_WIDTH,
+			{ pointer: "coarse", orientation: "portrait" } as DomOptions,
+		],
+	] as const) {
+		it(`${tier}, i opens the drawer and leaves the address alone`, async () => {
+			const [mounted, router] = await mountAt(width, options);
+
+			await press(mounted, "i");
+
+			assert.ok(intelligenceDrawer(mounted), "pressing i opened nothing");
+			assert.equal(
+				router.state.location.hash,
+				"",
+				"the address named a panel this width cannot render",
+			);
+		});
+
+		it(`${tier}, a second i puts the drawer away`, async () => {
+			const [mounted] = await mountAt(width, options);
+
+			await press(mounted, "i");
+			assert.ok(intelligenceDrawer(mounted), "pressing i opened nothing");
+
+			await press(mounted, "i");
+			assert.equal(
+				intelligenceDrawer(mounted),
+				null,
+				"the second press left it up",
+			);
+		});
+
+		it(`${tier}, b reaches block sender through the same drawer`, async () => {
+			const [mounted, router] = await mountAt(width, options);
+
+			await press(mounted, "b");
+
+			assert.ok(intelligenceDrawer(mounted), "pressing b opened nothing");
+			assert.equal(
+				router.state.location.hash,
+				"",
+				"the address named a panel this width cannot render",
+			);
+		});
+	}
+
+	it("still writes the fragment where the rail is the surface", async () => {
+		const [mounted, router] = await mountAt(RAIL_WIDTH);
+
+		await press(mounted, "i");
+
+		assert.equal(
+			router.state.location.hash,
+			"intelligence",
+			"the rail's own tier stopped writing the fragment",
+		);
+		assert.equal(
+			intelligenceDrawer(mounted),
+			null,
+			"the drawer came up where the rail is the surface",
+		);
+	});
+
+	it("writes the fragment for block sender where the rail is the surface", async () => {
+		const [mounted, router] = await mountAt(RAIL_WIDTH);
+
+		await press(mounted, "b");
+
+		assert.equal(router.state.location.hash, "intelligence");
+		assert.equal(
+			intelligenceDrawer(mounted),
+			null,
+			"the drawer came up where the rail is the surface",
+		);
+	});
+});
+
+/**
+ * What the fragment is worth at each width, on a cold load. The rail is the one
+ * renderer the name has, which is why the keys above must not write the name
+ * anywhere else.
+ */
+describe("#intelligence names a renderer only where the rail fits", () => {
+	it("mounts the rail where the address carries it and the width has room", async () => {
+		const [mounted] = await mountAt(
+			RAIL_WIDTH,
+			{},
+			`${MESSAGE_PATH}#intelligence`,
+		);
+
+		assert.ok(rail(mounted), "the fragment raised no rail");
+	});
+
+	it("mounts nothing for the same address below the rail's width", async () => {
+		const [mounted] = await mountAt(
+			TWO_PANE_WIDTH,
+			{},
+			`${MESSAGE_PATH}#intelligence`,
+		);
+
+		assert.equal(rail(mounted), null, "a rail rendered where none fits");
+		assert.equal(
+			intelligenceDrawer(mounted),
+			null,
+			"the fragment raised the drawer, which belongs to the thread",
+		);
+	});
+});

package/src/components/mail/intelligence-surface-reach.render.test.ts

@@ -32,15 +32,19 @@ import { type OpenThreadPath, useOpenThreadPath } from "@/routing";
 import { createDomHarness, type DomHarness } from "@/test-support/dom";
 import { makeThreadMessage } from "@/test-support/fixtures";
 import { type HttpMock, mockFetch } from "@/test-support/http";
+import {
+	describedMessage,
+	intelligenceDrawer,
+	MESSAGE_ID,
+	settle,
+	THREAD_ID,
+} from "@/test-support/intelligence-surface";
 import { BriefPane } from "./BriefPane";
 import { FlaggedPane } from "./FlaggedPane";
 
 /** Below the rail's 1280px gate, above the reading pane's 1024px one. */
 const TWO_PANE_WIDTH = 1100;
 
-const THREAD_ID = "thread-1";
-const MESSAGE_ID = "msg-1";
-
 const SHOW_INTELLIGENCE = "Show intelligence sidebar";
 const HIDE_INTELLIGENCE = "Hide intelligence sidebar";
 
@@ -60,24 +64,6 @@ const row = makeThreadMessage({
 	},
 });
 
-/** What the reading pane reads each message's own headers and body from. */
-const describedMessage = {
-	messageId: MESSAGE_ID,
-	envelope: {
-		from: [
-			{
-				addressId: "addr-1",
-				name: "Mondial Relay",
-				email: "delivery.notice@gmail.example",
-			},
-		],
-		to: [],
-		cc: [],
-		bcc: [],
-	},
-	bodyParts: [],
-};
-
 let harness: DomHarness | undefined;
 let http: HttpMock | undefined;
 
@@ -197,15 +183,6 @@ const mount = async (pane: PaneUnderTest): Promise<DomHarness> => {
 	return mounted;
 };
 
-const settle = async (mounted: DomHarness): Promise<void> => {
-	await mounted.flush();
-	await mounted.wait(20);
-	await mounted.flush();
-};
-
-const drawer = (mounted: DomHarness): HTMLElement | null =>
-	mounted.query('[role="dialog"][aria-label="Message details"]');
-
 describe("intelligence is reachable wherever the reading pane mounts (#817)", () => {
 	for (const pane of panes) {
 		it(`${pane.name} offers a live toolbar control below the rail's width`, async () => {
@@ -221,7 +198,7 @@ describe("intelligence is reachable wherever the reading pane mounts (#817)", ()
 			mounted.click(toggle);
 			await settle(mounted);
 
-			assert.ok(drawer(mounted), "pressing it opened nothing");
+			assert.ok(intelligenceDrawer(mounted), "pressing it opened nothing");
 			assert.ok(
 				mounted.query(`[aria-label="${HIDE_INTELLIGENCE}"]`),
 				"the toolbar still reports the surface as closed",
@@ -235,7 +212,7 @@ describe("intelligence is reachable wherever the reading pane mounts (#817)", ()
 			await settle(mounted);
 
 			assert.ok(
-				drawer(mounted),
+				intelligenceDrawer(mounted),
 				"the banner's Why? reached no intelligence surface",
 			);
 		});

package/src/hooks/useDeleteMessages.ts

@@ -16,7 +16,8 @@ import {
 	patchThreadListQueries,
 	restoreThreadListQueries,
 	snapshotThreadListQueries,
-	type ThreadListSnapshotEntry,
+	type ThreadMessagesData,
+	type ThreadMutationContext,
 	threadListCacheKeys,
 } from "@/lib/thread-list-cache";
 
@@ -39,23 +40,6 @@ interface UseDeleteMessagesOptions {
 	onAfterOptimisticRemove?: (messageIds: string[]) => void;
 }
 
-interface ThreadMessagesData {
-	items: RemitImapThreadMessageResponse[];
-	[key: string]: unknown;
-}
-
-interface SnapshotEntry<T> {
-	queryKey: readonly unknown[];
-	data: T;
-}
-
-interface DeleteContext {
-	threadMessagesPrefix: readonly unknown[];
-	listPrefixes: ReadonlyArray<readonly unknown[]>;
-	previousThreadMessages: SnapshotEntry<ThreadMessagesData>[];
-	previousThreadsList: ThreadListSnapshotEntry[];
-}
-
 /**
  * Pure helper: drop the messages in `messageIds` from a single page's items.
  *
@@ -94,7 +78,7 @@ export const useDeleteMessages = ({
 
 	const { mutateAsync, isPending } = useMutation({
 		...messageBulkOperationsDeleteMessagesMutation(),
-		onMutate: async (variables): Promise<DeleteContext> => {
+		onMutate: async (variables): Promise<ThreadMutationContext> => {
 			const messageIds = new Set(variables.body.messageIds ?? []);
 
 			const threadMessagesPrefix = threadId

package/src/hooks/useIntelligenceSurface.ts

@@ -1,5 +1,5 @@
 import { useAppShellLayout } from "@remit/ui";
-import { useCallback } from "react";
+import { type RefObject, useCallback, useEffect } from "react";
 import { useIntelligenceDrawer } from "@/hooks/useIntelligenceDrawer";
 import { useMailContext } from "@/lib/mail-context";
 
@@ -10,15 +10,11 @@ import { useMailContext } from "@/lib/mail-context";
  * rail's own gate as the answer for both tiers and offered a disabled control
  * with nothing behind it between 1024 and 1280 (#817).
  */
-export interface IntelligenceSurface {
+export interface IntelligenceSurface extends IntelligenceCommands {
 	/** There is a thread to say anything about, so the toolbar's control acts. */
 	canToggle: boolean;
 	/** What the toolbar reports: the rail above 1280, the drawer below it. */
 	isShowing: boolean;
-	/** The toolbar's control, over whichever surface this width has. */
-	toggle: () => void;
-	/** The banner's "Why?" — an open, never a close. */
-	open: () => void;
 	drawerOpen: boolean;
 	closeDrawer: () => void;
 	/** Whether this width has room for the rail, so the rail is the surface. */
@@ -27,6 +23,19 @@ export interface IntelligenceSurface {
 	openRail: () => void;
 }
 
+/**
+ * What a mounted intelligence surface answers for. The width gate is the
+ * shell's own measurement, so only a component inside `AppShellSlotted` knows
+ * which surface this tier has; a pane provider wrapping the shell reaches it
+ * through a ref the mounted surface publishes into.
+ */
+export interface IntelligenceCommands {
+	/** The toolbar's control, over whichever surface this width has. */
+	toggle: () => void;
+	/** The banner's "Why?" — an open, never a close. */
+	open: () => void;
+}
+
 export const useIntelligenceSurface = (
 	openThreadId: string | undefined,
 ): IntelligenceSurface => {
@@ -50,15 +59,40 @@ export const useIntelligenceSurface = (
 		if (!railFits || intelligenceOpen) return;
 		onToggleIntelligence();
 	}, [railFits, intelligenceOpen, onToggleIntelligence]);
+	const open = useCallback(() => {
+		if (!railFits) {
+			openDrawer();
+			return;
+		}
+		openRail();
+	}, [railFits, openDrawer, openRail]);
 
 	return {
 		canToggle: threadId !== null,
 		isShowing: threadId !== null && (railFits ? intelligenceOpen : drawerOpen),
 		toggle,
-		open: railFits ? onToggleIntelligence : openDrawer,
+		open,
 		drawerOpen,
 		closeDrawer: drawer.close,
 		railFits,
 		openRail,
 	};
 };
+
+/**
+ * Publish the mounted surface for the pane provider's keyboard handlers. Null
+ * while nothing is mounted to serve them, so a shortcut fired with no surface
+ * reaches nothing rather than writing `#intelligence` at a width that cannot
+ * render it (`docs/architecture/url-state.md`, R6).
+ */
+export const usePublishIntelligenceCommands = (
+	ref: RefObject<IntelligenceCommands | null>,
+	{ toggle, open }: IntelligenceCommands,
+): void => {
+	useEffect(() => {
+		ref.current = { toggle, open };
+		return () => {
+			ref.current = null;
+		};
+	}, [ref, toggle, open]);
+};

package/src/hooks/useMarkAsRead.ts

@@ -16,7 +16,8 @@ import {
 	patchThreadListQueries,
 	restoreThreadListQueries,
 	snapshotThreadListQueries,
-	type ThreadListSnapshotEntry,
+	type ThreadMessagesData,
+	type ThreadMutationContext,
 	threadListCacheKeys,
 } from "@/lib/thread-list-cache";
 
@@ -28,23 +29,6 @@ interface UseMarkAsReadOptions {
 	accountId?: string;
 }
 
-interface ThreadMessagesData {
-	items: RemitImapThreadMessageResponse[];
-	[key: string]: unknown;
-}
-
-interface SnapshotEntry<T> {
-	queryKey: readonly unknown[];
-	data: T;
-}
-
-interface MarkAsReadContext {
-	threadMessagesPrefix: readonly unknown[];
-	listPrefixes: ReadonlyArray<readonly unknown[]>;
-	previousThreadMessages: SnapshotEntry<ThreadMessagesData>[];
-	previousThreadsList: ThreadListSnapshotEntry[];
-}
-
 /**
  * Dwell before a message the user is viewing is marked read. A glance closed
  * within this window leaves it unread (#140). Applied by the single shared
@@ -145,7 +129,7 @@ export const useMarkAsRead = ({
 	const { mutate: markAsRead } = useMutation({
 		...messageBulkOperationsUpdateFlagsMutation(),
 		meta: softErrorMeta,
-		onMutate: async (variables): Promise<MarkAsReadContext> => {
+		onMutate: async (variables): Promise<ThreadMutationContext> => {
 			const messageIds = new Set(variables.body.messageIds ?? []);
 			const isRead = variables.body.isRead ?? true;
 

package/src/hooks/useMoveMessages.ts

@@ -15,7 +15,8 @@ import {
 	patchThreadListQueries,
 	restoreThreadListQueries,
 	snapshotThreadListQueries,
-	type ThreadListSnapshotEntry,
+	type ThreadMessagesData,
+	type ThreadMutationContext,
 	threadListCacheKeys,
 } from "@/lib/thread-list-cache";
 
@@ -31,23 +32,6 @@ interface UseMoveMessagesOptions {
 	onAfterOptimisticRemove?: (messageIds: string[]) => void;
 }
 
-interface ThreadMessagesData {
-	items: RemitImapThreadMessageResponse[];
-	[key: string]: unknown;
-}
-
-interface SnapshotEntry<T> {
-	queryKey: readonly unknown[];
-	data: T;
-}
-
-interface MoveContext {
-	threadMessagesPrefix: readonly unknown[];
-	listPrefixes: ReadonlyArray<readonly unknown[]>;
-	previousThreadMessages: SnapshotEntry<ThreadMessagesData>[];
-	previousThreadsList: ThreadListSnapshotEntry[];
-}
-
 /**
  * Pure helper: drop the messages in `messageIds` from a single page's items.
  *
@@ -73,7 +57,7 @@ export const useMoveMessages = ({
 
 	const { mutateAsync, isPending, isError } = useMutation({
 		...messageBulkOperationsMoveMessagesMutation(),
-		onMutate: async (variables): Promise<MoveContext> => {
+		onMutate: async (variables): Promise<ThreadMutationContext> => {
 			const messageIds = new Set(variables.body.messageIds ?? []);
 
 			const threadMessagesPrefix = threadId

package/src/hooks/useToggleStar.ts

@@ -13,7 +13,8 @@ import {
 	patchThreadListQueries,
 	restoreThreadListQueries,
 	snapshotThreadListQueries,
-	type ThreadListSnapshotEntry,
+	type ThreadMessagesData,
+	type ThreadMutationContext,
 	threadListCacheKeys,
 } from "@/lib/thread-list-cache";
 
@@ -48,23 +49,6 @@ export const resolveMailboxForMessage = (
 	messages?.find((message) => message.messageId === messageId)?.mailboxId ??
 	fallbackMailboxId;
 
-interface ThreadMessagesData {
-	items: RemitImapThreadMessageResponse[];
-	[key: string]: unknown;
-}
-
-interface SnapshotEntry<T> {
-	queryKey: readonly unknown[];
-	data: T;
-}
-
-interface ToggleStarContext {
-	threadMessagesPrefix: readonly unknown[];
-	listPrefixes: ReadonlyArray<readonly unknown[]>;
-	previousThreadMessages: SnapshotEntry<ThreadMessagesData>[];
-	previousThreadsList: ThreadListSnapshotEntry[];
-}
-
 export const toggleStarsInItems = (
 	items: RemitImapThreadMessageResponse[],
 	messageId: string,
@@ -84,7 +68,7 @@ export const useToggleStar = ({
 
 	const { mutate, isPending, variables } = useMutation({
 		...messageOperationsUpdateMessageFlagsMutation(),
-		onMutate: async (vars): Promise<ToggleStarContext> => {
+		onMutate: async (vars): Promise<ThreadMutationContext> => {
 			const messageId = vars.path.messageId;
 			const nextStarred = vars.body.isStarred ?? false;
 

package/src/hooks/useToggleTrusted.ts

@@ -11,19 +11,15 @@ import type {
 import { useMutation, useQueryClient } from "@tanstack/react-query";
 import { useErrorBanners } from "@/components/ui/ErrorBannerProvider";
 import { buildMutationErrorBanner } from "@/components/ui/error-banners";
+import type { SnapshotEntry } from "@/lib/thread-list-cache";
 
 interface UseToggleTrustedOptions {
 	messageId: string;
 }
 
-interface SnapshotEntry {
-	queryKey: readonly unknown[];
-	data: RemitImapDescribeMessageResponse;
-}
-
 interface ToggleTrustedContext {
 	describePrefix: readonly unknown[];
-	previous: SnapshotEntry[];
+	previous: SnapshotEntry<RemitImapDescribeMessageResponse>[];
 }
 
 export const buildTrustedFlag = (

package/src/lib/thread-list-cache.ts

@@ -7,9 +7,31 @@ import type { RemitImapThreadMessageResponse } from "@remit/api-http-client/type
 import type { QueryClient } from "@tanstack/react-query";
 import { patchThreadListCache, type ThreadListCache } from "./thread-cache.js";
 
-export interface ThreadListSnapshotEntry {
+export interface SnapshotEntry<T> {
 	queryKey: readonly unknown[];
-	data: ThreadListCache;
+	data: T;
+}
+
+export type ThreadListSnapshotEntry = SnapshotEntry<ThreadListCache>;
+
+/** A cached page of one thread's messages, as the thread-detail endpoint serves it. */
+export interface ThreadMessagesData {
+	items: RemitImapThreadMessageResponse[];
+	[key: string]: unknown;
+}
+
+/**
+ * The rollback state an optimistic thread mutation captures in `onMutate`.
+ *
+ * The shape belongs to the snapshot/restore helpers below rather than to any
+ * one mutation, so mark-read, star, delete and move all carry the same one
+ * (#868).
+ */
+export interface ThreadMutationContext {
+	threadMessagesPrefix: readonly unknown[];
+	listPrefixes: ReadonlyArray<readonly unknown[]>;
+	previousThreadMessages: SnapshotEntry<ThreadMessagesData>[];
+	previousThreadsList: ThreadListSnapshotEntry[];
 }
 
 /**

package/src/test-support/intelligence-surface.ts

@@ -0,0 +1,42 @@
+/**
+ * What every intelligence-surface spec needs to poke one: the message the
+ * reading pane reads its headers from, the settle the router and the query
+ * client both need, and the drawer as the DOM names it.
+ *
+ * The thread row itself is each spec's own, because the DKIM mismatch that
+ * raises the authenticity banner also raises the rail wherever the rail fits.
+ */
+
+import type { DomHarness } from "@/test-support/dom";
+
+export const THREAD_ID = "thread-1";
+export const MESSAGE_ID = "msg-1";
+
+/** What the reading pane reads each message's own headers and body from. */
+export const describedMessage = {
+	messageId: MESSAGE_ID,
+	envelope: {
+		from: [
+			{
+				addressId: "addr-1",
+				name: "Mondial Relay",
+				email: "delivery.notice@gmail.example",
+			},
+		],
+		to: [],
+		cc: [],
+		bcc: [],
+	},
+	bodyParts: [],
+};
+
+/** Let the router commit, the queries land, and the render that follows run. */
+export const settle = async (mounted: DomHarness): Promise<void> => {
+	await mounted.flush();
+	await mounted.wait(20);
+	await mounted.flush();
+};
+
+/** The intelligence drawer, by the role and label it publishes. */
+export const intelligenceDrawer = (mounted: DomHarness): HTMLElement | null =>
+	mounted.query('[role="dialog"][aria-label="Message details"]');