beatrina 0.9.83 → 1.0.0

package/host/latex-compile.mjs

@@ -0,0 +1,673 @@
+// latex-compile.mjs — compiling a LaTeX root, and reading what the compiler
+// said, from Node (plans/getting_rid_of_R.md Stage 3, K7).
+//
+// A port of spike/latex.R's COMPILE half (`latex_compile()` and every helper
+// it calls), rule for rule, so a .tex can be compiled on a machine with no R.
+// The PREVIEW half of that file was ported earlier and lives in
+// host/planes/latex.mjs; nothing here touches it.
+//
+// Two halves in one file, the split latex.R already had:
+//
+//   · PURE — discovery (with an injectable lookup), the literal argv, the log
+//     parser that turns a transcript into diagnostics, the 79-column unwrap,
+//     severity, the failure sentence and the machine-actionable fix, and the
+//     bibliography verdict. Each is an exported function of its inputs, and
+//     test/latex-compile-node.test.mjs holds every one of them against the R
+//     original, value by value.
+//   · ORCHESTRATION — `latexCompile()`, which the Node job child
+//     (host/jobs/document-child.mjs) runs: one reused build folder, up to
+//     three passes, the diagnostics/fix/citations frames sent for EVERY
+//     compile (success included, so a page never keeps a stale band), and the
+//     PDF placed beside the source atomically, only by a successful run.
+//
+// Three places where JavaScript and R disagree by default, and this file sides
+// with R on purpose, because the answer must be the same whichever child ran:
+//
+//   · `trimws()` strips only space, tab, CR and LF; String#trim strips every
+//     Unicode space. `rTrim` is the R rule.
+//   · PCRE's `.` matches a carriage return and JavaScript's does not — and a
+//     CRLF log split on "\n" leaves one on every line. Every `.` below is
+//     written `[^\n]`.
+//   · `[[:space:]]` under R's PCRE is ASCII whitespace (no UCP), so it is
+//     written `[ \t\n\r\f\v]`, never `\s`.
+//
+// Diagnostic columns are 1-based CODE POINTS, as R reports them; the browser
+// (lib/latex-diagnostics.js) converts to UTF-16 against the real line.
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import crypto from "node:crypto";
+import { readEnvName } from "./env-names.mjs";
+import { LATEX_ENGINES, LATEX_TIMEOUT, latexOptions } from "./planes/jobs.mjs";
+
+export { LATEX_ENGINES, LATEX_TIMEOUT };
+export const LATEX_DIAGNOSTIC_MAX = 500;
+export const LATEX_SOURCE_READ_MAX = 4e6;          // a source file consulted for a column
+export const LATEX_CITATION_MAX = 100;
+// TeX's max_print_line: a log line of exactly this width has been hard-wrapped
+// and continues on the next line, with no marker (LEARNINGS 2026-09-07).
+export const LATEX_LOG_WRAP = 79;
+/** How much of the .log is read back: its final megabyte, as latex.R. */
+export const LATEX_LOG_TAIL = 1000000;
+
+const SPACE = "[ \\t\\n\\r\\f\\v]";                 // PCRE [[:space:]], ASCII only
+const scalar = (x) => typeof x === "string";
+/** R's trimws(): space, tab, CR and LF only. */
+export const rTrim = (s) => String(s).replace(/^[ \t\r\n]+/, "").replace(/[ \t\r\n]+$/, "");
+/** R's nchar(type = "chars"): code points, not UTF-16 units. */
+const chars = (s) => Array.from(s).length;
+/** R's as.integer() on a digit string: NA (null) past the 32-bit range. */
+const rInt = (digits) => { const n = Number(digits); return Number.isFinite(n) && n <= 2147483647 ? n : null; };
+/** paste() of a possibly-NA scalar. */
+const pasteNA = (v) => (v == null ? "NA" : String(v));
+
+/**
+ * R's readLines(): LF, CRLF or CR end a line, a final incomplete line is kept,
+ * an empty file is no lines, and an embedded NUL ends its line.
+ * @param {string} text
+ * @returns {string[]}
+ */
+export function splitReadLines(text) {
+  if (text === "") return [];
+  const out = text.split(/\r\n|\r|\n/);
+  if (/(\r\n|\r|\n)$/.test(text)) out.pop();
+  return out.map((line) => line.split("\0")[0]);
+}
+
+/**
+ * R's `strsplit(value, "\n", fixed = TRUE)[[1L]]`: trailing empty pieces are
+ * NOT kept ("a\nb\n" is two lines), and "" is no lines at all.
+ * @param {string} text
+ * @returns {string[]}
+ */
+export function splitLog(text) {
+  if (text === "") return [];
+  const out = text.split("\n");
+  if (out[out.length - 1] === "") out.pop();
+  return out;
+}
+
+// ── discovery and argv ──────────────────────────────────────────────────────
+
+/** Is this a usable executable file? (latex_executable) */
+export function latexExecutable(p) {
+  if (!scalar(p) || !p) return false;
+  try {
+    if (!fs.statSync(p).isFile()) return false;
+    fs.accessSync(p, fs.constants.X_OK);
+    return true;
+  } catch { return false; }
+}
+
+/** `Sys.which()`: the first executable of that name on PATH, or "". */
+export function whichOnPath(name, { env = process.env, platform = process.platform } = {}) {
+  const exts = platform === "win32" ? ["", ".exe", ".cmd", ".bat"] : [""];
+  for (const dir of String(env.PATH || "").split(path.delimiter)) {
+    if (!dir) continue;
+    for (const ext of exts) {
+      const candidate = path.join(dir, name + ext);
+      if (latexExecutable(candidate)) return candidate;
+    }
+  }
+  return "";
+}
+
+/**
+ * Discover an engine through explicit environment override, PATH and installs.
+ *
+ * The override is `BEATRINA_<ENGINE>` (e.g. BEATRINA_TECTONIC) and it is a
+ * promise: naming a file that is not executable is an error, never a silent
+ * fall-through to some other copy. Then PATH, then the places TeX installs
+ * put binaries when nothing put them on PATH (Homebrew, MacTeX, MiKTeX).
+ *
+ * @param {string} [engine] engine name or "auto"
+ * @param {Object} [o]
+ * @param {(name: string) => string} [o.lookup] PATH lookup, "" when absent
+ * @param {(name: string) => string} [o.getenv] environment lookup, "" when unset
+ * @param {(p: string) => boolean} [o.usable] executable predicate
+ * @returns {{engine: string, binary: string}} or throws naming the missing engine
+ */
+export function latexDiscover(engine = "auto", {
+  lookup = (name) => whichOnPath(name),
+  getenv = (name) => readEnvName(process.env, name),
+  usable = latexExecutable,
+} = {}) {
+  if (!scalar(engine) || !["auto", ...LATEX_ENGINES].includes(engine)) throw new Error(`unknown LaTeX engine '${engine}'`);
+  const engines = engine === "auto" ? LATEX_ENGINES : [engine];
+  const env = (name) => String(getenv(name) ?? "");
+  for (const name of engines) {
+    const override = env(`BEATRINA_${name.toUpperCase()}`);
+    if (override) {
+      if (!usable(override)) throw new Error(`BEATRINA_${name.toUpperCase()} does not name an executable file.`);
+      return { engine: name, binary: override };
+    }
+    // file.path() joins with "/" on every platform, and so does this.
+    const candidates = [String(lookup(name) ?? ""),
+      ...["/opt/homebrew/bin", "/usr/local/bin", "/Library/TeX/texbin", "/usr/bin"].map((dir) => `${dir}/${name}`)];
+    if (env("LOCALAPPDATA")) candidates.push([env("LOCALAPPDATA"), "Programs", "MiKTeX", "miktex", "bin", "x64", `${name}.exe`].join("/"));
+    if (env("ProgramFiles")) candidates.push([env("ProgramFiles"), "MiKTeX", "miktex", "bin", "x64", `${name}.exe`].join("/"));
+    const hit = candidates.find((c) => usable(c));
+    if (hit !== undefined) return { engine: name, binary: hit };
+  }
+  throw new Error(`${engine === "auto" ? "A LaTeX engine" : engine} was not found. Install a TeX engine or set its BEATRINA_<ENGINE> binary path.`);
+}
+
+/**
+ * Build argv without shell interpolation. Compilation is offline by default.
+ *
+ * `fetch` is the ONE exception and it exists because of a mismatch nobody
+ * chose: `--only-cached` is a strict-offline promise, and on a machine whose
+ * only engine is Tectonic — whose whole design is fetch-on-demand — it means
+ * the first compile of any real paper fails with a list of packages and an
+ * instruction to go and use a terminal. So the promise is restated as the one
+ * Beatrina keeps everywhere else: the kernel reaches the network only when the
+ * person pressed something that said so. `fetch` is that press — never a
+ * default, never a setting, never sticky. `--untrusted` is kept either way;
+ * that is the flag that matters for running someone else's .tex.
+ *
+ * NO -halt-on-error, and Tectonic's equivalent turned OFF, on purpose. TeX's
+ * own behaviour for a missing font is to substitute one and carry on; for a
+ * missing package, to keep going and let the undefined commands surface.
+ * Halting throws that away and returns NOTHING — measured on the owner's own
+ * CVs, six of eight produced no PDF for causes TeX could work around. This is
+ * only safe because the result is LABELLED: `latexCompile()` counts the error
+ * diagnostics of a successful compile and the PDF pane says how many.
+ *
+ * @param {string} engine resolved engine name
+ * @param {string} target absolute source path
+ * @param {string} output absolute output directory
+ * @param {boolean} [fetch] allow the engine to download missing packages, this run only
+ * @returns {{wd: string, args: string[]}}
+ */
+export function latexArgv(engine, target, output, fetch = false) {
+  if (!LATEX_ENGINES.includes(engine) || !scalar(target) || !scalar(output)) throw new Error("latexArgv: invalid engine, target or output");
+  const common = ["-interaction=nonstopmode", "-file-line-error", "-no-shell-escape"];
+  const args = engine === "tectonic"
+    ? [...(fetch === true ? [] : ["--only-cached"]), "--untrusted", "--print", "--keep-logs", "--color", "never",
+      "-Z", "continue-on-errors", "--outdir", output, target]
+    : engine === "latexmk"
+      ? ["-pdf", "-norc", ...common, `-outdir=${output}`, target]
+      : [...common, `-output-directory=${output}`, target];
+  return { wd: path.dirname(target), args };
+}
+
+// ── what went wrong, in words and as a fact ─────────────────────────────────
+
+/**
+ * The sentence a person can act on, for a missing asset under either engine.
+ * Tectonic and a local TeX fail the same way for different reasons: a Tectonic
+ * failure is almost always "not fetched yet" (the compile is offline), a local
+ * TeX failure is "not installed". THE BUTTON FIRST, the terminal second.
+ */
+export function latexMissingHint(what, engine, target, plural = false) {
+  const are = plural === true ? "are" : "is";
+  if (engine === "tectonic") {
+    return `${what} ${are} not in Tectonic's package cache. Beatrina compiles offline, so nothing was `
+      + `downloaded: use Fetch and compile below to get ${plural === true ? "them" : "it"} for one compile, or run `
+      + `tectonic "${path.basename(target)}" in a terminal (in ${path.dirname(target)}).`;
+  }
+  return `${what} ${are} not installed. Install ${plural === true ? "them" : "it"} in your TeX distribution, then compile again.`;
+}
+
+// The engine echoes the macro that raised the error (`File \`#1.#2' not
+// found`); a name holding a parameter token is the definition, not a file.
+const MISSING_FILE = /File `[^'#]+' not found/;
+const missingFiles = (lines) => {
+  const hits = lines.map((l) => (l.match(MISSING_FILE) || [null])[0]).filter((h) => h != null);
+  return [...new Set(hits.map((h) => h.replace(/^File `([^']+)' not found$/, "$1")))];
+};
+
+/**
+ * What Beatrina could DO about this failure, as a fact rather than a sentence.
+ * One reader, two renderings: the hint is prose for a person, this is the same
+ * reading for the PAGE, which must not decide on a button by matching English.
+ * Only ONE fix is machine-actionable: missing packages under Tectonic.
+ * @param {string[]} lines
+ * @param {string} engine
+ * @returns {{fix: ""|"fetch", assets: string[]}}
+ */
+export function latexFailureFix(lines, engine) {
+  if (!Array.isArray(lines) || !scalar(engine)) throw new Error("latexFailureFix: lines and engine are required");
+  const none = { fix: "", assets: [] };
+  if (engine !== "tectonic") return none;
+  const assets = missingFiles(lines);
+  return assets.length ? { fix: "fetch", assets } : none;
+}
+
+const PDF_PRIMITIVE = /\\pdf(shellescape|output|pagewidth|pageheight|compresslevel|minorversion|horigin|vorigin)/;
+
+/**
+ * Turn a failed engine's output into the sentence that names the fix. THE
+ * LADDER IS ORDERED BY HOW SPECIFIC THE ADVICE IS, and it ends in the
+ * diagnostics rather than in the log: "see the compile log" points at the pane
+ * that holds LESS than Problems already holds. The bare pointer survives only
+ * for a failure that produced no diagnostics at all.
+ * @param {string[]} lines compiler stdout and log lines
+ * @param {string} engine
+ * @param {string} target
+ * @param {object[]} [diagnostics] rows from latexLogDiagnostics()
+ * @returns {string} one sentence, never empty
+ */
+export function latexFailureHint(lines, engine, target, diagnostics = []) {
+  if (!Array.isArray(lines) || !scalar(engine) || !scalar(target) || !Array.isArray(diagnostics)) {
+    throw new Error("latexFailureHint: invalid arguments");
+  }
+  const missing = missingFiles(lines);
+  if (missing.length) return latexMissingHint(missing.join(", "), engine, target, missing.length > 1);
+  // Tectonic is XeTeX: a document that names the pdftex driver loads
+  // pdftex.def, whose first \pdf... primitive is "Undefined control sequence"
+  // at \begin{document} — a driver mismatch, not a typo.
+  if (engine === "tectonic" && lines.some((l) => /^! Undefined control sequence/.test(l)) && lines.some((l) => PDF_PRIMITIVE.test(l))) {
+    return "an undefined \\pdf... primitive: this document names the pdftex driver ([pdftex] on graphicx or hyperref) "
+      + "and Tectonic is XeTeX-based. Remove the [pdftex] option (the driver is detected automatically), then compile again.";
+  }
+  // A font TeX cannot load is the SAME condition as a missing .sty. The name
+  // after `=` is what the person has to obtain (brackets and XeTeX's feature
+  // string after `:` are request syntax). THE PHRASE AND THE NAME ARE MATCHED
+  // SEPARATELY, because TeX hard-wraps its log at 79 columns and a long font
+  // name splits "not loadable" mid-word onto the next line.
+  const named = [...new Set(lines.map((l) => l.match(/^! Font [^=]+=([^ :]+)/)).filter(Boolean)
+    .map((m) => m[1].replace(/^\[|\]$/g, "")))];
+  if (named.length && lines.some((l) => /not loadable|Metric \(TFM\)/.test(l))) {
+    return latexMissingHint(`the font${named.length > 1 ? "s" : ""} ${named.join(", ")}`, engine, target, named.length > 1);
+  }
+  const errors = diagnostics.filter((row) => row && row.severity === "error");
+  if (errors.length) {
+    const first = errors[0];
+    // A diagnostic may carry no line; "line NA" is not a place.
+    const where = first.line == null ? path.basename(first.path) : `${path.basename(first.path)} line ${first.line}`;
+    return `${errors.length === 1 ? "1 error is listed" : `${errors.length} errors are listed`} in Problems; the first is ${where}: ${String(first.message).replace(/[.]+$/, "")}`;
+  }
+  return "See the compile log.";
+}
+
+// ── the log parser ──────────────────────────────────────────────────────────
+
+/**
+ * Severity of a compiler message. The engine's own `error:`/`warning:` prefix
+ * is authoritative; without one, only a LEADING warning marker counts — an
+ * error whose text merely contains the word "warning" is still an error.
+ */
+export function latexSeverity(prefix, message) {
+  const p = rTrim(prefix == null ? "" : String(prefix)).toLowerCase();
+  if (p === "warning") return "warning";
+  if (p === "error") return "error";
+  return new RegExp(`^(?:LaTeX|Package[^:]*|Class[^:]*|pdfTeX|Font)${SPACE}+[Ww]arning:`).test(message == null ? "" : String(message))
+    ? "warning" : "error";
+}
+
+/**
+ * The 1-based CODE POINT column an `l.N` echo points at, or null.
+ *
+ * The echo is LOSSY: measured against tectonic 0.15.0, a source `\U1D538` is
+ * logged as `\UD538`, so a column counted in the echo lands inside a surrogate
+ * pair. The echo is only ever a HINT, and a column is returned only when it
+ * is an EXACT prefix of the genuine source line. A column that cannot be
+ * justified is worse than none.
+ */
+export function latexEchoColumn(echo, sourceLine) {
+  if (!scalar(echo) || !echo || !scalar(sourceLine)) return null;
+  if (!sourceLine.startsWith(echo)) return null;
+  return chars(echo) + 1;
+}
+
+/** R's normalizePath(mustWork = FALSE) on a Unix: realpath when it resolves, else as given. */
+function normalizePath(p) {
+  try { return fs.realpathSync.native(p); } catch { return p; }
+}
+const exists = (p) => { try { fs.statSync(p); return true; } catch { return false; } };
+
+const FILE_LINE = new RegExp(`^(?:(error|warning):${SPACE}*)?([^\\n]+?):([0-9]+):(?:([0-9]+):)?${SPACE}*([^\\n]+)$`);
+const LOCATION = new RegExp(`^l\\.([0-9]+)${SPACE}([^\\n]*)$`);
+const WARNING = /(?:LaTeX|Package [^\n]+) Warning: ([^\n]+?)(?: on input line ([0-9]+))?\.?$/;
+const OPENED = new RegExp(`^("[^"\\n]+\\.(?:tex|sty|cls)"|[^()\\n]*?\\.(?:tex|sty|cls))(?=[ \\t\\n\\r\\f\\v)]|$)`);
+const SHORT = /^("[^"]+"|[^ \t\n\r\f\v()]+)/;
+
+/**
+ * Normalize compiler messages into bounded diagnostic rows, retaining 1-based
+ * code-point coordinates (the browser owns the UTF-16 conversion).
+ *
+ * @param {string[]} lines compiler stdout or log lines
+ * @param {string} root absolute root source path
+ * @returns {{path: string, line: number|null, col: number|null, message: string,
+ *   severity: "error"|"warning", source: string, log: string}[]}
+ */
+export function latexLogDiagnostics(lines, root) {
+  if (!Array.isArray(lines) || !scalar(root)) throw new Error("latexLogDiagnostics: lines and root are required");
+  const rows = [];
+  const seen = new Set();
+  let pending = null;
+  const stack = [];
+  // Scoped to THIS call on purpose: a cache outliving one compile would
+  // compute a column from the text as it was before the edit that triggered
+  // the rebuild.
+  const sourceCache = new Map();
+  const sourceLine = (file, line) => {
+    if (line == null || !Number.isFinite(line) || line < 1) return null;
+    if (!sourceCache.has(file)) {
+      // Unreadable, absent, oversized or binary: no column. The documented safe
+      // outcome, not a swallowed failure — the row is still reported.
+      let value = [];
+      try {
+        const st = fs.statSync(file);
+        if (st.isFile() && st.size <= LATEX_SOURCE_READ_MAX) value = splitReadLines(fs.readFileSync(file, "utf8"));
+      } catch { value = []; }
+      sourceCache.set(file, value);
+    }
+    const text = sourceCache.get(file);
+    return line > text.length ? null : text[line - 1];
+  };
+  const current = () => {
+    const files = stack.filter((v) => v != null && v !== "");
+    return files.length ? files[files.length - 1] : root;
+  };
+  const resolveFile = (file) => {
+    let f = file.replace(/^"|"$/g, "");
+    if (!/^(\/|[A-Za-z]:[/\\])/.test(f)) f = path.dirname(root) + "/" + f;
+    if (!exists(f) && exists(`${f}.tex`)) f = `${f}.tex`;
+    return normalizePath(f);
+  };
+  // The log lines AROUND a finding, bounded: TeX says what it was reading
+  // (`l.12 \badcommand`) and what it did about it on the lines that follow.
+  // At most 8 non-blank lines and 600 characters.
+  const excerpt = (from, to) => {
+    if (from == null || to == null) return "";
+    const span = lines.slice(Math.max(1, from) - 1, Math.min(lines.length, Math.max(from, to)))
+      .filter((l) => rTrim(l) !== "").slice(0, 8);
+    return Array.from(span.join("\n")).slice(0, 600).join("");
+  };
+  const add = (file, line, message, severity = "error", col = null, from = null, to = null) => {
+    const resolved = resolveFile(file);
+    const key = [resolved, pasteNA(line), pasteNA(col), rTrim(message).replace(/[.]+$/, "")].join("\r");
+    if (!seen.has(key) && rows.length < LATEX_DIAGNOSTIC_MAX) {
+      seen.add(key);
+      rows.push({ path: resolved, line, col, message: rTrim(message), severity, source: "LaTeX compiler", log: excerpt(from, to) });
+    }
+  };
+  lines.forEach((line, index) => {
+    const i = index + 1;                                  // 1-based, as the R
+    // file-line-error and Tectonic include the file explicitly, including drives.
+    const hit = line.match(FILE_LINE);
+    if (hit) {
+      const [, prefix = "", file, lineNo, colNo = "", message] = hit;
+      if (prefix || /\.(tex|sty|cls|bib)$/.test(file) || exists(resolveFile(file))) {
+        add(file, rInt(lineNo), message, latexSeverity(prefix, message), colNo ? rInt(colNo) : null, i, i + 4);
+        pending = null;
+        return;
+      }
+    }
+    if (line.startsWith("!")) { pending = { file: current(), message: rTrim(line.replace(/^!/, "")), at: i }; return; }
+    const location = line.match(LOCATION);
+    if (location && pending) {
+      const atLine = rInt(location[1]);
+      // The echo is a hint; the genuine source line is the authority.
+      const col = latexEchoColumn(location[2], sourceLine(resolveFile(pending.file), atLine));
+      add(pending.file, atLine, pending.message, "error", col, pending.at, i + 2);
+      pending = null;
+      return;
+    }
+    // A message with no `on input line` has NO line, and saying 1 would be
+    // inventing one; null travels as a file-level diagnostic.
+    const warning = line.match(WARNING);
+    if (warning) { add(current(), warning[2] ? rInt(warning[2]) : null, warning[1], "warning"); return; }
+    if (/^error:/.test(line) && !/^error: (halted on|unexpectedly halted)/.test(line)) {
+      add(current(), null, line.replace(/^error:[ \t\n\r\f\v]*/, ""));
+      return;
+    }
+    // Track log parentheses, including anonymous parentheses, so a closing
+    // package group returns !/l.N diagnostics to the including source.
+    for (let at = 0; at < line.length; at += 1) {
+      const c = line[at];
+      if (c === ")") { stack.pop(); continue; }
+      if (c !== "(") continue;
+      const rest = line.slice(at + 1);
+      let name = rest.match(OPENED);
+      if (!name) {
+        const short = rest.match(SHORT);
+        if (short && exists(resolveFile(short[1]))) name = short;
+      }
+      stack.push(name ? name[1] : "");
+    }
+  });
+  if (pending) add(pending.file, 1, pending.message);
+  return rows;
+}
+
+// ── the bibliography verdict ────────────────────────────────────────────────
+
+/**
+ * Re-join TeX's hard-wrapped log lines: a line of exactly 79 characters was
+ * cut, and the next line continues it with no marker. BibTeX's .blg is not
+ * wrapped this way, and a complete 79-character line costs only a longer
+ * string, so this is safe over both.
+ * @param {string[]} lines
+ * @returns {string[]}
+ */
+export function latexUnwrap(lines) {
+  if (!Array.isArray(lines)) throw new Error("latexUnwrap: lines must be an array");
+  if (lines.length < 2) return lines.slice();
+  const out = [];
+  lines.forEach((line, i) => {
+    if (i > 0 && chars(lines[i - 1]) === LATEX_LOG_WRAP) out[out.length - 1] += line;
+    else out.push(line);
+  });
+  return out;
+}
+
+/**
+ * Bibliography and citation problems that do NOT fail a compile.
+ *
+ * Tectonic runs BibTeX itself and, when BibTeX cannot open the style file,
+ * prints "errors were issued by BibTeX, but were ignored", finishes, and exits
+ * 0 — every citation `[?]`, the reference list empty: a WRONG PDF delivered
+ * as a success. So the compile carries a second list beside the diagnostics.
+ * BibTeX's messages are read from `bibLines` (the .blg plus the engine's
+ * stdout); undefined citations from the FINAL pass only (`texLines`), or a key
+ * the second pass resolved would be reported as broken.
+ *
+ * @param {string[]} texLines
+ * @param {string[]} bibLines
+ * @param {string} engine
+ * @param {boolean} [fetch] was this compile allowed to reach the network?
+ * @returns {{kind: string, file: string, key: string, line: number|null,
+ *   message: string, log: string, fetchable: boolean}[]}
+ */
+export function latexCitationProblems(texLines, bibLines, engine, fetch = false) {
+  if (!Array.isArray(texLines) || !Array.isArray(bibLines) || !scalar(engine) || typeof fetch !== "boolean") {
+    throw new Error("latexCitationProblems: invalid arguments");
+  }
+  const tex = latexUnwrap(texLines);
+  const bib = latexUnwrap(bibLines);
+  const rows = [];
+  const seen = new Set();
+  const add = (kind, message, log, { file = "", key = "", line = null, fetchable = false } = {}) => {
+    const id = [kind, file, key].join("\r");
+    if (seen.has(id) || rows.length >= LATEX_CITATION_MAX) return;
+    seen.add(id);
+    rows.push({ kind, file, key, line, message, log: rTrim(log), fetchable: fetchable === true });
+  };
+  const tectonic = engine === "tectonic";
+  // The sentence names the RECOVERY, and which one depends on the engine and
+  // on whether the network was already tried.
+  const styleSentence = (file) => (tectonic && !fetch
+    ? `Tectonic could not find ${file}; it fetches it when online — retry with a connection, or place the file beside the document.`
+    : tectonic
+      ? `Tectonic could not find ${file} even when allowed to fetch; place the file beside the document.`
+      : `BibTeX could not find ${file}; install it in your TeX distribution, or place the file beside the document.`);
+  const matches = (re) => bib.map((l) => l.match(re)).filter(Boolean);
+  // ── BibTeX's own complaints, in the order a reader can act on them ──
+  matches(/^I couldn't open style file ([^ \t\n\r\f\v]+)/).forEach((m) =>
+    add("missing-style", styleSentence(m[1]), m[0], { file: m[1], fetchable: tectonic && !fetch }));
+  matches(/^I couldn't open database file ([^ \t\n\r\f\v]+)/).forEach((m) =>
+    add("missing-bib", `BibTeX could not open ${m[1]}; place it beside the document, or point \\bibliography{} at a file that exists.`, m[0], { file: m[1] }));
+  matches(/^Warning--I didn't find a database entry for "([^"]+)"/).forEach((m) =>
+    add("missing-entry", `\\cite{${m[1]}} has no entry in the .bib files, so it prints as [?].`, m[0], { key: m[1] }));
+  const ignored = bib.filter((l) => /errors were issued by BibTeX, but were ignored/.test(l));
+  if (ignored.length) {
+    const counts = matches(/^\(There (?:was|were) ([0-9]+) error messages?\)/);
+    const n = counts.length ? rInt(counts[counts.length - 1][1]) : null;
+    add("bibtex-errors", `BibTeX reported ${n == null ? "errors" : `${n} error${n === 1 ? "" : "s"}`} and the compile carried on without them: the reference list was not built.`, ignored[0]);
+  }
+  // ── what the final pass still could not resolve ──
+  const citeRe = /Warning: Citation `([^']+)' on page [0-9]+ undefined(?: on input line ([0-9]+))?/;
+  tex.forEach((l) => {
+    const m = l.match(citeRe);
+    if (m) add("undefined-citation", `\\cite{${m[1]}} is undefined: it prints as [?] and is missing from the reference list.`, l,
+      { key: m[1], line: m[2] ? rInt(m[2]) : null });
+  });
+  // The summary line alone (a key too long for the wrap to save): still said.
+  const summary = tex.filter((l) => /Warning: There were undefined citations/.test(l));
+  if (summary.length && !rows.some((r) => r.kind === "undefined-citation")) {
+    add("undefined-citation", "There were undefined citations: they print as [?] and are missing from the reference list.", summary[0]);
+  }
+  return rows;
+}
+
+// ── the compile ─────────────────────────────────────────────────────────────
+
+/** The negative-signal convention processx reports for a killed process. */
+export function exitStatus(result) {
+  if (result.code != null) return result.code;
+  if (result.signal && os.constants.signals[result.signal]) return -os.constants.signals[result.signal];
+  return null;
+}
+
+/**
+ * Read at most the final `max` bytes of a log as lines. Invalid UTF-8 (a seek
+ * that lands mid-character, a latin1 font name) is DROPPED, as R's
+ * `iconv(sub = "")` does, rather than turned into U+FFFD.
+ * @param {string} file
+ * @returns {string[]}
+ */
+export function readLogTail(file, max = LATEX_LOG_TAIL) {
+  let fd;
+  try {
+    fd = fs.openSync(file, "r");
+    const size = fs.fstatSync(fd).size;
+    const start = Math.max(0, size - max);
+    const buf = Buffer.alloc(Math.min(size, max));
+    const n = fs.readSync(fd, buf, 0, buf.length, start);
+    const bytes = buf.subarray(0, n);
+    // Valid UTF-8 (the usual case) is decoded as it is, a genuine U+FFFD
+    // included; only a buffer that FAILS strict decoding has its replacement
+    // characters removed — the bytes iconv(sub = "") would have dropped.
+    let text;
+    try { text = new TextDecoder("utf-8", { fatal: true }).decode(bytes); } catch { text = new TextDecoder("utf-8").decode(bytes).replace(/\uFFFD/g, ""); }
+    return splitLog(text);
+  } finally {
+    if (fd !== undefined) fs.closeSync(fd);
+  }
+}
+
+/**
+ * Compile one saved root. Emits `diagnostics`, `fix` and `citations` for every
+ * compile, then `output` for a successful one; throws (with the sentence that
+ * names the fix) for a failed one, after those frames went out.
+ *
+ * @param {Object} o
+ * @param {string} o.target absolute source path
+ * @param {string} o.engine engine choice ("auto" or a name)
+ * @param {number} o.timeout total deadline in seconds, including repeat passes
+ * @param {boolean} [o.fetch] allow this ONE compile to download missing packages
+ * @param {(bin: string, args: string[], o: {cwd: string, timeoutMs: number}) =>
+ *   Promise<{code: number|null, signal?: string|null, lines: string[], timedOut: boolean,
+ *   truncated?: boolean, error?: string}>} o.runStreaming
+ * @param {(frame: object) => void} o.emit
+ * @param {(text: string) => void} [o.print] the job's log (stdout)
+ * @param {Object} [o.discover] options for latexDiscover (tests)
+ * @returns {Promise<string>} the verified PDF path
+ */
+export async function latexCompile({ target, engine, timeout, fetch = false, runStreaming, emit,
+  print = (text) => process.stdout.write(text), discover = {} }) {
+  if (!scalar(target) || typeof runStreaming !== "function" || typeof emit !== "function") throw new Error("latexCompile: invalid arguments");
+  latexOptions({ engine, timeout, fetch });
+  const found = latexDiscover(engine, discover);
+  // ONE build folder per root, reused: aux files make the second pass fast, and
+  // nothing accumulates. The PDF lands BESIDE the root as `<stem>.pdf`, where
+  // every TeX tool puts it, and is replaced only by a successful run,
+  // atomically, so a failed compile leaves the previous PDF where it was.
+  const stem = path.basename(target).replace(/\.[^.]+$/, "");
+  const here = path.dirname(target);
+  const output = path.join(here, ".beatrina-latex", stem);
+  const isDir = (p) => { try { return fs.statSync(p).isDirectory(); } catch { return false; } };
+  if (!isDir(output)) { try { fs.mkdirSync(output, { recursive: true }); } catch { /* said on the next line */ } }
+  if (!isDir(output)) throw new Error("Cannot create the LaTeX build folder.");
+  const spec = latexArgv(found.engine, target, output, fetch === true);
+  if (fetch === true) print("Fetching missing packages for this compile (this one reaches the network).\n");
+  const pdf = path.join(output, `${stem}.pdf`);
+  const final = path.join(here, `${stem}.pdf`);
+  // A PDF left in the build folder by an earlier run must not pass for this
+  // run's: an engine that exits 0 without writing one is a failed compile.
+  try { fs.rmSync(pdf, { force: true }); } catch { /* a folder by that name: unlink() leaves it too, and it is no PDF */ }
+  const logPath = path.join(output, `${stem}.log`);
+  const startedAt = Date.now();
+  let pass = 0;
+  let result = null;
+  for (;;) {
+    const remaining = timeout - (Date.now() - startedAt) / 1000;
+    if (remaining <= 0) throw new Error(`LaTeX compile timed out after ${timeout} seconds.`);
+    pass += 1;
+    print(`Compiling with ${found.engine} (pass ${pass})\n`);
+    result = await runStreaming(found.binary, spec.args, { cwd: spec.wd, timeoutMs: remaining * 1000 });
+    // processx raises when the binary cannot be started; so does this.
+    if (result.error) throw new Error(`${found.engine} could not be started: ${result.error}`);
+    if (result.timedOut || exitStatus(result) !== 0 || pass >= 3 || ["tectonic", "latexmk"].includes(found.engine)
+      || !result.lines.some((l) => /Rerun|run LaTeX again|Label[^\n]*changed/i.test(l))) break;
+  }
+  const status = result.timedOut ? null : exitStatus(result);
+  // Some engines write diagnostics only to the log. Read at most its final MB.
+  const logLines = exists(logPath) ? readLogTail(logPath) : [];
+  // Successful multi-pass engines leave the authoritative final pass in .log.
+  // Keep earlier passes in Jobs output, but do not publish resolved warnings.
+  const diagnosticLines = status === 0 && logLines.length ? logLines : [...result.lines, ...logLines];
+  // Parsed once and used twice: the pane gets the rows, and the failure
+  // sentence gets to say what is in the pane rather than pointing at the log.
+  const diagnostics = latexLogDiagnostics(diagnosticLines, target);
+  // `engine`: a FAILED compile emits no `output` frame, and the moment an
+  // explanation needs the engine is exactly that one.
+  emit({ type: "job", event: "diagnostics", rows: diagnostics, root: target, truncated: result.truncated === true, engine: found.engine });
+  // What could be DONE about it, sent as a fact beside the rows — for a
+  // success too, so a page never carries a stale offer from the previous run.
+  const fix = latexFailureFix(diagnosticLines, found.engine);
+  emit({ type: "job", event: "fix", fix: fix.fix, assets: fix.assets, fetched: fetch === true });
+  // The bibliography's verdict. A missing `.bst` under Tectonic EXITS 0 with
+  // every citation `[?]`, so this is read for a success above all.
+  const blgPath = path.join(output, `${stem}.blg`);
+  let blgLines = [];
+  if (exists(blgPath)) blgLines = splitReadLines(fs.readFileSync(blgPath, "utf8"));
+  const citations = latexCitationProblems(diagnosticLines, [...blgLines, ...result.lines], found.engine, fetch === true);
+  emit({ type: "job", event: "citations", rows: citations, root: target });
+  if (result.timedOut) throw new Error(`LaTeX compile timed out after ${timeout} seconds.`);
+  if (status !== 0) {
+    throw new Error(`${found.engine} exited ${pasteNA(status)}. ${latexFailureHint(diagnosticLines, found.engine, target, diagnostics)}`);
+  }
+  let validPdf = false;
+  try {
+    if (fs.statSync(pdf).isFile()) {
+      const fd = fs.openSync(pdf, "r");
+      const head = Buffer.alloc(5);
+      try { fs.readSync(fd, head, 0, 5, 0); } finally { fs.closeSync(fd); }
+      validPdf = head.toString("latin1") === "%PDF-";
+    }
+  } catch { validPdf = false; }
+  // With the engine no longer halting, "exit 0 and no PDF" is what a genuinely
+  // fatal document looks like, so this branch needs the sentence too.
+  if (!validPdf) throw new Error(`The compiler finished without producing a PDF. ${latexFailureHint(diagnosticLines, found.engine, target, diagnostics)}`);
+  // Copy into a sibling temp name, then rename: a reader opening `<stem>.pdf`
+  // sees the old PDF or the new one, never a half-written file.
+  const staging = path.join(here, `.${stem}-${crypto.randomBytes(6).toString("hex")}.pdf`);
+  try {
+    fs.copyFileSync(pdf, staging);
+    fs.renameSync(staging, final);
+  } catch {
+    fs.rmSync(staging, { force: true });
+    throw new Error("The PDF was built but could not be placed beside the source.");
+  }
+  const placed = fs.realpathSync.native(final);
+  // The count travels with the output so the PDF can be labelled: a document
+  // TeX had to improvise parts of is a success with a caveat.
+  const errors = diagnostics.filter((row) => row.severity === "error").length;
+  emit({ type: "job", event: "output", renderer: found.engine, path: placed, format: "pdf", errors, citations: citations.length });
+  return placed;
+}