@remit/web-client 0.0.295 → 0.0.297

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/web-client",
-  "version": "0.0.295",
+  "version": "0.0.297",
   "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": {
@@ -109,6 +109,7 @@
     "dictionary-nl": "2.0.0",
     "esbuild": "*",
     "jsdom": "^29.1.1",
+    "msw": "^2",
     "react": "^19",
     "react-dom": "^19.2.4",
     "tailwindcss": "^4",

package/src/components/mail/IntelligencePane.tsx

@@ -323,11 +323,6 @@ function WiredPanel({
 		updateFlags({ muted: { value: next } });
 	}, [data?.flags?.muted, updateFlags]);
 
-	const handleToggleUnsubscribe = useCallback(() => {
-		const next = !(data?.flags?.unsubscribed === true);
-		updateFlags({ unsubscribed: { value: next } });
-	}, [data?.flags?.unsubscribed, updateFlags]);
-
 	const handleReclassifySelect = useCallback(
 		(category: CategoryOverride) => {
 			setReclassifyOpen(false);
@@ -349,7 +344,6 @@ function WiredPanel({
 	const actions: IntelligenceQuickActions = {
 		onToggleVip: canUpdateFlags ? handleToggleVip : undefined,
 		onToggleMute: canUpdateFlags ? handleToggleMute : undefined,
-		onToggleUnsubscribe: canUpdateFlags ? handleToggleUnsubscribe : undefined,
 		onReclassify: canUpdateFlags ? () => setReclassifyOpen(true) : undefined,
 		onNotSpam: spamAction === "notSpam" ? handleNotSpam : undefined,
 		onReportSpam: spamAction === "reportSpam" ? handleReportSpam : undefined,

package/src/components/mail/daily-brief.stories.tsx

@@ -0,0 +1,250 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { expect, userEvent, waitFor, within } from "storybook/test";
+import { AppStory } from "@/mocks/story-frame/AppStory";
+import { mailHandlers } from "@/mocks/story-frame/mail-handlers";
+import { mailWorld, newsletterBacklog } from "@/mocks/story-frame/mail-world";
+import { longPress } from "@/mocks/story-frame/touch";
+
+const world = mailWorld();
+
+const meta = {
+	title: "Playground/Shipped/Mail/Daily brief",
+	component: AppStory,
+	args: { url: "/mail/brief" },
+	parameters: {
+		layout: "fullscreen",
+		msw: { handlers: mailHandlers(world) },
+	},
+} satisfies Meta<typeof AppStory>;
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+const phone = { viewport: { value: "mobile", isRotated: false } };
+
+const rows = (canvasElement: HTMLElement): HTMLElement[] =>
+	Array.from(canvasElement.querySelectorAll<HTMLElement>("[data-list-row]"));
+
+const ticked = (canvasElement: HTMLElement): number =>
+	rows(canvasElement).filter((row) =>
+		row.querySelector('[aria-label="Deselect message"]'),
+	).length;
+
+const openFilters = async (
+	canvasElement: HTMLElement,
+	label: "Expand filters" | "Search filters" = "Expand filters",
+) => {
+	const canvas = within(canvasElement);
+	await userEvent.click(await canvas.findByLabelText(label));
+};
+
+const pick = async (
+	canvasElement: HTMLElement,
+	group: "Accounts" | "Categories" | "Attributes",
+	name: string,
+) => {
+	const fieldset = await within(canvasElement).findByLabelText(group);
+	await userEvent.click(within(fieldset).getByRole("button", { name }));
+};
+
+export const Default: Story = {
+	play: async ({ canvasElement }) => {
+		const canvas = within(canvasElement);
+		await expect(await canvas.findByText("Q3 planning")).toBeVisible();
+		await expect(canvas.getByText("Autumn sale starts now")).toBeVisible();
+	},
+};
+
+export const Phone: Story = {
+	globals: phone,
+	play: async ({ canvasElement }) => {
+		const canvas = within(canvasElement);
+		await expect(await canvas.findByText("Q3 planning")).toBeVisible();
+	},
+};
+
+export const CaughtUp: Story = {
+	parameters: {
+		msw: { handlers: mailHandlers(mailWorld({ threads: [] })) },
+	},
+	play: async ({ canvasElement }) => {
+		const canvas = within(canvasElement);
+		await expect(await canvas.findByText("You're caught up")).toBeVisible();
+	},
+};
+
+export const FilteredToCategory: Story = {
+	play: async ({ canvasElement }) => {
+		const canvas = within(canvasElement);
+		await canvas.findByText("Q3 planning");
+		await openFilters(canvasElement);
+		await pick(canvasElement, "Categories", "Newsletter");
+		await waitFor(() =>
+			expect(canvas.queryByText("Q3 planning")).not.toBeInTheDocument(),
+		);
+		await expect(
+			await canvas.findByText("This week in type systems"),
+		).toBeVisible();
+	},
+};
+
+export const WorkOnly: Story = {
+	play: async ({ canvasElement }) => {
+		const canvas = within(canvasElement);
+		await canvas.findByText("Dinner on Saturday?");
+		await openFilters(canvasElement);
+		await pick(canvasElement, "Accounts", "alice.tan");
+		await waitFor(() =>
+			expect(canvas.queryByText("Dinner on Saturday?")).not.toBeInTheDocument(),
+		);
+		await expect(await canvas.findByText("Q3 planning")).toBeVisible();
+	},
+};
+
+export const SelectAllThenNarrow: Story = {
+	parameters: {
+		msw: {
+			handlers: mailHandlers(
+				mailWorld({
+					threads: [...world.threads, ...newsletterBacklog(14)],
+				}),
+			),
+		},
+	},
+	play: async ({ canvasElement }) => {
+		const canvas = within(canvasElement);
+		await canvas.findByText("Q3 planning");
+		await expect(
+			await canvas.findByRole("button", { name: /^Show (all|\d+ more)/ }),
+		).toBeVisible();
+		await openFilters(canvasElement);
+
+		const firstRow = rows(canvasElement)[0];
+		firstRow?.focus();
+		await expect(document.activeElement).toBe(firstRow);
+		await userEvent.keyboard("{Meta>}a{/Meta}");
+		await waitFor(() =>
+			expect(
+				canvas.getByText(/(loaded selected|messages? selected)$/),
+			).toHaveTextContent(`All ${rows(canvasElement).length} loaded selected`),
+		);
+		const selectedEverywhere = ticked(canvasElement);
+
+		await expect(selectedEverywhere).toBe(rows(canvasElement).length);
+
+		await pick(canvasElement, "Categories", "Newsletter");
+		await expect(
+			await canvas.findByText("Issue 1: notes from the field"),
+		).toBeVisible();
+		await waitFor(() => expect(ticked(canvasElement)).toBe(0));
+		await expect(
+			canvas.queryByText(/(loaded selected|messages? selected)$/),
+		).toBeNull();
+	},
+};
+
+export const ShiftArrowRange: Story = {
+	play: async ({ canvasElement }) => {
+		const canvas = within(canvasElement);
+		await canvas.findByText("Q3 planning");
+		rows(canvasElement)[0]?.focus();
+		await userEvent.keyboard("j");
+		await userEvent.keyboard("{Shift>}{ArrowDown}{ArrowDown}{/Shift}");
+		await waitFor(() =>
+			expect(canvas.getByText("2 messages selected")).toBeInTheDocument(),
+		);
+	},
+};
+
+export const OpenWithJ: Story = {
+	play: async ({ canvasElement }) => {
+		const canvas = within(canvasElement);
+		await canvas.findByText("Q3 planning");
+		rows(canvasElement)[0]?.focus();
+		await userEvent.keyboard("j");
+		await waitFor(() =>
+			expect(
+				canvas.getAllByText("Here is the countersigned copy for your records."),
+			).toHaveLength(2),
+		);
+	},
+};
+
+export const MultiSelect: Story = {
+	play: async ({ canvasElement }) => {
+		const canvas = within(canvasElement);
+		await canvas.findByText("Q3 planning");
+		const [first, , third] = rows(canvasElement);
+		for (const row of [first, third]) {
+			const toggle = row?.querySelector<HTMLElement>(
+				'[aria-label="Select message"]',
+			);
+			if (toggle) await userEvent.click(toggle);
+		}
+		await expect(await canvas.findByText("2 messages selected")).toBeVisible();
+	},
+};
+
+export const MultiSelectPhone: Story = {
+	globals: phone,
+	play: async ({ canvasElement }) => {
+		const canvas = within(canvasElement);
+		await canvas.findByText("Q3 planning");
+		const first = rows(canvasElement)[0];
+		if (first) await longPress(first);
+		await expect(await canvas.findByText("1 message selected")).toBeVisible();
+	},
+};
+
+export const Search: Story = {
+	args: { url: "/mail/brief?q=lease" },
+	play: async ({ canvasElement }) => {
+		const canvas = within(canvasElement);
+		await expect(
+			await canvas.findByText("Signed lease attached"),
+		).toBeVisible();
+		await expect(canvas.queryByText("Dinner on Saturday?")).toBeNull();
+	},
+};
+
+export const SearchWithChips: Story = {
+	args: { url: "/mail/brief?q=your" },
+	play: async ({ canvasElement }) => {
+		const canvas = within(canvasElement);
+		await canvas.findByText("Signed lease attached");
+		await openFilters(canvasElement);
+		await pick(canvasElement, "Attributes", "Unread");
+		await waitFor(() =>
+			expect(canvas.getByLabelText("Search mail")).toHaveValue(
+				"your is:unread",
+			),
+		);
+	},
+};
+
+export const SearchOfChipsOnly: Story = {
+	args: { url: "/mail/brief?q=is:unread" },
+	play: async ({ canvasElement }) => {
+		const canvas = within(canvasElement);
+		const offer = await canvas.findByRole("button", {
+			name: "Make this a filter",
+		});
+		await userEvent.click(offer);
+		await expect(
+			await canvas.findByText(/isn't a filter condition/, { selector: "p" }),
+		).toBeVisible();
+	},
+};
+
+export const SearchHitOutsideTheBrief: Story = {
+	args: { url: "/mail/brief?q=outline" },
+	play: async ({ canvasElement }) => {
+		const canvas = within(canvasElement);
+		await userEvent.click(await canvas.findByText("Conference talk outline"));
+		await waitFor(() =>
+			expect(
+				canvas.getAllByText("Here is the rough structure for the keynote."),
+			).toHaveLength(2),
+		);
+	},
+};

package/src/components/mail/drafts.stories.tsx

@@ -0,0 +1,61 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { expect, within } from "storybook/test";
+import { AppStory } from "@/mocks/story-frame/AppStory";
+import { mailHandlers } from "@/mocks/story-frame/mail-handlers";
+import {
+	mailboxIdFor,
+	mailWorld,
+	PERSONAL,
+} from "@/mocks/story-frame/mail-world";
+
+const world = mailWorld();
+const draftsMailboxId = mailboxIdFor(PERSONAL, "Drafts");
+
+const meta = {
+	title: "Playground/Shipped/Mail/Drafts",
+	component: AppStory,
+	args: { url: `/mail/${draftsMailboxId}` },
+	parameters: {
+		layout: "fullscreen",
+		msw: { handlers: mailHandlers(world) },
+	},
+} satisfies Meta<typeof AppStory>;
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Segmented: Story = {
+	play: async ({ canvasElement }) => {
+		const canvas = within(canvasElement);
+		await expect(await canvas.findByText("Not yet sent (Remit)")).toBeVisible();
+		await expect(canvas.getByText("On the server")).toBeVisible();
+		await expect(canvas.getByText("Re: Q3 planning")).toBeVisible();
+		await expect(canvas.getByText("Re: Conference talk outline")).toBeVisible();
+	},
+};
+
+export const Phone: Story = {
+	globals: { viewport: { value: "mobile", isRotated: false } },
+	play: async ({ canvasElement }) => {
+		const canvas = within(canvasElement);
+		await expect(await canvas.findByText("Not yet sent (Remit)")).toBeVisible();
+	},
+};
+
+export const Empty: Story = {
+	parameters: {
+		msw: {
+			handlers: mailHandlers({
+				...world,
+				threads: world.threads.filter(
+					(row) => row.mailboxId !== draftsMailboxId,
+				),
+				outbox: world.outbox.filter((message) => message.status !== "draft"),
+			}),
+		},
+	},
+	play: async ({ canvasElement }) => {
+		const canvas = within(canvasElement);
+		await expect(await canvas.findByText("No drafts")).toBeVisible();
+	},
+};

package/src/components/mail/flagged.stories.tsx

@@ -0,0 +1,159 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { expect, userEvent, waitFor, within } from "storybook/test";
+import { AppStory } from "@/mocks/story-frame/AppStory";
+import { mailHandlers } from "@/mocks/story-frame/mail-handlers";
+import { mailWorld } from "@/mocks/story-frame/mail-world";
+
+const world = mailWorld();
+
+const meta = {
+	title: "Playground/Shipped/Mail/Flagged",
+	component: AppStory,
+	args: { url: "/mail/flagged" },
+	parameters: {
+		layout: "fullscreen",
+		msw: { handlers: mailHandlers(world) },
+	},
+} satisfies Meta<typeof AppStory>;
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+const filterToCategory = async (canvasElement: HTMLElement, name: string) => {
+	const canvas = within(canvasElement);
+	await userEvent.click(await canvas.findByLabelText("Expand filters"));
+	const categories = await canvas.findByLabelText("Categories");
+	await userEvent.click(within(categories).getByRole("button", { name }));
+};
+
+const listHeader = (canvasElement: HTMLElement): HTMLElement => {
+	const title = within(canvasElement)
+		.getAllByText("Starred")
+		.find((element) => element.closest("header"));
+	const header = title?.closest("header");
+	if (!header) throw new Error("The Starred list header is not on screen");
+	return header;
+};
+
+export const Default: Story = {
+	play: async ({ canvasElement }) => {
+		const canvas = within(canvasElement);
+		await expect(await canvas.findByText("Q3 planning")).toBeVisible();
+		await expect(canvas.getByText("Conference talk outline")).toBeVisible();
+		await expect(canvas.getByText("Invoice #1042")).toBeVisible();
+		await expect(canvas.queryByText("Dinner on Saturday?")).toBeNull();
+	},
+};
+
+export const Phone: Story = {
+	globals: { viewport: { value: "mobile", isRotated: false } },
+	play: async ({ canvasElement }) => {
+		const canvas = within(canvasElement);
+		await expect(await canvas.findByText("Q3 planning")).toBeVisible();
+	},
+};
+
+export const CountUnavailable: Story = {
+	parameters: {
+		msw: { handlers: mailHandlers(world, { withholdCounts: true }) },
+	},
+	play: async ({ canvasElement }) => {
+		const canvas = within(canvasElement);
+		await canvas.findByText("Q3 planning");
+		await expect(listHeader(canvasElement).textContent).not.toMatch(/\d/);
+	},
+};
+
+export const FilteredWithResults: Story = {
+	play: async ({ canvasElement }) => {
+		const canvas = within(canvasElement);
+		await canvas.findByText("Invoice #1042");
+		await filterToCategory(canvasElement, "Personal");
+		await waitFor(() =>
+			expect(canvas.queryByText("Invoice #1042")).not.toBeInTheDocument(),
+		);
+		await expect(await canvas.findByText("Q3 planning")).toBeVisible();
+		await expect(canvas.getByText("Conference talk outline")).toBeVisible();
+	},
+};
+
+export const FilteredEmpty: Story = {
+	play: async ({ canvasElement }) => {
+		const canvas = within(canvasElement);
+		await canvas.findByText("Q3 planning");
+		await filterToCategory(canvasElement, "Newsletter");
+		await expect(
+			await canvas.findByText("Every message in this folder was checked."),
+		).toBeVisible();
+		await expect(canvas.queryByText("No messages in Starred")).toBeNull();
+	},
+};
+
+export const FilteredSearchEmpty: Story = {
+	play: async ({ canvasElement }) => {
+		const canvas = within(canvasElement);
+		await canvas.findByText("Q3 planning");
+		await filterToCategory(canvasElement, "Newsletter");
+		await canvas.findByText("Every message in this folder was checked.");
+		await userEvent.type(
+			canvas.getByLabelText("Search mail"),
+			"planning{Enter}",
+		);
+		await expect(
+			await canvas.findByText("No results for “planning” in Newsletter mail"),
+		).toBeVisible();
+		await expect(
+			canvas.getByText("Every message in this folder was checked."),
+		).toBeVisible();
+	},
+};
+
+export const FilteredWithMorePages: Story = {
+	parameters: {
+		msw: { handlers: mailHandlers(world, { pageSize: 2 }) },
+	},
+	play: async ({ canvasElement }) => {
+		const canvas = within(canvasElement);
+		await canvas.findByText("Q3 planning");
+		await filterToCategory(canvasElement, "Personal");
+		await expect(
+			await canvas.findByRole("button", { name: "Load more" }),
+		).toBeEnabled();
+	},
+};
+
+export const FilteredFetchingMore: Story = {
+	parameters: {
+		msw: {
+			handlers: mailHandlers(world, { pageSize: 2, holdLaterPages: true }),
+		},
+	},
+	play: async ({ canvasElement }) => {
+		const canvas = within(canvasElement);
+		await canvas.findByText("Q3 planning");
+		await filterToCategory(canvasElement, "Personal");
+		await userEvent.click(
+			await canvas.findByRole("button", { name: "Load more" }),
+		);
+		await expect(
+			await canvas.findByRole("button", { name: "Loading…" }),
+		).toBeDisabled();
+	},
+};
+
+export const Empty: Story = {
+	parameters: {
+		msw: {
+			handlers: mailHandlers({
+				...world,
+				threads: world.threads.filter((row) => !row.hasStars),
+			}),
+		},
+	},
+	play: async ({ canvasElement }) => {
+		const canvas = within(canvasElement);
+		await expect(
+			await canvas.findByText("No messages in Starred"),
+		).toBeVisible();
+	},
+};

package/src/components/mail/outbox.stories.tsx

@@ -0,0 +1,59 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { expect, within } from "storybook/test";
+import { AppStory } from "@/mocks/story-frame/AppStory";
+import { mailHandlers } from "@/mocks/story-frame/mail-handlers";
+import { mailWorld } from "@/mocks/story-frame/mail-world";
+
+const meta = {
+	title: "Playground/Shipped/Mail/Outbox",
+	component: AppStory,
+	args: { url: "/mail/outbox" },
+	parameters: {
+		layout: "fullscreen",
+		msw: { handlers: mailHandlers(mailWorld()) },
+	},
+} satisfies Meta<typeof AppStory>;
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const AllStatuses: Story = {
+	play: async ({ canvasElement }) => {
+		const canvas = within(canvasElement);
+		await expect(await canvas.findByText("Design review notes")).toBeVisible();
+		for (const subject of [
+			"Re: Q3 planning",
+			"Weekly update",
+			"Signed lease",
+			"Re: contract",
+		]) {
+			await expect(canvas.getByText(subject)).toBeVisible();
+		}
+		for (const error of [
+			"Sent, but not filed: this account has no Sent folder",
+			"SMTP connection timed out",
+			"No SMTP server configured for this account",
+		]) {
+			await expect(canvas.getByText(error, { exact: false })).toBeVisible();
+		}
+		await expect(canvas.queryByText("Invoice #1042")).toBeNull();
+	},
+};
+
+export const Phone: Story = {
+	globals: { viewport: { value: "mobile", isRotated: false } },
+	play: async ({ canvasElement }) => {
+		const canvas = within(canvasElement);
+		await expect(await canvas.findByText("Design review notes")).toBeVisible();
+	},
+};
+
+export const Empty: Story = {
+	parameters: {
+		msw: { handlers: mailHandlers(mailWorld({ outbox: [] })) },
+	},
+	play: async ({ canvasElement }) => {
+		const canvas = within(canvasElement);
+		await expect(await canvas.findByText("No outbox messages")).toBeVisible();
+	},
+};

package/src/hooks/useIntelligenceData.ts

@@ -118,7 +118,6 @@ function buildSenderFlags(
 		vip: address.flags.vip?.value === true,
 		muted: address.flags.muted?.value === true,
 		blocked: address.flags.blocked?.value === true,
-		unsubscribed: address.flags.unsubscribed?.value === true,
 	};
 }
 

package/src/hooks/useUpdateAddressFlags.ts

@@ -55,7 +55,7 @@ function applyFlagPatch(
 }
 
 /**
- * Optimistic PATCH for per-sender flags (VIP / Mute / Block / Unsubscribe).
+ * Optimistic PATCH for per-sender flags (VIP / Mute / Block).
  * Mirrors the `useToggleTrusted` pattern: patch the cached
  * address-search response so the toggle flips instantly, roll back on error,
  * and invalidate on settle to reconcile with the server.

package/src/mocks/story-frame/AppStory.tsx

@@ -0,0 +1,47 @@
+import {
+	MutationCache,
+	QueryCache,
+	QueryClient,
+	QueryClientProvider,
+} from "@tanstack/react-query";
+import { createMemoryHistory, RouterProvider } from "@tanstack/react-router";
+import { useState } from "react";
+import {
+	handleMutationCacheError,
+	handleQueryCacheError,
+} from "@/lib/query-error-handler";
+import { noopTelemetry } from "@/lib/telemetry";
+import { createAppRouter } from "@/router";
+import "@/lib/i18n";
+import "@/lib/client";
+
+export interface AppStoryProps {
+	url: string;
+}
+
+const createStoryQueryClient = (): QueryClient =>
+	new QueryClient({
+		queryCache: new QueryCache({ onError: handleQueryCacheError }),
+		mutationCache: new MutationCache({ onError: handleMutationCacheError }),
+		defaultOptions: {
+			queries: { staleTime: Number.POSITIVE_INFINITY, retry: false },
+			mutations: { retry: false },
+		},
+	});
+
+export function AppStory({ url }: AppStoryProps) {
+	const [queryClient] = useState(createStoryQueryClient);
+	const [router] = useState(() =>
+		createAppRouter(
+			queryClient,
+			noopTelemetry,
+			createMemoryHistory({ initialEntries: [url] }),
+		),
+	);
+
+	return (
+		<QueryClientProvider client={queryClient}>
+			<RouterProvider router={router} />
+		</QueryClientProvider>
+	);
+}

package/src/mocks/story-frame/mail-handlers.ts

@@ -0,0 +1,299 @@
+import type {
+	FilterOperationsListFiltersResponse,
+	LabelOperationsListLabelsResponse,
+	MailboxOperationsListMailboxesResponse,
+	MeOperationsListQuarantineResponse,
+	MeOperationsListVipSuggestionsResponse,
+	MessageBulkOperationsUpdateFlagsResponse,
+	MessageCalendarSuggestionOperationsListMessageCalendarSuggestionsResponse,
+	OutboxOperationsListOutboxMessagesResponse,
+	RemitImapConfigDescriptionResponse,
+	RemitImapDescribeMessageResponse,
+	RemitImapThreadMessageResponse,
+	RemitImapThreadSearchResponse,
+	SemanticSearchOperationsSemanticSearchResponse,
+	SyncOperationsGetSyncStatusResponse,
+	SyncOperationsTriggerSyncResponse,
+	SystemOperationsGetSystemUpdateResponse,
+	ThreadDetailOperationsListThreadMessagesResponse,
+	ThreadOperationsListThreadsResponse,
+} from "@remit/api-http-client/types.gen.ts";
+import { type HttpHandler, HttpResponse, http } from "msw";
+import { makeConfig } from "@/test-support/fixtures";
+import type { MailWorld } from "./mail-world";
+
+const API = "/api";
+
+export interface MailHandlerOptions {
+	withholdCounts?: boolean;
+	pageSize?: number;
+	holdLaterPages?: boolean;
+}
+
+const contentPath = (row: RemitImapThreadMessageResponse): string =>
+	`/content/accounts/${row.accountConfigId}/${row.accountId}/messages/${row.messageId}/parts/1`;
+
+const describe = (
+	row: RemitImapThreadMessageResponse,
+): RemitImapDescribeMessageResponse => ({
+	message: {
+		messageId: row.messageId,
+		mailboxId: row.mailboxId,
+		uid: 1,
+		rfc822Size: 2048,
+		internalDate: row.sentDate,
+		status: row.status,
+		syncStatus: row.syncStatus,
+		abandonedMutation: row.abandonedMutation,
+	},
+	envelope: {
+		messageId: row.messageId,
+		date: row.sentDate,
+		subject: row.subject,
+		from: [
+			{
+				addressId: `addr-${row.messageId}`,
+				displayName: row.fromName,
+				normalizedEmail: row.fromEmail ?? "",
+				addressRole: "from",
+				addressOrder: 0,
+			},
+		],
+		to: [],
+		cc: [],
+		bcc: [],
+		replyTo: [],
+		category: row.category,
+		senderTrust: row.senderTrust,
+	},
+	flags: row.isRead ? ["\\Seen"] : [],
+	bodyParts: [
+		{
+			bodyPartId: `part-${row.messageId}`,
+			mediaType: "TEXT",
+			mediaSubtype: "plain",
+			sizeOctets: (row.snippet ?? "").length,
+			isMultipart: false,
+			contentUrl: contentPath(row),
+		},
+	],
+	references: [],
+});
+
+const matchesText = (
+	row: RemitImapThreadMessageResponse,
+	needle: string,
+	fields: (keyof RemitImapThreadMessageResponse)[],
+): boolean => {
+	const lowered = needle.toLowerCase();
+	return fields.some((field) =>
+		String(row[field] ?? "")
+			.toLowerCase()
+			.includes(lowered),
+	);
+};
+
+const narrow = (
+	rows: RemitImapThreadMessageResponse[],
+	params: URLSearchParams,
+): RemitImapThreadMessageResponse[] => {
+	const categories = params.getAll("category");
+	const query = params.get("query");
+	const from = params.get("from");
+	const subject = params.get("subject");
+	const accountId = params.get("accountId");
+	const mailboxId = params.get("mailboxId");
+	return rows.filter((row) => {
+		if (params.get("starred") === "true" && !row.hasStars) return false;
+		if (params.get("unread") === "true" && row.isRead) return false;
+		if (params.get("attachments") === "true" && !row.hasAttachment)
+			return false;
+		if (categories.length > 0 && !categories.includes(row.category))
+			return false;
+		if (accountId && row.accountId !== accountId) return false;
+		if (mailboxId && row.mailboxId !== mailboxId) return false;
+		if (query && !matchesText(row, query, ["subject", "fromName", "snippet"]))
+			return false;
+		if (from && !matchesText(row, from, ["fromName", "fromEmail"]))
+			return false;
+		if (subject && !matchesText(row, subject, ["subject"])) return false;
+		return true;
+	});
+};
+
+const newestFirst = (
+	rows: RemitImapThreadMessageResponse[],
+): RemitImapThreadMessageResponse[] =>
+	[...rows].sort((a, b) => b.sentDate - a.sentDate);
+
+const listing = (
+	rows: RemitImapThreadMessageResponse[],
+	params: URLSearchParams,
+	options: MailHandlerOptions,
+): RemitImapThreadSearchResponse => {
+	const offset = Number(params.get("continuationToken") ?? 0);
+	const size = options.pageSize ?? Number(params.get("limit") ?? rows.length);
+	const next = offset + size;
+	const counted = params.get("count") === "true" && !options.withholdCounts;
+	return {
+		items:
+			params.get("results") === "false"
+				? []
+				: newestFirst(rows).slice(offset, next),
+		continuationToken:
+			options.pageSize !== undefined && next < rows.length
+				? String(next)
+				: undefined,
+		count: counted ? new Set(rows.map((row) => row.threadId)).size : undefined,
+	};
+};
+
+const pending = (): Promise<never> => new Promise<never>(() => undefined);
+
+export const mailHandlers = (
+	world: MailWorld,
+	options: MailHandlerOptions = {},
+): HttpHandler[] => {
+	const byMessageId = new Map(world.threads.map((row) => [row.messageId, row]));
+	const inboxIds = new Set(
+		world.accounts.flatMap((account) =>
+			account.folderAppointments
+				.filter((appointment) => appointment.role === "Inbox")
+				.map((appointment) => appointment.mailboxId),
+		),
+	);
+
+	return [
+		http.get(`${API}/config`, () =>
+			HttpResponse.json<RemitImapConfigDescriptionResponse>(
+				makeConfig(world.accounts),
+			),
+		),
+		http.get(`${API}/accounts/:accountId/mailboxes`, ({ params }) =>
+			HttpResponse.json<MailboxOperationsListMailboxesResponse>({
+				items: world.mailboxes.filter(
+					(mailbox) => mailbox.accountId === params.accountId,
+				),
+			}),
+		),
+		http.get(`${API}/accounts/:accountId/sync/status`, ({ params }) =>
+			HttpResponse.json<SyncOperationsGetSyncStatusResponse>({
+				accountId: String(params.accountId),
+				syncPhase: "complete",
+				mailboxes: [],
+			}),
+		),
+		http.get(`${API}/accounts/:accountId/labels`, () =>
+			HttpResponse.json<LabelOperationsListLabelsResponse>({ items: [] }),
+		),
+		http.get(`${API}/accounts/:accountId/filters`, () =>
+			HttpResponse.json<FilterOperationsListFiltersResponse>({ items: [] }),
+		),
+		http.post(`${API}/accounts/:accountId/sync`, () =>
+			HttpResponse.json<SyncOperationsTriggerSyncResponse>({
+				triggered: false,
+				message: "Already up to date",
+			}),
+		),
+		http.get(`${API}/messages/:messageId/calendar-suggestions`, () =>
+			HttpResponse.json<MessageCalendarSuggestionOperationsListMessageCalendarSuggestionsResponse>(
+				{ items: [] },
+			),
+		),
+		http.get(`${API}/messages/:messageId`, ({ params }) => {
+			const row = byMessageId.get(String(params.messageId));
+			if (!row)
+				return HttpResponse.json(
+					{ status: 404, message: "Message not found" },
+					{ status: 404 },
+				);
+			return HttpResponse.json<RemitImapDescribeMessageResponse>(describe(row));
+		}),
+		http.post(`${API}/messages/flags`, () =>
+			HttpResponse.json<MessageBulkOperationsUpdateFlagsResponse>({
+				successCount: 1,
+				failureCount: 0,
+			}),
+		),
+		http.get(
+			"/content/accounts/:accountConfigId/:accountId/messages/:messageId/parts/*",
+			({ params }) =>
+				HttpResponse.text(
+					byMessageId.get(String(params.messageId))?.snippet ?? "",
+				),
+		),
+		http.get(`${API}/threads/:threadId/messages`, ({ params }) =>
+			HttpResponse.json<ThreadDetailOperationsListThreadMessagesResponse>({
+				items: world.threads.filter((row) => row.threadId === params.threadId),
+			}),
+		),
+		http.get(`${API}/threads`, ({ request }) => {
+			const params = new URL(request.url).searchParams;
+			const searching = params.has("query");
+			const scope = world.threads.filter(
+				(row) =>
+					searching ||
+					params.get("starred") === "true" ||
+					inboxIds.has(row.mailboxId),
+			);
+			if (options.holdLaterPages && params.has("continuationToken"))
+				return pending();
+			return HttpResponse.json(listing(narrow(scope, params), params, options));
+		}),
+		http.get(
+			`${API}/mailboxes/:mailboxId/threads/search`,
+			({ request, params }) =>
+				HttpResponse.json(
+					listing(
+						narrow(
+							world.threads.filter((row) => row.mailboxId === params.mailboxId),
+							new URL(request.url).searchParams,
+						),
+						new URL(request.url).searchParams,
+						options,
+					),
+				),
+		),
+		http.get(`${API}/mailboxes/:mailboxId/threads`, ({ params }) =>
+			HttpResponse.json<ThreadOperationsListThreadsResponse>({
+				items: newestFirst(
+					world.threads.filter((row) => row.mailboxId === params.mailboxId),
+				),
+			}),
+		),
+		http.get(`${API}/outbox`, () =>
+			HttpResponse.json<OutboxOperationsListOutboxMessagesResponse>({
+				items: world.outbox,
+			}),
+		),
+		http.get(`${API}/search/semantic`, () =>
+			HttpResponse.json<SemanticSearchOperationsSemanticSearchResponse>({
+				items: [],
+			}),
+		),
+		http.get(`${API}/me/quarantine`, () =>
+			HttpResponse.json<MeOperationsListQuarantineResponse>({ entries: [] }),
+		),
+		http.get(`${API}/me/vip-suggestions`, () =>
+			HttpResponse.json<MeOperationsListVipSuggestionsResponse>({
+				suggestions: [],
+			}),
+		),
+		http.get(`${API}/system/update`, () =>
+			HttpResponse.json<SystemOperationsGetSystemUpdateResponse>({
+				currentVersion: "0.0.0-storybook",
+				check: { status: "disabled" },
+				run: null,
+			}),
+		),
+		http.all(`${API}/*`, ({ request }) =>
+			HttpResponse.json(
+				{
+					status: 501,
+					message: `No story handler for ${request.method} ${new URL(request.url).pathname}`,
+				},
+				{ status: 501 },
+			),
+		),
+	];
+};

package/src/mocks/story-frame/mail-world.ts

@@ -0,0 +1,389 @@
+import type {
+	RemitImapAccountResponse,
+	RemitImapCanonicalMailboxRole,
+	RemitImapMailboxResponse,
+	RemitImapMessageCategory,
+	RemitImapOutboxMessageResponse,
+	RemitImapOutboxMessageStatus,
+	RemitImapThreadMessageResponse,
+} from "@remit/api-http-client/types.gen.ts";
+import {
+	makeAccount,
+	makeMailbox,
+	makeThreadMessage,
+} from "@/test-support/fixtures";
+
+export interface MailWorld {
+	accounts: RemitImapAccountResponse[];
+	mailboxes: RemitImapMailboxResponse[];
+	threads: RemitImapThreadMessageResponse[];
+	outbox: RemitImapOutboxMessageResponse[];
+}
+
+const MINUTE = 60_000;
+const HOUR = 60 * MINUTE;
+const DAY = 24 * HOUR;
+const NOW = Date.UTC(2026, 8, 24, 13, 0);
+
+const ROLES = [
+	"Inbox",
+	"Drafts",
+	"Sent",
+	"Archive",
+	"Junk",
+	"Trash",
+] as const satisfies readonly RemitImapCanonicalMailboxRole[];
+
+const FOLDER_PATHS: Record<(typeof ROLES)[number], string> = {
+	Inbox: "INBOX",
+	Drafts: "Drafts",
+	Sent: "Sent",
+	Archive: "Archive",
+	Junk: "Junk",
+	Trash: "Trash",
+};
+
+export const mailboxIdFor = (
+	accountId: string,
+	role: RemitImapCanonicalMailboxRole,
+): string => `mbx-${accountId}-${role.toLowerCase()}`;
+
+const accountWithFolders = (
+	accountId: string,
+	email: string,
+	displayName: string,
+): RemitImapAccountResponse =>
+	makeAccount({
+		accountId,
+		email,
+		username: email,
+		smtpUsername: email,
+		displayName,
+		lastSyncAt: NOW,
+		folderAppointments: ROLES.map((role) => ({
+			role,
+			source: "Appointed",
+			mailboxId: mailboxIdFor(accountId, role),
+		})),
+	});
+
+const foldersOf = (accountId: string): RemitImapMailboxResponse[] =>
+	ROLES.map((role) =>
+		makeMailbox({
+			accountId,
+			mailboxId: mailboxIdFor(accountId, role),
+			fullPath: FOLDER_PATHS[role],
+			specialUse: role === "Inbox" ? undefined : [role],
+		}),
+	);
+
+export const PERSONAL = "acc-personal";
+export const WORK = "acc-work";
+
+const accounts = [
+	accountWithFolders(PERSONAL, "alice@example.com", "Personal"),
+	accountWithFolders(WORK, "alice.tan@acme.example", "Work"),
+];
+
+interface ThreadSeed {
+	id: string;
+	accountId: string;
+	role?: RemitImapCanonicalMailboxRole;
+	fromName: string;
+	fromEmail: string;
+	subject: string;
+	snippet: string;
+	category: RemitImapMessageCategory;
+	ago: number;
+	isRead?: boolean;
+	starred?: boolean;
+	hasAttachment?: boolean;
+}
+
+const thread = (seed: ThreadSeed): RemitImapThreadMessageResponse =>
+	makeThreadMessage({
+		messageId: `msg-${seed.id}`,
+		threadId: `thread-${seed.id}`,
+		threadMessageId: `tm-${seed.id}`,
+		accountId: seed.accountId,
+		mailboxId: mailboxIdFor(seed.accountId, seed.role ?? "Inbox"),
+		fromName: seed.fromName,
+		fromEmail: seed.fromEmail,
+		subject: seed.subject,
+		snippet: seed.snippet,
+		category: seed.category,
+		sentDate: NOW - seed.ago,
+		isRead: seed.isRead ?? false,
+		hasAttachment: seed.hasAttachment ?? false,
+		star: seed.starred ? "yellow" : "none",
+		hasStars: seed.starred ?? false,
+		syncStatus: "synced",
+	});
+
+const inboxThreads: RemitImapThreadMessageResponse[] = [
+	thread({
+		id: "q3-planning",
+		accountId: WORK,
+		fromName: "Ada Lovelace",
+		fromEmail: "ada@acme.example",
+		subject: "Q3 planning",
+		snippet: "Can we move the review to Thursday? I have the numbers ready.",
+		category: "personal",
+		ago: 20 * MINUTE,
+		starred: true,
+	}),
+	thread({
+		id: "lease",
+		accountId: PERSONAL,
+		fromName: "Amara Okafor",
+		fromEmail: "amara@example.org",
+		subject: "Signed lease attached",
+		snippet: "Here is the countersigned copy for your records.",
+		category: "personal",
+		ago: 2 * HOUR,
+		hasAttachment: true,
+		starred: true,
+	}),
+	thread({
+		id: "dinner",
+		accountId: PERSONAL,
+		fromName: "Grace Hopper",
+		fromEmail: "grace@example.org",
+		subject: "Dinner on Saturday?",
+		snippet: "We are thinking the new place on the corner, around seven.",
+		category: "personal",
+		ago: 5 * HOUR,
+		isRead: true,
+	}),
+	thread({
+		id: "invoice",
+		accountId: WORK,
+		fromName: "Billing",
+		fromEmail: "billing@saas.example",
+		subject: "Invoice #1042",
+		snippet: "Your invoice for September is ready.",
+		category: "transactional",
+		ago: 7 * HOUR,
+		isRead: true,
+		starred: true,
+	}),
+	thread({
+		id: "shipping",
+		accountId: PERSONAL,
+		fromName: "Parcel Service",
+		fromEmail: "track@parcel.example",
+		subject: "Your order has shipped",
+		snippet: "Estimated delivery: tomorrow before noon.",
+		category: "transactional",
+		ago: 9 * HOUR,
+	}),
+	thread({
+		id: "weekly-digest",
+		accountId: PERSONAL,
+		fromName: "The Weekly",
+		fromEmail: "digest@weekly.example",
+		subject: "This week in type systems",
+		snippet: "Variance, soundness and a long read on gradual typing.",
+		category: "newsletter",
+		ago: DAY,
+	}),
+	thread({
+		id: "sale",
+		accountId: PERSONAL,
+		fromName: "Outdoor Store",
+		fromEmail: "news@outdoor.example",
+		subject: "Autumn sale starts now",
+		snippet: "Up to 40% off jackets and boots this weekend only.",
+		category: "marketing",
+		ago: DAY + 3 * HOUR,
+	}),
+	thread({
+		id: "mention",
+		accountId: WORK,
+		fromName: "Chat",
+		fromEmail: "notifications@chat.example",
+		subject: "Linus mentioned you in #design",
+		snippet: "Linus: can you take a look at the new header?",
+		category: "social",
+		ago: DAY + 5 * HOUR,
+	}),
+	thread({
+		id: "build",
+		accountId: WORK,
+		fromName: "CI",
+		fromEmail: "ci@builds.example",
+		subject: "Build passed on main",
+		snippet: "All 212 checks passed in 6m 12s.",
+		category: "automated",
+		ago: 2 * DAY,
+		isRead: true,
+	}),
+	thread({
+		id: "talk-outline",
+		accountId: PERSONAL,
+		role: "Archive",
+		fromName: "Ken Thompson",
+		fromEmail: "ken@example.org",
+		subject: "Conference talk outline",
+		snippet: "Here is the rough structure for the keynote.",
+		category: "personal",
+		ago: 3 * DAY,
+		isRead: true,
+		starred: true,
+	}),
+];
+
+const serverDrafts: RemitImapThreadMessageResponse[] = [
+	thread({
+		id: "draft-talk",
+		accountId: PERSONAL,
+		role: "Drafts",
+		fromName: "Alice",
+		fromEmail: "alice@example.com",
+		subject: "Re: Conference talk outline",
+		snippet: "Thanks Ken, I will send slides by Friday.",
+		category: "personal",
+		ago: 4 * HOUR,
+		isRead: true,
+	}),
+];
+
+interface OutboxSeed {
+	id: string;
+	accountId: string;
+	to: string;
+	subject: string;
+	body: string;
+	status: RemitImapOutboxMessageStatus;
+	ago: number;
+	lastError?: string;
+}
+
+export const outboxMessage = (
+	seed: OutboxSeed,
+): RemitImapOutboxMessageResponse => {
+	const from = accounts.find((account) => account.accountId === seed.accountId);
+	return {
+		outboxMessageId: `out-${seed.id}`,
+		accountId: seed.accountId,
+		fromAddress: from?.email ?? "alice@example.com",
+		fromName: "Alice",
+		toAddresses: [seed.to],
+		ccAddresses: [],
+		bccAddresses: [],
+		subject: seed.subject,
+		references: [],
+		textBody: seed.body,
+		status: seed.status,
+		lastError: seed.lastError,
+		sentAt: seed.status === "sent" ? NOW - seed.ago : undefined,
+		createdAt: NOW - seed.ago,
+		updatedAt: NOW - seed.ago,
+		attachments: [],
+	};
+};
+
+const remitDrafts: RemitImapOutboxMessageResponse[] = [
+	outboxMessage({
+		id: "draft-q3",
+		accountId: PERSONAL,
+		to: "ada@acme.example",
+		subject: "Re: Q3 planning",
+		body: "Thanks, Thursday works for me.",
+		status: "draft",
+		ago: 10 * MINUTE,
+	}),
+	outboxMessage({
+		id: "draft-untitled",
+		accountId: PERSONAL,
+		to: "team@example.com",
+		subject: "",
+		body: "",
+		status: "draft",
+		ago: HOUR,
+	}),
+];
+
+export const outboxInEveryStatus: RemitImapOutboxMessageResponse[] = [
+	outboxMessage({
+		id: "queued",
+		accountId: WORK,
+		to: "ada@acme.example",
+		subject: "Re: Q3 planning",
+		body: "Thursday it is.",
+		status: "queued",
+		ago: 2 * MINUTE,
+	}),
+	outboxMessage({
+		id: "sending",
+		accountId: WORK,
+		to: "team@acme.example",
+		subject: "Weekly update",
+		body: "Highlights from this week.",
+		status: "sending",
+		ago: 3 * MINUTE,
+	}),
+	outboxMessage({
+		id: "sent",
+		accountId: WORK,
+		to: "grace@example.org",
+		subject: "Invoice #1042",
+		body: "Paid, thanks.",
+		status: "sent",
+		ago: 16 * MINUTE,
+	}),
+	outboxMessage({
+		id: "unfiled",
+		accountId: PERSONAL,
+		to: "amara@example.org",
+		subject: "Signed lease",
+		body: "Signed and attached.",
+		status: "unfiled",
+		ago: 22 * MINUTE,
+		lastError: "Sent, but not filed: this account has no Sent folder",
+	}),
+	outboxMessage({
+		id: "failed",
+		accountId: WORK,
+		to: "linus@example.org",
+		subject: "Design review notes",
+		body: "Notes from today.",
+		status: "failed",
+		ago: 34 * MINUTE,
+		lastError: "SMTP connection timed out",
+	}),
+	outboxMessage({
+		id: "blocked",
+		accountId: PERSONAL,
+		to: "ken@example.org",
+		subject: "Re: contract",
+		body: "Looks good to me.",
+		status: "blocked",
+		ago: DAY,
+		lastError: "No SMTP server configured for this account",
+	}),
+];
+
+export const newsletterBacklog = (
+	count: number,
+): RemitImapThreadMessageResponse[] =>
+	Array.from({ length: count }, (_, index) =>
+		thread({
+			id: `digest-${index}`,
+			accountId: PERSONAL,
+			fromName: "The Weekly",
+			fromEmail: "digest@weekly.example",
+			subject: `Issue ${index + 1}: notes from the field`,
+			snippet: "Three long reads and a short one.",
+			category: "newsletter",
+			ago: 2 * DAY + index * HOUR,
+		}),
+	);
+
+export const mailWorld = (overrides: Partial<MailWorld> = {}): MailWorld => ({
+	accounts,
+	mailboxes: accounts.flatMap((account) => foldersOf(account.accountId)),
+	threads: [...inboxThreads, ...serverDrafts],
+	outbox: [...remitDrafts, ...outboxInEveryStatus],
+	...overrides,
+});

package/src/mocks/story-frame/touch.ts

@@ -0,0 +1,21 @@
+const HOLD_MS = 700;
+
+const touch = (target: HTMLElement, type: string) => {
+	const { left, top } = target.getBoundingClientRect();
+	target.dispatchEvent(
+		new PointerEvent(type, {
+			bubbles: true,
+			pointerType: "touch",
+			pointerId: 1,
+			isPrimary: true,
+			clientX: left + 20,
+			clientY: top + 10,
+		}),
+	);
+};
+
+export const longPress = async (target: HTMLElement): Promise<void> => {
+	touch(target, "pointerdown");
+	await new Promise((resolve) => setTimeout(resolve, HOLD_MS));
+	touch(target, "pointerup");
+};

package/src/router.tsx

@@ -1,5 +1,5 @@
 import type { QueryClient } from "@tanstack/react-query";
-import { createRouter } from "@tanstack/react-router";
+import { createRouter, type RouterHistory } from "@tanstack/react-router";
 import { AppShellSkeleton } from "./components/layout/AppShellSkeleton";
 import { recordRoute } from "./lib/route-breadcrumbs";
 import { stringifySearch } from "./lib/search-params";
@@ -13,10 +13,12 @@ export interface RouterContext {
 export const createAppRouter = (
 	queryClient: QueryClient,
 	telemetry: Telemetry,
+	history?: RouterHistory,
 ) => {
 	const router = createRouter({
 		routeTree,
 		context: { queryClient },
+		history,
 		// A query param that carries a list writes one param per value
 		// (`lib/search-params.ts`), which is what the router's own reader already
 		// expects and what a hand-written link says.