@remit/web-client 0.0.158 → 0.0.160

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/web-client",
-  "version": "0.0.158",
+  "version": "0.0.160",
   "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": {
@@ -30,7 +30,7 @@
     "build:dist": "npm run generate:routes && node --import tsx harness/build.mjs",
     "preview": "vite preview",
     "test:typecheck": "npm run generate:routes && tsgo --noEmit && tsgo --noEmit -p tsconfig.node.json",
-    "test:run": "TSX_TSCONFIG_PATH=./tsconfig.test.json node $NODE_TEST_FLAGS --import tsx --import ./test-support/register.mjs --experimental-test-coverage --test-coverage-include='src/**' --test-coverage-exclude='src/**/*.test.ts' --test-coverage-exclude='src/**/*.test.tsx' --test-coverage-exclude='src/test-support/**' --test-coverage-lines=86 --test 'src/**/*.test.ts'",
+    "test:run": "TSX_TSCONFIG_PATH=./tsconfig.test.json node $NODE_TEST_FLAGS --import tsx --import ./test-support/register.mjs --experimental-test-coverage --test-coverage-include='src/**' --test-coverage-exclude='src/**/*.test.ts' --test-coverage-exclude='src/**/*.test.tsx' --test-coverage-exclude='src/test-support/**' --test-coverage-lines=86 --test 'src/**/*.test.ts' 'spellcheck/**/*.test.ts'",
     "test": "npm run test:typecheck && npm run test:run"
   },
   "peerDependencies": {

package/spellcheck/empty-build.test.ts

@@ -0,0 +1,160 @@
+/**
+ * The self-hoster's opt-out, proven by building it.
+ *
+ * `REMIT_SPELLCHECK_LANGUAGES=` is the documented way to build an image with no
+ * spellchecker — a small box, or an operator who does not want to carry
+ * somebody else's licence obligations. What it has to produce is a *clean*
+ * build: a web client that works, with no `spellcheck/` tree to serve, and none
+ * of the worker's code shipped to browsers that can never start it. Nothing
+ * short of a real build can tell those apart from a broken one, so this runs
+ * vite twice and reads the output.
+ *
+ * The second build is the control. Asserting only that an empty list emits no
+ * worker chunk would pass just as well if the chunk were renamed, if the
+ * composer stopped reaching the worker at all, or if the build quietly produced
+ * nothing — so the same assertions are made against a build that must carry it.
+ */
+
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, readdirSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, relative, resolve, sep } from "node:path";
+import { after, before, describe, it } from "node:test";
+
+const packageRoot = resolve(import.meta.dirname, "..");
+
+const BUILD_TIMEOUT_MS = 600_000;
+
+const outputs: string[] = [];
+
+// A child process, because the language set is read out of the environment when
+// the plugin configures itself and two builds in one process would share it.
+const build = (languages: string): readonly string[] => {
+	const outDir = mkdtempSync(join(tmpdir(), "spellcheck-build-"));
+	outputs.push(outDir);
+	const result = spawnSync(
+		process.execPath,
+		[
+			"--input-type=module",
+			"-e",
+			`import { build } from "vite";
+			 await build({
+				 logLevel: "warn",
+				 build: { outDir: ${JSON.stringify(outDir)}, emptyOutDir: true },
+			 });`,
+		],
+		{
+			cwd: packageRoot,
+			encoding: "utf8",
+			env: { ...process.env, REMIT_SPELLCHECK_LANGUAGES: languages },
+		},
+	);
+	assert.equal(
+		result.status,
+		0,
+		`vite build with REMIT_SPELLCHECK_LANGUAGES="${languages}" failed:\n${result.stdout}\n${result.stderr}`,
+	);
+	return emitted(outDir);
+};
+
+const emitted = (root: string): readonly string[] => {
+	const found: string[] = [];
+	const walk = (current: string): void => {
+		for (const entry of readdirSync(current, { withFileTypes: true })) {
+			const full = join(current, entry.name);
+			if (entry.isDirectory()) {
+				walk(full);
+				continue;
+			}
+			found.push(relative(root, full).split(sep).join("/"));
+		}
+	};
+	walk(root);
+	return found.sort();
+};
+
+/**
+ * The worker, the port it speaks over, and the bundle vite emits for the `new
+ * Worker(new URL(...))` that reaches it. Vite emits that bundle while
+ * transforming the module rather than while writing the output, so it survives
+ * tree-shaking: its absence means the specifier never resolved there at all.
+ */
+const workerChunks = (files: readonly string[]): readonly string[] =>
+	files.filter((file) => /rich-text-spellcheck-/.test(file));
+
+const spellcheckAssets = (files: readonly string[]): readonly string[] =>
+	files.filter((file) => file.startsWith("spellcheck/"));
+
+describe("a build that carries no dictionaries", () => {
+	let files: readonly string[] = [];
+
+	before(
+		() => {
+			files = build("");
+		},
+		{ timeout: BUILD_TIMEOUT_MS },
+	);
+
+	after(() => {
+		for (const outDir of outputs)
+			rmSync(outDir, { recursive: true, force: true });
+	});
+
+	it("is still a web client", () => {
+		assert.ok(files.includes("index.html"), "the build emitted no index.html");
+		assert.ok(
+			files.some((file) => file.startsWith("assets/") && file.endsWith(".js")),
+			"the build emitted no JavaScript",
+		);
+	});
+
+	it("serves no spellcheck tree", () => {
+		assert.deepEqual(spellcheckAssets(files), []);
+	});
+
+	it("ships no worker to browsers that could never start it", () => {
+		assert.deepEqual(workerChunks(files), []);
+	});
+});
+
+describe("a build that carries one", () => {
+	let files: readonly string[] = [];
+
+	before(
+		() => {
+			files = build("nl");
+		},
+		{ timeout: BUILD_TIMEOUT_MS },
+	);
+
+	it("stages the engine, the dictionary and the notice", () => {
+		// The staged directory is named after a digest of its own contents, so
+		// what is asserted is the tree under it rather than the whole path.
+		const staged = spellcheckAssets(files).map((file) =>
+			file.replace(/^spellcheck\/[0-9a-f]+\//, ""),
+		);
+		// English rides along whether or not it was asked for: it is the language
+		// every account is guaranteed to offer.
+		assert.deepEqual(staged.sort(), [
+			"LICENSE",
+			"NOTICE.txt",
+			"dictionaries/en/LICENSE",
+			"dictionaries/en/index.aff",
+			"dictionaries/en/index.dic",
+			"dictionaries/nl/LICENSE",
+			"dictionaries/nl/index.aff",
+			"dictionaries/nl/index.dic",
+			"hunspell.mjs",
+			"hunspell.wasm",
+			"license.hunspell",
+			"manifest.json",
+		]);
+	});
+
+	// The control for the two assertions above: both names are real, and a build
+	// that should carry them does.
+	it("ships the worker the empty build must not", () => {
+		assert.notDeepEqual(workerChunks(files), []);
+	});
+});

package/spellcheck/languages.test.ts

@@ -0,0 +1,80 @@
+/**
+ * The switch, at the point where a self-hoster's `REMIT_SPELLCHECK_LANGUAGES`
+ * becomes the set the image carries. Everything downstream — the staged files,
+ * the manifest, NOTICE.txt, and what the composer believes it can check — is
+ * that set and nothing else, so a wrong answer here is wrong everywhere at once.
+ */
+
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import {
+	DEFAULT_SPELLCHECK_LANGUAGES,
+	DICTIONARY_SOURCES,
+	resolveLanguages,
+} from "./languages.ts";
+
+const tagsOf = (requested: string | undefined): readonly string[] =>
+	resolveLanguages(requested).map((source) => source.tag);
+
+describe("the language set an image is built with", () => {
+	it("carries the published default when nothing is asked for", () => {
+		assert.deepEqual(
+			tagsOf(undefined),
+			DEFAULT_SPELLCHECK_LANGUAGES.split(","),
+		);
+	});
+
+	// `defaultComposeLanguages` appends `en` to every account, so an image
+	// without it would leave the one language every account offers as the one
+	// language it cannot check.
+	it("carries English whether or not it was asked for", () => {
+		assert.deepEqual(tagsOf("nl"), ["en", "nl"]);
+		assert.equal(tagsOf("en,nl")[0], "en");
+	});
+
+	it("reads a tag the same however it was typed, and carries it once", () => {
+		assert.deepEqual(tagsOf(" nl , EN-gb ,nl, en "), ["en", "nl", "en-GB"]);
+	});
+
+	// The self-hoster's opt-out. An empty list is a legitimate answer and not a
+	// typo to be corrected into the default, so it does not acquire English.
+	it("carries nothing at all when the list is empty", () => {
+		assert.deepEqual(tagsOf(""), []);
+		assert.deepEqual(tagsOf("  "), []);
+		assert.deepEqual(tagsOf(",, ,"), []);
+	});
+
+	it("hands back the whole row, not just the tag", () => {
+		const [english] = resolveLanguages("en");
+		assert.equal(english.package, "dictionary-en");
+		assert.ok(english.licence.length > 0);
+		assert.ok(english.source.startsWith("https://"));
+	});
+
+	// A tag nobody can ship must stop the build rather than quietly produce an
+	// image whose NOTICE.txt is a list of what the operator asked for.
+	it("stops on a tag no dictionary covers, and says which one", () => {
+		assert.throws(
+			() => resolveLanguages("en,nl,fi"),
+			(failed: Error) => {
+				assert.match(failed.message, /"fi"/);
+				assert.match(
+					failed.message,
+					/packages\/web-client\/spellcheck\/languages/,
+				);
+				// The remedy is picking a known tag, so the message lists them.
+				for (const source of DICTIONARY_SOURCES) {
+					assert.ok(
+						failed.message.includes(source.tag),
+						`the failure does not offer ${source.tag}`,
+					);
+				}
+				return true;
+			},
+		);
+	});
+
+	it("stops on an unknown tag even when every other tag is known", () => {
+		assert.throws(() => resolveLanguages("nl,de"), /"de"/);
+	});
+});

package/spellcheck/vite-plugin-licence.test.ts

@@ -0,0 +1,92 @@
+/**
+ * A dictionary whose licence text cannot travel with it must stop the build.
+ *
+ * Every licence in the table obliges the text to ship alongside the files, and
+ * the build generates NOTICE.txt from the same rows — so a package that lost its
+ * licence file (an upstream repackage, a pruned install) would otherwise produce
+ * an image whose notice points at a `LICENSE` nobody staged. That is the one
+ * failure mode a reader cannot see and a distributor is answerable for.
+ *
+ * The dictionary is shadowed rather than the real one damaged: node resolves
+ * from the importer outwards, so a package planted in this directory's own
+ * `node_modules` answers for `dictionary-en-gb` here and nowhere else. That
+ * makes this file its own process — node's test runner gives each file one —
+ * because module resolution is cached per process and a sibling test resolving
+ * the real package first would decide which one this sees.
+ */
+
+import assert from "node:assert/strict";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { after, describe, it } from "node:test";
+
+const shadowRoot = join(import.meta.dirname, "node_modules");
+const shadow = join(shadowRoot, "dictionary-en-gb");
+mkdirSync(shadow, { recursive: true });
+writeFileSync(
+	join(shadow, "package.json"),
+	JSON.stringify({ name: "dictionary-en-gb", version: "0.0.0-shadow" }),
+);
+writeFileSync(join(shadow, "index.js"), "");
+writeFileSync(join(shadow, "index.aff"), "SET UTF-8\n");
+writeFileSync(join(shadow, "index.dic"), "1\nword\n");
+
+const engineDir = mkdtempSync(join(tmpdir(), "spellcheck-engine-"));
+for (const name of [
+	"hunspell.wasm",
+	"hunspell.mjs",
+	"LICENSE",
+	"license.hunspell",
+]) {
+	writeFileSync(join(engineDir, name), "stub");
+}
+process.env.REMIT_SPELLCHECK_ENGINE_DIR = engineDir;
+
+const { stageSpellcheck } = await import("./vite-plugin.ts");
+
+after(() => {
+	rmSync(shadow, { recursive: true, force: true });
+	rmSync(shadowRoot, { recursive: true, force: true });
+	rmSync(engineDir, { recursive: true, force: true });
+});
+
+describe("a dictionary that ships no licence text", () => {
+	it("stops the build rather than staging it", () => {
+		assert.throws(() => stageSpellcheck("en-GB", "/"));
+	});
+
+	// The remedy is the whole message: which directory, and why a missing
+	// licence file is fatal rather than something the notice can paper over.
+	it("names the directory and what is wrong with it", () => {
+		assert.throws(
+			() => stageSpellcheck("en-GB", "/"),
+			(failed: Error) => {
+				assert.ok(
+					failed.message.includes(shadow),
+					`the failure does not name the dictionary directory: ${failed.message}`,
+				);
+				assert.match(failed.message, /licence/i);
+				assert.match(failed.message, /NOTICE\.txt/);
+				return true;
+			},
+		);
+	});
+
+	// The languages before the broken one must not reach the output either: a
+	// half-staged tree with a complete-looking notice is worse than no build.
+	it("takes the whole build with it, not just that language", () => {
+		assert.throws(() => stageSpellcheck("en,en-GB", "/"));
+	});
+});
+
+describe("a dictionary that does ship one", () => {
+	it("stages the licence text beside the files it covers", () => {
+		const build = stageSpellcheck("en", "/");
+		const licence = build.files.find(
+			(file) => file.path === "dictionaries/en/LICENSE",
+		);
+		assert.ok(licence);
+		assert.ok(licence.source.byteLength > 0);
+	});
+});

package/spellcheck/vite-plugin.test.ts

@@ -0,0 +1,230 @@
+/**
+ * What the build stages, and whether NOTICE.txt describes it.
+ *
+ * The licence obligation this repo took on is that the notice matches the image
+ * exactly and that the served dictionary is the upstream file — which is the
+ * whole reason the language set is fixed at build time rather than chosen at
+ * run time. A notice that names a dictionary the image does not carry, or omits
+ * one it does, is a licence failure and not a cosmetic one, so the chain from
+ * the resolved set through the manifest to the notice is asserted end to end
+ * rather than at either end.
+ *
+ * This runs in the checkout, against the dictionary packages actually
+ * installed, which is what makes the byte-for-byte and licence-text assertions
+ * mean anything. `npm-scripts/lib/spellcheck-staging.test.mjs` is the other
+ * half: the same function against a synthetic tree shaped like the published
+ * package, where the question is which file gets read and what a distributor is
+ * told when one is missing. Base, `servePath` and the digest belong to that
+ * one.
+ *
+ * The engine is stubbed: what it weighs is gated where it is built
+ * (npm-scripts/build-hunspell.mjs), and staging it here would make every one of
+ * these tests wait on a WebAssembly toolchain.
+ */
+
+import assert from "node:assert/strict";
+import { mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { describe, it } from "node:test";
+
+const require = createRequire(import.meta.url);
+
+const ENGINE_FILES = {
+	"hunspell.wasm": "\0asm stub",
+	"hunspell.mjs": "export default () => {};",
+	LICENSE: "Mozilla Public Licence 1.1, stub",
+	"license.hunspell": "Hunspell licence, stub",
+};
+
+const engineDir = mkdtempSync(join(tmpdir(), "spellcheck-engine-"));
+for (const [name, body] of Object.entries(ENGINE_FILES)) {
+	writeFileSync(join(engineDir, name), body);
+}
+
+process.env.REMIT_SPELLCHECK_ENGINE_DIR = engineDir;
+const { stageSpellcheck } = await import("./vite-plugin.ts");
+
+const staged = (requested: string) => stageSpellcheck(requested, "/");
+
+const fileNamed = (
+	build: ReturnType<typeof staged>,
+	path: string,
+): Buffer | undefined => build.files.find((file) => file.path === path)?.source;
+
+const textOf = (build: ReturnType<typeof staged>, path: string): string => {
+	const found = fileNamed(build, path);
+	if (!found) throw new Error(`${path} was not staged`);
+	return found.toString("utf8");
+};
+
+/** The tags NOTICE.txt claims this image carries, read back off the notice. */
+const tagsNoticed = (notice: string): readonly string[] => {
+	const dictionaries = notice.split("\nDictionaries\n")[1];
+	if (dictionaries === undefined) {
+		throw new Error("NOTICE.txt has no Dictionaries section");
+	}
+	return dictionaries
+		.split("\n")
+		.map((line) => /^(\S+) — /.exec(line)?.[1])
+		.filter((tag): tag is string => tag !== undefined);
+};
+
+/** The tags the image actually carries a dictionary for. */
+const tagsStaged = (build: ReturnType<typeof staged>): readonly string[] => [
+	...new Set(
+		build.files
+			.map((file) => /^dictionaries\/([^/]+)\//.exec(file.path)?.[1])
+			.filter((tag): tag is string => tag !== undefined),
+	),
+];
+
+describe("what a build stages", () => {
+	it("stages the engine, both dictionary files and a licence per language", () => {
+		const build = staged("en,nl");
+		const paths = build.files.map((file) => file.path).sort();
+		assert.deepEqual(paths, [
+			"LICENSE",
+			"NOTICE.txt",
+			"dictionaries/en/LICENSE",
+			"dictionaries/en/index.aff",
+			"dictionaries/en/index.dic",
+			"dictionaries/nl/LICENSE",
+			"dictionaries/nl/index.aff",
+			"dictionaries/nl/index.dic",
+			"hunspell.mjs",
+			"hunspell.wasm",
+			"license.hunspell",
+			"manifest.json",
+		]);
+	});
+
+	// GPL and MPL correspondence is discharged by the served file being the
+	// upstream one. Anything that rewrote a dictionary on the way through —
+	// a normaliser, a re-encode, a line-ending fix — would break that quietly.
+	it("serves the upstream dictionary byte for byte", () => {
+		const build = staged("nl");
+		const upstream = dirname(require.resolve("dictionary-nl"));
+		for (const name of ["index.aff", "index.dic"]) {
+			assert.deepEqual(
+				fileNamed(build, `dictionaries/nl/${name}`),
+				readFileSync(join(upstream, name)),
+				`dictionaries/nl/${name} is not the upstream file`,
+			);
+		}
+	});
+});
+
+describe("NOTICE.txt", () => {
+	it("names every language the image carries", () => {
+		const build = staged("en,en-GB,nl");
+		const noticed = tagsNoticed(textOf(build, "NOTICE.txt"));
+		assert.deepEqual([...noticed].sort(), ["en", "en-GB", "nl"]);
+	});
+
+	// Over-claiming is the failure that matters: a notice listing a dictionary
+	// the image does not carry offers a licence text nobody can find, and one
+	// missing a dictionary it does carry ships that dictionary with no licence
+	// at all. Both are the same defect from opposite sides, so the three lists
+	// the build produces are compared to each other rather than to a fixture.
+	it("names only the languages the image carries", () => {
+		for (const requested of ["en", "nl", "en,en-GB,nl"]) {
+			const build = staged(requested);
+			const notice = textOf(build, "NOTICE.txt");
+			const carried = tagsStaged(build);
+			const manifest = JSON.parse(textOf(build, "manifest.json"));
+
+			assert.deepEqual(
+				[...tagsNoticed(notice)].sort(),
+				[...carried].sort(),
+				`NOTICE.txt and the staged dictionaries disagree for "${requested}"`,
+			);
+			assert.deepEqual(
+				manifest.languages.map((language: { tag: string }) => language.tag),
+				build.languages.map((language) => language.tag),
+			);
+			assert.deepEqual(
+				[...carried].sort(),
+				build.languages.map((language) => language.tag).sort(),
+			);
+		}
+	});
+
+	it("points every language at a licence text the image ships", () => {
+		const build = staged("en,en-GB,nl");
+		const notice = textOf(build, "NOTICE.txt");
+		const referenced = [...notice.matchAll(/Licence text: (\S+?),/g)]
+			.map((match) => match[1])
+			.sort();
+		assert.deepEqual(referenced, [
+			"LICENSE",
+			"dictionaries/en-GB/LICENSE",
+			"dictionaries/en/LICENSE",
+			"dictionaries/nl/LICENSE",
+		]);
+		for (const path of referenced) {
+			const licence = fileNamed(build, path);
+			assert.ok(licence, `NOTICE.txt names ${path}, which is not staged`);
+			assert.ok(licence.byteLength > 0, `${path} is empty`);
+		}
+	});
+
+	it("states each licence, its author and the version that was staged", () => {
+		const build = staged("nl");
+		const notice = textOf(build, "NOTICE.txt");
+		const [dutch] = build.languages.filter((language) => language.tag === "nl");
+		assert.match(notice, /nl — OpenTaal/);
+		assert.ok(notice.includes(`Licence: ${dutch.licence}`));
+		assert.ok(notice.includes(`Authors: ${dutch.authors}`));
+		assert.ok(notice.includes(`dictionary-nl@${dutch.version}`));
+		assert.match(dutch.version, /^\d+\.\d+\.\d+/);
+	});
+
+	it("says the served files are the source where a licence requires it", () => {
+		const gpl = textOf(staged("nl,en"), "NOTICE.txt");
+		// Neither English nor Dutch is under a correspondence licence here, so
+		// the sentence must not appear; German would bring it.
+		assert.ok(!gpl.includes("unmodified upstream source"));
+	});
+
+	it("carries the engine's own provenance, checksum included", () => {
+		const notice = textOf(staged("en"), "NOTICE.txt");
+		const pins = readFileSync(
+			join(
+				import.meta.dirname,
+				"..",
+				"..",
+				"..",
+				"docker",
+				"hunspell",
+				"pin.env",
+			),
+			"utf8",
+		);
+		const version = /HUNSPELL_VERSION=(\S+)/.exec(pins)?.[1];
+		const sha = /HUNSPELL_SHA256=(\S+)/.exec(pins)?.[1];
+		assert.ok(version && sha);
+		assert.ok(notice.includes(`Hunspell ${version}`));
+		assert.ok(notice.includes(sha));
+	});
+});
+
+describe("the manifest the app reads", () => {
+	it("describes the engine and every language it staged", () => {
+		const build = staged("en,nl");
+		const manifest = JSON.parse(textOf(build, "manifest.json"));
+		assert.equal(manifest.engine.project, "Hunspell");
+		assert.equal(manifest.engine.licence, "MPL-1.1");
+		assert.deepEqual(
+			manifest.languages.map(
+				(language: { licenceFile: string }) => language.licenceFile,
+			),
+			["dictionaries/en/LICENSE", "dictionaries/nl/LICENSE"],
+		);
+		for (const language of manifest.languages) {
+			assert.ok(fileNamed(build, language.licenceFile));
+			assert.match(language.package, /@\d+\.\d+\.\d+/);
+		}
+	});
+});

package/spellcheck/worker-stub.ts

@@ -0,0 +1,36 @@
+/**
+ * Keeps the spellchecking worker out of a build that staged no dictionaries.
+ *
+ * Vite emits a worker bundle for whatever module graph reaches a `new
+ * Worker(new URL(...))`, and it emits it while transforming that module —
+ * before tree-shaking, and whether or not anything in the output still imports
+ * it. So a dead branch around the dynamic import is not enough on its own: the
+ * bundle is already a file by the time the branch is dropped. The only way the
+ * worker never becomes an asset is for the specifier never to resolve to it.
+ *
+ * The decision is `resolveLanguages`, the same function the staging plugin
+ * asks, so there is no second answer to what this build carries.
+ */
+
+import type { Plugin } from "vite";
+import { resolveLanguages } from "./languages.ts";
+
+const WORKER_MODULE = "@remit/ui/spellcheck-worker";
+const STUB = "\0remit-spellcheck-absent";
+
+export const spellcheckWorkerStub = (): Plugin => ({
+	name: "remit-spellcheck-worker-stub",
+	enforce: "pre",
+	resolveId(source) {
+		if (source !== WORKER_MODULE) return null;
+		const staged = resolveLanguages(process.env.REMIT_SPELLCHECK_LANGUAGES);
+		return staged.length === 0 ? STUB : null;
+	},
+	load(id) {
+		// The provider's own contract for a language it cannot check: answer null,
+		// start no worker, and leave the browser's checking switched on.
+		return id === STUB
+			? "export const openSpellcheckWorker = async () => null;\n"
+			: null;
+	},
+});

package/src/components/settings/QuarantinePanel.render.test.ts

@@ -0,0 +1,71 @@
+/**
+ * The pane in Settings › Advanced that is the only place a quarantined message
+ * is ever mentioned. Every read state has to say something: an empty list is
+ * the normal one, and a failed read is never a blank panel.
+ */
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { type QuarantineEntry, quarantineDemoEntries } from "@remit/ui";
+import React, { createElement } from "react";
+import { renderToString } from "react-dom/server";
+import { QuarantinePanelView } from "./QuarantinePanel";
+
+// See MessageToolbar.render.test.ts: the SSR test loader transpiles remit-ui
+// `.tsx` with the classic JSX runtime, which needs a global `React`.
+(globalThis as { React?: typeof React }).React = React;
+
+const render = (props: {
+	entries: readonly QuarantineEntry[];
+	isPending: boolean;
+	error: Error | null;
+}): string =>
+	renderToString(createElement(QuarantinePanelView, props) as never);
+
+describe("QuarantinePanelView", () => {
+	it("says nothing was set aside rather than rendering nothing", () => {
+		const html = render({ entries: [], isPending: false, error: null });
+		assert.match(html, /Messages set aside/);
+		assert.match(html, /Nothing is set aside/);
+	});
+
+	it("lists a set-aside message with a way to report it", () => {
+		const html = render({
+			entries: quarantineDemoEntries.slice(0, 1),
+			isPending: false,
+			error: null,
+		});
+		assert.match(html, /Cut a bug/);
+		assert.match(html, /could not read/i);
+	});
+
+	it("calls more than one set aside a pattern, not a list", () => {
+		const html = render({
+			entries: quarantineDemoEntries,
+			isPending: false,
+			error: null,
+		});
+		assert.match(
+			html,
+			new RegExp(`${quarantineDemoEntries.length} messages could not be read`),
+		);
+	});
+
+	it("reports a failed read in the pane, with a way to file it", () => {
+		const html = render({
+			entries: [],
+			isPending: false,
+			error: new Error("Failed to fetch"),
+		});
+		assert.match(html, /role="alert"/);
+		assert.match(html, /could not be read/);
+		assert.match(html, /Failed to fetch/);
+		assert.match(html, /Report this/);
+		assert.doesNotMatch(html, /Nothing is set aside/);
+	});
+
+	it("says it is still reading rather than claiming an empty list", () => {
+		const html = render({ entries: [], isPending: true, error: null });
+		assert.match(html, /Checking for messages set aside/);
+		assert.doesNotMatch(html, /Nothing is set aside/);
+	});
+});

package/src/components/settings/QuarantinePanel.tsx

@@ -0,0 +1,136 @@
+/**
+ * Settings › Advanced — the messages sync set aside.
+ *
+ * A quarantined message exists on the server and nowhere else in the app, so
+ * this pane is the only place it is ever mentioned. Three states are all
+ * visible: the list, the reassurance that there is nothing in it, and the
+ * failure to read it at all. None of them is an empty panel.
+ */
+import { meOperationsListQuarantineOptions } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import {
+	Button,
+	QuarantineBugDialog,
+	type QuarantineEntry,
+	QuarantineSection,
+	quarantineIssueTitle,
+	quarantineReportSections,
+} from "@remit/ui";
+import { useQuery } from "@tanstack/react-query";
+import { Bug } from "lucide-react";
+import { useState } from "react";
+import { formatErrorMessage } from "@/components/ui/ErrorState";
+import { buildBugReportContext, buildGitHubIssueUrl } from "@/lib/bug-report";
+import { toQuarantineEntry } from "@/lib/quarantine-entries";
+
+function openIssue(url: string): void {
+	window.open(url, "_blank", "noopener,noreferrer");
+}
+
+function issueUrlFor(entry: QuarantineEntry): string {
+	return buildGitHubIssueUrl(
+		buildBugReportContext({
+			quarantine: quarantineReportSections(entry),
+			title: quarantineIssueTitle(entry),
+		}),
+	);
+}
+
+function QuarantineReadFailure({ error }: { error: Error }) {
+	return (
+		<section role="alert" className="space-y-3">
+			<h2 className="text-sm font-semibold text-fg">Messages set aside</h2>
+			<div className="space-y-2 rounded-sm border border-danger/40 bg-danger-soft px-row-inset py-3">
+				<p className="text-sm font-medium text-danger">
+					The list of set-aside messages could not be read.
+				</p>
+				<p className="break-words text-sm text-fg-muted">
+					{formatErrorMessage(error)}
+				</p>
+				<p className="text-xs text-fg-muted">
+					Mail may still have been set aside — this page cannot say either way
+					until it can read the list. Reporting this gets it fixed.
+				</p>
+				<Button
+					variant="secondary"
+					size="sm"
+					icon={<Bug className="size-3.5" />}
+					onClick={() =>
+						openIssue(buildGitHubIssueUrl(buildBugReportContext()))
+					}
+				>
+					Report this
+				</Button>
+			</div>
+		</section>
+	);
+}
+
+export interface QuarantinePanelViewProps {
+	entries: readonly QuarantineEntry[];
+	isPending: boolean;
+	error: Error | null;
+}
+
+export function QuarantinePanelView({
+	entries,
+	isPending,
+	error,
+}: QuarantinePanelViewProps) {
+	const [reporting, setReporting] = useState<QuarantineEntry | null>(null);
+	const [copyFailed, setCopyFailed] = useState(false);
+
+	if (isPending) {
+		return (
+			<p className="animate-pulse text-sm text-fg-subtle">
+				Checking for messages set aside…
+			</p>
+		);
+	}
+
+	if (error) return <QuarantineReadFailure error={error} />;
+
+	const handleCopy = (report: string) => {
+		navigator.clipboard.writeText(report).then(
+			() => {
+				setCopyFailed(false);
+				setReporting(null);
+			},
+			() => {
+				setCopyFailed(true);
+				setReporting(null);
+			},
+		);
+	};
+
+	return (
+		<>
+			{copyFailed && (
+				<p role="alert" className="mb-3 text-sm text-danger">
+					The report was not copied — this browser refused clipboard access. Cut
+					the bug again and use Open on GitHub, which needs no clipboard.
+				</p>
+			)}
+			<QuarantineSection entries={entries} onCutBug={setReporting} />
+			<QuarantineBugDialog
+				entry={reporting}
+				issueUrl={reporting ? issueUrlFor(reporting) : ""}
+				onClose={() => setReporting(null)}
+				onCopy={handleCopy}
+			/>
+		</>
+	);
+}
+
+export function QuarantinePanel() {
+	const { data, isPending, error } = useQuery(
+		meOperationsListQuarantineOptions(),
+	);
+
+	return (
+		<QuarantinePanelView
+			entries={(data?.entries ?? []).map(toQuarantineEntry)}
+			isPending={isPending}
+			error={error}
+		/>
+	);
+}

package/src/lib/quarantine-entries.test.ts

@@ -0,0 +1,72 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import type { RemitImapQuarantineResponse } from "@remit/api-http-client/types.gen.ts";
+import { toQuarantineEntry } from "./quarantine-entries";
+
+const wire: RemitImapQuarantineResponse = {
+	quarantineId: "8b1e0c2a-0000-4000-8000-000000000001",
+	accountConfigId: "8b1e0c2a-0000-4000-8000-000000000002",
+	accountId: "8b1e0c2a-0000-4000-8000-000000000003",
+	mailboxId: "8b1e0c2a-0000-4000-8000-000000000004",
+	uidValidity: 1717171717,
+	uid: 4211,
+	mailboxRole: "Junk",
+	mailboxPath: "INBOX/Spam",
+	quarantinedAt: 1_750_000_000_000,
+	attempts: 3,
+	failureStage: "BodyParse",
+	failureCode: "UnknownCharset",
+	failureMessage: 'unknown charset "x-mac-roman"',
+	failurePartPath: "1.2",
+	workerVersion: "imap-worker@1.4.0",
+	contentType: "multipart/mixed",
+	transferEncoding: "base64",
+	charset: "x-mac-roman",
+	sizeBytes: 91_204,
+	structure: [
+		{ depth: 0, contentType: "multipart/mixed" },
+		{ depth: 1, contentType: "text/plain" },
+	],
+	messageIdHash: "sha256:abc",
+	createdAt: 1_750_000_000_000,
+	updatedAt: 1_750_000_000_000,
+};
+
+describe("toQuarantineEntry", () => {
+	it("spells the folder role the way the kit does", () => {
+		assert.equal(toQuarantineEntry(wire).mailboxRole, "junk");
+	});
+
+	it("leaves the role absent when the folder has none appointed", () => {
+		const { mailboxRole: _dropped, ...roleless } = wire;
+		assert.equal(toQuarantineEntry(roleless).mailboxRole, undefined);
+	});
+
+	it("carries every field the report and the row are built from", () => {
+		const entry = toQuarantineEntry(wire);
+		assert.equal(entry.quarantineId, wire.quarantineId);
+		assert.equal(entry.uid, wire.uid);
+		assert.equal(entry.uidValidity, wire.uidValidity);
+		assert.equal(entry.mailboxPath, wire.mailboxPath);
+		assert.equal(entry.failureCode, wire.failureCode);
+		assert.equal(entry.failureStage, wire.failureStage);
+		assert.equal(entry.failureMessage, wire.failureMessage);
+		assert.equal(entry.failurePartPath, wire.failurePartPath);
+		assert.equal(entry.attempts, wire.attempts);
+		assert.equal(entry.quarantinedAt, wire.quarantinedAt);
+		assert.equal(entry.workerVersion, wire.workerVersion);
+		assert.equal(entry.contentType, wire.contentType);
+		assert.equal(entry.transferEncoding, wire.transferEncoding);
+		assert.equal(entry.charset, wire.charset);
+		assert.equal(entry.sizeBytes, wire.sizeBytes);
+		assert.equal(entry.messageIdHash, wire.messageIdHash);
+		assert.deepEqual(entry.structure, wire.structure);
+	});
+
+	it("drops the fields the settings surface has no use for", () => {
+		const entry = toQuarantineEntry(wire);
+		assert.equal("accountConfigId" in entry, false);
+		assert.equal("createdAt" in entry, false);
+		assert.equal("updatedAt" in entry, false);
+	});
+});

package/src/lib/quarantine-entries.ts

@@ -0,0 +1,38 @@
+import type { RemitImapQuarantineResponse } from "@remit/api-http-client/types.gen.ts";
+import type { QuarantineEntry } from "@remit/ui";
+import { CANONICAL_TO_NAV_ROLE } from "./folder-roles";
+
+/**
+ * The wire record carries `accountConfigId`, `createdAt` and `updatedAt`, which
+ * the settings surface has no use for, and spells the folder role in the
+ * canonical PascalCase the API uses everywhere. Both differences are resolved
+ * here rather than by widening the kit's entry type.
+ */
+export function toQuarantineEntry(
+	wire: RemitImapQuarantineResponse,
+): QuarantineEntry {
+	return {
+		quarantineId: wire.quarantineId,
+		accountId: wire.accountId,
+		mailboxId: wire.mailboxId,
+		uidValidity: wire.uidValidity,
+		uid: wire.uid,
+		mailboxRole: wire.mailboxRole
+			? CANONICAL_TO_NAV_ROLE[wire.mailboxRole]
+			: undefined,
+		mailboxPath: wire.mailboxPath,
+		failureStage: wire.failureStage,
+		failureCode: wire.failureCode,
+		failureMessage: wire.failureMessage,
+		failurePartPath: wire.failurePartPath,
+		quarantinedAt: wire.quarantinedAt,
+		attempts: wire.attempts,
+		sizeBytes: wire.sizeBytes,
+		contentType: wire.contentType,
+		transferEncoding: wire.transferEncoding,
+		charset: wire.charset,
+		structure: wire.structure,
+		messageIdHash: wire.messageIdHash,
+		workerVersion: wire.workerVersion,
+	};
+}

package/src/routes/settings/advanced.tsx

@@ -1,11 +1,12 @@
 /**
  * Advanced settings. Updates live here — and only here — with a full pane in
- * Settings › Advanced. Notification rules, export, and diagnostics are future
- * scope.
+ * Settings › Advanced, alongside the messages sync could not read. Notification
+ * rules and export are future scope.
  */
 import { SettingsShell } from "@remit/ui";
 import { createFileRoute, useNavigate } from "@tanstack/react-router";
 import { useState } from "react";
+import { QuarantinePanel } from "@/components/settings/QuarantinePanel";
 import { SelfUpdatePanel } from "@/components/settings/SelfUpdatePanel";
 import { TlsRootCaDownload } from "@/components/settings/TlsRootCaDownload";
 import { AppVersion } from "@/components/ui/AppVersion";
@@ -18,8 +19,14 @@ export const Route = createFileRoute("/settings/advanced")({
 const advancedHelp = (
 	<div className="space-y-3">
 		<p>
-			<strong className="text-fg">Notification rules</strong>, data export, and
-			per-account diagnostics are coming in a future release.
+			<strong className="text-fg">Notification rules</strong> and data export
+			are coming in a future release.
+		</p>
+		<p>
+			A message Remit cannot read is{" "}
+			<strong className="text-fg">set aside</strong> rather than skipped, and
+			the folder keeps syncing. Setting one aside is a defect in Remit, so every
+			entry can be reported with the diagnostics already attached.
 		</p>
 	</div>
 );
@@ -46,10 +53,12 @@ function AdvancedSettings() {
 			onBackToMail={() => void navigate({ to: "/mail" })}
 		>
 			<SelfUpdatePanel />
-			<p className="text-sm text-fg-muted">
-				Notification rules, data export, and raw sync diagnostics are coming in
-				a future release.
-			</p>
+			<QuarantinePanel />
+			<div className="mt-6 border-t border-line pt-4">
+				<p className="text-sm text-fg-muted">
+					Notification rules and data export are coming in a future release.
+				</p>
+			</div>
 			<TlsRootCaDownload />
 			<div className="border-t border-line pt-4 mt-4">
 				<p className="text-sm font-medium text-fg mb-1">About</p>

package/vite.base.ts

@@ -5,6 +5,7 @@ import { tanstackRouter } from "@tanstack/router-plugin/vite";
 import react from "@vitejs/plugin-react";
 import type { AliasOptions, BuildOptions, PluginOption } from "vite";
 import { spellcheckPlugin } from "./spellcheck/vite-plugin.ts";
+import { spellcheckWorkerStub } from "./spellcheck/worker-stub.ts";
 
 /**
  * The one place the web-client build toolchain is described. Both the dev
@@ -56,4 +57,5 @@ export const webClientPlugins = (routes: RouterPaths = {}): PluginOption[] => [
 	react(),
 	tailwindcss(),
 	spellcheckPlugin(),
+	spellcheckWorkerStub(),
 ];