@remit/ui 0.0.15 → 0.0.17

package/package.json

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

package/src/components/button.tsx

@@ -1,4 +1,8 @@
-import type { ButtonHTMLAttributes, ReactNode } from "react";
+import type {
+	AnchorHTMLAttributes,
+	ButtonHTMLAttributes,
+	ReactNode,
+} from "react";
 import { cn } from "../lib/cn.js";
 
 type Variant = "primary" | "secondary" | "ghost" | "danger";
@@ -50,3 +54,37 @@ export function Button({
 		</button>
 	);
 }
+
+export interface ButtonLinkProps
+	extends AnchorHTMLAttributes<HTMLAnchorElement> {
+	variant?: Variant;
+	size?: Size;
+	icon?: ReactNode;
+	/** Opens in a new tab with the repo's standard `rel` hardening. */
+	external?: boolean;
+}
+
+/**
+ * An anchor that carries the button styling — same base, so it keeps the
+ * focus-visible ring a hand-rolled `<a className="bg-accent …">` drops.
+ */
+export function ButtonLink({
+	variant = "primary",
+	size = "md",
+	icon,
+	external,
+	className,
+	children,
+	...props
+}: ButtonLinkProps) {
+	return (
+		<a
+			className={cn(base, variants[variant], sizes[size], className)}
+			{...(external ? { target: "_blank", rel: "noopener noreferrer" } : {})}
+			{...props}
+		>
+			{icon}
+			{children}
+		</a>
+	);
+}

package/src/components/quarantine-bug-dialog.tsx

@@ -0,0 +1,72 @@
+import { Copy, ExternalLink } from "lucide-react";
+import { Button, ButtonLink } from "./button.js";
+import { Dialog } from "./dialog.js";
+import {
+	formatQuarantineReport,
+	type QuarantineEntry,
+} from "./quarantine-report.js";
+
+export interface QuarantineBugDialogProps {
+	entry: QuarantineEntry | null;
+	onClose: () => void;
+	/**
+	 * Prefilled new-issue URL, built by the app's shared bug-report helper so
+	 * the URL budget and the repository constant stay in one place.
+	 */
+	issueUrl: string;
+	onCopy: (report: string) => void;
+}
+
+/**
+ * The report, in full, before it goes anywhere. Filing opens the user's own
+ * GitHub session with the issue prefilled — Remit never posts on their behalf,
+ * and nothing is sent that is not on this screen.
+ */
+export function QuarantineBugDialog({
+	entry,
+	onClose,
+	issueUrl,
+	onCopy,
+}: QuarantineBugDialogProps) {
+	if (!entry) return null;
+	const report = formatQuarantineReport(entry);
+
+	return (
+		<Dialog open onClose={onClose} title="Report this message">
+			<div className="flex max-h-[80vh] flex-col">
+				<header className="space-y-1 border-b border-line px-4 py-3">
+					<h3 className="text-sm font-semibold text-fg">Report this message</h3>
+					<p className="text-xs text-fg-muted">
+						This is everything the report contains. It describes the shape of
+						the message — never its contents, addresses, subject, attachment
+						names, or the parser's own error text.
+					</p>
+				</header>
+				<pre className="flex-1 overflow-auto bg-surface-sunken px-4 py-3 text-2xs leading-relaxed whitespace-pre-wrap text-fg-muted">
+					{report}
+				</pre>
+				<footer className="flex flex-wrap items-center justify-end gap-2 border-t border-line px-4 py-3">
+					<Button variant="ghost" size="sm" onClick={onClose}>
+						Cancel
+					</Button>
+					<Button
+						variant="secondary"
+						size="sm"
+						icon={<Copy className="size-3.5" />}
+						onClick={() => onCopy(report)}
+					>
+						Copy report
+					</Button>
+					<ButtonLink
+						external
+						size="sm"
+						href={issueUrl}
+						icon={<ExternalLink className="size-3.5" />}
+					>
+						Open on GitHub
+					</ButtonLink>
+				</footer>
+			</div>
+		</Dialog>
+	);
+}

package/src/components/quarantine-entry-row.tsx

@@ -0,0 +1,71 @@
+import { Bug } from "lucide-react";
+import { Badge } from "./badge.js";
+import { Button } from "./button.js";
+import { canonicalRoleLabel, providerLeaf } from "./folder-role.js";
+import {
+	type QuarantineEntry,
+	quarantineSummary,
+} from "./quarantine-report.js";
+
+export interface QuarantineEntryRowProps {
+	entry: QuarantineEntry;
+	onCutBug: (entry: QuarantineEntry) => void;
+}
+
+function formatQuarantinedAt(epochMillis: number): string {
+	return new Date(epochMillis).toLocaleString(undefined, {
+		dateStyle: "medium",
+		timeStyle: "short",
+	});
+}
+
+/**
+ * One quarantined message. Leads with what went wrong in plain language, then
+ * the parser's own words — which stay on this screen and never enter a report
+ * — and the folder, uid and time as identifying detail.
+ */
+export function QuarantineEntryRow({
+	entry,
+	onCutBug,
+}: QuarantineEntryRowProps) {
+	return (
+		<li className="flex flex-col gap-2 border-b border-line px-row-inset py-3 last:border-b-0 sm:flex-row sm:items-start sm:justify-between">
+			<div className="min-w-0 space-y-1">
+				<p className="text-sm text-fg">
+					{quarantineSummary(entry.failureStage)}
+				</p>
+				<p
+					className="truncate text-xs text-fg-muted"
+					title={entry.failureMessage}
+				>
+					{entry.failureMessage}
+				</p>
+				<p className="flex flex-wrap items-center gap-x-2 gap-y-1 text-2xs text-fg-subtle">
+					<Badge tone="warning">{canonicalRoleLabel(entry.mailboxRole)}</Badge>
+					<span className="truncate" title={entry.mailboxPath}>
+						{providerLeaf(entry.mailboxPath)}
+					</span>
+					<span aria-hidden>·</span>
+					<span>{`uid ${entry.uid}`}</span>
+					<span aria-hidden>·</span>
+					<span>{formatQuarantinedAt(entry.quarantinedAt)}</span>
+					{entry.attempts > 1 && (
+						<>
+							<span aria-hidden>·</span>
+							<span>{`${entry.attempts} attempts`}</span>
+						</>
+					)}
+				</p>
+			</div>
+			<Button
+				variant="secondary"
+				size="sm"
+				className="shrink-0"
+				icon={<Bug className="size-3.5" />}
+				onClick={() => onCutBug(entry)}
+			>
+				Cut a bug
+			</Button>
+		</li>
+	);
+}

package/src/components/quarantine-fixtures.ts

@@ -0,0 +1,81 @@
+import type { QuarantineEntry } from "./quarantine-report.js";
+
+/**
+ * Demo entries backing the quarantine stories. Exported so the kit's own
+ * stories and the workbench settings screen render the same data — they had
+ * drifted on `appVersion` when each file carried its own copy.
+ */
+export const quarantineDemoEntries: readonly QuarantineEntry[] = [
+	{
+		quarantineId: "q-1",
+		accountId: "acct-1",
+		mailboxId: "mbx-inbox",
+		uid: 40217,
+		mailboxRole: "inbox",
+		mailboxPath: "INBOX",
+		failureStage: "BodyParse",
+		failureCode: "UnterminatedMultipartBoundary",
+		failureMessage: "multipart boundary was never closed",
+		failurePartPath: null,
+		quarantinedAt: Date.parse("2026-07-18T09:12:00Z"),
+		attempts: 3,
+		sizeBytes: 184_233,
+		contentType: "multipart/mixed",
+		transferEncoding: "7bit",
+		charset: "utf-8",
+		structure: {
+			contentType: "multipart/mixed",
+			parts: [
+				{
+					contentType: "multipart/alternative",
+					parts: [{ contentType: "text/plain" }, { contentType: "text/html" }],
+				},
+				{ contentType: "application/pdf" },
+			],
+		},
+		messageIdHash: "sha256:6f1c4a9d20",
+		appVersion: "worker 1.0.0",
+	},
+	{
+		quarantineId: "q-2",
+		accountId: "acct-1",
+		mailboxId: "mbx-archive",
+		uid: 40219,
+		mailboxRole: "archive",
+		mailboxPath: "Archive/2026",
+		failureStage: "BodyParse",
+		failureCode: "UnknownCharset",
+		failureMessage: "declared charset is not a known encoding",
+		failurePartPath: "1.2",
+		quarantinedAt: Date.parse("2026-07-18T14:40:00Z"),
+		attempts: 3,
+		sizeBytes: 9_812,
+		contentType: "text/plain",
+		transferEncoding: "quoted-printable",
+		charset: "x-user-defined",
+		structure: { contentType: "text/plain" },
+		messageIdHash: "sha256:b31e0744af",
+		appVersion: "worker 1.0.0",
+	},
+	{
+		quarantineId: "q-3",
+		accountId: "acct-1",
+		mailboxId: "mbx-junk",
+		uid: 40251,
+		mailboxRole: "junk",
+		mailboxPath: "Junk",
+		failureStage: "BodyParse",
+		failureCode: "TruncatedBody",
+		failureMessage: "stream ended before the declared body length",
+		failurePartPath: null,
+		quarantinedAt: Date.parse("2026-07-19T06:03:00Z"),
+		attempts: 1,
+		sizeBytes: 2_140,
+		contentType: "text/html",
+		transferEncoding: "base64",
+		charset: null,
+		structure: { contentType: "text/html" },
+		messageIdHash: "sha256:0a77de1c05",
+		appVersion: "worker 1.0.0",
+	},
+];

package/src/components/quarantine-report.test.ts

@@ -0,0 +1,151 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { quarantineDemoEntries } from "./quarantine-fixtures.js";
+import {
+	formatQuarantineReport,
+	QUARANTINE_REPORT_DISCLAIMER,
+	type QuarantineEntry,
+	quarantineIssueTitle,
+	quarantineReportSections,
+	quarantineSummary,
+} from "./quarantine-report.js";
+
+const entry: QuarantineEntry = {
+	...quarantineDemoEntries[0],
+	mailboxPath: "Clients/Acme Holdings",
+	failureMessage: "invalid address: joan@acme-holdings.example",
+};
+
+describe("formatQuarantineReport", () => {
+	it("names the stage, the code and the build that failed", () => {
+		const report = formatQuarantineReport(entry);
+		assert.match(report, /BodyParse/);
+		assert.match(report, /UnterminatedMultipartBoundary/);
+		assert.match(report, /worker 1\.0\.0/);
+	});
+
+	it("renders the MIME tree as structure with no content", () => {
+		const report = formatQuarantineReport(entry);
+		assert.match(report, /\n- multipart\/mixed/);
+		assert.match(report, /\n {2}- multipart\/alternative/);
+		assert.match(report, /\n {4}- text\/html/);
+		assert.match(report, /\n {2}- application\/pdf/);
+	});
+
+	it("withholds the user's own folder name", () => {
+		const report = formatQuarantineReport(entry);
+		assert.doesNotMatch(report, /Acme Holdings/);
+		assert.match(report, /Folder role.*inbox/);
+	});
+
+	it("withholds the parser's own error text, which can quote the input", () => {
+		const report = formatQuarantineReport(entry);
+		assert.doesNotMatch(report, /joan@acme-holdings\.example/);
+		assert.doesNotMatch(report, /invalid address/);
+	});
+
+	it("strips content-type parameters, which carry attachment filenames", () => {
+		const report = formatQuarantineReport({
+			...entry,
+			contentType: 'multipart/mixed; boundary="=_a1b2"',
+			structure: {
+				contentType: "multipart/mixed",
+				parts: [
+					{
+						contentType:
+							'application/octet-stream; name="Q3 payroll — Acme.pdf"',
+					},
+				],
+			},
+		});
+		assert.doesNotMatch(report, /payroll/);
+		assert.doesNotMatch(report, /boundary/);
+		assert.match(report, /- application\/octet-stream/);
+	});
+
+	it("says so when the failure is not attributable to one part", () => {
+		assert.match(formatQuarantineReport(entry), /Failing part.*whole message/);
+		assert.match(
+			formatQuarantineReport({ ...entry, failurePartPath: "1.2" }),
+			/Failing part.*`1\.2`/,
+		);
+	});
+
+	it("marks an undeclared charset rather than omitting it", () => {
+		const report = formatQuarantineReport({ ...entry, charset: null });
+		assert.match(report, /Charset.*not declared/);
+	});
+});
+
+describe("sender-controlled BODYSTRUCTURE strings", () => {
+	// charset, transferEncoding and contentType are arbitrary quoted strings
+	// chosen by whoever sent the message, echoed into an issue filed under the
+	// user's own account. They are hostile input.
+	const injection = "`\n\n**Click here:** https://evil.example\n\n`";
+
+	it("cannot break out of the code span and inject markdown", () => {
+		const report = formatQuarantineReport({ ...entry, charset: injection });
+		const line = report.split("\n").find((l) => l.startsWith("- **Charset**:"));
+		assert.ok(line, "Expected a charset line");
+		// Neutralised, not deleted: the payload survives as literal text inside
+		// a code span, which needs the value to carry no raw newline and no
+		// backtick beyond the two delimiters.
+		assert.equal((line.match(/`/g) ?? []).length, 2);
+		assert.doesNotMatch(report, /^\s*\*\*Click here:\*\*/m);
+	});
+
+	it("keeps the malformed value visible, since it is usually the bug", () => {
+		const report = formatQuarantineReport({ ...entry, charset: injection });
+		assert.match(report, /malformed/);
+		assert.match(report, /evil\.example/);
+	});
+
+	it("renders a conforming value as itself", () => {
+		const report = formatQuarantineReport({ ...entry, charset: "utf-8" });
+		assert.match(report, /\*\*Charset\*\*: `utf-8`/);
+		assert.doesNotMatch(report, /malformed/);
+	});
+
+	it("keeps a hostile node type from closing the MIME fence", () => {
+		const report = formatQuarantineReport({
+			...entry,
+			structure: {
+				contentType: "multipart/mixed",
+				parts: [{ contentType: "```\n## Injected heading" }],
+			},
+		});
+		assert.equal((report.match(/^```/gm) ?? []).length, 2);
+		assert.doesNotMatch(report, /^## Injected heading/m);
+	});
+});
+
+describe("quarantineReportSections", () => {
+	it("hands the MIME tree over unfenced, so it can be truncated safely", () => {
+		const { head, structure, disclaimer } = quarantineReportSections(entry);
+		assert.doesNotMatch(structure, /```/);
+		assert.doesNotMatch(head, /```/);
+		assert.equal(disclaimer, QUARANTINE_REPORT_DISCLAIMER);
+	});
+
+	it("assembles back into the fenced report the dialog shows", () => {
+		const report = formatQuarantineReport(entry);
+		assert.equal((report.match(/^```/gm) ?? []).length, 2);
+		assert.ok(report.endsWith(QUARANTINE_REPORT_DISCLAIMER));
+	});
+});
+
+describe("quarantineIssueTitle", () => {
+	it("carries only the closed vocabulary", () => {
+		const title = quarantineIssueTitle(entry);
+		assert.match(title, /UnterminatedMultipartBoundary/);
+		assert.match(title, /BodyParse/);
+		assert.doesNotMatch(title, /joan@/);
+	});
+});
+
+describe("quarantineSummary", () => {
+	it("explains the stage without parser jargon", () => {
+		const summary = quarantineSummary("BodyParse");
+		assert.doesNotMatch(summary, /MIME|RFC|mailparser|charset=/i);
+	});
+});

package/src/components/quarantine-report.ts

@@ -0,0 +1,221 @@
+import type { FolderRole } from "./folder-role.js";
+
+/**
+ * The pipeline step that refused the message.
+ *
+ * One member, because **no catch site on the sync path can currently tell a
+ * parse failure from an infrastructure failure**. The per-message frame in
+ * `body-sync.ts` wraps the S3 body write, the parsed-body cache write, the
+ * body-part `pMap` and DynamoDB upsert, the placement move (SQS + DynamoDB)
+ * and the label and counter writes, alongside the `simpleParser` call; only
+ * connection drops are filtered out of it.
+ *
+ * **Precondition on Phase 3**: narrow the try block to the parse call before
+ * quarantining anything. Quarantining at the frame as it stands would set a
+ * message aside for a DynamoDB throttle, tell the user it was unreadable, and
+ * invite a public GitHub issue for an outage — the same defect as naming an
+ * S3 write `AttachmentExtract`, one layer up.
+ *
+ * There are three distinct parse sites, and a quarantine would have to
+ * attribute them differently: the fresh-fetch path, `backfillClassification`
+ * (its own parse over a different result list), and the header parse in
+ * `imapflow-connection.ts`, which is swallowed and treated as "no thread
+ * parent". Stages are added as those sites are separated — never ahead of it.
+ *
+ * The stages this replaced could not fire at all: an unparseable Date falls
+ * back to INTERNALDATE, and an unrecognized MIME type maps to a safe default
+ * rather than throwing. Unparseable addresses are dropped with a `continue`
+ * and the message is written anyway — so that defect is reached but discarded,
+ * never raised, which is a reason to have no `AddressParse` stage but not the
+ * reason that it cannot happen.
+ */
+export type QuarantineFailureStage = "BodyParse";
+
+/**
+ * The specific defect within a stage.
+ *
+ * Closed, because `quarantineIssueTitle` interpolates it into a public issue
+ * title: a `string` here would make the one field whose publishability is
+ * asserted rather than derived into free text. Grows with the narrowing
+ * described on `QuarantineFailureStage`, and no faster.
+ */
+export type QuarantineFailureCode =
+	| "UnterminatedMultipartBoundary"
+	| "UnknownCharset"
+	| "TruncatedBody";
+
+/**
+ * A node in the message's MIME tree.
+ *
+ * `contentType` is `type/subtype` only. BODYSTRUCTURE hands the type and its
+ * parameters over separately, so a node is built from `type`/`subtype` and
+ * never from a raw content-type line — parameters carry `name=` and
+ * `filename=`, which name the user's attachments.
+ */
+export interface QuarantineMimeNode {
+	contentType: string;
+	parts?: readonly QuarantineMimeNode[];
+}
+
+/**
+ * A quarantined message as the settings surface sees it.
+ *
+ * Two fields are stored and shown on screen but never travel in the report:
+ * `mailboxPath` (the user's own folder names can be personal) and
+ * `failureMessage` (parser errors quote the input that broke them, and
+ * redacting arbitrary parser text is not solvable). Everything else is safe to
+ * paste into a public issue without reading it first.
+ */
+export interface QuarantineEntry {
+	quarantineId: string;
+	accountId: string;
+	mailboxId: string;
+	/** IMAP uid of the message that was not written. */
+	uid: number;
+	/** Canonical role of the folder it arrived in — travels in the report. */
+	mailboxRole: FolderRole;
+	/** The user's own folder name. Shown on screen, withheld from the report. */
+	mailboxPath: string;
+	failureStage: QuarantineFailureStage;
+	failureCode: QuarantineFailureCode;
+	/** Parser error text. Shown on screen, never in the report. */
+	failureMessage: string;
+	/**
+	 * Dot-numbered part path the failure is attributable to, or null when it is
+	 * not attributable to one node — the case for a whole-body parse failure.
+	 */
+	failurePartPath: string | null;
+	/** Epoch millis the message was quarantined. */
+	quarantinedAt: number;
+	/** Rounds attempted before the message was set aside. */
+	attempts: number;
+	sizeBytes: number;
+	/** Top-level Content-Type, `type/subtype` only. */
+	contentType: string;
+	transferEncoding: string;
+	/** Declared charset, or null when the message declared none. */
+	charset: string | null;
+	/** The MIME tree, structure only. */
+	structure: QuarantineMimeNode;
+	/** SHA-256 of the Message-ID, `sha256:` prefixed. */
+	messageIdHash: string;
+	/** Build of the worker that failed to parse — a parse bug belongs to it. */
+	appVersion: string;
+}
+
+const stageSummaries: Record<QuarantineFailureStage, string> = {
+	BodyParse: "The message is built in a way Remit could not read.",
+};
+
+/** Plain-language one-liner for a row. The detail lives in the report. */
+export function quarantineSummary(stage: QuarantineFailureStage): string {
+	return stageSummaries[stage];
+}
+
+/**
+ * Guards the node contract where the report is rendered, so a node built from
+ * a raw content-type line cannot put an attachment filename in the report even
+ * if Phase 3 gets the construction wrong.
+ */
+function stripParameters(contentType: string): string {
+	return contentType.split(";")[0].trim();
+}
+
+/** RFC 2045 token characters — what a charset or encoding is allowed to be. */
+const TOKEN = /^[A-Za-z0-9!#$%&'*+._-]+$/;
+const MEDIA_TYPE = /^[A-Za-z0-9!#$%&'*+._-]+\/[A-Za-z0-9!#$%&'*+._-]+$/;
+
+/**
+ * `charset`, `transferEncoding` and `contentType` are BODYSTRUCTURE strings —
+ * arbitrary quoted text chosen by whoever sent the message, echoed into an
+ * issue filed under the user's own account. A conforming value renders as
+ * itself; anything else is JSON-escaped, so newlines and backticks cannot
+ * close the code span and inject markdown. The malformed value is kept rather
+ * than dropped, because a malformed value is usually the bug.
+ */
+function renderToken(value: string, pattern: RegExp): string {
+	if (pattern.test(value)) return `\`${value}\``;
+	const escaped = JSON.stringify(value).replace(/`/g, "\\u0060");
+	return `\`${escaped}\` (malformed)`;
+}
+
+/** Inside a fence the only escape is a lone fence line, so tokens are enough. */
+function renderNodeType(contentType: string): string {
+	const stripped = stripParameters(contentType);
+	if (MEDIA_TYPE.test(stripped)) return stripped;
+	return JSON.stringify(stripped);
+}
+
+function renderStructure(node: QuarantineMimeNode, depth = 0): string[] {
+	const line = `${"  ".repeat(depth)}- ${renderNodeType(node.contentType)}`;
+	const children = node.parts ?? [];
+	return [
+		line,
+		...children.flatMap((part) => renderStructure(part, depth + 1)),
+	];
+}
+
+export const QUARANTINE_REPORT_DISCLAIMER =
+	"_No message content, addresses, subject, attachment names or parser output are included._";
+
+/**
+ * The report split into the parts a bug report assembles.
+ *
+ * `structure` is the only unbounded section, so it is handed over unfenced:
+ * the URL budget truncates it and fences it afterwards, the same shape a
+ * stacktrace already uses. Fencing here instead would let the binary search
+ * cut inside the fence, leaving every following section rendered inside one
+ * code block — and the first line lost would be the disclaimer, so the one
+ * report that is truncated would be the one with no statement of what was
+ * withheld.
+ */
+export interface QuarantineReportSections {
+	head: string;
+	structure: string;
+	disclaimer: string;
+}
+
+export function quarantineReportSections(
+	entry: QuarantineEntry,
+): QuarantineReportSections {
+	const head = [
+		`### Message quarantined at \`${entry.failureStage}\``,
+		"",
+		`- **Failure**: \`${entry.failureCode}\``,
+		`- **Folder role**: ${entry.mailboxRole}`,
+		`- **Failing part**: ${entry.failurePartPath === null ? "_whole message_" : `\`${entry.failurePartPath}\``}`,
+		`- **Attempts before quarantine**: ${entry.attempts}`,
+		`- **Worker build**: ${entry.appVersion}`,
+		`- **Message-ID hash**: \`${entry.messageIdHash}\``,
+		"",
+		"#### Message shape",
+		"",
+		`- **Content-Type**: ${renderToken(stripParameters(entry.contentType), MEDIA_TYPE)}`,
+		`- **Content-Transfer-Encoding**: ${renderToken(entry.transferEncoding, TOKEN)}`,
+		`- **Charset**: ${entry.charset === null ? "_not declared_" : renderToken(entry.charset, TOKEN)}`,
+		`- **Size**: ${entry.sizeBytes} bytes`,
+		"",
+		"MIME structure:",
+	].join("\n");
+
+	return {
+		head,
+		structure: renderStructure(entry.structure).join("\n"),
+		disclaimer: QUARANTINE_REPORT_DISCLAIMER,
+	};
+}
+
+/**
+ * The whole report as one string — what the dialog shows and the copy action
+ * copies. The published issue is assembled from the sections instead, so that
+ * a long MIME tree can be truncated without breaking the fence.
+ */
+export function formatQuarantineReport(entry: QuarantineEntry): string {
+	const { head, structure, disclaimer } = quarantineReportSections(entry);
+	return [head, "", "```", structure, "```", "", disclaimer].join("\n");
+}
+
+/** Issue title. Closed vocabulary only, so it is safe to publish. */
+export function quarantineIssueTitle(entry: QuarantineEntry): string {
+	return `Message quarantined: ${entry.failureCode} at ${entry.failureStage}`;
+}

package/src/components/quarantine-section.render.test.ts

@@ -0,0 +1,101 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { createElement } from "react";
+import { renderToString } from "react-dom/server";
+import { QuarantineBugDialog } from "./quarantine-bug-dialog.js";
+import { quarantineDemoEntries } from "./quarantine-fixtures.js";
+import type { QuarantineEntry } from "./quarantine-report.js";
+import { QuarantineSection } from "./quarantine-section.js";
+
+const noop = () => {};
+const [base, second] = quarantineDemoEntries;
+const ISSUE_URL = "https://github.com/remit-mail/reader/issues/new?title=x";
+
+const render = (entries: readonly QuarantineEntry[]) =>
+	renderToString(createElement(QuarantineSection, { entries, onCutBug: noop }));
+
+describe("QuarantineSection", () => {
+	it("reassures when nothing is set aside", () => {
+		const html = render([]);
+		assert.match(html, /Nothing is set aside/);
+		assert.doesNotMatch(html, /role="alert"/);
+	});
+
+	it("shows a single entry as a fact, without an alert", () => {
+		const html = render([base]);
+		assert.match(html, /uid 40217/);
+		assert.doesNotMatch(html, /role="alert"/);
+	});
+
+	it("raises an alert once more than one message is set aside", () => {
+		const html = render([base, second]);
+		assert.match(html, /role="alert"/);
+		assert.match(html, /2 messages could not be read/);
+	});
+
+	it("shows the parser's own words on screen, where the report will not", () => {
+		const html = render([base]);
+		assert.match(html, /multipart boundary was never closed/);
+	});
+
+	it("offers reporting as the only per-row action", () => {
+		const html = render([base]);
+		assert.match(html, /Cut a bug/);
+		assert.doesNotMatch(html, /Try again|Retry/);
+	});
+});
+
+describe("QuarantineBugDialog", () => {
+	it("shows the whole report before anything is filed", () => {
+		const html = renderToString(
+			createElement(QuarantineBugDialog, {
+				entry: base,
+				onClose: noop,
+				onCopy: noop,
+				issueUrl: ISSUE_URL,
+			}),
+		);
+		assert.match(html, /UnterminatedMultipartBoundary/);
+		assert.match(html, /attachment names, or the parser's own error text/);
+		assert.match(html, /Copy report/);
+	});
+
+	it("never renders the parser's own error text into the report", () => {
+		const html = renderToString(
+			createElement(QuarantineBugDialog, {
+				entry: base,
+				onClose: noop,
+				onCopy: noop,
+				issueUrl: ISSUE_URL,
+			}),
+		);
+		// The row shows it; the report must not. Locked at the render boundary,
+		// which is where the regression would actually happen.
+		assert.doesNotMatch(html, /multipart boundary was never closed/);
+	});
+
+	it("files through the supplied url with hardened external rel", () => {
+		const html = renderToString(
+			createElement(QuarantineBugDialog, {
+				entry: base,
+				onClose: noop,
+				onCopy: noop,
+				issueUrl: ISSUE_URL,
+			}),
+		);
+		assert.match(html, /rel="noopener noreferrer"/);
+		assert.match(html, /focus-visible:ring-2/);
+	});
+
+	it("renders nothing without an entry", () => {
+		const html = renderToString(
+			createElement(QuarantineBugDialog, {
+				entry: null,
+				onClose: noop,
+				onCopy: noop,
+				issueUrl: ISSUE_URL,
+			}),
+		);
+		assert.equal(html, "");
+	});
+});

package/src/components/quarantine-section.stories.tsx

@@ -0,0 +1,74 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { useState } from "react";
+import { QuarantineBugDialog } from "./quarantine-bug-dialog.js";
+import { quarantineDemoEntries } from "./quarantine-fixtures.js";
+import type { QuarantineEntry } from "./quarantine-report.js";
+import { QuarantineSection } from "./quarantine-section.js";
+
+const [unterminatedBoundary, unknownCharset, truncatedBody] =
+	quarantineDemoEntries;
+
+/**
+ * Stands in for the app's shared bug-report helper, which owns the URL budget
+ * and the repository constant.
+ */
+const demoIssueUrl = "https://github.com/remit-mail/reader/issues/new";
+
+const meta: Meta<typeof QuarantineSection> = {
+	title: "Settings/Quarantine",
+	component: QuarantineSection,
+	parameters: { layout: "padded" },
+	args: { onCutBug: () => {} },
+	decorators: [
+		(Story) => (
+			<div className="mx-auto max-w-2xl">
+				<Story />
+			</div>
+		),
+	],
+};
+export default meta;
+
+type Story = StoryObj<typeof QuarantineSection>;
+
+export const Empty: Story = {
+	args: { entries: [] },
+};
+
+export const OneEntry: Story = {
+	args: { entries: [unterminatedBoundary] },
+};
+
+export const AlertState: Story = {
+	args: { entries: [unterminatedBoundary, unknownCharset, truncatedBody] },
+};
+
+export const CutABugFlow: Story = {
+	render: () => {
+		const [open, setOpen] = useState<QuarantineEntry | null>(null);
+		const [copied, setCopied] = useState(false);
+		return (
+			<>
+				<QuarantineSection entries={quarantineDemoEntries} onCutBug={setOpen} />
+				{copied && <p className="mt-3 text-xs text-positive">Report copied.</p>}
+				<QuarantineBugDialog
+					entry={open}
+					issueUrl={demoIssueUrl}
+					onClose={() => setOpen(null)}
+					onCopy={() => setCopied(true)}
+				/>
+			</>
+		);
+	},
+};
+
+export const BugReport: Story = {
+	render: () => (
+		<QuarantineBugDialog
+			entry={unterminatedBoundary}
+			issueUrl={demoIssueUrl}
+			onClose={() => {}}
+			onCopy={() => {}}
+		/>
+	),
+};

package/src/components/quarantine-section.tsx

@@ -0,0 +1,71 @@
+import { CheckCircle2, TriangleAlert } from "lucide-react";
+import { Banner } from "./banner.js";
+import { QuarantineEntryRow } from "./quarantine-entry-row.js";
+import type { QuarantineEntry } from "./quarantine-report.js";
+
+export interface QuarantineSectionProps {
+	entries: readonly QuarantineEntry[];
+	onCutBug: (entry: QuarantineEntry) => void;
+}
+
+/**
+ * The quarantine list in settings.
+ *
+ * A message that could not be read was never written, so it cannot be found
+ * anywhere else — this list is the only record that it existed. One entry is a
+ * fact and reads as one. More than one is a pattern, and a pattern is a bug, so
+ * it raises an alert.
+ */
+export function QuarantineSection({
+	entries,
+	onCutBug,
+}: QuarantineSectionProps) {
+	return (
+		<section className="space-y-3">
+			<header className="space-y-1">
+				<h2 className="text-sm font-semibold text-fg">Messages set aside</h2>
+				<p className="text-xs text-fg-muted">
+					Mail Remit could not read is set aside here instead of being skipped,
+					so nothing goes missing quietly. The rest of the folder keeps syncing.
+					Recovering a set-aside message is a re-sync, not a per-row action.
+				</p>
+			</header>
+
+			{entries.length === 0 && (
+				<div className="flex items-center gap-2 rounded-sm border border-line bg-surface px-row-inset py-3">
+					<CheckCircle2 className="size-4 shrink-0 text-positive" aria-hidden />
+					<p className="text-sm text-fg-muted">
+						Every message has been read successfully. Nothing is set aside.
+					</p>
+				</div>
+			)}
+
+			{entries.length > 1 && (
+				<Banner tone="warning">
+					<p className="flex items-start gap-2">
+						<TriangleAlert className="mt-0.5 size-4 shrink-0" aria-hidden />
+						<span>
+							<span className="font-semibold">
+								{`${entries.length} messages could not be read.`}
+							</span>{" "}
+							More than one means something is wrong with how Remit reads mail,
+							not with the mail. Reporting one of these gets it fixed.
+						</span>
+					</p>
+				</Banner>
+			)}
+
+			{entries.length > 0 && (
+				<ul className="rounded-sm border border-line bg-surface">
+					{entries.map((entry) => (
+						<QuarantineEntryRow
+							key={entry.quarantineId}
+							entry={entry}
+							onCutBug={onCutBug}
+						/>
+					))}
+				</ul>
+			)}
+		</section>
+	);
+}

package/src/components/selection-top-bar.stories.tsx

@@ -74,9 +74,15 @@ export const AllSelected: Story = {
 
 /**
  * The search has more matches than are loaded: an escalation notice offers a
- * real button (not prose) naming the total. Tapping it is what flips the
- * selection's identity from an id set to the search query (out of scope for
- * this kit — the caller supplies the count once paging resolves it).
+ * real button (not prose) naming the scope. Tapping it is what flips the
+ * selection's identity from an id set to the search query (`useEscalatedDelete`
+ * in web-client). No count in the label yet — the real client's own read path
+ * (`ThreadOperations.searchThreads`) only counts within a capped recency
+ * window short of paging the whole result set, and paging it just to seed a
+ * button label the user hasn't asked for yet would burn a request on every
+ * render of "all loaded selected" for a number that goes stale the moment new
+ * mail arrives. Tapping the button is what pays for the real count, via the
+ * counting state below.
  */
 export const EscalationAvailable: Story = {
 	args: {
@@ -90,7 +96,7 @@ export const EscalationAvailable: Story = {
 			tone: "info",
 			text: "",
 			action: {
-				label: 'Select all 3,412 matching "npm"',
+				label: 'Select all matching "npm"',
 				onClick: () => undefined,
 			},
 		},

package/src/index.ts

@@ -75,7 +75,12 @@ export {
 	BriefSections,
 	type BriefSectionsProps,
 } from "./components/brief-sections.js";
-export { Button, type ButtonProps } from "./components/button.js";
+export {
+	Button,
+	ButtonLink,
+	type ButtonLinkProps,
+	type ButtonProps,
+} from "./components/button.js";
 export {
 	Card,
 	CardBody,
@@ -243,6 +248,31 @@ export {
 	PullToRefresh,
 	type PullToRefreshProps,
 } from "./components/pull-to-refresh.js";
+export {
+	QuarantineBugDialog,
+	type QuarantineBugDialogProps,
+} from "./components/quarantine-bug-dialog.js";
+export {
+	QuarantineEntryRow,
+	type QuarantineEntryRowProps,
+} from "./components/quarantine-entry-row.js";
+export { quarantineDemoEntries } from "./components/quarantine-fixtures.js";
+export {
+	formatQuarantineReport,
+	QUARANTINE_REPORT_DISCLAIMER,
+	type QuarantineEntry,
+	type QuarantineFailureCode,
+	type QuarantineFailureStage,
+	type QuarantineMimeNode,
+	type QuarantineReportSections,
+	quarantineIssueTitle,
+	quarantineReportSections,
+	quarantineSummary,
+} from "./components/quarantine-report.js";
+export {
+	QuarantineSection,
+	type QuarantineSectionProps,
+} from "./components/quarantine-section.js";
 export {
 	QuotedText,
 	type QuotedTextProps,