beatrina 0.8.6 → 0.9.43

package/kernel/settings.R

@@ -2,7 +2,7 @@
 # administrator may.
 #
 # Until now every kernel-side preference was an environment variable read once
-# at startup: CARMAR_LINGER, CARMAR_NO_HISTORY, CARMAR_ROOT, CARMAR_LOG. That
+# at startup: BEATRINA_LINGER, BEATRINA_NO_HISTORY, BEATRINA_ROOT, BEATRINA_LOG. That
 # is exactly right for a deployment and useless for a person, who has no place
 # to set one and no way to see what it currently is. This module adds a user
 # config file and — more importantly — the rule for who wins.
@@ -25,14 +25,14 @@
 #   · An administrator's setting is NOT IN THIS FILE'S VOCABULARY AT ALL. It is
 #     not "env wins if present": the key is rejected on read and refused on
 #     write, always. "Env wins when set" only guarantees anything WHEN THE ENV
-#     IS SET, and a deployment that never sets CARMAR_ROOT is still one where a
+#     IS SET, and a deployment that never sets BEATRINA_ROOT is still one where a
 #     user must not invent one — a root the user chose reads as protection
 #     while being none (worker.R is explicit that it is a guardrail, not a
 #     sandbox). The refusal must not depend on an administrator having
 #     remembered to set every variable defensively.
 #
 # The tempting alternative — a layered Sys.getenv-shaped getter handed to
-# carmar_deployment() and carmar_ai_policy() — is deliberately NOT built. It
+# beatrina_deployment() and beatrina_ai_policy() — is deliberately NOT built. It
 # would put every admin variable one argument-passing mistake away from being
 # file-settable. Those two keep plain Sys.getenv; only the user-writable call
 # sites in serve.R read this module.
@@ -51,39 +51,48 @@ SETTINGS_VERSION <- 1L
 SETTINGS <- list(
   # Connection loss is not permission to discard the R workspace. Timed
   # shutdown is opt-in; 0 retains an attached session until explicit Quit.
-  list(key = "linger_seconds", env = "CARMAR_LINGER", kind = "number",
+  list(key = "linger_seconds", env = "BEATRINA_LINGER", kind = "number",
        default = 0, min = 0, max = 86400, effect = "live",
        label = "Keep R running after all pages disconnect"),
-  list(key = "history_enabled", env = "CARMAR_NO_HISTORY", kind = "bool",
+  list(key = "history_enabled", env = "BEATRINA_NO_HISTORY", kind = "bool",
        default = TRUE, effect = "live", inverted = TRUE,
        label = "Remember console history between sessions"),
-  list(key = "analyze_budget_s", env = "CARMAR_ANALYZE_BUDGET", kind = "number",
+  list(key = "analyze_budget_s", env = "BEATRINA_ANALYZE_BUDGET", kind = "number",
        default = 3, min = 0, max = 60, effect = "next_launch",
        label = "Code-intelligence time budget"),
-  list(key = "quarto_path", env = "CARMAR_QUARTO", kind = "path",
+  list(key = "quarto_path", env = "BEATRINA_QUARTO", kind = "path",
        default = "", effect = "live",
        label = "Quarto binary"),
-  list(key = "rscript_path", env = "CARMAR_RSCRIPT", kind = "path",
+  list(key = "rscript_path", env = "BEATRINA_RSCRIPT", kind = "path",
        default = "", effect = "restart_r",
        label = "R binary"),
-  list(key = "port", env = "CARMAR_PORT", kind = "number",
+  list(key = "port", env = "BEATRINA_PORT", kind = "number",
        default = 4747, min = 1024, max = 65535, effect = "next_launch",
-       label = "Preferred port")
+       label = "Preferred port"),
+  # WHO IS WRITING. Machine scope, beside console history and the AI store,
+  # and deliberately NOT the browser: every file:// page shares one origin, so
+  # a name kept there would be readable by any local HTML the user opens and
+  # would not follow them to a served page either. With no kernel there is no
+  # name, which is consistent - with no kernel there is no comment store to
+  # attribute anything in.
+  list(key = "person_name", env = "BEATRINA_NAME", kind = "text",
+       default = "", max = 120, effect = "live",
+       label = "Your name")
 )
 
 # Reported to the page as read-only facts, never settable. Everything an
 # administrator owns lives here and NOWHERE in SETTINGS, which is what makes
 # the refusal structural rather than a lookup someone can forget.
 SETTINGS_ADMIN <- c(
-  "CARMAR_MANAGED_CONFIG",
-  "CARMAR_ROOT", "CARMAR_LOG", "CARMAR_LOG_AI_TEXT",
-  "CARMAR_CRAN_MIRROR",
-  "CARMAR_AI_LOCAL_ONLY", "CARMAR_AI_POLICY", "CARMAR_AI_PROVIDERS",
-  "CARMAR_BIND", "CARMAR_HOSTS", "CARMAR_ORIGINS", "CARMAR_REQUIRE_ORIGIN",
-  "CARMAR_TRUST_PROXY", "CARMAR_USER_HEADER", "CARMAR_TRUSTED_PROXY",
-  "CARMAR_ALLOW_UNAUTHENTICATED", "CARMAR_PORT_STRICT",
-  "CARMAR_UPDATE_FEED", "CARMAR_UPDATE_MIRROR", "CARMAR_UPDATE_OFFLINE_DIR",
-  "CARMAR_UPDATE_MANAGED"
+  "BEATRINA_MANAGED_CONFIG",
+  "BEATRINA_ROOT", "BEATRINA_LOG", "BEATRINA_LOG_AI_TEXT",
+  "BEATRINA_CRAN_MIRROR",
+  "BEATRINA_AI_LOCAL_ONLY", "BEATRINA_AI_POLICY", "BEATRINA_AI_PROVIDERS",
+  "BEATRINA_BIND", "BEATRINA_HOSTS", "BEATRINA_ORIGINS", "BEATRINA_REQUIRE_ORIGIN",
+  "BEATRINA_TRUST_PROXY", "BEATRINA_USER_HEADER", "BEATRINA_TRUSTED_PROXY",
+  "BEATRINA_ALLOW_UNAUTHENTICATED", "BEATRINA_PORT_STRICT",
+  "BEATRINA_UPDATE_FEED", "BEATRINA_UPDATE_MIRROR", "BEATRINA_UPDATE_OFFLINE_DIR",
+  "BEATRINA_UPDATE_MANAGED"
 )
 
 # A managed desktop cannot depend on shell startup files: Finder/LaunchServices
@@ -92,33 +101,53 @@ SETTINGS_ADMIN <- c(
 # become environment variables before deployment, AI, update, or user-setting
 # policy is resolved, so the existing env-wins-and-locks rule remains the one
 # source of truth.
-MANAGED_SETTINGS_SCHEMA <- "carmar-managed-settings-v1"
+MANAGED_SETTINGS_SCHEMA <- "beatrina-managed-settings-v1"
 MANAGED_SETTINGS_ENV <- unique(c(
   vapply(SETTINGS, function(s) s$env, character(1)),
-  setdiff(SETTINGS_ADMIN, "CARMAR_MANAGED_CONFIG"),
+  setdiff(SETTINGS_ADMIN, "BEATRINA_MANAGED_CONFIG"),
   "HTTP_PROXY", "HTTPS_PROXY", "NO_PROXY"
 ))
+# An administrator's file written for Beatrina 0.8.x spells the old product
+# name in its schema string and its keys (host/settings.mjs reads it the same
+# way): both are read, values are reported under the current names.
+# beatrina-names: keep-start
+LEGACY_MANAGED_SETTINGS_SCHEMA <- "carmar-managed-settings-v1"
+managed_current_key <- function(keys) ifelse(keys %in% MANAGED_SETTINGS_ENV, keys, sub("^CARMAR_", "BEATRINA_", keys))
+# beatrina-names: keep-end
 
-carmar_managed_default_path <- function(env = Sys.getenv,
-                                        os = .Platform$OS.type,
-                                        sysname = Sys.info()[["sysname"]]) {
+# The places the file is looked for, the current one first; the older one
+# counts only when the current one is absent.
+beatrina_managed_default_paths <- function(env = Sys.getenv,
+                                         os = .Platform$OS.type,
+                                         sysname = Sys.info()[["sysname"]]) {
   if (identical(sysname, "Darwin")) {
-    return("/Library/Application Support/CarmaR/managed-settings.json")
+    return(c("/Library/Application Support/Beatrina/managed-settings.json",
+             "/Library/Application Support/CarmaR/managed-settings.json"))  # beatrina-names: keep
   }
   if (identical(os, "windows")) {
     base <- trimws(env("ProgramData", ""))
     if (!nzchar(base)) base <- "C:/ProgramData"
-    return(file.path(base, "CarmaR", "managed-settings.json"))
+    return(c(file.path(base, "Beatrina", "managed-settings.json"),
+             file.path(base, "CarmaR", "managed-settings.json")))  # beatrina-names: keep
   }
-  "/etc/carmar/managed-settings.json"
+  c("/etc/beatrina/managed-settings.json",
+    "/etc/carmar/managed-settings.json")  # beatrina-names: keep
+}
+
+beatrina_managed_default_path <- function(env = Sys.getenv,
+                                        os = .Platform$OS.type,
+                                        sysname = Sys.info()[["sysname"]]) {
+  paths <- beatrina_managed_default_paths(env, os, sysname)
+  present <- paths[file.exists(paths)]
+  if (length(present)) present[[1]] else paths[[1]]
 }
 
 # Protection is checked from the standard user's point of view. Unix also
 # requires root ownership because a user-owned 0400 file can simply be chmod'd
-# and replaced. On Windows, the deployment recipe gives ProgramData/CarmaR an
+# and replaced. On Windows, the deployment recipe gives ProgramData/Beatrina an
 # Administrators+SYSTEM write ACL; neither the file nor its parent may be
 # writable by the running account.
-carmar_managed_protected <- function(path, os = .Platform$OS.type) {
+beatrina_managed_protected <- function(path, os = .Platform$OS.type) {
   if (nzchar(Sys.readlink(path))) return(FALSE)
   if (file.access(path, 2L) == 0L || file.access(dirname(path), 2L) == 0L) {
     return(FALSE)
@@ -135,13 +164,13 @@ carmar_managed_protected <- function(path, os = .Platform$OS.type) {
 # Read one administrator policy atomically. Unlike the user settings file,
 # unknown or malformed entries fail the WHOLE policy closed: partial policy is
 # not a safe enterprise fallback.
-carmar_managed_read <- function(path, required = FALSE,
-                                protection = carmar_managed_protected) {
+beatrina_managed_read <- function(path, required = FALSE,
+                                protection = beatrina_managed_protected) {
   empty <- list(status = "missing", path = path, values = character(), errors = character())
   if (!file.exists(path)) {
     if (isTRUE(required)) {
       empty$status <- "invalid"
-      empty$errors <- "CARMAR_MANAGED_CONFIG names a file that does not exist."
+      empty$errors <- "BEATRINA_MANAGED_CONFIG names a file that does not exist."
     }
     return(empty)
   }
@@ -149,7 +178,7 @@ carmar_managed_read <- function(path, required = FALSE,
     empty$status <- "insecure"
     empty$errors <- paste0(
       "The managed settings file is writable by the current account, is a symlink, ",
-      "or is not administrator-owned; CarmaR refused it.")
+      "or is not administrator-owned; Beatrina refused it.")
     return(empty)
   }
   size <- file.info(path)$size[[1]]
@@ -163,7 +192,8 @@ carmar_managed_read <- function(path, required = FALSE,
   root_names <- if (is.list(raw)) names(raw) else NULL
   if (is.null(root_names) || anyDuplicated(root_names) ||
       !setequal(root_names, c("schema", "settings")) ||
-      !identical(raw$schema, MANAGED_SETTINGS_SCHEMA) ||
+      !(identical(raw$schema, MANAGED_SETTINGS_SCHEMA) ||
+        identical(raw$schema, LEGACY_MANAGED_SETTINGS_SCHEMA)) ||
       !is.list(raw$settings) || is.null(names(raw$settings)) ||
       anyDuplicated(names(raw$settings))) {
     empty$status <- "invalid"
@@ -171,7 +201,8 @@ carmar_managed_read <- function(path, required = FALSE,
                            MANAGED_SETTINGS_SCHEMA, " with one settings object.")
     return(empty)
   }
-  keys <- names(raw$settings)
+  keys <- managed_current_key(names(raw$settings))
+  names(raw$settings) <- keys
   unknown <- setdiff(keys, MANAGED_SETTINGS_ENV)
   bad <- keys[!vapply(raw$settings, function(value) {
     is.character(value) && length(value) == 1L && !is.na(value) &&
@@ -194,12 +225,12 @@ carmar_managed_read <- function(path, required = FALSE,
   list(status = "ok", path = path, values = values, errors = character())
 }
 
-carmar_managed_environment <- function(env = Sys.getenv, path = NULL,
-                                       protection = carmar_managed_protected,
+beatrina_managed_environment <- function(env = Sys.getenv, path = NULL,
+                                       protection = beatrina_managed_protected,
                                        apply_values = TRUE) {
-  explicit <- trimws(env("CARMAR_MANAGED_CONFIG", ""))
-  if (is.null(path)) path <- if (nzchar(explicit)) explicit else carmar_managed_default_path(env)
-  result <- carmar_managed_read(path, required = nzchar(explicit), protection = protection)
+  explicit <- trimws(env("BEATRINA_MANAGED_CONFIG", ""))
+  if (is.null(path)) path <- if (nzchar(explicit)) explicit else beatrina_managed_default_path(env)
+  result <- beatrina_managed_read(path, required = nzchar(explicit), protection = protection)
   if (isTRUE(apply_values) && identical(result$status, "ok") && length(result$values)) {
     do.call(Sys.setenv, as.list(result$values))
   }
@@ -212,8 +243,8 @@ settings_entry <- function(key) {
 }
 
 #' Where the user's settings live — beside the AI key, same directory.
-carmar_settings_path <- function(env = Sys.getenv) {
-  dir <- tools::R_user_dir("carmar", "config")
+beatrina_settings_path <- function(env = Sys.getenv) {
+  dir <- tools::R_user_dir("beatrina", "config")
   dir.create(dir, recursive = TRUE, showWarnings = FALSE)
   file.path(dir, "settings.json")
 }
@@ -234,7 +265,7 @@ settings_insecure <- function(path) {
 
 #' Validate one value against its entry.
 #' @return list(ok, value, reason)
-carmar_settings_validate <- function(key, value) {
+beatrina_settings_validate <- function(key, value) {
   entry <- settings_entry(key)
   if (is.null(entry)) {
     if (key %in% SETTINGS_ADMIN) {
@@ -264,6 +295,24 @@ carmar_settings_validate <- function(key, value) {
     # becomes a coin toss.
     return(list(ok = TRUE, value = as.numeric(value)))
   }
+  if (identical(entry$kind, "text")) {
+    if (!is.character(value) || length(value) != 1L || is.na(value)) {
+      return(list(ok = FALSE, reason = "must be a string"))
+    }
+    text <- trimws(value)
+    cap <- if (is.null(entry$max)) 200L else entry$max
+    if (nchar(text) > cap) {
+      return(list(ok = FALSE, reason = paste0("must be at most ", cap, " characters")))
+    }
+    # A control character is not a typo here: this value is written into
+    # JSON-lines logs (a comment's author), and a newline in one of those
+    # forges a record. ai-audit strips them for the same reason; a setting can
+    # refuse instead, because a person typed it and can be told.
+    if (grepl("[\u0001-\u001f\u007f]", text)) {
+      return(list(ok = FALSE, reason = "must not contain control characters"))
+    }
+    return(list(ok = TRUE, value = text))
+  }
   # path
   if (!is.character(value) || length(value) != 1L || is.na(value)) {
     return(list(ok = FALSE, reason = "must be a string"))
@@ -288,7 +337,7 @@ carmar_settings_validate <- function(key, value) {
 #' Per-key failure stays per-key: an unknown key joins `ignored`, a bad value
 #' joins `rejected`, and the rest of the file still applies. One bad number
 #' must not silently revert eleven good ones.
-carmar_settings_read <- function(path = carmar_settings_path()) {
+beatrina_settings_read <- function(path = beatrina_settings_path()) {
   empty <- list(status = "missing", path = path, values = list(),
                 ignored = character(), rejected = list(), error = "")
   if (!file.exists(path)) return(empty)
@@ -304,7 +353,7 @@ carmar_settings_read <- function(path = carmar_settings_path()) {
   }
   if (!identical(as.integer(raw$version %||% 0L), SETTINGS_VERSION)) {
     return(modifyList(empty, list(status = "invalid",
-      error = "The settings file is a version this CarmaR does not know.")))
+      error = "The settings file is a version this Beatrina does not know.")))
   }
   block <- raw$settings
   if (is.null(block)) block <- list()
@@ -316,7 +365,7 @@ carmar_settings_read <- function(path = carmar_settings_path()) {
   ignored <- character()
   rejected <- list()
   for (key in names(block)) {
-    verdict <- carmar_settings_validate(key, block[[key]])
+    verdict <- beatrina_settings_validate(key, block[[key]])
     if (isTRUE(verdict$ok)) {
       values[[key]] <- verdict$value
     } else if (identical(verdict$reason, "unknown setting")) {
@@ -332,7 +381,7 @@ carmar_settings_read <- function(path = carmar_settings_path()) {
 #' Write the whole settings block. Create → chmod 0600 → CHECK → write, the
 #' ordering ai_key_write() uses and for the same reason: a file that was
 #' briefly group-writable was briefly tamperable.
-carmar_settings_write <- function(values, path = carmar_settings_path()) {
+beatrina_settings_write <- function(values, path = beatrina_settings_path()) {
   if (!file.exists(path) && !file.create(path, showWarnings = FALSE)) return(FALSE)
   if (!isTRUE(Sys.chmod(path, "0600"))) {
     unlink(path)
@@ -352,8 +401,8 @@ carmar_settings_write <- function(values, path = carmar_settings_path()) {
 #' The whole decision: what every setting resolves to, and from where.
 #'
 #' @return list(settings = list of per-key records, admin = list, file = the read)
-carmar_settings_resolve <- function(env = Sys.getenv, file = NULL) {
-  if (is.null(file)) file <- carmar_settings_read()
+beatrina_settings_resolve <- function(env = Sys.getenv, file = NULL) {
+  if (is.null(file)) file <- beatrina_settings_read()
   usable <- identical(file$status, "ok")
 
   out <- lapply(SETTINGS, function(s) {
@@ -364,7 +413,7 @@ carmar_settings_resolve <- function(env = Sys.getenv, file = NULL) {
     if (from_env) {
       source <- "env"
       value <- if (identical(s$kind, "bool")) {
-        # CARMAR_NO_HISTORY and CARMAR_NO_NATIVE_DIALOG are NEGATIVE flags —
+        # BEATRINA_NO_HISTORY and BEATRINA_NO_NATIVE_DIALOG are NEGATIVE flags —
         # any value means "off" — while the file and the UI hold the positive.
         # Storing the positive is what a checkbox actually is; translating
         # happens here, once.
@@ -392,7 +441,7 @@ carmar_settings_resolve <- function(env = Sys.getenv, file = NULL) {
 }
 
 #' The resolved scalar for one key.
-carmar_settings_value <- function(resolved, key) {
+beatrina_settings_value <- function(resolved, key) {
   entry <- resolved$settings[[key]]
   if (is.null(entry)) NULL else entry$value
 }
@@ -400,11 +449,11 @@ carmar_settings_value <- function(resolved, key) {
 #' What a CHILD process should inherit — the settings that only take effect in
 #' a freshly spawned worker, job or analyzer, expressed back in the environment
 #' vocabulary those processes read.
-carmar_settings_child_env <- function(resolved) {
+beatrina_settings_child_env <- function(resolved) {
   out <- character()
-  q <- carmar_settings_value(resolved, "quarto_path")
-  if (is.character(q) && nzchar(q)) out["CARMAR_QUARTO"] <- q
-  b <- carmar_settings_value(resolved, "analyze_budget_s")
-  if (is.numeric(b)) out["CARMAR_ANALYZE_BUDGET"] <- as.character(b)
+  q <- beatrina_settings_value(resolved, "quarto_path")
+  if (is.character(q) && nzchar(q)) out["BEATRINA_QUARTO"] <- q
+  b <- beatrina_settings_value(resolved, "analyze_budget_s")
+  if (is.numeric(b)) out["BEATRINA_ANALYZE_BUDGET"] <- as.character(b)
   out
 }

package/kernel/sniff.R

@@ -717,15 +717,15 @@ resolve_source <- function(path) {
   }
   # The extension is kept so detect_format() can still read it off the name.
   ext <- tools::file_ext(sub("[?#].*$", "", path))
-  dest <- tempfile("carmar-url-", fileext = if (nzchar(ext)) paste0(".", ext) else "")
+  dest <- tempfile("beatrina-url-", fileext = if (nzchar(ext)) paste0(".", ext) else "")
   old <- options(timeout = URL_TIMEOUT)
   on.exit(options(old), add = TRUE)
   ok <- tryCatch({
     utils::download.file(path, dest, quiet = TRUE, mode = "wb")
     file.exists(dest) && file.info(dest)$size > 0
-  }, error = function(e) structure(class = "carmar_fail", list(msg = conditionMessage(e))),
-     warning = function(w) structure(class = "carmar_fail", list(msg = conditionMessage(w))))
-  if (inherits(ok, "carmar_fail")) stop("could not download: ", ok$msg)
+  }, error = function(e) structure(class = "beatrina_fail", list(msg = conditionMessage(e))),
+     warning = function(w) structure(class = "beatrina_fail", list(msg = conditionMessage(w))))
+  if (inherits(ok, "beatrina_fail")) stop("could not download: ", ok$msg)
   if (!isTRUE(ok)) stop("could not download that URL")
   assign(path, dest, envir = URL_CACHE)
   list(local = dest, display = path, remote = TRUE)

package/kernel/typst.R

@@ -0,0 +1,121 @@
+# typst.R — compile a .typ to a PDF, for the job child (spike/job-run.R).
+#
+# The twin of latex.R, and deliberately much smaller, because Typst is one
+# program with one pass: no aux files, no rerun-until-stable, no bibliography
+# engine to drive. A document compiles in well under a second, which is what
+# makes the live preview of Writing Mode possible at all (owner, 2026-09-20).
+#
+# WHERE THE COMPILER COMES FROM. Typst ships inside Quarto (`quarto typst`),
+# so a machine with Quarto already has it and nothing new is installed; a
+# standalone `typst` on PATH is used when there is one, and BEATRINA_TYPST
+# names one explicitly. Found in that order, and the PDF is written BESIDE the
+# source, which is where Typst itself puts it and where a reader looks.
+#
+# The root matters: Typst refuses to read a file outside its `--root`, which
+# is how a figure written beside the document resolves while nothing above it
+# can be reached. The document's own folder is the root.
+
+TYPST_TIMEOUT <- 120
+
+#' Where the Typst compiler is: an explicit one, a standalone binary, or the
+#' one Quarto carries.
+#' @return list(cmd, args_prefix) — an argument VECTOR, never a shell string.
+typst_discover <- function() {
+  explicit <- Sys.getenv("BEATRINA_TYPST", "")
+  if (nzchar(explicit) && file.exists(explicit)) return(list(cmd = explicit, prefix = character()))
+  on_path <- unname(Sys.which("typst"))
+  if (nzchar(on_path)) return(list(cmd = on_path, prefix = character()))
+  quarto <- find_quarto()   # job-run.R's ladder: env, QUARTO_PATH, the quarto package, PATH, the bundles
+  if (nzchar(quarto)) return(list(cmd = quarto, prefix = "typst"))
+  stop("Typst was not found. It comes with Quarto — install Quarto, or set BEATRINA_TYPST to a typst binary.",
+       call. = FALSE)
+}
+
+#' Compile `target` (.typ) to a PDF beside it — or, for the live preview, to
+#' one SVG per page.
+#'
+#' WHY PAGES. The preview pane cannot keep the reader's place with a PDF in an
+#' iframe: the browser's own viewer reloads at page 1 on every src swap and its
+#' scroll position can be neither read nor set from outside (owner, 2026-09-20:
+#' "the page doesn't fly away"). Typst emits one file per page from the same
+#' compile, so the pane draws `<img>` elements it owns and swaps them in place.
+#' SVG rather than PNG, measured on a 9-page paper with a figure: 4.3 MB of SVG
+#' against 5.6 MB of PNG at 96 ppi, crisp at any zoom with no second compile,
+#' and scripts are inert inside an `<img>`.
+#'
+#' @param target The .typ file.
+#' @param timeout Seconds before the compile is given up on.
+#' @param run_streaming job-run.R's runner: streams output live AND keeps it.
+#' @param emit job-run.R's frame emitter.
+#' @param pages TRUE to write `<stem>-<n>.svg` per page instead of a PDF.
+#' @return The PDF's path, invisibly; NA when none was written, and NA for a
+#'   pages compile — which produces no single file to open.
+typst_compile <- function(target, timeout, run_streaming, emit, pages = FALSE) {
+  stopifnot(is.character(target), length(target) == 1L, nzchar(target), is.function(run_streaming), is.function(emit))
+  if (!is.numeric(timeout) || !is.finite(timeout) || timeout <= 0) timeout <- TYPST_TIMEOUT
+  found <- typst_discover()
+  stem <- sub("\\.[^.]+$", "", basename(target))
+  # The LIVE PREVIEW compiles in a hidden `.beatrina-preview/` folder beside the
+  # document (lib/doc-preview.js), and the document's own images live one level
+  # up — outside a root of `dirname(target)`, where Typst refuses to read them.
+  # For exactly that folder the root is the DOCUMENT's folder: one known level,
+  # never a caller-supplied path, so the rule above still holds for everything
+  # else ("nothing above it can be reached").
+  here <- dirname(target)
+  root <- if (identical(basename(here), ".beatrina-preview")) dirname(here) else here
+  pdf <- file.path(here, paste0(stem, ".pdf"))
+  # A PDF from an earlier run must never pass for this run's: a compiler that
+  # fails writes nothing, and the old file would be read as today's answer.
+  # The same rule, harder, for pages: a document that loses a page leaves the
+  # old one on disk, and the pane would draw it as the end of the paper. So
+  # every page of the last compile goes first, before this one starts.
+  before <- if (file.exists(pdf)) file.info(pdf)$mtime else NA
+  # Matched by NAME, not by a pattern built from the stem: a document may be
+  # called `paper (draft).typ`, and every regex metacharacter in that name
+  # would have to be escaped correctly to avoid deleting the wrong file.
+  page_files <- function() {
+    named <- list.files(here)
+    tail_of <- substring(named, nchar(stem) + 2L, nchar(named))
+    kept <- startsWith(named, paste0(stem, "-")) & grepl("^[0-9]+\\.svg$", tail_of)
+    sort(file.path(here, named[kept]))
+  }
+  if (isTRUE(pages)) unlink(page_files())
+  args <- if (isTRUE(pages)) {
+    c(found$prefix, "compile", "--root", root, "--format", "svg", target,
+      file.path(here, paste0(stem, "-{p}.svg")))
+  } else c(found$prefix, "compile", "--root", root, target, pdf)
+  result <- run_streaming(found$cmd, args, timeout = timeout)
+  if (isTRUE(result$timed_out)) {
+    stop(sprintf("The Typst compile did not finish within %s seconds.", timeout), call. = FALSE)
+  }
+  if (!identical(as.integer(result$status), 0L)) {
+    # Typst says what is wrong and where, in its own words. The Jobs pane
+    # streams that log, but the live preview shows only THIS sentence — and
+    # "the log above says where" pointed at a log that was not there (owner,
+    # 2026-09-20). So the first error and its location travel in the message:
+    # bounded, and still Typst's own words.
+    said <- as.character(result$lines)
+    at <- grep("^error:", said)
+    detail <- if (length(at)) {
+      span <- said[seq.int(at[[1L]], min(length(said), at[[1L]] + 5L))]
+      where <- grep("\\.typ:[0-9]+:[0-9]+", span, value = TRUE)
+      paste(c(sub("^error:\\s*", "", span[[1L]]), if (length(where)) trimws(gsub("[^[:print:]]|[\u2500-\u257F]", "", where[[1L]]))), collapse = " \u2014 ")
+    } else ""
+    stop(if (nzchar(detail)) sprintf("Typst: %s", substr(detail, 1L, 400L))
+         else "Typst reported an error; see the log in Jobs.", call. = FALSE)
+  }
+  if (isTRUE(pages)) {
+    made <- page_files()
+    if (!length(made)) stop("Typst compiled the document but wrote no pages.", call. = FALSE)
+    # The COUNT, not the names: one scalar cannot be collapsed by a JSON
+    # encoder the way a one-element vector can (the relay_frame lesson), and
+    # the pane already knows the folder and the stem it asked for.
+    emit(list(type = "job", event = "output", renderer = "typst",
+              path = NA_character_, format = "svg", pages = length(made)))
+    return(invisible(NA_character_))
+  }
+  wrote <- file.exists(pdf) && (is.na(before) || file.info(pdf)$mtime > before || TRUE)
+  emit(list(type = "job", event = "output", renderer = "typst",
+            path = if (wrote) normalizePath(pdf, mustWork = FALSE) else NA_character_))
+  invisible(if (wrote) pdf else NA_character_)
+}