paperlint 2.0.0

package/src/new-paper.harness.mjs

@@ -0,0 +1,216 @@
+/**
+ * Both halves for `new-paper.ts` — the module behind `paperlint new` and `paperlint init --paper`.
+ *
+ * What is checked, and why each one matters:
+ *   - the scaffold is what `paperlint lint` ACCEPTS: the old first run opened with "missing
+ *     PIPELINE-STATUS.md", and a scaffold that still produced a finding would move that error
+ *     from a missing file into a created one;
+ *   - the scorecard carries `researchQuestion` and NO `stages` — a new paper has shipped nothing,
+ *     and a placeholder stage would be a red `paper/stages` on the very first run;
+ *   - the scorecard PARSES as a scorecard (`pipeline-check.mjs` finds its four sections). The
+ *     template used to live in a code fence; moved into a file, it must still be the format the
+ *     skills' checker reads;
+ *   - it never overwrites, and on an existing folder adds only what is missing;
+ *   - the project's `<papers>/.template/` wins over the package, file by file.
+ *
+ * ⚠️ Assertions at the TOP LEVEL: `vigiles test` imports the file and counts "did not throw"
+ * as a pass.
+ */
+import assert from "node:assert/strict";
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  realpathSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { spawnSync } from "node:child_process";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { load } from "js-yaml";
+import { frontmatterBlock } from "../lib/markdown.mjs";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const ROOT = dirname(HERE);
+const {
+  newPaper,
+  nameProblem,
+  wantedFiles,
+  PACKAGE_TEMPLATES,
+  OVERRIDE_DIR,
+  STATUS_FILE,
+  SOURCE_FILE,
+} = await import(join(HERE, "new-paper.ts"));
+const { run } = await import(join(HERE, "cli.ts"));
+
+let n = 0;
+const check = (label, cond) => {
+  n++;
+  assert.ok(cond, label);
+};
+
+const work = realpathSync(mkdtempSync(join(tmpdir(), "rpp-new-")));
+const read = (...p) => readFileSync(join(...p), "utf8");
+const front = (text) => load(frontmatterBlock(text) ?? "") ?? {};
+
+/** `paperlint lint <dir>` in-process, output captured. */
+async function lint(dir) {
+  const out = [];
+  const code = await run(["lint", dir], {
+    log: (...a) => out.push(a.join(" ")),
+    err: (...a) => out.push(a.join(" ")),
+    cwd: work,
+  });
+  return { code, text: out.join("\n") };
+}
+
+try {
+  // ── the templates are FILES in the package, one per required file ──────────────────────
+  for (const f of [STATUS_FILE, SOURCE_FILE.tex, SOURCE_FILE.md])
+    check(
+      `the package ships templates/paper/${f}`,
+      existsSync(join(PACKAGE_TEMPLATES, f)),
+    );
+  check(
+    "🔴 the templates ship in the npm tarball — `templates` is in package.json `files`",
+    JSON.parse(read(ROOT, "package.json")).files.includes("templates"),
+  );
+
+  // ── names ───────────────────────────────────────────────────────────────────────────
+  for (const ok of ["demo", "aisec-2026", "v1.2_final"])
+    check(`\`${ok}\` is a valid name`, nameProblem(ok) === null);
+  for (const bad of ["Demo", "my paper", "a/b", "../x", "", "ÿ"])
+    check(`\`${bad}\` is refused`, typeof nameProblem(bad) === "string");
+  for (const dot of [".template", ".x", ".."])
+    check(
+      `\`${dot}\` is refused — discovery skips dot-directories, so it would never be linted`,
+      /starting with a dot/.test(nameProblem(dot) ?? ""),
+    );
+  check(
+    "a refused name creates nothing",
+    newPaper(work, "Bad", "tex").ok === false && !existsSync(join(work, "Bad")),
+  );
+
+  // ── a fresh LaTeX paper ─────────────────────────────────────────────────────────────
+  const papers = join(work, "papers");
+  const r = newPaper(papers, "demo", "tex");
+  check(
+    "a fresh folder gets the scorecard and a .tex source, both from the package",
+    r.ok &&
+      r.fresh &&
+      r.files.map((f) => `${f.file}:${f.status}:${f.from}`).join(" ") ===
+        "PIPELINE-STATUS.md:created:package paper.tex:created:package",
+  );
+  const status = read(papers, "demo", STATUS_FILE);
+  const fm = front(status);
+  check(
+    "🔴 the scorecard has NO `stages` — a new paper has shipped nothing and owes nothing",
+    !("stages" in fm),
+  );
+  check(
+    "and carries `researchQuestion`, present and empty",
+    "researchQuestion" in fm && fm.researchQuestion === "",
+  );
+  check(
+    "the name is filled in, and no placeholder survives in any file",
+    /PIPELINE-STATUS — demo/.test(status) &&
+      !status.includes("{{name}}") &&
+      !read(papers, "demo", "paper.tex").includes("{{name}}"),
+  );
+  const l = await lint(join(papers, "demo"));
+  check(
+    "🔴 `paperlint lint` passes the scaffold clean — the first run is green, not a missing-file error",
+    l.code === 0 && /no findings/.test(l.text),
+  );
+
+  // The format contract of the skills' checker: four sections, parsed.
+  const pc = spawnSync(
+    process.execPath,
+    [
+      join(ROOT, "skills", "paper-pipeline", "scripts", "pipeline-check.mjs"),
+      join(papers, "demo"),
+      "--json",
+      "--today=2026-09-23",
+    ],
+    { cwd: work, encoding: "utf8" },
+  );
+  let parsed = null;
+  try {
+    parsed = JSON.parse(pc.stdout);
+  } catch {
+    parsed = null;
+  }
+  check(
+    "the scorecard PARSES for pipeline-check — its four sections are found (it prints JSON, not the format warning)",
+    Array.isArray(parsed) && !/expected the four sections/.test(pc.stderr),
+  );
+
+  // ── never overwrite; on an existing folder only the missing files ─────────────────────
+  writeFileSync(join(papers, "demo", STATUS_FILE), "mine\n");
+  const again = newPaper(papers, "demo", "md");
+  check(
+    "🔴 a second run overwrites nothing and adds no second source",
+    again.ok &&
+      !again.fresh &&
+      read(papers, "demo", STATUS_FILE) === "mine\n" &&
+      !existsSync(join(papers, "demo", "paper.md")) &&
+      again.files.every((f) => f.status === "kept"),
+  );
+  mkdirSync(join(papers, "old"), { recursive: true });
+  writeFileSync(join(papers, "old", "paper.md"), "# Old\n");
+  const migrated = newPaper(papers, "old", "tex");
+  check(
+    "an old folder with only paper.md gets ONLY the scorecard — that is the migration",
+    migrated.ok &&
+      existsSync(join(papers, "old", STATUS_FILE)) &&
+      !existsSync(join(papers, "old", "paper.tex")) &&
+      read(papers, "old", "paper.md") === "# Old\n",
+  );
+  check(
+    "wantedFiles asks for a source only when neither format is there",
+    wantedFiles(join(papers, "old"), "tex").join() === STATUS_FILE &&
+      wantedFiles(join(papers, "nowhere"), "md").join() ===
+        `${STATUS_FILE},paper.md`,
+  );
+  writeFileSync(join(papers, "afile"), "x");
+  check(
+    "a name taken by a FILE is refused, not written through",
+    newPaper(papers, "afile", "tex").ok === false,
+  );
+
+  // ── the project's template wins, file by file ─────────────────────────────────────────
+  mkdirSync(join(papers, OVERRIDE_DIR), { recursive: true });
+  writeFileSync(
+    join(papers, OVERRIDE_DIR, STATUS_FILE),
+    "---\n---\n# House scorecard for {{name}}\n",
+  );
+  const own = newPaper(papers, "house", "md");
+  check(
+    "🔴 <papers>/.template/ is preferred for the file it holds, the package fills the rest",
+    own.ok &&
+      read(papers, "house", STATUS_FILE) ===
+        "---\n---\n# House scorecard for house\n" &&
+      own.files.find((f) => f.file === STATUS_FILE)?.from === "project" &&
+      own.files.find((f) => f.file === "paper.md")?.from === "package",
+  );
+
+  // ── a missing template is a broken install, not an empty file ─────────────────────────
+  const broken = newPaper(join(work, "b"), "x", "tex", {
+    packageTemplates: join(work, "no-such-dir"),
+  });
+  check(
+    "a missing package template refuses and leaves no half-made folder",
+    broken.ok === false &&
+      /no template for/.test(broken.reason) &&
+      !existsSync(join(work, "b", "x")),
+  );
+} finally {
+  rmSync(work, { recursive: true, force: true });
+}
+
+console.log(
+  `✓ ${String(n)} assertions passed — paperlint new scaffolds what paperlint lint accepts`,
+);

package/src/new-paper.mutations.mjs

@@ -0,0 +1,79 @@
+/**
+ * Battery for `new-paper.ts`.
+ *
+ * Every case reintroduces a way `paperlint new` damages a paper folder or produces one the linter
+ * refuses — the first a loss nobody notices until the text is gone, the second the exact
+ * "missing file on the first run" this command was written to end.
+ */
+import { fileURLToPath } from "node:url";
+import { dirname, join, resolve } from "node:path";
+import { runMutations } from "../lib/mutation-driver.mjs";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const ROOT = resolve(HERE, "..");
+const SRC = join(HERE, "new-paper.ts");
+const HARNESS = join(HERE, "new-paper.harness.mjs");
+
+process.exit(
+  runMutations({
+    root: ROOT,
+    runner: "node",
+    cases: [
+      {
+        name: "an existing file is overwritten",
+        harness: HARNESS,
+        expect: "a second run overwrites nothing",
+        disables:
+          "the one promise that makes `paperlint new` safe on an existing folder. A scorecard with a " +
+          "year of journal in it is replaced by the empty template",
+        edits: [
+          [
+            SRC,
+            '    if (existsSync(join(dir, file))) {\n      files.push({ file, status: "kept" });\n      continue;\n    }\n',
+            "",
+          ],
+          [SRC, '{ encoding: "utf8", flag: "wx" }', '{ encoding: "utf8" }'],
+        ],
+      },
+      {
+        name: "a second source is added beside an existing one",
+        harness: HARNESS,
+        // The first owner is the re-run on a .tex paper asked for md: it must add no paper.md.
+        expect: "adds no second source",
+        disables:
+          "the migration of an old folder: a paper written in Markdown gains a stub paper.tex, " +
+          "and every tex rule starts linting a file the author never wrote",
+        edits: [
+          [
+            SRC,
+            "  return hasSource ? [STATUS_FILE] : [STATUS_FILE, SOURCE_FILE[format]];",
+            "  return [STATUS_FILE, SOURCE_FILE[format]];",
+          ],
+        ],
+      },
+      {
+        name: "the project's template is ignored",
+        harness: HARNESS,
+        expect: "is preferred for the file it holds",
+        disables:
+          "the override slot. A project with its own richer scorecard gets the package's every time",
+        edits: [
+          [
+            SRC,
+            "    const [src, from] = existsSync(project)",
+            "    const [src, from] = false",
+          ],
+        ],
+      },
+      {
+        name: "a leading dot is accepted",
+        harness: HARNESS,
+        expect: "discovery skips dot-directories",
+        disables:
+          "the refusal of a name that would be created and then never linted — the scaffold " +
+          "would sit beside the papers, invisible to every check",
+        edits: [[SRC, '  if (name.startsWith("."))', "  if (false)"]],
+      },
+    ],
+  }),
+);

package/src/new-paper.ts

@@ -0,0 +1,158 @@
+/**
+ * `paperlint new <name>` — a paper folder the linter accepts, made from a template FILE.
+ *
+ * 🔴 WHY THIS EXISTS. `paperlint lint` requires `PIPELINE-STATUS.md` in every paper folder, and until
+ * this command nothing made one: the template sat inside a fenced block of a reference page and a
+ * human copied it. The README's own "First run" example opened with the error for the missing file.
+ *
+ * Every rule below is taken from a tool that already solved it (docs/prior-art/paper-folder-scaffolding.md):
+ *   - the template is a FILE with a lookup order — the project's `<papers>/.template/<file>` first,
+ *     the package's `templates/paper/<file>` second (Hugo's archetypes);
+ *   - it NEVER overwrites: on an existing folder it adds only the missing required files, which is
+ *     also the migration for an old folder that has only `paper.md` (`cargo init`);
+ *   - the name is validated, because it becomes a path and, through the hooks, a shell argument.
+ *
+ * The only substitution is `{{name}}` → the folder name. Nothing else in a template is touched.
+ */
+/* eslint-disable boundaries/dependencies -- legacy I/O, moves behind a port in #76 */
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+/* eslint-enable boundaries/dependencies */
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export type PaperFormat = "tex" | "md";
+export const FORMATS: readonly PaperFormat[] = ["tex", "md"];
+export const DEFAULT_FORMAT: PaperFormat = "tex";
+
+/** The package's default templates. Read from disk, so they ship in the tarball (`files`). */
+export const PACKAGE_TEMPLATES = fileURLToPath(
+  new URL("../templates/paper/", import.meta.url),
+);
+
+/**
+ * The project's override directory, inside the papers directory. It starts with a dot, and that
+ * is what keeps it from being a paper: discovery (`papersIn`, `checkStructure`, `detectPapers`)
+ * skips dot-directories, and `buildConfig` ignores it for ESLint.
+ */
+export const OVERRIDE_DIR = ".template";
+
+export const STATUS_FILE = "PIPELINE-STATUS.md";
+export const SOURCE_FILE: Readonly<Record<PaperFormat, string>> = {
+  tex: "paper.tex",
+  md: "paper.md",
+};
+
+export const isFormat = (v: unknown): v is PaperFormat =>
+  FORMATS.includes(v as PaperFormat);
+
+/**
+ * Why a name is refused, or null. `[a-z0-9._-]+` is the charset; a LEADING dot is refused on top
+ * of it, because discovery skips dot-directories — a paper named `.x` would be created and then
+ * never linted, which is worse than a refusal.
+ */
+export function nameProblem(name: string): string | null {
+  if (!/^[a-z0-9._-]+$/.test(name))
+    return `\`${name}\` — a paper name may hold only a-z, 0-9, dot, underscore and hyphen (it becomes a path and a shell argument)`;
+  if (name.startsWith("."))
+    return `\`${name}\` — a name starting with a dot is skipped by paper discovery, so it would never be linted`;
+  return null;
+}
+
+export interface FileOutcome {
+  readonly file: string;
+  /** `created` from a template, `kept` because it was already there. */
+  readonly status: "created" | "kept";
+  /** Which template it came from, for a created file. */
+  readonly from?: "project" | "package";
+}
+
+export type NewPaperResult =
+  | {
+      readonly ok: true;
+      readonly dir: string;
+      /** The folder did not exist before this run. */
+      readonly fresh: boolean;
+      readonly files: readonly FileOutcome[];
+    }
+  | { readonly ok: false; readonly reason: string };
+
+/**
+ * The files a paper folder must end up with: the scorecard, plus a source in `format` — unless
+ * it already has a source in EITHER format, in which case that one stands and nothing is added.
+ */
+export function wantedFiles(dir: string, format: PaperFormat): string[] {
+  const hasSource = Object.values(SOURCE_FILE).some((f) =>
+    existsSync(join(dir, f)),
+  );
+  return hasSource ? [STATUS_FILE] : [STATUS_FILE, SOURCE_FILE[format]];
+}
+
+// Documented in README.md#starting-a-paper — update it when this changes.
+export function newPaper(
+  papersRoot: string,
+  name: string,
+  format: PaperFormat,
+  { packageTemplates = PACKAGE_TEMPLATES }: { packageTemplates?: string } = {},
+): NewPaperResult {
+  const problem = nameProblem(name);
+  if (problem) return { ok: false, reason: problem };
+  const dir = join(papersRoot, name);
+  const fresh = !existsSync(dir);
+  if (!fresh && !statSync(dir).isDirectory())
+    return { ok: false, reason: `${dir} exists and is not a directory` };
+
+  const files: FileOutcome[] = [];
+  const toWrite: { file: string; text: string; from: "project" | "package" }[] =
+    [];
+  for (const file of wantedFiles(dir, format)) {
+    if (existsSync(join(dir, file))) {
+      files.push({ file, status: "kept" });
+      continue;
+    }
+    const project = join(papersRoot, OVERRIDE_DIR, file);
+    const fromPackage = join(packageTemplates, file);
+    const [src, from] = existsSync(project)
+      ? [project, "project" as const]
+      : [fromPackage, "package" as const];
+    // A missing package template is a broken install, not a reason to write an empty file.
+    if (!existsSync(src))
+      return {
+        ok: false,
+        reason: `no template for ${file}: ${src} is missing`,
+      };
+    const text = readFileSync(src, "utf8").split("{{name}}").join(name);
+    toWrite.push({ file, text, from });
+  }
+  // Read every template before writing any file, so a missing one leaves no half-made folder.
+  mkdirSync(dir, { recursive: true });
+  for (const { file, text, from } of toWrite) {
+    // `wx`: fail rather than overwrite, even if something appeared since the check above.
+    writeFileSync(join(dir, file), text, { encoding: "utf8", flag: "wx" });
+    files.push({ file, status: "created", from });
+  }
+  return { ok: true, dir, fresh, files };
+}
+
+/** The report lines, shared by `paperlint new` and the first-paper offer in `paperlint init`. */
+export function reportNewPaper(
+  result: NewPaperResult,
+  here: (p: string) => string,
+): string[] {
+  if (!result.ok) return [`  ✗ ${result.reason}`];
+  const out = [
+    `  ${result.fresh ? "✓ created" : "✓ already there, only missing files added:"} ${here(result.dir)}`,
+  ];
+  for (const f of result.files)
+    out.push(
+      f.status === "created"
+        ? `      + ${f.file}  (from the ${f.from === "project" ? `project's ${OVERRIDE_DIR}/` : "package"} template)`
+        : `      = ${f.file}  (kept — never overwritten)`,
+    );
+  return out;
+}

package/src/pdf-facts.harness.mjs

@@ -0,0 +1,188 @@
+/**
+ * `pdf-facts.ts` — pdf.js reading REAL PDFs, committed under `fixtures/pdf-facts/`.
+ *
+ * The pure decisions are tested in `pdf-geometry.harness.mjs` with hand-written words. This file is
+ * the other half: that the shell asks pdf.js the right questions, with the right options, and maps
+ * what comes back. The expected numbers are the ones poppler reported for the same files in the
+ * 2026-09-24 measurement (issue #61), so a pass here is agreement with the tool this replaced.
+ */
+import assert from "node:assert/strict";
+import { writeFileSync, mkdtempSync, realpathSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const FIX = resolve(HERE, "..", "fixtures", "pdf-facts");
+const { readPdf } = await import(join(HERE, "pdf-facts.ts"));
+const { classifyLastPage } = await import(join(HERE, "pdf-geometry.ts"));
+
+let n = 0;
+const check = (label, cond, detail = "") => {
+  assert.ok(cond, detail ? `${label} — ${detail}` : label);
+  n++;
+};
+
+const read = async (name) => {
+  const r = await readPdf(join(FIX, name));
+  assert.ok(r.ok, `${name} must read: ${JSON.stringify(r)}`);
+  return r.facts;
+};
+const kinds = (facts) =>
+  facts.fonts.kind === "drawn" ? facts.fonts.list.map((f) => f.kind) : [];
+const named = (facts, name) =>
+  facts.fonts.kind === "drawn"
+    ? facts.fonts.list.find((f) => f.name === name)
+    : undefined;
+
+// ── t3-all: every text font is Type 3 ──────────────────────────────────────────────────
+{
+  const f = await read("t3-all.pdf");
+  check(
+    "t3-all: four Type 3 fonts, as poppler lists — including one no text item names",
+    kinds(f).length === 4 && kinds(f).every((k) => k === "type3"),
+    JSON.stringify(f.fonts),
+  );
+  const last = classifyLastPage(f.last);
+  check(
+    "t3-all: one page, measured, within 7.2 pt of poppler's 150.1 / 553.2",
+    f.pages === 1 &&
+      last.kind === "measured" &&
+      Math.abs(last.columns[0] - 150.1) <= 7.2 &&
+      Math.abs(last.columns[1] - 553.2) <= 7.2,
+    JSON.stringify(last),
+  );
+}
+
+// ── ttf: a LuaLaTeX PDF, composite TrueType ────────────────────────────────────────────
+{
+  const f = await read("ttf.pdf");
+  const arsenal = named(f, "Arsenal SC Regular");
+  check(
+    "ttf: the composite TrueType font is CIDTrueType — the program is read, not guessed",
+    arsenal?.kind === "embedded" && arsenal.program === "CIDTrueType",
+    JSON.stringify(f.fonts),
+  );
+  check(
+    "ttf: two pages, and the 8-word last page is a stub",
+    f.pages === 2 && classifyLastPage(f.last).kind === "stub",
+  );
+}
+
+// ── t3-mixed: the sub/uni bug of the poppler reader ────────────────────────────────────
+{
+  const f = await read("t3-mixed.pdf");
+  // pdffonts prints this font as `Times-Roman  Type 1  Custom  no  no  yes`. The old reader
+  // tested `yes` anywhere in the row, found the `uni` column's, and called the font embedded.
+  const times = named(f, "Times-Roman");
+  check(
+    "🔴 t3-mixed: Times-Roman (pdffonts: `no no yes`) is NOT embedded",
+    times?.kind === "not-embedded",
+    JSON.stringify(times),
+  );
+  const cols = classifyLastPage(f.last);
+  check(
+    "t3-mixed: columns within 0.2 pt of poppler's 153.5 / 554.9 — the fonts' own ascent is used",
+    cols.kind === "measured" &&
+      Math.abs(cols.columns[0] - 153.5) <= 0.2 &&
+      Math.abs(cols.columns[1] - 554.9) <= 0.2,
+    JSON.stringify(cols),
+  );
+  check(
+    "t3-mixed: four fonts — two embedded Type 1, one Type 3, one not embedded",
+    JSON.stringify(kinds(f)) ===
+      JSON.stringify(["embedded", "embedded", "type3", "not-embedded"]),
+    JSON.stringify(f.fonts),
+  );
+}
+
+// ── corrupt-font: poppler says embedded, the program does not parse ────────────────────
+{
+  const f = await read("corrupt-font.pdf");
+  check(
+    "corrupt-font: a font program that does not parse counts as not embedded",
+    named(f, "CMR10")?.kind === "not-embedded" &&
+      named(f, "CMBX12")?.kind === "embedded",
+    JSON.stringify(f.fonts),
+  );
+}
+
+// ── what cannot be read says so ─────────────────────────────────────────────────────────
+{
+  const r = await readPdf(join(FIX, "encrypted.pdf"));
+  check(
+    "an encrypted PDF is `encrypted`, not a crash",
+    !r.ok && r.reason === "encrypted",
+    JSON.stringify(r),
+  );
+}
+const tmp = realpathSync(mkdtempSync(join(tmpdir(), "rpp-pdf-facts-")));
+try {
+  const notPdf = join(tmp, "paper.pdf");
+  writeFileSync(notPdf, "%PDF-stale\n");
+  const bad = await readPdf(notPdf);
+  check(
+    "a file that is not a PDF is `unreadable`, with pdf.js's reason",
+    !bad.ok && bad.reason === "unreadable" && /PDF/.test(bad.detail),
+    JSON.stringify(bad),
+  );
+  const missing = await readPdf(join(tmp, "nope.pdf"));
+  check(
+    "a missing file is `unreadable`, not an exception",
+    !missing.ok && missing.reason === "unreadable",
+    JSON.stringify(missing),
+  );
+} finally {
+  rmSync(tmp, { recursive: true, force: true });
+}
+
+// ── hidden-text: the boxes banal is fed ────────────────────────────────────────────────
+{
+  const f = await read("hidden-text.pdf");
+  const boxes = f.layout.flatMap((p, i) =>
+    p.boxes.map((b) => ({ ...b, page: i + 1 })),
+  );
+  const chars = (pred) =>
+    boxes.filter(pred).reduce((sum, b) => sum + b.text.length, 0);
+  check(
+    "hidden-text: one layout per page, each US letter",
+    f.layout.length === 3 &&
+      f.layout.every((p) => p.widthPt === 612 && p.heightPt === 792),
+    JSON.stringify(f.layout.map((p) => [p.widthPt, p.heightPt])),
+  );
+  // Guards: the rotation test in viewer space — the rotated margin text must reach the writer
+  // marked as not upright, or it is counted as body text.
+  check(
+    "hidden-text: the rotated text is marked not upright, and only it",
+    boxes
+      .filter((b) => !b.upright)
+      .every((b) => b.text.includes("Rotated") || b.text.includes("rotated")) &&
+      chars((b) => !b.upright) > 200,
+  );
+  // Guards: the fill walk on a real operator list — the render-mode-3 layer is found.
+  check(
+    "hidden-text: the render-mode-3 text is marked invisible",
+    chars((b) => b.fill.kind === "invisible") > 150 &&
+      boxes
+        .filter((b) => b.fill.kind === "invisible")
+        .every((b) => /visi|text|layer/i.test(b.text)),
+  );
+  check(
+    "hidden-text: the gray!8 text carries its colour, #f5f5f5",
+    chars((b) => b.fill.kind === "rgb" && b.fill.hex === "#f5f5f5") > 3000,
+  );
+  check(
+    "hidden-text: the body text is upright, visible and not light",
+    chars(
+      (b) =>
+        b.upright &&
+        b.fill.kind !== "invisible" &&
+        !(b.fill.kind === "rgb" && b.fill.hex !== "#000000") &&
+        Math.abs(b.size - 9.96) < 0.1,
+    ) > 3000,
+  );
+}
+
+console.log(
+  `✓ ${String(n)} assertions passed — pdf-facts: pdf.js on real PDFs agrees with poppler, and says what it cannot read`,
+);