@remit/ui 0.0.16 → 0.0.18

package/package.json

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

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

@@ -41,7 +41,11 @@ export function QuarantineEntryRow({
 					{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>
+					{entry.mailboxRole && (
+						<Badge tone="warning">
+							{canonicalRoleLabel(entry.mailboxRole)}
+						</Badge>
+					)}
 					<span className="truncate" title={entry.mailboxPath}>
 						{providerLeaf(entry.mailboxPath)}
 					</span>

package/src/components/quarantine-fixtures.ts

@@ -3,43 +3,42 @@ 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.
+ * drifted on the worker build when each file carried its own copy.
  */
 export const quarantineDemoEntries: readonly QuarantineEntry[] = [
 	{
 		quarantineId: "q-1",
 		accountId: "acct-1",
 		mailboxId: "mbx-inbox",
+		uidValidity: 1_712_000_000,
 		uid: 40217,
 		mailboxRole: "inbox",
 		mailboxPath: "INBOX",
 		failureStage: "BodyParse",
 		failureCode: "UnterminatedMultipartBoundary",
 		failureMessage: "multipart boundary was never closed",
-		failurePartPath: null,
+		failurePartPath: undefined,
 		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" },
-			],
-		},
+		structure: [
+			{ depth: 0, contentType: "multipart/mixed" },
+			{ depth: 1, contentType: "multipart/alternative" },
+			{ depth: 2, contentType: "text/plain" },
+			{ depth: 2, contentType: "text/html" },
+			{ depth: 1, contentType: "application/pdf" },
+		],
 		messageIdHash: "sha256:6f1c4a9d20",
-		appVersion: "worker 1.0.0",
+		workerVersion: "worker 1.0.0",
 	},
 	{
 		quarantineId: "q-2",
 		accountId: "acct-1",
 		mailboxId: "mbx-archive",
+		uidValidity: 1_712_000_100,
 		uid: 40219,
 		mailboxRole: "archive",
 		mailboxPath: "Archive/2026",
@@ -53,29 +52,57 @@ export const quarantineDemoEntries: readonly QuarantineEntry[] = [
 		contentType: "text/plain",
 		transferEncoding: "quoted-printable",
 		charset: "x-user-defined",
-		structure: { contentType: "text/plain" },
+		structure: [{ depth: 0, contentType: "text/plain" }],
 		messageIdHash: "sha256:b31e0744af",
-		appVersion: "worker 1.0.0",
+		workerVersion: "worker 1.0.0",
 	},
 	{
 		quarantineId: "q-3",
 		accountId: "acct-1",
 		mailboxId: "mbx-junk",
+		uidValidity: 1_712_000_200,
 		uid: 40251,
-		mailboxRole: "junk",
-		mailboxPath: "Junk",
+		// A folder the user never appointed a role to — the ordinary state of a
+		// plain folder, and the reason mailboxRole is optional.
+		mailboxRole: undefined,
+		mailboxPath: "Clients/Acme Holdings",
 		failureStage: "BodyParse",
 		failureCode: "TruncatedBody",
 		failureMessage: "stream ended before the declared body length",
-		failurePartPath: null,
+		failurePartPath: undefined,
 		quarantinedAt: Date.parse("2026-07-19T06:03:00Z"),
 		attempts: 1,
 		sizeBytes: 2_140,
 		contentType: "text/html",
 		transferEncoding: "base64",
-		charset: null,
-		structure: { contentType: "text/html" },
+		charset: undefined,
+		structure: [{ depth: 0, contentType: "text/html" }],
 		messageIdHash: "sha256:0a77de1c05",
-		appVersion: "worker 1.0.0",
+		workerVersion: "worker 1.0.0",
+	},
+	{
+		// The message shape is absent as a set: a message that failed before its
+		// BODYSTRUCTURE was read carries no content type, encoding, size or
+		// tree, and one that declared no Message-ID carries no hash either.
+		quarantineId: "q-4",
+		accountId: "acct-1",
+		mailboxId: "mbx-inbox",
+		uidValidity: 1_712_000_000,
+		uid: 40263,
+		mailboxRole: "inbox",
+		mailboxPath: "INBOX",
+		failureStage: "BodyParse",
+		failureCode: "TruncatedBody",
+		failureMessage: "connection closed mid-body",
+		failurePartPath: undefined,
+		quarantinedAt: Date.parse("2026-07-19T11:27:00Z"),
+		attempts: 2,
+		sizeBytes: undefined,
+		contentType: undefined,
+		transferEncoding: undefined,
+		charset: undefined,
+		structure: [],
+		messageIdHash: undefined,
+		workerVersion: "worker 1.0.0",
 	},
 ];

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

@@ -48,15 +48,13 @@ describe("formatQuarantineReport", () => {
 		const report = formatQuarantineReport({
 			...entry,
 			contentType: 'multipart/mixed; boundary="=_a1b2"',
-			structure: {
-				contentType: "multipart/mixed",
-				parts: [
-					{
-						contentType:
-							'application/octet-stream; name="Q3 payroll — Acme.pdf"',
-					},
-				],
-			},
+			structure: [
+				{ depth: 0, contentType: "multipart/mixed" },
+				{
+					depth: 1,
+					contentType: 'application/octet-stream; name="Q3 payroll — Acme.pdf"',
+				},
+			],
 		});
 		assert.doesNotMatch(report, /payroll/);
 		assert.doesNotMatch(report, /boundary/);
@@ -71,10 +69,39 @@ describe("formatQuarantineReport", () => {
 		);
 	});
 
+	it("says no role was appointed rather than inventing one", () => {
+		const report = formatQuarantineReport({
+			...entry,
+			mailboxRole: undefined,
+		});
+		assert.match(report, /Folder role.*none appointed/);
+	});
+
 	it("marks an undeclared charset rather than omitting it", () => {
-		const report = formatQuarantineReport({ ...entry, charset: null });
+		const report = formatQuarantineReport({ ...entry, charset: undefined });
 		assert.match(report, /Charset.*not declared/);
 	});
+
+	// Absent is the wire shape: the API omits an optional diagnostic and the
+	// repo maps a null column to undefined. A report that printed `undefined`
+	// into a public issue would do it on the common case — a whole-body parse
+	// failure has no failing part, which is every failure today.
+	it("never prints undefined for a diagnostic the message did not carry", () => {
+		const report = formatQuarantineReport({
+			...entry,
+			failurePartPath: undefined,
+			charset: undefined,
+			contentType: undefined,
+			transferEncoding: undefined,
+			sizeBytes: undefined,
+			messageIdHash: undefined,
+			structure: [],
+		});
+		assert.doesNotMatch(report, /undefined|null/);
+		assert.match(report, /Failing part.*whole message/);
+		assert.match(report, /Message-ID hash.*none declared/);
+		assert.match(report, /no MIME structure was read/);
+	});
 });
 
 describe("sender-controlled BODYSTRUCTURE strings", () => {
@@ -109,16 +136,38 @@ describe("sender-controlled BODYSTRUCTURE strings", () => {
 	it("keeps a hostile node type from closing the MIME fence", () => {
 		const report = formatQuarantineReport({
 			...entry,
-			structure: {
-				contentType: "multipart/mixed",
-				parts: [{ contentType: "```\n## Injected heading" }],
-			},
+			structure: [
+				{ depth: 0, contentType: "multipart/mixed" },
+				{ depth: 1, contentType: "```\n## Injected heading" },
+			],
 		});
 		assert.equal((report.match(/^```/gm) ?? []).length, 2);
 		assert.doesNotMatch(report, /^## Injected heading/m);
 	});
 });
 
+describe("a message that failed before its shape was read", () => {
+	const shapeless: QuarantineEntry = {
+		...entry,
+		contentType: undefined,
+		transferEncoding: undefined,
+		sizeBytes: undefined,
+		structure: [],
+	};
+
+	it("says the shape was never read rather than guessing one", () => {
+		const report = formatQuarantineReport(shapeless);
+		assert.match(report, /Content-Type.*not read/);
+		assert.match(report, /Content-Transfer-Encoding.*not read/);
+		assert.match(report, /Size.*not read/);
+	});
+
+	it("keeps the fence balanced with an empty tree", () => {
+		const report = formatQuarantineReport(shapeless);
+		assert.equal((report.match(/^```/gm) ?? []).length, 2);
+	});
+});
+
 describe("quarantineReportSections", () => {
 	it("hands the MIME tree over unfenced, so it can be truncated safely", () => {
 		const { head, structure, disclaimer } = quarantineReportSections(entry);

package/src/components/quarantine-report.ts

@@ -45,7 +45,12 @@ export type QuarantineFailureCode =
 	| "TruncatedBody";
 
 /**
- * A node in the message's MIME tree.
+ * One node of the message's MIME tree, in a pre-order walk.
+ *
+ * The tree arrives flat with an explicit `depth` rather than as nested
+ * children: a self-referential model is not expressible in the schema this
+ * comes from, and the tree is only ever rendered as an indented list, which a
+ * pre-order walk reproduces exactly.
  *
  * `contentType` is `type/subtype` only. BODYSTRUCTURE hands the type and its
  * parameters over separately, so a node is built from `type`/`subtype` and
@@ -53,8 +58,8 @@ export type QuarantineFailureCode =
  * `filename=`, which name the user's attachments.
  */
 export interface QuarantineMimeNode {
+	depth: number;
 	contentType: string;
-	parts?: readonly QuarantineMimeNode[];
 }
 
 /**
@@ -70,10 +75,19 @@ export interface QuarantineEntry {
 	quarantineId: string;
 	accountId: string;
 	mailboxId: string;
+	/**
+	 * UIDVALIDITY of the mailbox when the message was set aside. A uid names a
+	 * message only alongside it.
+	 */
+	uidValidity: number;
 	/** 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;
+	/**
+	 * Canonical role of the folder it arrived in — travels in the report.
+	 * Absent when the user appointed no role to that folder, which is the
+	 * ordinary state of a plain folder.
+	 */
+	mailboxRole?: FolderRole;
 	/** The user's own folder name. Shown on screen, withheld from the report. */
 	mailboxPath: string;
 	failureStage: QuarantineFailureStage;
@@ -81,26 +95,36 @@ export interface QuarantineEntry {
 	/** 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.
+	 * Dot-numbered part path the failure is attributable to. Absent when it is
+	 * not attributable to one node — the case for a whole-body parse failure,
+	 * which is every failure today.
 	 */
-	failurePartPath: string | null;
+	failurePartPath?: string;
 	/** Epoch millis the message was quarantined. */
 	quarantinedAt: number;
 	/** Rounds attempted before the message was set aside. */
 	attempts: number;
-	sizeBytes: number;
+	/**
+	 * The message-shape fields all come off BODYSTRUCTURE and RFC822.SIZE in
+	 * the same FETCH, so a message that failed before either was read carries
+	 * none of them — they are absent together, and `structure` is empty.
+	 */
+	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;
+	contentType?: string;
+	transferEncoding?: string;
+	/** Declared charset. Absent when the message declared none. */
+	charset?: string;
+	/** The MIME tree, structure only, as a pre-order walk. */
+	structure: readonly QuarantineMimeNode[];
+	/**
+	 * SHA-256 of the Message-ID, `sha256:` prefixed. Absent when the message
+	 * declared no Message-ID — a shared hash of nothing would correlate
+	 * unrelated reports.
+	 */
+	messageIdHash?: string;
 	/** Build of the worker that failed to parse — a parse bug belongs to it. */
-	appVersion: string;
+	workerVersion: string;
 }
 
 const stageSummaries: Record<QuarantineFailureStage, string> = {
@@ -146,13 +170,18 @@ function renderNodeType(contentType: string): string {
 	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)),
-	];
+/**
+ * What a message-shape field reads as when the message failed before its
+ * BODYSTRUCTURE was read. Distinct from "not declared", which is a statement
+ * about the message rather than about how far sync got.
+ */
+const NOT_READ = "_not read_";
+
+function renderStructure(nodes: readonly QuarantineMimeNode[]): string[] {
+	if (nodes.length === 0) return ["(no MIME structure was read)"];
+	return nodes.map(
+		(node) => `${"  ".repeat(node.depth)}- ${renderNodeType(node.contentType)}`,
+	);
 }
 
 export const QUARANTINE_REPORT_DISCLAIMER =
@@ -182,18 +211,18 @@ export function quarantineReportSections(
 		`### Message quarantined at \`${entry.failureStage}\``,
 		"",
 		`- **Failure**: \`${entry.failureCode}\``,
-		`- **Folder role**: ${entry.mailboxRole}`,
-		`- **Failing part**: ${entry.failurePartPath === null ? "_whole message_" : `\`${entry.failurePartPath}\``}`,
+		`- **Folder role**: ${entry.mailboxRole ?? "_none appointed_"}`,
+		`- **Failing part**: ${entry.failurePartPath == null ? "_whole message_" : `\`${entry.failurePartPath}\``}`,
 		`- **Attempts before quarantine**: ${entry.attempts}`,
-		`- **Worker build**: ${entry.appVersion}`,
-		`- **Message-ID hash**: \`${entry.messageIdHash}\``,
+		`- **Worker build**: ${entry.workerVersion}`,
+		`- **Message-ID hash**: ${entry.messageIdHash == null ? "_none declared_" : `\`${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`,
+		`- **Content-Type**: ${entry.contentType == null ? NOT_READ : renderToken(stripParameters(entry.contentType), MEDIA_TYPE)}`,
+		`- **Content-Transfer-Encoding**: ${entry.transferEncoding == null ? NOT_READ : renderToken(entry.transferEncoding, TOKEN)}`,
+		`- **Charset**: ${entry.charset == null ? "_not declared_" : renderToken(entry.charset, TOKEN)}`,
+		`- **Size**: ${entry.sizeBytes == null ? NOT_READ : `${entry.sizeBytes} bytes`}`,
 		"",
 		"MIME structure:",
 	].join("\n");

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

@@ -8,7 +8,7 @@ import type { QuarantineEntry } from "./quarantine-report.js";
 import { QuarantineSection } from "./quarantine-section.js";
 
 const noop = () => {};
-const [base, second] = quarantineDemoEntries;
+const [base, second, unappointedFolder] = quarantineDemoEntries;
 const ISSUE_URL = "https://github.com/remit-mail/reader/issues/new?title=x";
 
 const render = (entries: readonly QuarantineEntry[]) =>
@@ -38,6 +38,12 @@ describe("QuarantineSection", () => {
 		assert.match(html, /multipart boundary was never closed/);
 	});
 
+	it("names no role for a folder the user never appointed one to", () => {
+		const html = render([unappointedFolder]);
+		assert.doesNotMatch(html, /Inbox|Spam|Archive/);
+		assert.match(html, /Acme Holdings/);
+	});
+
 	it("offers reporting as the only per-row action", () => {
 		const html = render([base]);
 		assert.match(html, /Cut a bug/);

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

@@ -5,7 +5,7 @@ import { quarantineDemoEntries } from "./quarantine-fixtures.js";
 import type { QuarantineEntry } from "./quarantine-report.js";
 import { QuarantineSection } from "./quarantine-section.js";
 
-const [unterminatedBoundary, unknownCharset, truncatedBody] =
+const [unterminatedBoundary, unknownCharset, truncatedBody, shapeUnread] =
 	quarantineDemoEntries;
 
 /**
@@ -62,6 +62,22 @@ export const CutABugFlow: Story = {
 	},
 };
 
+/**
+ * A message that failed before its BODYSTRUCTURE was read carries no content
+ * type, encoding, size or MIME tree, and one that declared no Message-ID
+ * carries no hash. The report says so rather than printing an empty value.
+ */
+export const BugReportWithoutMessageShape: Story = {
+	render: () => (
+		<QuarantineBugDialog
+			entry={shapeUnread}
+			issueUrl={demoIssueUrl}
+			onClose={() => {}}
+			onCopy={() => {}}
+		/>
+	),
+};
+
 export const BugReport: Story = {
 	render: () => (
 		<QuarantineBugDialog

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,
 			},
 		},