beatrina 0.8.6

package/kernel/latex.R

@@ -0,0 +1,609 @@
+# latex.R — LaTeX compile decisions and diagnostics for the existing Jobs plane.
+# Used by the supervisor's job spec and the isolated job-run.R child.
+# Origin: carmar-latex-plugin/host/workbench.mjs compilerSpec and
+# parseCompilerDiagnostics; SHA-256 fd168f3c2a70d5f010542b8c080e9173d03cb4e8e40862e7d957731f2fee519b
+# Captured argv and observed log results: test/fixtures/latex/compiler.json.
+# These are prototype inputs to review, not a validated engine contract.
+# WP4 must add !/l.N diagnostics, safe output resolution, discovery,
+# argv-only execution and tested process-group Stop through Jobs.
+#
+# function compilerSpec(engine, binary, rootAbsolute, outputDirectory) {
+#   const cwd = path.dirname(rootAbsolute);
+#   const input = path.basename(rootAbsolute);
+#   if (engine === "tectonic") {
+#     return {
+#       cwd,
+#       args: ["--keep-logs", "--synctex", "--outdir", outputDirectory, rootAbsolute]
+#     };
+#   }
+#   if (engine === "latexmk") {
+#     return {
+#       cwd,
+#       args: ["-pdf", "-interaction=nonstopmode", "-file-line-error", "-synctex=1", "-outdir=" + outputDirectory, input]
+#     };
+#   }
+#   return {
+#     cwd,
+#     args: ["-interaction=nonstopmode", "-file-line-error", "-synctex=1", "-output-directory=" + outputDirectory, input]
+#   };
+# }
+# 
+
+LATEX_ENGINES <- c("tectonic", "latexmk", "pdflatex", "xelatex", "lualatex")
+LATEX_TIMEOUT <- 180L
+LATEX_DIAGNOSTIC_MAX <- 500L
+LATEX_CITATION_MAX <- 100L
+# 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).
+LATEX_LOG_WRAP <- 79L
+
+#' Compile one saved root through the shared streaming process owner.
+#' @param target Absolute source path.
+#' @param engine Engine choice from latex_options.
+#' @param timeout Total deadline in seconds, including repeat passes.
+#' @param job_id Supervisor-issued job identifier.
+#' @param run_streaming Existing Jobs process runner.
+#' @param emit Existing Jobs frame writer.
+#' @param fetch Allow this ONE compile to download missing packages.
+#' @return Invisibly the verified PDF path; errors preserve diagnostic frames.
+latex_compile <- function(target, engine, timeout, job_id, run_streaming, emit, fetch = FALSE) {
+  stopifnot(latex_scalar(target), latex_scalar(job_id), is.function(run_streaming), is.function(emit))
+  latex_options(list(engine = engine, timeout = timeout, fetch = fetch))
+  found <- latex_discover(engine)
+  # ONE build folder per root, reused: aux files make the second pass fast,
+  # and nothing accumulates. Until 7.18 every compile made its own
+  # `compile-*` folder and kept it, so a hundred compiles were a hundred PDFs
+  # inside the user's own repository. The PDF itself lands BESIDE the root as
+  # `<stem>.pdf`, which is where every TeX tool puts it and where a reader
+  # looks for it; it is replaced only by a successful run, atomically, so a
+  # failed compile leaves the previous PDF exactly where it was.
+  stem <- sub("\\.[^.]+$", "", basename(target))
+  output <- file.path(dirname(target), ".carmar-latex", stem)
+  if (!dir.exists(output)) dir.create(output, recursive = TRUE, showWarnings = FALSE)
+  if (!dir.exists(output)) stop("Cannot create the LaTeX build folder.", call. = FALSE)
+  spec <- latex_argv(found$engine, target, output, fetch = fetch)
+  if (isTRUE(fetch)) {
+    cat("Fetching missing packages for this compile (this one reaches the network).\n")
+    flush(stdout())
+  }
+  pdf <- file.path(output, paste0(stem, ".pdf"))
+  final <- file.path(dirname(target), paste0(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.
+  if (file.exists(pdf)) unlink(pdf)
+  log_path <- file.path(output, paste0(stem, ".log"))
+  started_at <- Sys.time(); pass <- 0L; result <- NULL
+  repeat {
+    remaining <- timeout - as.numeric(difftime(Sys.time(), started_at, units = "secs"))
+    if (remaining <= 0) stop(sprintf("LaTeX compile timed out after %s seconds.", timeout), call. = FALSE)
+    pass <- pass + 1L
+    cat(sprintf("Compiling with %s (pass %d)\n", found$engine, pass)); flush(stdout())
+    result <- run_streaming(found$binary, spec$args, wd = spec$wd, timeout = remaining)
+    if (isTRUE(result$timed_out) || !identical(as.integer(result$status), 0L) || pass >= 3L ||
+        found$engine %in% c("tectonic", "latexmk") ||
+        !any(grepl("Rerun|run LaTeX again|Label.*changed", result$lines, ignore.case = TRUE))) break
+  }
+  # Some engines write diagnostics only to the log. Read at most its final MB;
+  # the Jobs runner already bounds the retained stdout by the same limit.
+  log_lines <- if (file.exists(log_path)) local({
+    con <- file(log_path, "rb"); on.exit(close(con))
+    size <- file.info(log_path)$size
+    seek(con, max(0, size - 1000000), origin = "start")
+    value <- iconv(rawToChar(readBin(con, "raw", n = 1000000L)), from = "UTF-8", to = "UTF-8", sub = "")
+    strsplit(value, "\n", fixed = TRUE)[[1L]]
+  }) else character()
+  # Successful multi-pass engines leave the authoritative final pass in .log.
+  # Keep earlier passes in Jobs output, but do not publish resolved warnings.
+  diagnostic_lines <- if (identical(as.integer(result$status), 0L) && length(log_lines)) log_lines else c(result$lines, log_lines)
+  # 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.
+  diagnostics <- latex_log_diagnostics(diagnostic_lines, target)
+  emit(list(type = "job", event = "diagnostics", rows = I(diagnostics),
+    root = target, truncated = isTRUE(result$truncated)))
+  # What could be DONE about it, sent as a fact beside the rows rather than
+  # left for the page to read out of the hint's prose. Emitted before either
+  # `stop()` below, because the frame has to reach the browser whichever way
+  # this compile turns out to have failed — and emitted for a SUCCESS too, so
+  # a page never carries a stale offer from the previous run.
+  fix <- latex_failure_fix(diagnostic_lines, found$engine)
+  emit(list(type = "job", event = "fix", fix = fix$fix, assets = I(fix$assets),
+    fetched = isTRUE(fetch)))
+  # The bibliography's verdict, as a list beside the diagnostics. A missing
+  # `.bst` under Tectonic is a compile that EXITS 0 with every citation `[?]`
+  # (LEARNINGS 2026-09-08), so this is read for a success above all — and
+  # sent for every compile, so a page never keeps the previous run's band.
+  # BibTeX's transcript is the `.blg`; Tectonic also echoes it to stdout.
+  blg_path <- file.path(output, paste0(stem, ".blg"))
+  blg_lines <- if (file.exists(blg_path)) readLines(blg_path, warn = FALSE, encoding = "UTF-8") else character()
+  citations <- latex_citation_problems(diagnostic_lines, c(blg_lines, result$lines), found$engine, fetch = isTRUE(fetch))
+  emit(list(type = "job", event = "citations", rows = I(citations), root = target))
+  if (isTRUE(result$timed_out)) stop(sprintf("LaTeX compile timed out after %s seconds.", timeout), call. = FALSE)
+  if (!identical(as.integer(result$status), 0L)) stop(sprintf("%s exited %s. %s", found$engine, result$status,
+    latex_failure_hint(diagnostic_lines, found$engine, target, diagnostics)), call. = FALSE)
+  valid_pdf <- file.exists(pdf) && !dir.exists(pdf) && local({
+    con <- file(pdf, "rb"); on.exit(close(con))
+    identical(readBin(con, "raw", n = 5L), charToRaw("%PDF-"))
+  })
+  # With the engine no longer halting, "exit 0 and no PDF" is what a genuinely
+  # fatal document looks like — so this branch, not the exit status, is now the
+  # main failure path and needs the sentence that names the fix.
+  if (!valid_pdf) stop(sprintf("The compiler finished without producing a PDF. %s",
+    latex_failure_hint(diagnostic_lines, found$engine, target, diagnostics)), call. = FALSE)
+  # 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.
+  staging <- tempfile(pattern = paste0(".", stem, "-"), tmpdir = dirname(target), fileext = ".pdf")
+  placed <- file.copy(pdf, staging, overwrite = TRUE) && file.rename(staging, final)
+  if (!placed) { if (file.exists(staging)) unlink(staging); stop("The PDF was built but could not be placed beside the source.", call. = FALSE) }
+  final <- normalizePath(final, mustWork = TRUE)
+  # The count travels with the output so the PDF can be labelled. A compile
+  # that produced a document TeX had to improvise parts of is a success with a
+  # caveat, and the caveat is the whole reason continuing is allowed at all.
+  errors <- length(Filter(function(row) identical(row$severity, "error"), diagnostics))
+  emit(list(type = "job", event = "output", renderer = found$engine, path = final, format = "pdf",
+    errors = errors, citations = length(citations)))
+  invisible(final)
+}
+
+#' Check a scalar string before accepting an engine or path.
+#' @param value Candidate value.
+#' @return Logical scalar.
+latex_scalar <- function(value) is.character(value) && length(value) == 1L && !is.na(value)
+
+#' Validate the data-only options carried from the supervisor to a compile job.
+#' @param opts List with engine, timeout and optional source identity.
+#' @return Named environment strings. Invalid values raise a readable error.
+latex_options <- function(opts = list()) {
+  stopifnot(is.list(opts))
+  engine <- if (is.null(opts$engine)) "auto" else opts$engine
+  timeout <- if (is.null(opts$timeout)) LATEX_TIMEOUT else opts$timeout
+  if (!latex_scalar(engine) || !engine %in% c("auto", LATEX_ENGINES)) {
+    stop("Choose auto, tectonic, latexmk, pdflatex, xelatex or lualatex.", call. = FALSE)
+  }
+  if (!is.numeric(timeout) || length(timeout) != 1L || !is.finite(timeout) || timeout != floor(timeout) || timeout < 1 || timeout > 600) {
+    stop("Compile timeout must be a whole number from 1 to 600 seconds.", call. = FALSE)
+  }
+  identity <- opts$identity
+  if (!is.null(identity)) {
+    number <- function(value) is.numeric(value) && length(value) == 1L && is.finite(value) && value >= 0 && value <= 9007199254740991 && value == floor(value)
+    if (!is.list(identity) || !latex_scalar(identity$uri) || !nzchar(identity$uri) || nchar(identity$uri) > 4096L
+        || !number(identity$version) || !number(identity$generation)) stop("Invalid compile source identity.", call. = FALSE)
+    identity <- identity[c("uri", "version", "generation")]
+  }
+  # FETCH is the one option that changes what the compile may TOUCH, so it is
+  # strict where the others are lenient: exactly TRUE turns it on, anything
+  # else — absent, "1", "yes", NA — is off. An option that means "reach the
+  # network" must never be arrived at by coercion.
+  fetch <- isTRUE(opts$fetch)
+  c(CARMAR_LATEX_ENGINE = engine, CARMAR_LATEX_TIMEOUT = as.character(timeout),
+    CARMAR_LATEX_FETCH = if (fetch) "1" else "",
+    CARMAR_LATEX_IDENTITY = if (is.null(identity)) "" else jsonlite::toJSON(identity, auto_unbox = TRUE, digits = NA))
+}
+
+#' Is this a usable executable file?
+#' @param path Candidate binary path.
+#' @return Logical scalar.
+latex_executable <- function(path) latex_scalar(path) && nzchar(path) && file.exists(path) && !dir.exists(path) && file.access(path, 1L) == 0L
+
+#' Discover an engine through explicit environment override, PATH and installs.
+#' @param engine Engine name or auto.
+#' @param lookup PATH lookup, injectable for deterministic discovery checks.
+#' @param getenv Environment lookup.
+#' @param usable Executable predicate.
+#' @return List with engine and binary, or an error naming the missing engine.
+latex_discover <- function(engine = "auto", lookup = Sys.which, getenv = Sys.getenv, usable = latex_executable) {
+  stopifnot(latex_scalar(engine), engine %in% c("auto", LATEX_ENGINES))
+  engines <- if (engine == "auto") LATEX_ENGINES else engine
+  result <- NULL
+  Find(function(name) {
+    override <- getenv(paste0("CARMAR_", toupper(name)))
+    if (nzchar(override)) {
+      if (!usable(override)) stop(sprintf("CARMAR_%s does not name an executable file.", toupper(name)), call. = FALSE)
+      result <<- list(engine = name, binary = override)
+      return(TRUE)
+    }
+    candidates <- c(unname(lookup(name)), file.path(c("/opt/homebrew/bin", "/usr/local/bin", "/Library/TeX/texbin", "/usr/bin"), name),
+      if (nzchar(getenv("LOCALAPPDATA"))) file.path(getenv("LOCALAPPDATA"), "Programs", "MiKTeX", "miktex", "bin", "x64", paste0(name, ".exe")),
+      if (nzchar(getenv("ProgramFiles"))) file.path(getenv("ProgramFiles"), "MiKTeX", "miktex", "bin", "x64", paste0(name, ".exe")))
+    hit <- Find(usable, candidates)
+    if (is.null(hit)) return(FALSE)
+    result <<- list(engine = name, binary = hit)
+    TRUE
+  }, engines)
+  if (is.null(result)) stop(sprintf("%s was not found. Install a TeX engine or set its CARMAR_<ENGINE> binary path.",
+    if (engine == "auto") "A LaTeX engine" else engine), call. = FALSE)
+  result
+}
+
+#' 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. That is a policy misapplied to its
+#' engine rather than a policy doing its job.
+#'
+#' So the promise is restated as the one CarmaR already keeps everywhere else
+#' (spike/cite.R's style repository): the kernel reaches the network only when
+#' the person pressed something that said so. `fetch` is that press. It is
+#' never a default, never a setting, and never sticky — it is passed for ONE
+#' compile, from a button that names what it will do. `--untrusted` is kept
+#' either way; that is the flag that matters for running someone else's .tex.
+#'
+#' @param engine Resolved engine name.
+#' @param target Absolute source path.
+#' @param output Absolute output directory, unique to this job.
+#' @param fetch Allow the engine to download missing packages, this run only.
+#' @return List with working directory and literal argument vector.
+latex_argv <- function(engine, target, output, fetch = FALSE) {
+  stopifnot(latex_scalar(engine), engine %in% LATEX_ENGINES, latex_scalar(target), latex_scalar(output))
+  # 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
+  # with a warning; for a missing package it is to keep going and let the
+  # undefined commands surface. Halting throws that away and returns NOTHING —
+  # and measured on the owner's own CVs, six of eight failed to produce any PDF
+  # for causes TeX was fully able to work around: `lmodern.sty` not in the
+  # offline cache, a Latin Modern italic not cached, a `[pdftex]` driver option.
+  # With the engine allowed to continue, all six produce a readable PDF.
+  #
+  # This is only safe because the result is LABELLED. A silently substituted
+  # font in a CV is exactly the failure the author finds at the hiring
+  # committee, so `latex_compile()` counts the error diagnostics of a
+  # successful compile and the PDF pane says how many there were. The rule is
+  # the export doctrine one level over: a document that could not carry
+  # something says so; it does not quietly change.
+  common <- c("-interaction=nonstopmode", "-file-line-error", "-no-shell-escape")
+  args <- if (engine == "tectonic") c(if (isTRUE(fetch)) NULL else "--only-cached",
+      "--untrusted", "--print", "--keep-logs", "--color", "never",
+      "-Z", "continue-on-errors", "--outdir", output, target)
+    else if (engine == "latexmk") c("-pdf", "-norc", common, paste0("-outdir=", output), target)
+    else c(common, paste0("-output-directory=", output), target)
+  list(wd = dirname(target), args = args)
+}
+
+#' 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, so this is
+#' the one place that difference is worded. CarmaR compiles offline by design
+#' (`--only-cached`, so the kernel never touches the network), which means a
+#' Tectonic failure is almost always "not fetched yet" and the fix is one
+#' command; a local TeX failure is "not installed" and the fix is the
+#' distribution's package manager.
+#' @param what The asset, already named (a file, a font).
+#' @param engine Resolved engine name.
+#' @param target Absolute root source path.
+#' @param plural Is `what` more than one thing? Only the verb changes.
+#' @return One sentence.
+latex_missing_hint <- function(what, engine, target, plural = FALSE) {
+  are <- if (isTRUE(plural)) "are" else "is"
+  if (identical(engine, "tectonic")) {
+    # THE BUTTON FIRST, the terminal second. Until 7.19 this sentence named
+    # only the terminal, because there was nothing else to name — the page had
+    # no way to fetch and the person's only route was out of the application.
+    # There is one now (latex_argv's `fetch`, offered by the failure panel), so
+    # the sentence points at what is on screen and keeps the command for
+    # somebody who would rather, or whose page is not showing the panel.
+    sprintf(paste0("%s %s not in Tectonic's package cache. CarmaR compiles offline, so nothing was ",
+      "downloaded: use Fetch and compile below to get %s for one compile, or run ",
+      "tectonic \"%s\" in a terminal (in %s)."),
+      what, are, if (isTRUE(plural)) "them" else "it", basename(target), dirname(target))
+  } else {
+    sprintf("%s %s not installed. Install %s in your TeX distribution, then compile again.",
+      what, are, if (isTRUE(plural)) "them" else "it")
+  }
+}
+
+#' What CarmaR could DO about this failure, as a fact rather than a sentence.
+#'
+#' The hint below is prose for a person; this is the same reading of the same
+#' log for the PAGE, because a page that decides whether to offer a button by
+#' matching English against `latex_missing_hint`'s wording is a page that
+#' breaks when the wording improves. One reader, two renderings — the same
+#' split the export backends make over one parse tree.
+#'
+#' Only ONE fix is machine-actionable today: missing packages under Tectonic,
+#' which CarmaR can fetch for this compile. A local TeX distribution's missing
+#' package is not — installing it is the distribution's business, not a button
+#' this program is entitled to press.
+#'
+#' @param lines Compiler stdout and log lines.
+#' @param engine Resolved engine name.
+#' @return list(fix = "fetch" | "", assets = character()) — `fix` is empty
+#'   whenever there is nothing to offer, which is most failures.
+latex_failure_fix <- function(lines, engine) {
+  stopifnot(is.character(lines), latex_scalar(engine))
+  none <- list(fix = "", assets = character(0))
+  if (!identical(engine, "tectonic")) return(none)
+  hits <- regmatches(lines, regexpr("File `[^\'#]+\' not found", lines))
+  if (!length(hits)) return(none)
+  list(fix = "fetch", assets = unique(sub("^File `([^\']+)\' not found$", "\\1", hits)))
+}
+
+#' Turn a failed engine's output into the sentence that names the fix, when
+#' the output names one. The common case is a missing `.sty`/`.cls` under
+#' Tectonic: the compile is offline by design (`--only-cached`, so the kernel
+#' never touches the network), and the package must be fetched once by hand.
+#' "See the compile log" was the whole message until 7.25, and the owner's
+#' first real compile stopped there.
+#'
+#' 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 the Problems pane already holds — the log is
+#' thousands of lines of TeX bookkeeping, while `latex_log_diagnostics()` has
+#' already reduced it to a file, a line and a message. When nothing on the
+#' ladder matched but the parse found errors, saying the first one and where
+#' it is beats naming a pane. The bare pointer survives only for a failure
+#' that produced no diagnostics at all, which is the one case where the log
+#' really is all there is.
+#' @param lines Compiler stdout and log lines.
+#' @param engine Resolved engine name.
+#' @param target Absolute root source path.
+#' @param diagnostics Parsed rows from `latex_log_diagnostics()`; optional.
+#' @return One sentence, never empty.
+latex_failure_hint <- function(lines, engine, target, diagnostics = list()) {
+  stopifnot(is.character(lines), latex_scalar(engine), latex_scalar(target), is.list(diagnostics))
+  # 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.
+  hits <- regmatches(lines, regexpr("File `[^'#]+' not found", lines))
+  if (length(hits)) {
+    missing <- unique(sub("^File `([^']+)' not found$", "\\1", hits))
+    named <- paste(missing, collapse = ", ")
+    return(latex_missing_hint(named, engine, target, plural = length(missing) > 1L))
+  }
+  # Tectonic is XeTeX: a document that names the pdftex driver
+  # (\usepackage[pdftex]{graphicx}, [pdftex]{hyperref}) loads pdftex.def, whose
+  # first use of a \pdf... primitive is "Undefined control sequence" at
+  # \begin{document} — a driver mismatch, not a typo, and the log says which.
+  if (identical(engine, "tectonic") && any(grepl("^! Undefined control sequence", lines)) &&
+      any(grepl("\\\\pdf(shellescape|output|pagewidth|pageheight|compresslevel|minorversion|horigin|vorigin)", lines))) {
+    return(paste0("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 asset
+  # is not on this machine — and only the wording differs, which is why it
+  # shares latex_missing_hint(). Two spellings reach here:
+  #
+  #   ! Font TU/lmr/m/it/12=[lmroman12-italic]:mapping=tex-text; at 12.0pt not loadable: Metric (TFM) file or installed font not found.
+  #   ! Font T1/lmr/m/it/12=ec-lmri12 at 12.0pt not loadable: Metric (TFM) file or installed font not found.
+  #
+  # The name after `=` is what the person has to obtain, so that is what is
+  # reported — not the TeX-internal `TU/lmr/m/it/12`, which names a slot in a
+  # font table nobody can install. Brackets and the OpenType feature string
+  # after `:` are XeTeX's request syntax, not part of the name.
+  #
+  # THE PHRASE AND THE NAME ARE MATCHED SEPARATELY, because TeX HARD-WRAPS its
+  # log at 79 columns with no continuation marker. A long font name pushes the
+  # phrase over that edge and it is split mid-word:
+  #
+  #   ! Font TU/lmr/m/it/12=[lmroman12-italic]:mapping=tex-text; at 12.0pt not loada
+  #   ble: Metric (TFM) file or installed font not found.
+  #
+  # One regex spanning both would have to match "not loada" — so this rule
+  # takes the NAME off the head of the `! Font` line, which is never wrapped
+  # away, and confirms the CONDITION anywhere in the output. `Metric (TFM)`
+  # survives on the continuation line and appears intact in stdout, so either
+  # source answers. The first version required both on one line and silently
+  # missed exactly the documents whose font names were longest.
+  fonts <- regmatches(lines, regexec("^! Font [^=]+=([^ :]+)", lines))
+  named <- unique(vapply(Filter(length, fonts), function(hit) gsub("^\\[|\\]$", "", hit[[2L]]), character(1)))
+  if (length(named) && any(grepl("not loadable|Metric \\(TFM\\)", lines))) {
+    return(latex_missing_hint(sprintf("the font%s %s", if (length(named) > 1L) "s" else "", paste(named, collapse = ", ")),
+                              engine, target, plural = length(named) > 1L))
+  }
+  # Nothing on the ladder matched. The parse usually still found something, and
+  # a file and a line beat the name of a pane — see the note above.
+  errors <- Filter(function(row) identical(row$severity, "error"), diagnostics)
+  if (length(errors)) {
+    first <- errors[[1L]]
+    return(sprintf("%s in Problems; the first is %s line %d: %s",
+      if (length(errors) == 1L) "1 error is listed" else sprintf("%d errors are listed", length(errors)),
+      basename(first$path), first$line, sub("[.]+$", "", first$message)))
+  }
+  "See the compile log."
+}
+
+#' Normalize compiler messages, retaining 1-based code-point coordinates.
+#' @param lines Compiler stdout or log lines.
+#' @param root Absolute root source path.
+#' @return Bounded diagnostic records; browser conversion owns UTF-16 offsets.
+latex_log_diagnostics <- function(lines, root) {
+  stopifnot(is.character(lines), latex_scalar(root))
+  rows <- list(); seen <- character(); pending <- NULL; stack <- list()
+  current <- function() {
+    files <- Filter(function(value) !is.null(value) && nzchar(value), stack)
+    if (length(files)) files[[length(files)]] else root
+  }
+  resolve_file <- function(file) {
+    file <- gsub('^"|"$', "", file)
+    if (!grepl("^(/|[A-Za-z]:[/\\\\])", file)) file <- file.path(dirname(root), file)
+    if (!file.exists(file) && file.exists(paste0(file, ".tex"))) file <- paste0(file, ".tex")
+    normalizePath(file, mustWork = FALSE)
+  }
+  add <- function(file, line, message, severity = "error", col = NA_integer_) {
+    file <- resolve_file(file)
+    key <- paste(file, line, col, sub("[.]+$", "", trimws(message)), sep = "\r")
+    if (!key %in% seen && length(rows) < LATEX_DIAGNOSTIC_MAX) {
+      seen <<- c(seen, key)
+      rows[[length(rows) + 1L]] <<- list(path = file, line = as.integer(line), col = col,
+        message = trimws(message), severity = severity, source = "LaTeX compiler")
+    }
+  }
+  lapply(lines, function(line) {
+    # file-line-error and Tectonic include the file explicitly, including drives.
+    hit <- regmatches(line, regexec("^(?:(error|warning):[[:space:]]*)?(.+?):([0-9]+):(?:([0-9]+):)?[[:space:]]*(.+)$", line, perl = TRUE))[[1L]]
+    if (length(hit) && (nzchar(hit[[2]]) || grepl("\\.(tex|sty|cls|bib)$", hit[[3]]) || file.exists(resolve_file(hit[[3]])))) {
+      add(hit[[3]], as.integer(hit[[4]]), hit[[6]], if (grepl("warning", paste(hit[[2]], hit[[6]]), ignore.case = TRUE)) "warning" else "error",
+        if (nzchar(hit[[5]])) as.integer(hit[[5]]) else NA_integer_)
+      pending <<- NULL; return(NULL)
+    }
+    if (startsWith(line, "!")) { pending <<- list(file = current(), message = trimws(sub("^!", "", line))); return(NULL) }
+    location <- regmatches(line, regexec("^l\\.([0-9]+)[[:space:]]", line, perl = TRUE))[[1L]]
+    if (length(location) && !is.null(pending)) {
+      add(pending$file, as.integer(location[[2]]), pending$message); pending <<- NULL; return(NULL)
+    }
+    warning <- regmatches(line, regexec("(?:LaTeX|Package .+) Warning: (.+?)(?: on input line ([0-9]+))?\\.?$", line, perl = TRUE))[[1L]]
+    if (length(warning)) { add(current(), if (nzchar(warning[[3]])) as.integer(warning[[3]]) else 1L, warning[[2]], "warning"); return(NULL) }
+    if (grepl("^error:", line) && !grepl("^error: (halted on|unexpectedly halted)", line)) {
+      add(current(), 1L, sub("^error:[[:space:]]*", "", line)); return(NULL)
+    }
+    # Track log parentheses, including anonymous parentheses, so a closing
+    # package group returns !/l.N diagnostics to the including source.
+    offsets <- gregexpr("[()]", line, perl = TRUE)[[1L]]
+    lapply(offsets[offsets > 0L], function(at) {
+      if (substr(line, at, at) == ")") { if (length(stack)) stack <<- head(stack, -1L); return(NULL) }
+      name <- regmatches(substring(line, at + 1L), regexec('^("[^"\\n]+\\.(?:tex|sty|cls)"|[^()\\n]*?\\.(?:tex|sty|cls))(?=[[:space:])]|$)', substring(line, at + 1L), perl = TRUE))[[1L]]
+      if (!length(name)) {
+        short <- regmatches(substring(line, at + 1L), regexec('^("[^"]+"|[^[:space:]()]+)', substring(line, at + 1L), perl = TRUE))[[1L]]
+        if (length(short) && file.exists(resolve_file(short[[2]]))) name <- short
+      }
+      stack[[length(stack) + 1L]] <<- if (length(name)) name[[2]] else ""
+    })
+    NULL
+  })
+  if (!is.null(pending)) add(pending$file, 1L, pending$message)
+  rows
+}
+# function parseCompilerDiagnostics(log, rootRelative) {
+#   const diagnostics = [];
+#   const seen = new Set();
+#   for (const line of log.split(/\r?\n/)) {
+#     let match = line.match(/^(?:(error|warning):\s*)?(.+?\.tex):(\d+):\s*(.+)$/i);
+#     if (match) {
+#       const key = match[2] + ":" + match[3] + ":" + match[4];
+#       if (!seen.has(key)) {
+#         seen.add(key);
+#         diagnostics.push({
+#           severity: /warning/i.test(match[1] || match[4]) ? "warning" : "error",
+#           path: match[2],
+#           line: Number(match[3]),
+#           message: match[4].trim()
+#         });
+#       }
+#       continue;
+#     }
+#     match = line.match(/^error:\s*(.+)$/i);
+#     if (match) {
+#       if (/^halted on |^unexpectedly halted/i.test(match[1])) continue;
+#       const key = rootRelative + ":0:" + match[1];
+#       if (!seen.has(key)) {
+#         seen.add(key);
+#         diagnostics.push({ severity: "error", path: rootRelative, line: 1, message: match[1].trim() });
+#       }
+#     }
+#   }
+#   return diagnostics.slice(0, 500);
+# }
+# 
+
+#' Re-join TeX's hard-wrapped log lines. TeX breaks its transcript at
+#' `max_print_line` (79) with NO continuation marker, splitting a phrase or a
+#' citation key wherever the column falls; a line of exactly that width is one
+#' that was cut. BibTeX's own output (`.blg`) is not wrapped this way, and a
+#' 79-character line that happens to be complete costs nothing but a longer
+#' string, so this is safe to run over both.
+#' @param lines Character vector.
+#' @return Character vector with wrapped continuations glued back on.
+latex_unwrap <- function(lines) {
+  stopifnot(is.character(lines))
+  if (length(lines) < 2L) return(lines)
+  wrapped <- nchar(lines, type = "chars") == LATEX_LOG_WRAP
+  # Each line joins onto the previous one whenever the previous was cut;
+  # cumsum over "starts a new record" turns the runs into group ids.
+  starts <- c(TRUE, !wrapped[-length(wrapped)])
+  as.character(tapply(lines, cumsum(starts), paste, collapse = ""))
+}
+
+#' Bibliography and citation problems that do NOT fail a compile.
+#'
+#' The whole reason this exists: Tectonic runs BibTeX itself and, when BibTeX
+#' cannot open the style file, prints "errors were issued by BibTeX, but were
+#' ignored", finishes the document, and exits 0. Every citation is then `[?]`
+#' and the reference list is empty — a PDF that is WRONG, delivered as a
+#' success. Nothing on the failure ladder sees it because nothing failed.
+#' So the compile reply carries a second, structured list beside the
+#' diagnostics: what BibTeX could not open, what it could not find, and every
+#' key that stayed undefined in the final pass. Parsed from the `.blg` and
+#' the transcript, never from the PDF.
+#'
+#' Two inputs on purpose. BibTeX's messages are read from the `.blg` plus the
+#' engine's stdout (Tectonic's `--print` echoes the `.blg` there, and a local
+#' `latexmk` prints BibTeX's output inline); undefined citations are read from
+#' the FINAL pass only (`tex_lines`, the same lines the diagnostics use), or a
+#' key the second pass resolved would be reported as broken.
+#'
+#' @param tex_lines The final TeX transcript (log on success, stdout+log otherwise).
+#' @param bib_lines BibTeX's output: the `.blg` and the engine's stdout.
+#' @param engine Resolved engine name — decides whether a missing style is
+#'   something the engine could fetch.
+#' @param fetch Was this compile allowed to reach the network? A style still
+#'   missing after a fetch is not offered another fetch.
+#' @return A list of rows, each `list(kind, file, key, line, message, log,
+#'   fetchable)`; `kind` is one of `missing-style`, `missing-bib`,
+#'   `missing-entry`, `bibtex-errors`, `undefined-citation`. Empty when the
+#'   bibliography is fine. Capped at LATEX_CITATION_MAX.
+latex_citation_problems <- function(tex_lines, bib_lines, engine, fetch = FALSE) {
+  stopifnot(is.character(tex_lines), is.character(bib_lines), latex_scalar(engine), is.logical(fetch), length(fetch) == 1L)
+  tex_lines <- latex_unwrap(tex_lines); bib_lines <- latex_unwrap(bib_lines)
+  rows <- list(); seen <- character()
+  add <- function(kind, message, log, file = "", key = "", line = NA_integer_, fetchable = FALSE) {
+    id <- paste(kind, file, key, sep = "\r")
+    if (id %in% seen || length(rows) >= LATEX_CITATION_MAX) return(invisible(NULL))
+    seen <<- c(seen, id)
+    rows[[length(rows) + 1L]] <<- list(kind = kind, file = file, key = key, line = line,
+      message = message, log = trimws(log), fetchable = isTRUE(fetchable))
+    invisible(NULL)
+  }
+  tectonic <- identical(engine, "tectonic")
+  # The sentence names the RECOVERY, and which one depends on the engine and
+  # on whether the network was already tried: Tectonic fetches a style it
+  # lacks the moment it is allowed to; a local TeX never will.
+  style_sentence <- function(file) {
+    if (tectonic && !isTRUE(fetch)) sprintf(paste0("Tectonic could not find %s; it fetches it when online — retry with a ",
+      "connection, or place the file beside the document."), file)
+    else if (tectonic) sprintf("Tectonic could not find %s even when allowed to fetch; place the file beside the document.", file)
+    else sprintf("BibTeX could not find %s; install it in your TeX distribution, or place the file beside the document.", file)
+  }
+  # ── BibTeX's own complaints, in the order a reader can act on them ──────
+  styles <- regmatches(bib_lines, regexec("^I couldn't open style file ([^[:space:]]+)", bib_lines))
+  lapply(Filter(length, styles), function(hit) add("missing-style", style_sentence(hit[[2L]]), hit[[1L]],
+    file = hit[[2L]], fetchable = tectonic && !isTRUE(fetch)))
+  bibs <- regmatches(bib_lines, regexec("^I couldn't open database file ([^[:space:]]+)", bib_lines))
+  lapply(Filter(length, bibs), function(hit) add("missing-bib",
+    sprintf("BibTeX could not open %s; place it beside the document, or point \\bibliography{} at a file that exists.", hit[[2L]]),
+    hit[[1L]], file = hit[[2L]]))
+  entries <- regmatches(bib_lines, regexec("^Warning--I didn't find a database entry for \"([^\"]+)\"", bib_lines))
+  lapply(Filter(length, entries), function(hit) add("missing-entry",
+    sprintf("\\cite{%s} has no entry in the .bib files, so it prints as [?].", hit[[2L]]), hit[[1L]], key = hit[[2L]]))
+  ignored <- grep("errors were issued by BibTeX, but were ignored", bib_lines, value = TRUE)
+  if (length(ignored)) {
+    count <- regmatches(bib_lines, regexec("^\\(There (?:was|were) ([0-9]+) error messages?\\)", bib_lines))
+    count <- Filter(length, count)
+    n <- if (length(count)) as.integer(count[[length(count)]][[2L]]) else NA_integer_
+    add("bibtex-errors", sprintf("BibTeX reported %s and the compile carried on without them: the reference list was not built.",
+      if (is.na(n)) "errors" else sprintf("%d error%s", n, if (n == 1L) "" else "s")), ignored[[1L]])
+  }
+  # ── what the final pass still could not resolve ──────────────────────────
+  # Head-anchored, then the line number from the tail of the UNWRAPPED line.
+  cite_re <- "Warning: Citation `([^']+)' on page [0-9]+ undefined(?: on input line ([0-9]+))?"
+  lapply(grep(cite_re, tex_lines, perl = TRUE), function(i) {
+    hit <- regmatches(tex_lines[[i]], regexec(cite_re, tex_lines[[i]], perl = TRUE))[[1L]]
+    add("undefined-citation",
+      sprintf("\\cite{%s} is undefined: it prints as [?] and is missing from the reference list.", hit[[2L]]), tex_lines[[i]],
+      key = hit[[2L]], line = if (nzchar(hit[[3L]])) as.integer(hit[[3L]]) else NA_integer_)
+  })
+  # The summary line alone (a key too long for the wrap to save, an unusual
+  # package wording): still a problem, still said.
+  summary_line <- grep("Warning: There were undefined citations", tex_lines, value = TRUE)
+  if (length(summary_line) && !any(vapply(rows, function(row) identical(row$kind, "undefined-citation"), logical(1)))) {
+    add("undefined-citation", "There were undefined citations: they print as [?] and are missing from the reference list.", summary_line[[1L]])
+  }
+  rows
+}
+
+# ── the rapid preview ──────────────────────────────────────────────────────
+#
+# The live preview (a .tex through pandoc to HTML while you type) is answered by
+# the supervisor, host/planes/latex.mjs. It lived here while the R supervisor
+# did; it was retired with serve.R (docs/host-plan.md §13), and nothing in this
+# file's compile half used it.