@remit/ui 0.0.1

package/src/components/message-body-view.stories.tsx

@@ -0,0 +1,146 @@
+import type { Decorator, Meta, StoryObj } from "@storybook/react-vite";
+import { MessageBodyView } from "./message-body-view.js";
+
+/**
+ * `MessageBodyView` is the single source of truth for rendering an email body:
+ * it sanitizes the raw HTML (DOMPurify + privacy/XSS scrubbing), classifies it
+ * as framed (designed mail) or plain (theme-aware), and hands the result to the
+ * sandboxed `IsolatedEmailFrame`. The app's `MessageBody` and the kit reading
+ * panes both compose it, so Storybook renders email exactly as the app does
+ * (#940) — sandbox, flush layout and #727 scale-to-fit all visible.
+ *
+ * Unlike the `IsolatedEmailFrame` stories, these fixtures pass RAW author HTML:
+ * the component runs the real sanitizer, so the layout-clamp `<style>` and the
+ * image-blocking are produced here, not hand-prepended.
+ */
+
+const NODE_WEEKLY = `
+<table width="600" cellpadding="0" cellspacing="0" style="margin:0 auto;border-collapse:collapse;">
+	<tr>
+		<td width="600" style="width:600px;min-width:600px;background:#83cd29;padding:24px;font-family:Helvetica,Arial,sans-serif;color:#ffffff;">
+			<h1 style="margin:0;font-size:26px;">Node Weekly</h1>
+			<p style="margin:4px 0 0;font-size:14px;">Issue 540 — June 18, 2026</p>
+		</td>
+	</tr>
+	<tr>
+		<td width="600" style="width:600px;padding:24px;font-family:Georgia,serif;color:#1a1a1a;">
+			<h2 style="font-size:18px;color:#111;">Node.js 24 hits LTS</h2>
+			<p>The release line is now Active LTS. The permission model graduated
+			from experimental, and the built-in test runner picked up snapshot
+			testing — all without a single dependency.</p>
+			<p><a href="https://example.com/issue/540" style="color:#43853d;">Read the full issue &rarr;</a></p>
+		</td>
+	</tr>
+</table>
+`;
+
+const PLAIN = `
+<div style="color:#000">
+	<p>Hi there,</p>
+	<p>Just confirming our call for tomorrow at 10am. Let me know if that still
+	works for you.</p>
+	<p>Thanks,<br>Alex</p>
+</div>
+`;
+
+// Marketing mail with two remote images — with images blocked the sanitizer
+// swaps them for placeholders and the privacy notice slot reports the count.
+const WITH_REMOTE_IMAGES = `
+<div style="font-family: Helvetica, Arial, sans-serif; background:#ffffff; color:#1a1a1a; padding:20px;">
+	<img src="https://tracker.example/hero.png" alt="Hero" width="560" />
+	<h1 style="font-size:22px;">Summer sale</h1>
+	<p>Up to 40% off everything this weekend.</p>
+	<img src="https://tracker.example/footer.png" alt="Footer" width="560" />
+</div>
+`;
+
+const COLUMN: Decorator = (Story) => (
+	<div style={{ width: 720 }}>
+		<Story />
+	</div>
+);
+
+const PHONE: Decorator = (Story) => (
+	<div style={{ width: 390 }}>
+		<Story />
+	</div>
+);
+
+const meta: Meta<typeof MessageBodyView> = {
+	title: "Components/MessageBodyView",
+	component: MessageBodyView,
+	parameters: { layout: "padded" },
+	argTypes: {
+		isDark: { control: "boolean" },
+		allowImages: { control: "boolean" },
+	},
+};
+export default meta;
+
+type Story = StoryObj<typeof MessageBodyView>;
+
+/** A fixed-width newsletter rendered through the real pipeline: sanitized,
+ *  classified framed, rendered in the sandboxed frame. */
+export const Newsletter: Story = {
+	args: { html: NODE_WEEKLY, category: "newsletter", allowImages: true },
+	decorators: [COLUMN],
+};
+
+/** The same newsletter on a phone width — #727 scale-to-fit keeps it whole. */
+export const NewsletterMobile: Story = {
+	args: { html: NODE_WEEKLY, category: "newsletter", allowImages: true },
+	decorators: [PHONE],
+};
+
+/** Newsletter on the dark reading pane: smart-inverted to charcoal. */
+export const NewsletterDark: Story = {
+	args: {
+		html: NODE_WEEKLY,
+		category: "newsletter",
+		allowImages: true,
+		isDark: true,
+	},
+	parameters: { theme: "dark" },
+	decorators: [COLUMN],
+};
+
+/** Plain personal mail: UI font-stack + theme-aware colors injected. */
+export const Plain: Story = {
+	args: { html: PLAIN, category: "personal", allowImages: true },
+	decorators: [COLUMN],
+};
+
+/** Plain mail in dark mode: light text on the dark surface, never black-on-dark. */
+export const PlainDark: Story = {
+	args: { html: PLAIN, category: "personal", allowImages: true, isDark: true },
+	parameters: { theme: "dark" },
+	decorators: [COLUMN],
+};
+
+/** Images blocked: the sanitizer swaps remote images for placeholders and the
+ *  privacy notice reports the count via `renderBlockedNotice`. */
+export const ImagesBlocked: Story = {
+	args: {
+		html: WITH_REMOTE_IMAGES,
+		category: "marketing",
+		allowImages: false,
+		renderBlockedNotice: (count) => (
+			<div className="mb-3 rounded-md bg-surface-sunken/50 px-3 py-2 text-sm text-fg-muted">
+				{count} image{count > 1 ? "s" : ""} blocked for privacy
+			</div>
+		),
+	},
+	decorators: [COLUMN],
+};
+
+/** Same mail with images loaded — the remote images render and no notice shows. */
+export const ImagesLoaded: Story = {
+	args: { html: WITH_REMOTE_IMAGES, category: "marketing", allowImages: true },
+	decorators: [COLUMN],
+};
+
+/** No body content: the empty-state fallback. */
+export const Empty: Story = {
+	args: { html: undefined, text: undefined },
+	decorators: [COLUMN],
+};

package/src/components/message-body-view.tsx

@@ -0,0 +1,150 @@
+import { type ReactNode, useMemo } from "react";
+import type { CidResolver } from "../lib/cid-resolver.js";
+import { cn } from "../lib/cn.js";
+import {
+	classifyEmailRenderTreatment,
+	type EmailRenderCategory,
+} from "../lib/email-render-treatment.js";
+import { createEmailSanitizer } from "../lib/email-sanitizer.js";
+import { IsolatedEmailFrame } from "./isolated-email-frame.js";
+
+export type { EmailRenderCategory } from "../lib/email-render-treatment.js";
+
+export interface MessageBodyViewProps {
+	/**
+	 * Rendered email HTML (the `text/html` part's body, or a locally-rendered
+	 * draft). Passed RAW — this component sanitizes it before it reaches the
+	 * iframe. The single source of truth for "render an email body": app
+	 * `MessageBody` and the kit reading panes both compose it, so Storybook
+	 * shows the same sanitized, sandboxed rendering as the live app.
+	 */
+	html?: string;
+	/** Plain-text fallback for messages with no HTML part. */
+	text?: string;
+	/** App dark mode — drives the plain/framed dark canvas in the frame. */
+	isDark?: boolean;
+	/**
+	 * Message category (personal/newsletter/marketing/…). Together with the
+	 * sanitizer's author-background detection this picks the framed vs plain
+	 * treatment.
+	 */
+	category?: EmailRenderCategory;
+	/**
+	 * Whether external images are allowed to load. When false the sanitizer
+	 * swaps remote `<img src>` for a placeholder and stamps `data-blocked-src`;
+	 * `renderBlockedNotice` is then called with the count so the caller can
+	 * offer "load images".
+	 */
+	allowImages?: boolean;
+	/** Resolve `cid:` inline-image references to fetchable URLs. */
+	resolveCid?: CidResolver;
+	/** Extra classes for the body wrapper. */
+	className?: string;
+	/**
+	 * Render a notice above the body when external images were blocked. The
+	 * caller owns the "load once / always trust" affordances (they touch app
+	 * trust state), so this component only reports the count. Not called, or
+	 * called with `0`, when nothing was blocked.
+	 */
+	renderBlockedNotice?: (blockedImageCount: number) => ReactNode;
+}
+
+const EmptyBody = () => (
+	<p className="text-fg-muted text-sm italic">
+		This message has no body content.
+	</p>
+);
+
+/**
+ * Render an email body the way the app does: sanitize the raw HTML
+ * (DOMPurify + privacy/XSS scrubbing), classify it as framed (designed mail —
+ * author colors preserved) or plain (theme-aware base CSS), then hand the
+ * sanitized HTML to the sandboxed `IsolatedEmailFrame`. Never paints raw HTML
+ * into the app DOM — the only safe contract for untrusted mail.
+ */
+export const MessageBodyView = ({
+	html,
+	text,
+	isDark = false,
+	category,
+	allowImages = false,
+	resolveCid,
+	className,
+	renderBlockedNotice,
+}: MessageBodyViewProps) => {
+	const sanitized = useMemo(() => {
+		// DOMPurify needs a DOM. In a no-DOM context (SSR / unit render) we
+		// cannot sanitize, so we never emit the HTML — rendering unsanitized
+		// mail is not an option. The browser app always has a DOM; this guard
+		// only affects server / test rendering.
+		if (!html || typeof document === "undefined") return null;
+		const sanitize = createEmailSanitizer({
+			allowExternalImages: allowImages,
+			resolveCid,
+		});
+		return sanitize(html);
+	}, [html, allowImages, resolveCid]);
+
+	const sanitizedHtml = sanitized?.html ?? null;
+
+	const { framed, isPlain } = classifyEmailRenderTreatment(
+		category,
+		sanitized?.hasAuthorBackground ?? false,
+	);
+
+	const blockedImageCount = useMemo(() => {
+		if (!sanitizedHtml || allowImages) return 0;
+		return (sanitizedHtml.match(/data-blocked-src/g) || []).length;
+	}, [sanitizedHtml, allowImages]);
+
+	if (!sanitizedHtml && !text) {
+		return (
+			<div className={cn("message-body", className)}>
+				<EmptyBody />
+			</div>
+		);
+	}
+
+	return (
+		<div className={cn("message-body", className)}>
+			{blockedImageCount > 0 && renderBlockedNotice?.(blockedImageCount)}
+
+			{sanitizedHtml ? (
+				// Email HTML renders inside a sandboxed iframe so its own CSS and any
+				// (already-DOMPurify'd) markup cannot bleed into the app chrome. The
+				// frame sizes itself to its content; its sandbox omits `allow-scripts`
+				// so even a hypothetical sanitizer escape can't execute.
+				framed ? (
+					// Full-width wrapper so a fluid newsletter fills the reading column;
+					// max-w-full + overflow-x-auto trap any residual wide content inside
+					// this box rather than dragging the page on mobile. No border,
+					// padding or background — the email renders flush (#727).
+					<div className="w-full max-w-full overflow-x-auto">
+						<IsolatedEmailFrame
+							html={sanitizedHtml}
+							variant="framed"
+							isDark={isDark}
+						/>
+					</div>
+				) : (
+					// `lg:max-w-2xl` caps the reading column on desktop; `max-w-full`
+					// keeps the box within the viewport on mobile. `overflow-x-auto`
+					// traps residual wide content INSIDE this box on a phone (#727).
+					<div className="max-w-full overflow-x-auto lg:max-w-2xl">
+						<IsolatedEmailFrame
+							html={sanitizedHtml}
+							variant={isPlain ? "plain" : "framed"}
+							isDark={isDark}
+						/>
+					</div>
+				)
+			) : text ? (
+				<pre className="email-text whitespace-pre-wrap text-sm leading-relaxed">
+					{text}
+				</pre>
+			) : (
+				<EmptyBody />
+			)}
+		</div>
+	);
+};

package/src/components/message-header.render.test.ts

@@ -0,0 +1,58 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { createElement } from "react";
+import { renderToString } from "react-dom/server";
+import type { EnvelopeAddress } from "./address-display.js";
+import { MessageHeader, type MessageHeaderProps } from "./message-header.js";
+
+const ada: EnvelopeAddress = {
+	displayName: "Ada Lovelace",
+	normalizedEmail: "ada@example.com",
+};
+
+const base: MessageHeaderProps = {
+	subject: "Quarterly numbers",
+	from: [ada],
+	to: [{ normalizedEmail: "team@example.com" }],
+	date: "Mon, 23 Jun 2026, 14:00",
+	senderTrust: "wellknown",
+};
+
+describe("MessageHeader", () => {
+	it("renders subject, addresses and the formatted date", () => {
+		const html = renderToString(createElement(MessageHeader, base));
+		assert.match(html, /Quarterly numbers/);
+		assert.match(html, /Ada Lovelace/);
+		assert.match(html, /team@example.com/);
+		assert.match(html, /Mon, 23 Jun 2026, 14:00/);
+	});
+
+	it("shows a fallback for a missing subject", () => {
+		const html = renderToString(
+			createElement(MessageHeader, { ...base, subject: undefined }),
+		);
+		assert.match(html, /\(No subject\)/);
+	});
+
+	it("renders the category badge and trust indicator", () => {
+		const html = renderToString(
+			createElement(MessageHeader, {
+				...base,
+				category: "newsletter",
+				senderTrust: "vip",
+			}),
+		);
+		assert.match(html, /aria-label="Category: newsletter"/);
+		assert.match(html, /aria-label="VIP sender"/);
+	});
+
+	it("renders an actions slot when provided", () => {
+		const html = renderToString(
+			createElement(MessageHeader, {
+				...base,
+				actions: createElement("button", { type: "button" }, "Menu"),
+			}),
+		);
+		assert.match(html, /Menu/);
+	});
+});

package/src/components/message-header.stories.tsx

@@ -0,0 +1,79 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { Menu } from "lucide-react";
+import type { EnvelopeAddress } from "./address-display.js";
+import { MessageHeader } from "./message-header.js";
+
+const meta: Meta<typeof MessageHeader> = {
+	title: "Mail/MessageHeader",
+	component: MessageHeader,
+	parameters: { layout: "fullscreen" },
+};
+export default meta;
+
+type Story = StoryObj<typeof MessageHeader>;
+
+const named = (name: string, email: string): EnvelopeAddress => ({
+	displayName: name,
+	normalizedEmail: email,
+});
+
+const trustedFrom: EnvelopeAddress = {
+	...named("Ada Lovelace", "ada@example.com"),
+	flags: { trusted: { value: true } },
+};
+
+const date = "Mon, 23 Jun 2026, 14:00";
+
+export const TrustedSender: Story = {
+	args: {
+		subject: "Quarterly numbers are in",
+		from: [trustedFrom],
+		to: [named("The team", "team@example.com")],
+		date,
+		senderTrust: "wellknown",
+	},
+};
+
+export const NewSenderNewsletter: Story = {
+	name: "New sender + newsletter",
+	args: {
+		subject: "Welcome to the weekly digest",
+		from: [named("Digest", "hello@digest.example.com")],
+		to: [{ normalizedEmail: "you@example.com" }],
+		date,
+		category: "newsletter",
+		senderTrust: "unknown",
+	},
+};
+
+export const VipWithManyRecipients: Story = {
+	name: "VIP + many recipients",
+	args: {
+		subject: "Board meeting follow-up",
+		from: [{ ...named("Grace Hopper", "grace@example.com") }],
+		to: [
+			named("Alan Turing", "alan@example.com"),
+			named("Katherine Johnson", "katherine@example.com"),
+			named("Dorothy Vaughan", "dorothy@example.com"),
+			named("Mary Jackson", "mary@example.com"),
+		],
+		cc: [named("Margaret Hamilton", "margaret@example.com")],
+		date,
+		senderTrust: "vip",
+	},
+};
+
+export const NoSubjectWithActions: Story = {
+	name: "No subject + actions slot",
+	args: {
+		from: [named("Someone", "someone@example.com")],
+		to: [{ normalizedEmail: "you@example.com" }],
+		date,
+		senderTrust: "wellknown",
+		actions: (
+			<button type="button" aria-label="Menu" className="text-fg-muted">
+				<Menu className="size-5" />
+			</button>
+		),
+	},
+};

package/src/components/message-header.tsx

@@ -0,0 +1,59 @@
+import type { ReactNode } from "react";
+import { AddressList, type EnvelopeAddress } from "./address-display.js";
+import { CategoryBadge, type MessageCategory } from "./category-badge.js";
+import {
+	type SenderTrust,
+	SenderTrustIndicator,
+} from "./sender-trust-indicator.js";
+
+export interface MessageHeaderProps {
+	subject?: string;
+	from: EnvelopeAddress[];
+	to: EnvelopeAddress[];
+	cc?: EnvelopeAddress[];
+	/** Pre-formatted, human-readable date. The consumer owns formatting. */
+	date: string;
+	category?: MessageCategory;
+	senderTrust: SenderTrust;
+	/**
+	 * Optional slot for surfaces (hamburger menu, etc) rendered inline on the
+	 * right of the subject line. Kept generic so the header doesn't need to
+	 * know what action set is in play.
+	 */
+	actions?: ReactNode;
+}
+
+export const MessageHeader = ({
+	subject,
+	from,
+	to,
+	cc = [],
+	date,
+	category,
+	senderTrust,
+	actions,
+}: MessageHeaderProps) => {
+	return (
+		<div className="border-b border-line p-4">
+			<div className="flex items-start justify-between gap-2 mb-3">
+				<div className="flex items-center gap-2 min-w-0 flex-1">
+					<h1 className="text-xl font-semibold truncate">
+						{subject || "(No subject)"}
+					</h1>
+					<CategoryBadge category={category} size="md" />
+					<SenderTrustIndicator senderTrust={senderTrust} size="md" />
+				</div>
+				{actions && <div className="shrink-0">{actions}</div>}
+			</div>
+			<div className="space-y-1">
+				<AddressList label="From" addresses={from} showTrustedBadge />
+				<AddressList label="To" addresses={to} />
+				{cc.length > 0 && <AddressList label="Cc" addresses={cc} />}
+				<div className="flex gap-2 text-sm">
+					<span className="text-fg-muted shrink-0 w-12">Date:</span>
+					<span className="text-fg">{date}</span>
+				</div>
+			</div>
+		</div>
+	);
+};

package/src/components/message-list-pane.render.test.ts

@@ -0,0 +1,136 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { createElement } from "react";
+import { renderToString } from "react-dom/server";
+import type { ThreadSection } from "./app-shell-types.js";
+import { MessageListPane } from "./message-list-pane.js";
+
+const sections: ThreadSection[] = [
+	{
+		id: "today",
+		label: "Today",
+		threads: [
+			{
+				id: "t1",
+				accountId: "a1",
+				fromName: "Alex Rivera",
+				fromEmail: "alex@example.com",
+				subject: "Q3 planning notes",
+				snippet: "Here are the notes from today's planning session.",
+				timeLabel: "9:42",
+			},
+			{
+				id: "t2",
+				accountId: "a1",
+				fromName: "Acme Billing",
+				fromEmail: "billing@acme.com",
+				subject: "Your invoice is ready",
+				snippet: "Invoice #1042 is available to view.",
+				timeLabel: "8:15",
+			},
+		],
+	},
+];
+
+const baseProps = {
+	listTitle: "Inbox",
+	sections,
+	flatList: true,
+	onSelectThread: () => undefined,
+	onSelectBriefCategory: () => undefined,
+};
+
+describe("MessageListPane", () => {
+	it("renders the list title and the rows", () => {
+		const html = renderToString(
+			createElement(MessageListPane, { ...baseProps, isDesktop: true }),
+		);
+		assert.match(html, /Inbox/);
+		assert.match(html, /Q3 planning notes/);
+		assert.match(html, /Your invoice is ready/);
+	});
+
+	it("shows the pull-to-refresh affordance on the narrow touch list", () => {
+		const html = renderToString(
+			createElement(MessageListPane, {
+				...baseProps,
+				isDesktop: false,
+				listState: "ready",
+			}),
+		);
+		assert.match(html, /Pull to refresh/);
+	});
+
+	it("omits the pull-to-refresh affordance on the desktop list", () => {
+		const html = renderToString(
+			createElement(MessageListPane, { ...baseProps, isDesktop: true }),
+		);
+		assert.doesNotMatch(html, /Pull to refresh/);
+	});
+
+	it("renders the listBody slot instead of built-in rows when provided", () => {
+		const html = renderToString(
+			createElement(MessageListPane, {
+				...baseProps,
+				isDesktop: true,
+				listBody: createElement(
+					"div",
+					{ "data-testid": "custom-body" },
+					"virtualized rows here",
+				),
+			}),
+		);
+		// Custom body is rendered
+		assert.match(html, /virtualized rows here/);
+		// Built-in rows are NOT rendered when listBody is provided
+		assert.doesNotMatch(html, /Q3 planning notes/);
+	});
+
+	it("honors the listBody slot on the touch path so mobile rows stay real anchors", () => {
+		const html = renderToString(
+			createElement(MessageListPane, {
+				...baseProps,
+				isDesktop: false,
+				listState: "ready",
+				listBody: createElement(
+					"a",
+					{ href: "/mail/inbox?selectedMessageId=t1" },
+					"Q3 planning notes",
+				),
+			}),
+		);
+		// The consumer's anchor row is rendered on the mobile/touch path…
+		assert.match(html, /href="\/mail\/inbox\?selectedMessageId=t1"/);
+		// …and the built-in TouchListBody mock fallback is NOT substituted.
+		assert.doesNotMatch(html, /Pull to refresh/);
+	});
+
+	it("surfaces the specific error message and a report path in the error state", () => {
+		const html = renderToString(
+			createElement(MessageListPane, {
+				...baseProps,
+				isDesktop: true,
+				listState: "error",
+				errorMessage: "IMAP connection timed out",
+				onRetry: () => undefined,
+				onReportError: () => undefined,
+			}),
+		);
+		assert.match(html, /IMAP connection timed out/);
+		assert.match(html, /Retry/);
+		assert.match(html, /Report a problem/);
+	});
+
+	it("renders the selectionBar slot instead of the pane header when provided", () => {
+		const html = renderToString(
+			createElement(MessageListPane, {
+				...baseProps,
+				isDesktop: true,
+				selectionBar: createElement("div", null, "2 selected"),
+			}),
+		);
+		assert.match(html, /2 selected/);
+		// The mailbox title header is NOT rendered when selectionBar is provided
+		assert.doesNotMatch(html, /Inbox/);
+	});
+});