paperlint 2.0.0

package/src/adapters/banal/run.test.ts

@@ -0,0 +1,191 @@
+/**
+ * `adapters/banal/run.ts` — running and installing banal, on in-memory ports: which `Command` it builds, what it stages,
+ * what it downloads and writes, and what it concludes. No perl, no disk, no network: the adapters
+ * record, and each assertion reads the record. Real perl and the real banal are `test/e2e/banal.mjs`;
+ * the adapters' own behaviour is `src/adapters/node/*.test.ts`.
+ */
+import assert from "node:assert/strict";
+import { test } from "vitest";
+import {
+  exitedWith,
+  fixedDownload,
+  memoryFiles,
+  memoryPorts,
+  memoryWorkspace,
+  scriptedProcess,
+} from "../memory/index.ts";
+import { checkBanal, ensureBanal, measureGeometry } from "./run.ts";
+import { sha256Hex } from "../../domain/sha256.ts";
+import { installedBanal } from "./locate.ts";
+import { parseBanalSettings } from "./settings.ts";
+import type { AbsolutePath } from "../../domain/paths.ts";
+import type { Command, ProcessExit } from "../../ports/process.ts";
+
+const s = parseBanalSettings(
+  { BANAL: "/own/banal", PATH: "/bin" },
+  { home: "/h", tmp: "/t", cwd: "/w" },
+);
+const noExplicit = parseBanalSettings(
+  { PATH: "/bin" },
+  { home: "/h", tmp: "/t", cwd: "/w" },
+);
+const project = "/p" as AbsolutePath;
+/** What banal prints for the one-page probe. */
+const MEASURED = '{"bodyfontsize": 10.3, "columns": 1, "pages": [{}]}';
+const banalAnswers = (e: ProcessExit) =>
+  scriptedProcess((c: Command) => (c.args[0] === "-e" ? exitedWith("") : e));
+
+test("measureGeometry: perl runs the found banal on the staged XML, and the geometry comes back", () => {
+  const run = banalAnswers(exitedWith(MEASURED));
+  const workspace = memoryWorkspace();
+  const io = memoryPorts({
+    run,
+    workspace,
+    files: memoryFiles({ "/own/banal": "" }),
+  });
+  const g = measureGeometry(io, s, project, []);
+  assert.equal(g.source, "banal");
+  assert.equal(g.source === "banal" && g.geometry.bodyPt, 10.3);
+  const [c] = run.calls;
+  assert.equal(c?.file, "perl");
+  assert.equal(c?.args.at(-1), "/scratch/paper.xml");
+  // Guards: both files staged, once, and the scratch scope ended normally (cleanup ran).
+  assert.deepEqual(
+    workspace.written.map((w) => [w.name, w.mode]),
+    [
+      ["paper.xml", "read"],
+      ["pdftohtml", "exec"],
+    ],
+  );
+  assert.deepEqual(workspace.ended, ["returned"]);
+});
+
+test("measureGeometry: no banal anywhere is `banal-missing`, and nothing runs", () => {
+  const run = banalAnswers(exitedWith(MEASURED));
+  const g = measureGeometry(memoryPorts({ run }), noExplicit, project, []);
+  assert.equal(g.source === "none" && g.why.kind, "banal-missing");
+  assert.equal(run.calls.length, 0);
+});
+
+test("🔴 measureGeometry: perl not found is `perl-missing`, naming the banal that was tried", () => {
+  const io = memoryPorts({
+    run: scriptedProcess(() => ({ kind: "not-found", file: "perl" })),
+    files: memoryFiles({ "/own/banal": "" }),
+  });
+  const g = measureGeometry(io, s, project, []);
+  assert.equal(g.source === "none" && g.why.kind, "perl-missing");
+  assert.equal(g.source === "none" && g.tried?.path, "/own/banal");
+});
+
+test("measureGeometry: banal exiting 3 is `process-failed`", () => {
+  const io = memoryPorts({
+    run: banalAnswers({
+      kind: "exited",
+      status: 3,
+      stdout: "",
+      stderr: "boom",
+    }),
+    files: memoryFiles({ "/own/banal": "" }),
+  });
+  const g = measureGeometry(io, s, project, []);
+  assert.equal(g.source === "none" && g.why.kind, "process-failed");
+});
+
+// ── installing ──────────────────────────────────────────────────────────────────────────
+const BODY = "print qq(...);\n";
+const source = {
+  url: "https://example.test/banal",
+  sha256: sha256Hex(new TextEncoder().encode(BODY)),
+};
+const dest = installedBanal(noExplicit);
+
+test("ensureBanal: downloads, verifies, writes and probes — fresh; a second run downloads nothing", () => {
+  const files = memoryFiles();
+  const download = fixedDownload(BODY);
+  const io = memoryPorts({
+    run: banalAnswers(exitedWith(MEASURED)),
+    files,
+    download,
+  });
+  const first = ensureBanal(io, noExplicit, { source });
+  assert.equal(first.ok && first.value.banal.path, dest);
+  assert.equal(first.ok && first.value.fresh, true);
+  assert.ok(files.map.has(dest));
+  // Guards: idempotence — an installed, matching banal is not downloaded again.
+  const second = ensureBanal(io, noExplicit, { source });
+  assert.equal(second.ok && second.value.fresh, false);
+  assert.equal(download.urls.length, 1);
+});
+
+test("🔴 ensureBanal: bytes with another sha256 are refused, and nothing is written", () => {
+  const files = memoryFiles();
+  const io = memoryPorts({
+    run: banalAnswers(exitedWith(MEASURED)),
+    files,
+    download: fixedDownload("something else"),
+  });
+  const r = ensureBanal(io, noExplicit, { source });
+  // Guards: the sha256 pin — a changed upstream file (or a proxy's error page) is never installed.
+  assert.equal(!r.ok && r.error.kind, "sha-mismatch");
+  assert.equal(files.map.size, 0);
+});
+
+test("ensureBanal: a failed download names the URL", () => {
+  const io = memoryPorts({
+    run: banalAnswers(exitedWith(MEASURED)),
+    download: fixedDownload({ detail: "curl exited 22" }),
+  });
+  const r = ensureBanal(io, noExplicit, { source });
+  assert.deepEqual(!r.ok && r.error, {
+    kind: "download-failed",
+    url: source.url,
+    detail: "curl exited 22",
+  });
+});
+
+test("🔴 ensureBanal: a banal that downloads fine but measures nothing fails, saying why", () => {
+  const io = memoryPorts({
+    run: banalAnswers(exitedWith("not json")),
+    download: fixedDownload(BODY),
+  });
+  const r = ensureBanal(io, noExplicit, { source });
+  // Guards: acceptance by a run, not by the download.
+  assert.equal(!r.ok && r.error.kind, "does-not-run");
+  assert.equal(
+    !r.ok && r.error.kind === "does-not-run" && r.error.why.kind,
+    "no-json",
+  );
+});
+
+test("🔴 ensureBanal and checkBanal without perl: `perl-missing`, and nothing downloaded", () => {
+  const download = fixedDownload(BODY);
+  const io = memoryPorts({
+    run: scriptedProcess(() => ({ kind: "not-found", file: "perl" })),
+    download,
+  });
+  const r = ensureBanal(io, noExplicit, { source });
+  // Guards: perl first — no download when the program that would run it is missing.
+  assert.equal(!r.ok && r.error.kind, "perl-missing");
+  assert.equal(download.urls.length, 0);
+  const c = checkBanal(io, noExplicit, source);
+  assert.equal(!c.ok && c.error.kind, "perl-missing");
+});
+
+test("checkBanal: absent, other bytes, pinned-and-running", () => {
+  const run = banalAnswers(exitedWith(MEASURED));
+  const absent = checkBanal(memoryPorts({ run }), noExplicit, source);
+  assert.equal(!absent.ok && absent.error.kind, "banal-missing");
+  // Guards: the pin is checked on every run — a changed file is reported, not trusted.
+  const tampered = checkBanal(
+    memoryPorts({ run, files: memoryFiles({ [dest]: "tampered" }) }),
+    noExplicit,
+    source,
+  );
+  assert.equal(!tampered.ok && tampered.error.kind, "not-pinned");
+  const good = checkBanal(
+    memoryPorts({ run, files: memoryFiles({ [dest]: BODY }) }),
+    noExplicit,
+    source,
+  );
+  assert.equal(good.ok, true);
+});

package/src/adapters/banal/run.ts

@@ -0,0 +1,244 @@
+/**
+ * BANAL — the page-geometry script HotCRP's format checker runs — fetched, verified and run.
+ *
+ * banal (Eddie Kohler, Geoffrey M. Voelker; https://github.com/kohler/hotcrp/blob/master/src/banal)
+ * measures a paper's page size, column count, body and reference font sizes and page types. paperlint
+ * runs the REAL banal, unmodified, so the numbers in the facts file are the numbers HotCRP shows a
+ * reviewer at upload — a reimplementation would drift from them.
+ *
+ * ── THE LICENCE BOUNDARY ────────────────────────────────────────────────────────
+ * banal is GPL-2.0-or-later; paperlint is MIT. paperlint therefore never contains banal: `paperlint toolchain`
+ * DOWNLOADS it from HotCRP at a pinned commit, checks its sha256, and stores it in rpp's cache, and
+ * paperlint EXECUTES it as a separate program (`perl banal …`), reading its JSON output. Nothing of banal
+ * is copied, vendored, linked or translated into this package.
+ *
+ * ── WITHOUT POPPLER ──────────────────────────────────────────────────────────────
+ * banal reads a PDF by running poppler's `pdftohtml -xml` — but it also accepts that XML directly:
+ * `banal_open_input` (banal 1.2, line 1815) takes a file ending in `.xml` and opens it as is. paperlint
+ * writes that XML itself from the page layout pdf.js read (`./xml.ts`) and hands banal the `.xml` file,
+ * beside a stub that answers banal's one question to poppler (`./invocation.ts`).
+ *
+ * ── THIS FILE ───────────────────────────────────────────────────────────────────
+ * Running and installing banal, over the generic ports (`src/ports/`) and this folder's pure
+ * modules; it imports nothing from `node:*` that touches the outside world. Failures stay banal's
+ * own union here, so the tests can branch on them; `./index.ts` turns them into the ports the app
+ * sees (`MeasureGeometry`, `ToolInstaller`).
+ */
+import type { AbsolutePath } from "../../domain/paths.ts";
+import type { PageGeometry } from "../../domain/geometry.ts";
+import type { Download } from "../../ports/download.ts";
+import type { Files } from "../../ports/files.ts";
+import type { RunProcess } from "../../ports/process.ts";
+import type { Workspace } from "../../ports/workspace.ts";
+import { andThen, err, ok, type Result } from "../../domain/result.ts";
+import type { BanalFailure } from "./failure.ts";
+import {
+  banalCommand,
+  BANAL_RUN_MS,
+  stage,
+  stageBanalInput,
+} from "./invocation.ts";
+import { installedState, verifyPin } from "./install.ts";
+import {
+  installedBanal,
+  lookupOrder,
+  pickBanal,
+  type BanalCandidate,
+  type LocatedBanal,
+  type PinnedBanal,
+} from "./locate.ts";
+import {
+  geometryOf,
+  parseBanalOutput,
+  type BanalMeasurement,
+} from "./output.ts";
+import { BANAL_PIN, pinLabel, type BanalSource } from "./pin.ts";
+import { acceptProbe, PROBE_PAGE } from "./probe.ts";
+import type { BanalSettings } from "./settings.ts";
+import type { PageLayout } from "../../domain/page-layout.ts";
+
+/** Seconds: banal is ~90 KB. */
+export const BANAL_DOWNLOAD_SECONDS = 60;
+
+/** The ports banal runs with. */
+export interface BanalDeps {
+  readonly run: RunProcess;
+  readonly files: Files;
+  readonly workspace: Workspace;
+}
+
+/** The ports installing banal needs besides: it downloads. */
+export interface InstallDeps extends BanalDeps {
+  readonly download: Download;
+}
+
+/**
+ * What measuring came to, in banal's own terms: the banal found and its geometry, or banal's
+ * failure and the banal that was tried. `./index.ts` projects it onto the domain's `Geometry`.
+ */
+export type BanalOutcome =
+  | {
+      readonly source: "banal";
+      readonly by: BanalCandidate;
+      readonly geometry: PageGeometry;
+    }
+  | {
+      readonly source: "none";
+      readonly why: BanalFailure;
+      /** The banal that was run and failed; null when none was found. */
+      readonly tried: BanalCandidate | null;
+    };
+
+/** Run `banal` on `pages` in a scratch directory that is gone when this returns. */
+function runBanal(
+  d: BanalDeps,
+  s: BanalSettings,
+  banal: LocatedBanal,
+  pages: readonly PageLayout[],
+): Result<BanalMeasurement, BanalFailure> {
+  return d.workspace.within("rpp-banal-", (scratch) =>
+    parseBanalOutput(
+      d.run.run(
+        banalCommand(
+          banal,
+          stage(scratch, stageBanalInput(pages)),
+          s.processEnv,
+        ),
+      ),
+    ),
+  );
+}
+
+/**
+ * The page geometry banal measures for `pages` — the banal found by `$BANAL`, the project's
+ * `vendor/banal`, or `paperlint toolchain`'s — or why there is none.
+ */
+export function measureGeometry(
+  d: BanalDeps,
+  s: BanalSettings,
+  projectRoot: AbsolutePath,
+  pages: readonly PageLayout[],
+): BanalOutcome {
+  const located = pickBanal(lookupOrder(s, projectRoot), (p) =>
+    d.files.isFile(p),
+  );
+  if (!located.ok)
+    return {
+      source: "none",
+      why: { kind: "banal-missing", missing: located.error },
+      tried: null,
+    };
+  const by: BanalCandidate = located.value;
+  const r = runBanal(d, s, located.value, pages);
+  return r.ok
+    ? { source: "banal", by, geometry: geometryOf(r.value) }
+    : { source: "none", why: r.error, tried: by };
+}
+
+// ── installing it (`paperlint toolchain`) ──────────────────────────────────────────────────
+
+/** Does perl start? banal is a Perl program; without perl nothing below can succeed. */
+function perlRuns(d: BanalDeps, s: BanalSettings): boolean {
+  const r = d.run.run({
+    file: "perl",
+    args: ["-e", "exit 0"],
+    env: s.processEnv,
+    timeoutMs: BANAL_RUN_MS,
+  });
+  return r.kind === "exited" && r.status === 0;
+}
+
+/**
+ * Does the installed, pin-verified banal RUN — accepted by measuring the probe page, not by a
+ * download's exit code. The one place a `PinnedBanal` is minted; callers verified the bytes first.
+ */
+function probe(
+  d: BanalDeps,
+  s: BanalSettings,
+  path: AbsolutePath,
+): Result<PinnedBanal, BanalFailure> {
+  const at: BanalCandidate = { path, provenance: { kind: "cache" } };
+  const r = andThen(
+    runBanal(d, s, at as LocatedBanal, [PROBE_PAGE]),
+    acceptProbe,
+  );
+  return r.ok
+    ? ok(at as PinnedBanal)
+    : err({ kind: "does-not-run", path, why: r.error });
+}
+
+/** Download `source` into `dest`, keeping the bytes only when they hash to the pin. */
+function install(
+  d: InstallDeps,
+  source: BanalSource,
+  dest: AbsolutePath,
+): Result<null, BanalFailure> {
+  const got = d.download.fetch(source.url, BANAL_DOWNLOAD_SECONDS * 1000);
+  if (!got.ok)
+    return err({
+      kind: "download-failed",
+      url: source.url,
+      detail: got.error.detail,
+    });
+  const pinned = verifyPin(got.value, source);
+  if (!pinned.ok)
+    return err({ kind: "sha-mismatch", url: source.url, ...pinned.error });
+  d.files.writeAtomic(dest, pinned.value);
+  return ok(null);
+}
+
+export interface Installed {
+  readonly banal: PinnedBanal;
+  /** True when this run downloaded it. */
+  readonly fresh: boolean;
+}
+
+export interface EnsureOptions {
+  /** What to download — the pin by default; a test passes a local file. */
+  readonly source?: BanalSource;
+  /** Told before a download starts (it can take a while). */
+  readonly onDownload?: (line: string) => void;
+}
+
+/**
+ * Make `paperlint toolchain`'s banal present, byte-identical to the pin, and RUNNING: perl is checked
+ * first, a file with the wrong sha256 is replaced, and acceptance is a probe run that has to measure
+ * a page — not the download's exit code.
+ */
+export function ensureBanal(
+  d: InstallDeps,
+  s: BanalSettings,
+  o: EnsureOptions = {},
+): Result<Installed, BanalFailure> {
+  if (!perlRuns(d, s)) return err({ kind: "perl-missing" });
+  const source = o.source ?? BANAL_PIN;
+  const dest = installedBanal(s);
+  const present =
+    installedState(d.files.readBytes(dest), source).kind === "pinned";
+  if (!present) {
+    o.onDownload?.(`  downloading ${pinLabel()}…`);
+    const done = install(d, source, dest);
+    if (!done.ok) return done;
+  }
+  const ran = probe(d, s, dest);
+  return ran.ok ? ok({ banal: ran.value, fresh: !present }) : ran;
+}
+
+/** `--check`: is the pinned banal installed and running? The same predicate as `ensureBanal`, no download. */
+export function checkBanal(
+  d: BanalDeps,
+  s: BanalSettings,
+  source: BanalSource = BANAL_PIN,
+): Result<PinnedBanal, BanalFailure> {
+  if (!perlRuns(d, s)) return err({ kind: "perl-missing" });
+  const dest = installedBanal(s);
+  const state = installedState(d.files.readBytes(dest), source);
+  if (state.kind === "absent")
+    return err({
+      kind: "banal-missing",
+      missing: { kind: "not-installed", installed: dest },
+    });
+  if (state.kind === "other-bytes")
+    return err({ kind: "not-pinned", path: dest });
+  return probe(d, s, dest);
+}

package/src/adapters/banal/settings.test.ts

@@ -0,0 +1,31 @@
+import assert from "node:assert/strict";
+import { test } from "vitest";
+import { parseBanalSettings } from "./settings.ts";
+
+const dirs = { home: "/h", tmp: "/t", cwd: "/w" };
+
+test("cacheDir: $RPP_BANAL_DIR, else $XDG_CACHE_HOME/rpp/banal, else ~/.cache/rpp/banal", () => {
+  assert.equal(
+    parseBanalSettings({ RPP_BANAL_DIR: "/x" }, dirs).cacheDir,
+    "/x",
+  );
+  assert.equal(
+    parseBanalSettings({ XDG_CACHE_HOME: "/c" }, dirs).cacheDir,
+    "/c/rpp/banal",
+  );
+  assert.equal(parseBanalSettings({}, dirs).cacheDir, "/h/.cache/rpp/banal");
+});
+
+test("an empty variable is unset, and a relative one is relative to the cwd the root read", () => {
+  const s = parseBanalSettings({ BANAL: "b/banal", RPP_BANAL_DIR: "" }, dirs);
+  assert.equal(s.explicit, "/w/b/banal");
+  assert.equal(s.cacheDir, "/h/.cache/rpp/banal");
+  assert.equal(parseBanalSettings({}, dirs).explicit, null);
+});
+
+test("processEnv drops undefined values: a child's environment is strings only", () => {
+  assert.deepEqual(
+    parseBanalSettings({ A: "1", B: undefined }, dirs).processEnv,
+    { A: "1" },
+  );
+});

package/src/adapters/banal/settings.ts

@@ -0,0 +1,55 @@
+/**
+ * banal's settings, parsed from the environment VALUE the composition root read once
+ * (`domain/host.ts`): which banal the user named, where `paperlint toolchain` keeps it, where scratch
+ * directories go, and the environment perl and curl get. Nothing here reads the host itself.
+ */
+import { join, resolve } from "node:path";
+import {
+  childEnv,
+  type Environment,
+  type HostDirs,
+} from "../../domain/host.ts";
+import type { AbsolutePath } from "../../domain/paths.ts";
+
+/** An explicit banal to use instead of rpp's (a path to the script). */
+export const BANAL_ENV = "BANAL";
+/** Where `paperlint toolchain` stores banal. Default: `$XDG_CACHE_HOME/rpp/banal`, else `~/.cache/rpp/banal`. */
+export const BANAL_DIR_ENV = "RPP_BANAL_DIR";
+
+export interface BanalSettings {
+  /** `$BANAL`: the user's explicit choice; null when unset. */
+  readonly explicit: AbsolutePath | null;
+  /** `$RPP_BANAL_DIR` › `$XDG_CACHE_HOME/rpp/banal` › `<home>/.cache/rpp/banal`. */
+  readonly cacheDir: AbsolutePath;
+  /** Where scratch directories go. */
+  readonly tmpDir: AbsolutePath;
+  /** The environment a child process (perl, curl) gets: every value a string, none undefined. */
+  readonly processEnv: Readonly<Record<string, string>>;
+}
+
+/** `resolve` with an absolute base never consults the process's cwd. */
+const absolute = (cwd: string, p: string): AbsolutePath =>
+  resolve(cwd, p) as AbsolutePath;
+
+/** An unset variable and an empty one mean the same: not set. */
+const set = (v: string | undefined): string | null => (v ? v : null);
+
+function cacheDirOf(env: Environment, d: HostDirs): string {
+  return (
+    set(env[BANAL_DIR_ENV]) ??
+    join(set(env["XDG_CACHE_HOME"]) ?? join(d.home, ".cache"), "rpp", "banal")
+  );
+}
+
+export function parseBanalSettings(
+  env: Environment,
+  dirs: HostDirs,
+): BanalSettings {
+  const explicit = set(env[BANAL_ENV]);
+  return {
+    explicit: explicit === null ? null : absolute(dirs.cwd, explicit),
+    cacheDir: absolute(dirs.cwd, cacheDirOf(env, dirs)),
+    tmpDir: absolute(dirs.cwd, dirs.tmp),
+    processEnv: childEnv(env),
+  };
+}

package/src/adapters/banal/xml.test.ts

@@ -0,0 +1,111 @@
+/**
+ * `xml.ts` — the banal input XML (pdftohtml's dialect) the domain's text boxes become, and which of
+ * them a layout tool counts.
+ *
+ * Every page here is written by hand. The real-PDF half — pdf.js boxes of a committed fixture,
+ * written as XML, measured by the real banal and compared with banal on real pdftohtml — is
+ * `test/e2e/banal.mjs`, which runs where `paperlint toolchain` has installed banal.
+ */
+import assert from "node:assert/strict";
+import { test } from "vitest";
+import * as L from "./xml.ts";
+import type { PageLayout, TextBox } from "../../domain/page-layout.ts";
+
+/** One vitest case per assertion, named by its label. */
+const check = (label: string, cond: unknown, detail = "") => {
+  test(label, () => {
+    assert.ok(cond, detail ? `${label} — ${detail}` : label);
+  });
+};
+
+const box = (over: Partial<TextBox> = {}): TextBox => ({
+  top: 10,
+  left: 20,
+  width: 30,
+  height: 12,
+  size: 10,
+  font: "LinLibertineT",
+  text: "Hello",
+  upright: true,
+  fill: { kind: "unknown" },
+  ...over,
+});
+const page = (boxes: TextBox[], widthPt = 612, heightPt = 792): PageLayout => ({
+  widthPt,
+  heightPt,
+  boxes,
+});
+
+// ── the XML ─────────────────────────────────────────────────────────────────────────────
+{
+  const xml = L.pdf2xml([
+    page([box(), box({ top: 22.0417, text: 'a < b & c > "d"' })]),
+    page([box({ text: "again" }), box({ size: 9, text: "smaller" })]),
+  ]);
+  // Guards: the exact dialect banal reads — header, zoom-3 integer page size, a font declared on the
+  // first page that uses it and before its text, sizes as round(size × 3), coordinates × 3 unrounded.
+  const expected = [
+    '<?xml version="1.0" encoding="UTF-8"?>',
+    '<!DOCTYPE pdf2xml SYSTEM "pdf2xml.dtd">',
+    '<pdf2xml producer="research-paper-pipeline (pdf.js)" version="24.02.0">',
+    '<page number="1" position="absolute" top="0" left="0" height="2376" width="1836">',
+    '\t<fontspec id="0" size="30" family="LinLibertineT" color="#000000"/>',
+    '<text top="30.000000" left="60.000000" width="90.000000" height="36.000000" font="0">Hello</text>',
+    '<text top="66.125100" left="60.000000" width="90.000000" height="36.000000" font="0">a &lt; b &amp; c &gt; &#34;d&#34;</text>',
+    "</page>",
+    '<page number="2" position="absolute" top="0" left="0" height="2376" width="1836">',
+    '\t<fontspec id="1" size="27" family="LinLibertineT" color="#000000"/>',
+    '<text top="30.000000" left="60.000000" width="90.000000" height="36.000000" font="0">again</text>',
+    '<text top="30.000000" left="60.000000" width="90.000000" height="36.000000" font="1">smaller</text>',
+    "</page>",
+    "</pdf2xml>",
+    "",
+  ].join("\n");
+  check(
+    "pdf2xml: the exact pdftohtml dialect, on two pages",
+    xml === expected,
+    `\n${xml}`,
+  );
+}
+{
+  const xml = L.pdf2xml([
+    page([
+      box({ text: "rotated", upright: false }),
+      box({ text: "ocr layer", fill: { kind: "invisible" } }),
+      box({ text: "   " }),
+      box({ text: "watermark", fill: { kind: "rgb", hex: "#f5f5f5" } }),
+      box({ text: "body" }),
+    ]),
+  ]);
+  // Guards: condition 1 — pdftohtml writes rotated text with width 0 and banal drops it; writing it
+  // would count a rotated margin note as body text.
+  check("pdf2xml: rotated text is not written", !xml.includes("rotated"), xml);
+  // Guards: condition 2 — pdftohtml does not write render-mode-3 text (an OCR layer).
+  check(
+    "pdf2xml: invisible text is not written",
+    !xml.includes("ocr layer"),
+    xml,
+  );
+  // Guards: condition 3 — light text IS written, with its colour, because what counts as light is
+  // banal's decision (its own threshold), not a copy of it here.
+  check(
+    "pdf2xml: light text is written, with its colour in its own fontspec",
+    xml.includes('color="#f5f5f5"/>') &&
+      xml.includes(">watermark</text>") &&
+      xml.includes('color="#000000"/>'),
+    xml,
+  );
+  check(
+    "pdf2xml: a blank item is not written",
+    (xml.match(/<text /g) ?? []).length === 2,
+    xml,
+  );
+}
+check(
+  "xmlEscape: a newline becomes a space, as pdftohtml writes it",
+  L.xmlEscape("a\nb\r\nc") === "a b  c",
+);
+check(
+  "pdf2xml: no pages is a well-formed empty document",
+  L.pdf2xml([]).endsWith("</pdf2xml>\n") && !L.pdf2xml([]).includes("<page"),
+);