@remit/web-client 0.0.1

package/src/lib/keymap.test.ts

@@ -0,0 +1,49 @@
+import assert from "node:assert";
+import { describe, test } from "node:test";
+import { KEY_HINT_GROUPS, keysForAction, tooltipForAction } from "./keymap.ts";
+
+describe("keymap module", () => {
+	test("exposes the documented groups in reading order", () => {
+		const titles = KEY_HINT_GROUPS.map((g) => g.title);
+		assert.deepStrictEqual(titles, [
+			"Navigation",
+			"Selection",
+			"Actions",
+			"Sender",
+			"Go to",
+			"View & global",
+		]);
+	});
+
+	test("keysForAction returns the first hint's tokens", () => {
+		assert.deepStrictEqual(keysForAction("reply"), ["r"]);
+		assert.deepStrictEqual(keysForAction("goBrief"), ["g", "b"]);
+	});
+
+	test("keysForAction is undefined for an action with no hint", () => {
+		// `back` has a hint; a contrived missing lookup returns undefined.
+		assert.strictEqual(
+			keysForAction("totallyMissing" as Parameters<typeof keysForAction>[0]),
+			undefined,
+		);
+	});
+
+	test("tooltipForAction renders single keys, sequences and combos", () => {
+		assert.strictEqual(tooltipForAction("reply"), "(r)");
+		assert.strictEqual(tooltipForAction("goBrief"), "(g then b)");
+		// compose's first hint is the single 'c' key.
+		assert.strictEqual(tooltipForAction("compose"), "(c)");
+	});
+
+	test("every hint's action is a non-empty key list", () => {
+		for (const group of KEY_HINT_GROUPS) {
+			for (const hint of group.hints) {
+				assert.ok(hint.keys.length > 0, `${hint.action} has keys`);
+				assert.ok(
+					hint.description.length > 0,
+					`${hint.action} has a description`,
+				);
+			}
+		}
+	});
+});

package/src/lib/keymap.ts

@@ -0,0 +1,178 @@
+/**
+ * Single source of truth for the global keyboard triage layer (#429).
+ *
+ * Every shortcut the app responds to is declared here once. The help overlay
+ * (`KeyboardShortcutsModal`), the list footer hints and the toolbar tooltips
+ * all read from this module so the displayed bindings can never drift from the
+ * keys the dispatcher actually routes. The spec lives in
+ * `doc/design/flows/04-triage.md`.
+ */
+
+/** A logical action a key (or key sequence) maps to. */
+export type TriageAction =
+	// list navigation / focus model
+	| "focusNext"
+	| "focusPrevious"
+	| "openFocused"
+	| "back"
+	// selection
+	| "toggleSelect"
+	| "extendSelectDown"
+	| "extendSelectUp"
+	// message verbs (focused row / selection)
+	| "reply"
+	| "replyAll"
+	| "forward"
+	| "delete"
+	| "toggleStar"
+	| "toggleRead"
+	// sender verbs
+	| "muteSender"
+	| "blockSender"
+	| "vipSender"
+	| "markJunk"
+	// view
+	| "toggleIntelligence"
+	| "toggleDensity"
+	// global
+	| "focusSearch"
+	| "compose"
+	| "help"
+	// go-to sequences (g then …)
+	| "goBrief"
+	| "goInbox"
+	| "goSent"
+	| "goFlagged"
+	| "goSettings";
+
+/**
+ * One displayed binding row in the help overlay. `keys` is the human-readable
+ * sequence (e.g. ["g", "b"] or ["⌘", "N"]); `display` overrides the rendered
+ * label when a single token reads better (e.g. "Esc", "↵").
+ */
+export interface KeyHint {
+	action: TriageAction;
+	/** Tokens rendered as individual <Kbd> chips, in order. */
+	keys: string[];
+	description: string;
+}
+
+export interface KeyHintGroup {
+	title: string;
+	hints: KeyHint[];
+}
+
+/**
+ * The full key map, grouped by area, exactly as it appears in the `?` overlay.
+ * Order is intentional (matches 04-triage.md reading order).
+ */
+export const KEY_HINT_GROUPS: KeyHintGroup[] = [
+	{
+		title: "Navigation",
+		hints: [
+			{ action: "focusNext", keys: ["j"], description: "Focus next message" },
+			{
+				action: "focusPrevious",
+				keys: ["k"],
+				description: "Focus previous message",
+			},
+			{
+				action: "openFocused",
+				keys: ["Enter"],
+				description: "Open focused thread",
+			},
+			{ action: "back", keys: ["Esc"], description: "Back / close overlay" },
+		],
+	},
+	{
+		title: "Selection",
+		hints: [
+			{ action: "toggleSelect", keys: ["x"], description: "Toggle select" },
+			{
+				action: "extendSelectDown",
+				keys: ["Shift", "j"],
+				description: "Extend selection down",
+			},
+			{
+				action: "extendSelectUp",
+				keys: ["Shift", "k"],
+				description: "Extend selection up",
+			},
+		],
+	},
+	{
+		title: "Actions",
+		hints: [
+			{ action: "reply", keys: ["r"], description: "Reply" },
+			{ action: "replyAll", keys: ["a"], description: "Reply all" },
+			{ action: "forward", keys: ["f"], description: "Forward" },
+			{ action: "delete", keys: ["#"], description: "Delete" },
+			{ action: "toggleStar", keys: ["s"], description: "Star / unstar" },
+			{
+				action: "toggleRead",
+				keys: ["u"],
+				description: "Toggle read / unread",
+			},
+		],
+	},
+	{
+		title: "Sender",
+		hints: [
+			{ action: "muteSender", keys: ["m"], description: "Mute sender" },
+			{ action: "blockSender", keys: ["b"], description: "Block sender" },
+			{ action: "vipSender", keys: ["v"], description: "VIP sender" },
+			{ action: "markJunk", keys: ["!"], description: "Mark junk" },
+		],
+	},
+	{
+		title: "Go to",
+		hints: [
+			{ action: "goBrief", keys: ["g", "b"], description: "Daily brief" },
+			{ action: "goInbox", keys: ["g", "i"], description: "Inbox" },
+			{ action: "goSent", keys: ["g", "s"], description: "Sent" },
+			{ action: "goFlagged", keys: ["g", "f"], description: "Flagged" },
+			{ action: "goSettings", keys: ["g", ","], description: "Settings" },
+		],
+	},
+	{
+		title: "View & global",
+		hints: [
+			{
+				action: "toggleIntelligence",
+				keys: ["i"],
+				description: "Toggle intelligence",
+			},
+			{ action: "toggleDensity", keys: ["d"], description: "Toggle density" },
+			{ action: "focusSearch", keys: ["/"], description: "Focus search" },
+			{ action: "compose", keys: ["c"], description: "Compose" },
+			{ action: "compose", keys: ["⌘", "N"], description: "Compose" },
+			{ action: "help", keys: ["?"], description: "Shortcut help" },
+		],
+	},
+];
+
+/**
+ * Look up the displayed key tokens for an action (first matching hint). Used by
+ * toolbar tooltips so a single declaration drives both the overlay and the
+ * button titles. Returns `undefined` for actions with no hint.
+ */
+export function keysForAction(action: TriageAction): string[] | undefined {
+	for (const group of KEY_HINT_GROUPS) {
+		const hint = group.hints.find((h) => h.action === action);
+		if (hint) return hint.keys;
+	}
+	return undefined;
+}
+
+/**
+ * Render an action's binding as a compact tooltip suffix, e.g. "(r)" or
+ * "(g then b)". Returns "" when the action has no hint.
+ */
+export function tooltipForAction(action: TriageAction): string {
+	const keys = keysForAction(action);
+	if (!keys || keys.length === 0) return "";
+	if (keys.length === 1) return `(${keys[0]})`;
+	// Sequence (go-to) keys read as "g then b"; modifier combos as "⌘N".
+	if (keys[0] === "g") return `(${keys.join(" then ")})`;
+	return `(${keys.join("")})`;
+}

package/src/lib/mail-context.ts

@@ -0,0 +1,64 @@
+import type { RemitImapAccountResponse } from "@remit/api-http-client/types.gen.ts";
+import { createContext, useContext } from "react";
+
+/**
+ * Shared mail-layout context. Lives in `lib/` — NOT in `routes/mail.tsx` — on
+ * purpose: the generated route tree imports the mail route via a relative
+ * specifier (`./routes/mail`) while feature code imports via the `@/` alias.
+ * Vite can resolve those to two distinct module instances, which would give the
+ * `MailLayout` provider and a child-route consumer two different `MailContext`
+ * objects — the consumer then silently falls back to the defaults below (this
+ * bit the intelligence toggle: clicks reached a no-op handler). Keeping the
+ * context in a module that is only ever imported through the `@/` alias
+ * guarantees a single instance shared by provider and consumers.
+ */
+export interface MailContextValue {
+	accounts: RemitImapAccountResponse[];
+	/**
+	 * Name indexes `parseSearchTokens` resolves `in:`/`account:` chips against
+	 * (#428 follow-up). Computed once here so every consumer — chip rendering,
+	 * the brief/flagged token filters, `useSemanticSearch` — agrees on the same
+	 * resolution. See `lib/search-token-index.ts`.
+	 */
+	mailboxNameIndex: ReadonlyMap<string, string>;
+	accountNameIndex: ReadonlyMap<string, string>;
+	searchQuery: string;
+	/** Live (pre-debounce) search input — the toolbar's search field binds this. */
+	searchInput: string;
+	onSearchChange: (query: string) => void;
+	/** Full clear (X button): drops the query and any selected thread (#538). */
+	onSearchClear: () => void;
+	/** Query-only clear (Esc): drops the query, keeps the thread open (#489). */
+	onSearchClearQuery: () => void;
+	/** Pane 4 (intelligence) visibility. The shared toggle starts closed; the
+	 *  desktop route opens it by default with the thread, honouring the stored
+	 *  preference (#782). */
+	intelligenceOpen: boolean;
+	onToggleIntelligence: () => void;
+	/** Set the pane open/closed and persist the choice (desktop default-open). */
+	onSetIntelligenceOpen: (open: boolean) => void;
+}
+
+export const MailContext = createContext<MailContextValue | null>(null);
+
+export const useMailContext = (): MailContextValue => {
+	const context = useContext(MailContext);
+	// Return default values if context not yet available (e.g., during loading)
+	// This can happen when TanStack Router renders child routes before parent
+	// finishes.
+	return (
+		context ?? {
+			accounts: [],
+			mailboxNameIndex: new Map(),
+			accountNameIndex: new Map(),
+			searchQuery: "",
+			searchInput: "",
+			onSearchChange: () => {},
+			onSearchClear: () => {},
+			onSearchClearQuery: () => {},
+			intelligenceOpen: false,
+			onToggleIntelligence: () => {},
+			onSetIntelligenceOpen: () => {},
+		}
+	);
+};

package/src/lib/mail-route.test.ts

@@ -0,0 +1,80 @@
+/**
+ * Regression: the /mail shell must mount the MAILBOX pane (MessageList →
+ * SwipeableMessageRow → `a[href*=selectedMessageId]`) on /mail/$mailboxId,
+ * NOT the brief pane. The first slotted-shell cut keyed brief detection off
+ * the parent /mail layout's matched pathname ("/mail"), which is present on
+ * EVERY child route — so every mailbox rendered the unified DailyBrief and
+ * the message-row anchors disappeared (e2e sync-flow + smoke both failed on
+ * `a[href*='selectedMessageId']`). These tests pin detection to each leaf
+ * route's own routeId so that can't regress.
+ */
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import {
+	isBriefRoute,
+	isFlaggedRoute,
+	isMailboxRoute,
+	isOutboxRoute,
+	type MailRouteMatch,
+} from "./mail-route.js";
+
+/** Matches as TanStack Router reports them: parent /mail layout + the leaf. */
+const briefMatches: MailRouteMatch[] = [
+	{ routeId: "__root__" },
+	{ routeId: "/mail" },
+	{ routeId: "/mail/" },
+];
+const mailboxMatches: MailRouteMatch[] = [
+	{ routeId: "__root__" },
+	{ routeId: "/mail" },
+	{ routeId: "/mail/$mailboxId" },
+];
+const outboxMatches: MailRouteMatch[] = [
+	{ routeId: "__root__" },
+	{ routeId: "/mail" },
+	{ routeId: "/mail/outbox" },
+];
+const flaggedMatches: MailRouteMatch[] = [
+	{ routeId: "__root__" },
+	{ routeId: "/mail" },
+	{ routeId: "/mail/flagged" },
+];
+
+describe("mail route pane detection", () => {
+	it("classifies the brief index route as brief only", () => {
+		assert.equal(isBriefRoute(briefMatches), true);
+		assert.equal(isMailboxRoute(briefMatches), false);
+		assert.equal(isOutboxRoute(briefMatches), false);
+	});
+
+	it("classifies a mailbox route as mailbox, NOT brief (the regression)", () => {
+		// The bug: the parent /mail layout match made isBriefRoute true here,
+		// routing the mailbox through the brief pane and dropping message rows.
+		assert.equal(isBriefRoute(mailboxMatches), false);
+		assert.equal(isMailboxRoute(mailboxMatches), true);
+		assert.equal(isOutboxRoute(mailboxMatches), false);
+	});
+
+	it("classifies the outbox route as outbox only", () => {
+		assert.equal(isBriefRoute(outboxMatches), false);
+		assert.equal(isMailboxRoute(outboxMatches), false);
+		assert.equal(isOutboxRoute(outboxMatches), true);
+	});
+
+	it("classifies the flagged route as flagged only", () => {
+		assert.equal(isFlaggedRoute(flaggedMatches), true);
+		assert.equal(isBriefRoute(flaggedMatches), false);
+		assert.equal(isMailboxRoute(flaggedMatches), false);
+		assert.equal(isOutboxRoute(flaggedMatches), false);
+	});
+
+	it("never treats the parent /mail layout match as the brief route", () => {
+		// Every child route carries the parent /mail layout match. Brief
+		// detection must ignore it entirely.
+		const parentOnly: MailRouteMatch[] = [
+			{ routeId: "__root__" },
+			{ routeId: "/mail" },
+		];
+		assert.equal(isBriefRoute(parentOnly), false);
+	});
+});

package/src/lib/mail-route.ts

@@ -0,0 +1,44 @@
+/**
+ * Route detection for the /mail shell.
+ *
+ * `mail.tsx` mounts the right pane (brief, mailbox, or outbox) into
+ * `AppShellSlotted` by inspecting the router's matched routes. The parent
+ * `/mail` layout route is matched on EVERY child route, and its matched
+ * `pathname` is "/mail" everywhere — so detection MUST key off each leaf
+ * route's own `routeId`, never the parent pathname. Keying off "/mail"
+ * pathname routed every mailbox through the brief pane, which renders the
+ * unified DailyBrief instead of the mailbox MessageList — so the message
+ * rows (the `a[href*=selectedMessageId]` anchors) vanished. These pure
+ * predicates pin that contract.
+ */
+
+/** A matched route, minimal shape needed for pane detection. */
+export interface MailRouteMatch {
+	routeId: string;
+}
+
+/** The leaf route ids the /mail shell branches on. */
+export const MAIL_BRIEF_ROUTE_ID = "/mail/" as const;
+export const MAIL_MAILBOX_ROUTE_ID = "/mail/$mailboxId" as const;
+export const MAIL_OUTBOX_ROUTE_ID = "/mail/outbox" as const;
+export const MAIL_FLAGGED_ROUTE_ID = "/mail/flagged" as const;
+
+/** True only on the brief index route (/mail/), never on a mailbox/outbox. */
+export function isBriefRoute(matches: readonly MailRouteMatch[]): boolean {
+	return matches.some((m) => m.routeId === MAIL_BRIEF_ROUTE_ID);
+}
+
+/** True only on the flagged virtual-mailbox route (/mail/flagged). */
+export function isFlaggedRoute(matches: readonly MailRouteMatch[]): boolean {
+	return matches.some((m) => m.routeId === MAIL_FLAGGED_ROUTE_ID);
+}
+
+/** True only on the outbox route. */
+export function isOutboxRoute(matches: readonly MailRouteMatch[]): boolean {
+	return matches.some((m) => m.routeId === MAIL_OUTBOX_ROUTE_ID);
+}
+
+/** True only on a mailbox route (/mail/$mailboxId). */
+export function isMailboxRoute(matches: readonly MailRouteMatch[]): boolean {
+	return matches.some((m) => m.routeId === MAIL_MAILBOX_ROUTE_ID);
+}

package/src/lib/message-body-source.test.ts

@@ -0,0 +1,98 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import {
+	pickRenderablePart,
+	type RenderableBodyPart,
+} from "./message-body-source";
+
+const make = (overrides: Partial<RenderableBodyPart>): RenderableBodyPart => ({
+	mediaType: "TEXT",
+	mediaSubtype: "PLAIN",
+	contentUrl: "https://cdn.test/content/x",
+	isMultipart: false,
+	...overrides,
+});
+
+describe("pickRenderablePart", () => {
+	it("prefers the first text/html part over text/plain", () => {
+		const html = make({
+			mediaSubtype: "HTML",
+			contentUrl: "https://cdn.test/html",
+		});
+		const text = make({
+			mediaSubtype: "PLAIN",
+			contentUrl: "https://cdn.test/text",
+		});
+		const picked = pickRenderablePart([text, html]);
+		assert.deepEqual(picked, {
+			kind: "html",
+			contentUrl: "https://cdn.test/html",
+		});
+	});
+
+	it("falls back to text/plain when no html part exists", () => {
+		const text = make({
+			mediaSubtype: "PLAIN",
+			contentUrl: "https://cdn.test/text",
+		});
+		const picked = pickRenderablePart([text]);
+		assert.deepEqual(picked, {
+			kind: "text",
+			contentUrl: "https://cdn.test/text",
+		});
+	});
+
+	it("ignores multipart container rows", () => {
+		const container = make({
+			mediaType: "MULTIPART",
+			mediaSubtype: "ALTERNATIVE",
+			isMultipart: true,
+		});
+		const text = make({ mediaSubtype: "PLAIN" });
+		const picked = pickRenderablePart([container, text]);
+		assert.equal(picked?.kind, "text");
+	});
+
+	it("ignores attachment-disposition parts so a PDF doesn't shadow the body", () => {
+		const attachment = make({
+			mediaSubtype: "HTML",
+			disposition: "attachment",
+			contentUrl: "https://cdn.test/attachment.html",
+		});
+		const text = make({
+			mediaSubtype: "PLAIN",
+			contentUrl: "https://cdn.test/text",
+		});
+		const picked = pickRenderablePart([attachment, text]);
+		assert.deepEqual(picked, {
+			kind: "text",
+			contentUrl: "https://cdn.test/text",
+		});
+	});
+
+	it("returns null when nothing renderable is present", () => {
+		const image = make({ mediaType: "IMAGE", mediaSubtype: "PNG" });
+		assert.equal(pickRenderablePart([image]), null);
+	});
+
+	it("returns null on an empty list", () => {
+		assert.equal(pickRenderablePart([]), null);
+	});
+
+	it("treats casing variants of the subtype as equivalent (mailers are inconsistent)", () => {
+		const html = make({
+			mediaSubtype: "html",
+			contentUrl: "https://cdn.test/lower",
+		});
+		const picked = pickRenderablePart([html]);
+		assert.deepEqual(picked, {
+			kind: "html",
+			contentUrl: "https://cdn.test/lower",
+		});
+	});
+
+	it("skips parts with an empty contentUrl so the fetch never fires against the API root", () => {
+		const broken = make({ mediaSubtype: "HTML", contentUrl: "" });
+		assert.equal(pickRenderablePart([broken]), null);
+	});
+});

package/src/lib/message-body-source.ts

@@ -0,0 +1,48 @@
+/**
+ * Pick the renderable body part from a `describeMessage` BodyPartResponse list
+ * and fetch its content via CloudFront. The legacy inlined `bodyText` /
+ * `bodyHtml` fields were removed in #224 PR 3 — body content lives at the
+ * per-part `contentUrl`, JWT-authorized at the edge.
+ *
+ * Pure helpers (no React) so they can be unit-tested against the generated
+ * type without standing up jsdom or DOMPurify.
+ */
+
+export type BodyContentKind = "html" | "text";
+
+export interface RenderableBodyPart {
+	mediaType: string;
+	mediaSubtype: string;
+	disposition?: string;
+	contentUrl: string;
+	isMultipart: boolean;
+}
+
+export interface PickedBodyPart {
+	kind: BodyContentKind;
+	contentUrl: string;
+}
+
+/**
+ * Pick the best body part to render: prefer the first inline `text/html`,
+ * fall back to the first inline `text/plain`. Multipart container rows and
+ * attachment-disposition parts are ignored — they carry no renderable
+ * payload at this position. Returns `null` when nothing renderable is
+ * available so callers can show an empty-body affordance.
+ */
+export const pickRenderablePart = (
+	parts: readonly RenderableBodyPart[],
+): PickedBodyPart | null => {
+	const renderable = parts.filter(
+		(p) =>
+			!p.isMultipart &&
+			p.disposition !== "attachment" &&
+			p.mediaType === "TEXT" &&
+			p.contentUrl.length > 0,
+	);
+	const html = renderable.find((p) => p.mediaSubtype.toUpperCase() === "HTML");
+	if (html) return { kind: "html", contentUrl: html.contentUrl };
+	const text = renderable.find((p) => p.mediaSubtype.toUpperCase() === "PLAIN");
+	if (text) return { kind: "text", contentUrl: text.contentUrl };
+	return null;
+};