latexml_post/

graphics.rs

//! Graphics postprocessing.
//!
//! Port of `LaTeXML::Post::Graphics`.
//! Finds `<ltx:graphics>` elements without `imagesrc`, locates the source
//! graphic file, applies transformations (scaling, cropping, format conversion),
//! and sets the `imagesrc`, `imagewidth`, `imageheight` attributes.

use std::{
  path::{Path, PathBuf},
  sync::LazyLock,
};

use libxml::tree::Node;
use rustc_hash::FxHashMap as HashMap;

use crate::{
  document::PostDocument,
  processor::{ProcessResult, Processor},
};

thread_local! {
  /// The most recent converter-subprocess diagnostic on this thread: the program
  /// name plus its captured stderr (or the spawn error). Surfaced into the
  /// `imageprocessing:failed_to_convert` Error so an ENVIRONMENT failure is
  /// self-explaining in the log instead of needing a strace — e.g. `gs` not
  /// installed (`could not start … No such file or directory`), an AppArmor
  /// denial (`gs: … /undefinedfilename …` while gs exits 0), or an ImageMagick
  /// policy block. Set by `run_with_timeout`, cleared per node in `process`'s
  /// worker loop, read+cleared at the Error site. Worker-thread-local — it rides
  /// the same `logger::capture`/`replay_captured` fold to the main thread as the
  /// Error itself.
  static LAST_CONVERTER_DIAG: std::cell::RefCell<Option<String>> =
    const { std::cell::RefCell::new(None) };
}

/// Record (overwrite) the latest converter diagnostic on this thread.
fn record_converter_diag(msg: String) { LAST_CONVERTER_DIAG.with(|c| *c.borrow_mut() = Some(msg)); }

/// Take (read + clear) this thread's latest converter diagnostic.
fn take_converter_diag() -> Option<String> { LAST_CONVERTER_DIAG.with(|c| c.borrow_mut().take()) }

/// Program name for the ImageMagick CLI delegate. On Windows, `convert.exe`
/// is the system FAT→NTFS conversion utility in `System32`, which shadows
/// ImageMagick's legacy name — invoking bare `convert` there runs the wrong
/// program. ImageMagick 7's unified `magick` front-end accepts the same
/// argument syntax, so use it on Windows. Unix keeps `convert` (matching
/// Perl's Image::Magick-era delegate chain and ImageMagick 6 installs).
fn im_convert_program() -> &'static str { if cfg!(windows) { "magick" } else { "convert" } }

/// Program name for the Ghostscript CLI delegate. Unix installs `gs`.
/// Windows Ghostscript ships the console binary as `gswin64c.exe`
/// (32-bit: `gswin32c.exe`), MiKTeX bundles its own as `mgs.exe`, and
/// TeX Live for Windows bundles one behind the `rungs.exe` wrapper
/// (`tlpkg/tlgs`, same CLI) on the same bin dir as `kpsewhich` — so a
/// TL-only box still gets a working EPS/PS chain with no extra install.
/// Probed once per process, in that order, falling back to `gs` so a
/// failure surfaces as the usual could-not-start converter diagnostic.
fn gs_program() -> &'static str {
  if cfg!(windows) {
    // `which` applies the platform's own lookup rules (PATHEXT, so `.exe`/
    // `.bat`/`.cmd` all resolve) — the same crate + semantics the kpathsea
    // backend uses to find `kpsewhich`.
    static GS: LazyLock<&'static str> = LazyLock::new(|| {
      ["gswin64c", "gswin32c", "mgs", "rungs"]
        .into_iter()
        .find(|candidate| which::which(candidate).is_ok())
        .unwrap_or("gs")
    });
    *GS
  } else {
    "gs"
  }
}

/// Map a graphics-converter executable to a "what to install" hint, so a
/// "not installed" diagnostic tells the user how to fix it rather than just
/// naming a missing binary. Covers the optional tools the graphics cascade
/// shells out to — none are bundled; the host TeX/graphics ecosystem provides
/// them. Returns `None` for an unrecognized program (no hint appended).
/// The Windows Ghostscript aliases (`gswin64c`/`gswin32c`/`mgs`/`rungs`, from
/// `gs_program`) map to the same Ghostscript hint.
fn missing_tool_hint(prog: &str) -> Option<&'static str> {
  Some(match prog {
    "gs" | "gswin64c" | "gswin32c" | "mgs" | "rungs" | "ps2pdf" => {
      "install Ghostscript (apt `ghostscript`, brew `ghostscript`) for PDF/PostScript conversion"
    },
    "mutool" => "install MuPDF (apt `mupdf-tools`, brew `mupdf-tools`) for fast PDF rendering",
    "pdftocairo" | "pdftoppm" => {
      "install Poppler (apt `poppler-utils`, brew `poppler`) for vector-SVG PDF conversion"
    },
    "convert" | "magick" => {
      "install ImageMagick (apt `imagemagick`, brew `imagemagick`) for raster image conversion"
    },
    "dvisvgm" => {
      "install dvisvgm (apt `dvisvgm`, brew `texlive`) for vector-SVG LaTeX-image output"
    },
    "dvipng" => "install dvipng (apt `dvipng`, brew `texlive`) for raster LaTeX-image output",
    "latex" | "pdflatex" | "kpsewhich" | "tftopl" => {
      "install TeX Live (apt `texlive-latex-base`, brew `texlive` / MacTeX) — the TeX ecosystem \
       must be present at runtime"
    },
    _ => return None,
  })
}

// Diagnostic emission: `Error!` (and friends) live in
// `crate::diag` and are exposed crate-wide via `#[macro_use] pub mod
// diag;` in `lib.rs`. They emit harness-compatible structured Error
// lines (`Error:<class>:<object> <msg>`) matching what
// `latexml_core::common::error::Error!` produces.

// Process-once cached env var (see WISDOM #56 — getenv hot-path race).
// Parsed-and-validated at init: only positive integer values are
// honored; everything else (unset, empty, "0", malformed) leaves
// `SVG_CONVERT_TIMEOUT_SECS` at None and the caller falls back to the
// 15-second default in `svg_convert_timeout_secs`.
static SVG_CONVERT_TIMEOUT_SECS: LazyLock<Option<u64>> = LazyLock::new(|| {
  std::env::var("LATEXML_SVG_CONVERT_TIMEOUT_SECS")
    .ok()
    .and_then(|s| s.parse::<u64>().ok())
    .filter(|&n| n > 0)
});

/// Wall-clock timeout for the `convert` (ImageMagick / gs) subprocess.
/// Defaults to 60 s; override via `LATEXML_CONVERT_TIMEOUT_SECS`. Same
/// pattern as `SVG_CONVERT_TIMEOUT_SECS` — see WISDOM #56.
static CONVERT_TIMEOUT_SECS: LazyLock<Option<u64>> = LazyLock::new(|| {
  std::env::var("LATEXML_CONVERT_TIMEOUT_SECS")
    .ok()
    .and_then(|s| s.parse::<u64>().ok())
    .filter(|&n| n > 0)
});

/// Properties for a graphics file type.
#[derive(Debug, Clone)]
pub struct TypeProperties {
  pub destination_type: Option<String>,
  pub transparent:      bool,
  pub prescale:         bool,
  pub ncolors:          Option<String>,
  pub quality:          Option<u32>,
  pub unit:             String,
  pub raster:           Option<bool>,
  pub autocrop:         bool,
  pub desirability:     u32,
}

impl Default for TypeProperties {
  fn default() -> Self {
    TypeProperties {
      destination_type: None,
      transparent:      false,
      prescale:         false,
      ncolors:          None,
      quality:          None,
      unit:             "pixel".to_string(),
      raster:           None,
      autocrop:         false,
      desirability:     0,
    }
  }
}

/// Graphics post-processor.
///
/// Port of `LaTeXML::Post::Graphics`.
pub struct Graphics {
  name:             String,
  dpi:              Option<u32>,
  magnify:          f64,
  zoomout:          f64,
  trivial_scaling:  bool,
  graphics_types:   Vec<String>,
  type_properties:  HashMap<String, TypeProperties>,
  background:       String,
  /// Opt-in vector-SVG path for PDF graphics. When > 0, PDFs under this
  /// many KB are first attempted via the vector converters (mutool, then
  /// pdftocairo); fall back to the raster (`convert`/`gs` → PNG) path on
  /// failure or timeout. 0 disables the path entirely.
  /// Tracks upstream brucemiller/LaTeXML#902.
  svg_threshold_kb: u32,
  /// Whether conversions may be served from the shared, host-persistent
  /// graphics cache. Threaded explicitly (rather than read from a global)
  /// so a caller can guarantee its conversions actually run — see
  /// [`crate::graphics_cache::CachePolicy`] and `with_cache_policy`.
  cache_policy:     crate::graphics_cache::CachePolicy,
}

impl Graphics {
  // 120 dpi: a compromise between Perl's `$DPI = 100`
  // (Util/Image.pm:37) and our prior 150. Empirically (1910.01256
  // measured 2026-05-12) the dominant graphics-phase cost is vector
  // primitive iteration in matplotlib/pgfplots PDFs, NOT pixel count
  // — so density 100..150 produce near-identical wall on those
  // papers. 120 keeps text and thin strokes legible on hidpi displays
  // (Retina 144-192 dpi target) while shaving ~20-30% off the output
  // PNG byte count.
  // Override via `LATEXML_RASTER_DENSITY=<dpi>` for explicit control.
  const DEFAULT_RASTER_DENSITY: u32 = 120;
  const MAX_RASTER_DIMENSION_PX: u32 = 2048;

  pub fn new(dpi: Option<u32>, trivial_scaling: bool) -> Self {
    let mut type_properties = HashMap::default();

    // Default type properties matching Perl.
    // `.epsi` (EPS Interchange — EPS with optional embedded TIFF
    // preview, e.g. HIGZ / CERN PAW output) and `.epsf` are EPS
    // variants browsers can't render natively but `gs` rasterises
    // identically to plain `.eps`. SURPASS-PERL: Perl LaTeXML also
    // omits these from its type_properties so the files were copied
    // verbatim and rendered as broken images. Witness:
    // hep-ph0608319 Fig 1 (refit_av_extra.epsi, HIGZ 1.29/04 output).
    for ext in &["ai", "pdf", "ps", "eps", "epsi", "epsf"] {
      type_properties.insert(ext.to_string(), TypeProperties {
        destination_type: Some("png".to_string()),
        transparent: true,
        prescale: true,
        ncolors: Some("400%".to_string()),
        quality: Some(90),
        unit: "point".to_string(),
        ..Default::default()
      });
    }
    for ext in &["jpg", "jpeg"] {
      type_properties.insert(ext.to_string(), TypeProperties {
        destination_type: Some(ext.to_string()),
        ncolors: Some("400%".to_string()),
        unit: "pixel".to_string(),
        ..Default::default()
      });
    }
    type_properties.insert("gif".to_string(), TypeProperties {
      destination_type: Some("gif".to_string()),
      transparent: true,
      ncolors: Some("400%".to_string()),
      unit: "pixel".to_string(),
      ..Default::default()
    });
    type_properties.insert("png".to_string(), TypeProperties {
      destination_type: Some("png".to_string()),
      transparent: true,
      ncolors: Some("400%".to_string()),
      unit: "pixel".to_string(),
      ..Default::default()
    });
    type_properties.insert("svg".to_string(), TypeProperties {
      destination_type: Some("svg".to_string()),
      raster: Some(false),
      desirability: 11,
      ..Default::default()
    });

    Graphics {
      name: "Graphics".to_string(),
      dpi,
      magnify: 1.0,
      zoomout: 1.0,
      trivial_scaling,
      graphics_types: vec![
        "svg",
        "png",
        "gif",
        "jpg",
        "jpeg",
        "eps",
        "epsi",
        "epsf",
        "ps",
        "postscript",
        "ai",
        "pdf",
      ]
      .into_iter()
      .map(String::from)
      .collect(),
      type_properties,
      background: "#FFFFFF".to_string(),
      svg_threshold_kb: 0,
      cache_policy: crate::graphics_cache::CachePolicy::default(),
    }
  }

  /// Choose whether conversions may be served from the shared,
  /// host-persistent graphics cache. Defaults to
  /// [`CachePolicy::Shared`](crate::graphics_cache::CachePolicy::Shared).
  ///
  /// Pass [`CachePolicy::Bypass`](crate::graphics_cache::CachePolicy::Bypass)
  /// when the conversion *itself* is what matters — e.g. a test asserting
  /// on how many converter subprocesses ran, which a cache hit would
  /// silently satisfy without running any. The builder returns `self` so
  /// it composes with `Graphics::new(...)`.
  #[must_use]
  pub fn with_cache_policy(mut self, policy: crate::graphics_cache::CachePolicy) -> Self {
    self.cache_policy = policy;
    self
  }

  /// Enable the vector-SVG path for PDFs under `kb` KB. When `kb == 0`
  /// (default), the SVG path is fully disabled and all PDFs go through
  /// ImageMagick `convert`. The builder returns `self` so it composes with
  /// `Graphics::new(...)`.
  pub fn with_svg_threshold_kb(mut self, kb: u32) -> Self {
    self.svg_threshold_kb = kb;
    self
  }

  /// Find the graphics source file for a node.
  ///
  /// Port of `Graphics::findGraphicFile`.
  fn find_graphic_file(
    &self,
    _doc: &PostDocument,
    node: &Node,
    search_paths: &[String],
  ) -> Option<String> {
    let source = node.get_attribute("graphic")?;

    // Check candidates attribute first (comma-separated list of found files)
    // Perl: findGraphicFile checks each candidate path, resolving relative to search paths.
    if let Some(candidates) = node.get_attribute("candidates") {
      // Pick the best candidate by desirability
      let mut best: Option<(String, i32)> = None;
      for path in candidates.split(',') {
        let path = path.trim();
        if path.is_empty() {
          continue;
        }
        // Try the path directly, then in each search directory
        let resolved = if Path::new(path).exists() {
          Some(path.to_string())
        } else {
          search_paths.iter().find_map(|sp| {
            let candidate = format!("{}/{}", sp, path);
            if Path::new(&candidate).exists() {
              Some(candidate)
            } else {
              None
            }
          })
        };
        if let Some(resolved_path) = resolved {
          let ext = Path::new(&resolved_path)
            .extension()
            .and_then(|e| e.to_str())
            .unwrap_or("")
            .to_lowercase();
          // Skip candidates whose extension is NOT a known graphics type.
          // Perl's `findGraphicFile` re-searches with `types =>
          // getGraphicsSourceTypes` (Post/Graphics.pm L150-151), which excludes
          // non-graphics types — notably `.pdf_tex`, the inkscape "PDF+LaTeX"
          // wrapper that is `\input`'d (it itself does `\includegraphics{grid}`),
          // NOT a raster/vector image. `image_candidates` is deliberately
          // unfiltered (matching Perl's `types => ['*']`), so a sibling
          // `grid.pdf_tex` lands in the `candidates` attribute next to the real
          // `grid.pdf`/`grid.eps`; without this filter it sorts first and gets
          // picked, then fails to convert (`pdf_tex` has no destination_type).
          // Empty ext is kept (the file may carry no extension but known content).
          // Witness 1907.12308 (`\input{grid.pdf_tex}` → `\includegraphics{grid}`).
          if !ext.is_empty() && !self.graphics_types.iter().any(|t| t == &ext) {
            continue;
          }
          let props = self.type_properties.get(&ext);
          let d = props.map(|p| p.desirability as i32).unwrap_or(0);
          let is_same_type = props
            .and_then(|p| p.destination_type.as_ref())
            .map(|dt| dt == &ext)
            .unwrap_or(false);
          let desirability = if is_same_type { 10 } else { d };
          if best.as_ref().is_none_or(|(_, bd)| desirability > *bd) {
            best = Some((resolved_path, desirability));
          }
        }
      }
      if let Some((path, _)) = best {
        return Some(path);
      }
    }

    // Search for the file in search paths
    let path = Path::new(&source);
    let name = path.file_stem().and_then(|s| s.to_str()).unwrap_or(&source);
    let dir = path.parent().and_then(|p| p.to_str()).unwrap_or("");

    let file_base = if dir.is_empty() {
      name.to_string()
    } else {
      format!("{}/{}", dir, name)
    };

    // Try each type in search paths
    let mut best_desirability: i32 = -1;
    let mut best_path: Option<String> = None;

    let types: Vec<String> = self
      .graphics_types
      .iter()
      .flat_map(|t| vec![t.clone(), t.to_uppercase()])
      .collect();

    for search_path in search_paths {
      // Try without extension first (source might already have one)
      let candidate = if search_path.is_empty() {
        source.clone()
      } else {
        format!("{}/{}", search_path, source)
      };
      if Path::new(&candidate).exists() {
        let ext = Path::new(&candidate)
          .extension()
          .and_then(|e| e.to_str())
          .unwrap_or("")
          .to_lowercase();
        let props = self.type_properties.get(&ext);
        let d = props.map(|p| p.desirability as i32).unwrap_or(5);
        if d > best_desirability {
          best_desirability = d;
          best_path = Some(candidate);
        }
      }
      // Try each extension
      for ext in &types {
        let candidate = format!("{}/{}.{}", search_path, file_base, ext);
        if Path::new(&candidate).exists() {
          let props = self.type_properties.get(&ext.to_lowercase());
          let d = props.map(|p| p.desirability as i32).unwrap_or(0);
          let is_same_type = props
            .and_then(|p| p.destination_type.as_ref())
            .map(|dt| dt == &ext.to_lowercase())
            .unwrap_or(false);
          let desirability = if is_same_type { 10 } else { d };
          if desirability > best_desirability {
            best_desirability = desirability;
            best_path = Some(candidate);
          }
        }
      }
    }
    if best_path.is_some() {
      return best_path;
    }

    // kpathsea-parity casefold fallback (`texmf_casefold_search`, default ON
    // since TL2018): pdflatex finds `images/NLPOptNet.jpg` even when the
    // file on disk is `images/NLPOPtNet.jpg`, so an author case-typo that
    // builds fine on arXiv must not lose the figure here (witness
    // 2605.00260, Figure 1). Like kpathsea, this fires only AFTER every
    // exact search misses; only the filename component is folded, and an
    // ambiguous directory (two case-variants) refuses to guess.
    for sp in std::iter::once(String::new()).chain(search_paths.iter().cloned()) {
      let cand = if sp.is_empty() {
        source.clone()
      } else {
        format!("{}/{}", sp, source)
      };
      if let Some(found) = Self::casefold_resolve(&cand) {
        Info!(
          "graphics",
          "casefold",
          "Graphic '{}' resolved case-insensitively to '{}' (kpathsea casefold parity)",
          source,
          found
        );
        return Some(found);
      }
    }
    None
  }

  /// Case-insensitive filename resolution within the path's directory.
  /// Returns the unique match, or None when absent or ambiguous.
  fn casefold_resolve(path: &str) -> Option<String> {
    let p = Path::new(path);
    if p.exists() {
      return Some(path.to_string());
    }
    let parent = match p.parent() {
      Some(d) if !d.as_os_str().is_empty() => d,
      _ => Path::new("."),
    };
    let want = p.file_name()?.to_str()?;
    let mut hit: Option<String> = None;
    for entry in std::fs::read_dir(parent).ok()? {
      let entry = entry.ok()?;
      let name = entry.file_name();
      let Some(name) = name.to_str() else { continue };
      if name.eq_ignore_ascii_case(want) && entry.path().is_file() {
        if hit.is_some() {
          return None; // ambiguous — never guess between case-variants
        }
        hit = Some(entry.path().to_string_lossy().to_string());
      }
    }
    hit
  }

  /// Set the image source attributes on a graphics node.
  ///
  /// Port of `Graphics::setGraphicSrc`.
  fn set_graphic_src(node: &mut Node, src: &str, width: Option<u32>, height: Option<u32>) {
    node.set_attribute("imagesrc", src).ok();
    // HTML width/height are in pixels (unitless)
    if let Some(w) = width {
      node.set_attribute("imagewidth", &w.to_string()).ok();
    }
    if let Some(h) = height {
      node.set_attribute("imageheight", &h.to_string()).ok();
    }
    // Set aspect ratio class
    if let (Some(w), Some(h)) = (width, height) {
      let class = if w as f64 > 1.24 * h as f64 {
        "ltx_img_landscape"
      } else if h as f64 > 1.24 * w as f64 {
        "ltx_img_portrait"
      } else {
        "ltx_img_square"
      };
      let existing = node.get_attribute("class").unwrap_or_default();
      let new_class = if existing.is_empty() {
        class.to_string()
      } else {
        format!("{} {}", existing, class)
      };
      node.set_attribute("class", &new_class).ok();
      // brucemiller/LaTeXML#2392: also emit the REQUESTED aspect ratio explicitly.
      // The coarse `ltx_img_{square,portrait,landscape}` bucket is enough to pick a
      // flex layout, but the flex CSS caps `max-width`, changing the width and not
      // the height — so a square picture renders as a vertical ellipsoid. An
      // `aspect-ratio:W/H` on the img lets a width-only cap (paired with
      // `height:auto` in the flex rules) preserve the ratio, and the *requested*
      // ratio (from `\includegraphics`), not the file's. Beyond Perl 0.8.8, which
      // emits no aspect-ratio (OXIDIZED_DESIGN #139).
      let ar = format!("aspect-ratio:{w}/{h}");
      let cssstyle = match node.get_attribute("cssstyle") {
        Some(s) if !s.is_empty() => format!("{s};{ar}"),
        _ => ar,
      };
      node.set_attribute("cssstyle", &cssstyle).ok();
    }
  }

  /// Find graphicspath from processing instructions.
  fn find_graphics_paths(&self, doc: &PostDocument) -> Vec<String> {
    // Perl `Post/Graphics.pm:91`:
    //   [map { pathname_canonical($_) }
    //    $self->findGraphicsPaths($doc), $doc->getSearchPaths]
    // — the search paths are the union of graphicspath PIs PLUS the
    // document's own search paths (typically the source directory). The
    // prior Rust port included only the PI half, which left every paper
    // with raw `.ps`/`.eps`/etc. files in the source directory (and no
    // explicit `\graphicspath{...}`) emitting `Error:expected:source`
    // for every figure, even though the source files are present.
    // Driver: astro-ph0002170 (8 .ps figures in the zip, all "not found").
    use std::sync::LazyLock;
    static GRAPHICSPATH_RE: LazyLock<regex::Regex> =
      LazyLock::new(|| regex::Regex::new(r#"^\s*graphicspath\s*=\s*[\"'](.*?)[\"']\s*$"#).unwrap());
    let mut paths = Vec::new();
    for pi in doc.findnodes("//processing-instruction('latexml')") {
      let text = pi.get_content();
      if let Some(cap) = GRAPHICSPATH_RE.captures(&text) {
        paths.push(cap[1].to_string());
      }
    }
    paths.extend(doc.get_search_paths().iter().cloned());
    paths
  }

  /// Read a named parameter from processing instructions.
  /// Port of Perl's `Graphics::getParameter`.
  /// Checks both direct PI (`<?latexml DPI="100"?>`) and
  /// latexml.sty package options (`<?latexml package="latexml" options="magnify=1.2"?>`).
  fn get_parameter(&self, doc: &PostDocument, param: &str) -> Option<f64> {
    let direct_re = regex::Regex::new(&format!(
      r#"^\s*{}\s*=\s*[\"']?([\d.]+)[\"']?\s*$"#,
      regex::escape(param)
    ))
    .ok()?;
    let options_re =
      regex::Regex::new(r#"package\s*=\s*[\"']latexml[\"'].*options\s*=\s*[\"'](.*?)[\"']"#)
        .ok()?;
    let param_in_options_re =
      regex::Regex::new(&format!(r#"\b{}\s*=\s*([\d.]+)"#, regex::escape(param))).ok()?;

    for pi in doc.findnodes("//processing-instruction('latexml')") {
      let text = pi.get_content();
      if let Some(cap) = direct_re.captures(&text) {
        return cap[1].parse().ok();
      }
      if let Some(cap) = options_re.captures(&text) {
        if let Some(inner) = param_in_options_re.captures(&cap[1]) {
          return inner[1].parse().ok();
        }
      }
    }
    None
  }

  /// Read image dimensions using imagesize crate.
  /// Returns (width, height) in pixels.
  fn read_image_dimensions(path: &str) -> Option<(u32, u32)> {
    match imagesize::size(path) {
      Ok(dim) => Some((dim.width as u32, dim.height as u32)),
      Err(_) => None,
    }
  }

  /// Read a *source* graphic's intrinsic dimensions, dispatching on type.
  ///
  /// Port of Perl `Util/Image.pm:image_size` (L86-97), which sizes ANY
  /// supported source type — there Image::Magick covers SVG. The
  /// `imagesize` crate is raster-only, so SVG dispatches to
  /// `read_svg_dimensions` (already the SVG-dims reader on the PDF→SVG
  /// convert path). Without this, a web-native SVG going through the
  /// trivial-copy path got NO imagewidth/imageheight and rendered at
  /// intrinsic size, ignoring `\includegraphics[width=…]` (issue 498).
  fn read_source_dimensions(path: &str) -> Option<(u32, u32)> {
    let is_svg = Path::new(path)
      .extension()
      .and_then(|e| e.to_str())
      .is_some_and(|e| e.eq_ignore_ascii_case("svg"));
    if is_svg {
      Self::read_svg_dimensions(path)
    } else {
      Self::read_image_dimensions(path)
    }
  }

  /// Parse `angle=N` from graphicx options. Returns angle normalised
  /// to one of {0, 90, 180, 270} when within 5° of those targets,
  /// otherwise the raw float (rotation of arbitrary angles is
  /// handled separately and is more complex due to bounding-box
  /// changes).
  fn parse_angle_option(options: &str) -> Option<f64> {
    for opt in options.split(',') {
      let opt = opt.trim();
      if let Some((key, val)) = opt.split_once('=') {
        if key.trim() == "angle" {
          return val.trim().parse::<f64>().ok();
        }
      }
    }
    None
  }

  /// Apply the graphicx options to a measured pixel size.
  ///
  /// Delegates to the shared algebra in `latexml_core::util::image` — the port
  /// of Perl `image_graphicx_size` (`Util/Image.pm` L221-256) — so the pixel
  /// count written into the HTML and the box the engine reserved come from one
  /// implementation. Pixel space, hence `DPI/72.27` per bp and Perl's `ceil` at
  /// each step.
  ///
  /// Two behaviours changed when this stopped being its own implementation, both
  /// toward Perl:
  ///
  /// * **Option values now go through `to_bp` first.** The local parser stripped
  ///   a `pt` suffix and used the number as-is, skipping Perl's pt->bp step, so
  ///   every explicit size came out up to one pixel wider than the engine's box
  ///   for the same request (`width=100pt`: 139 px here vs 138 in the engine).
  ///   It also silently ignored every unit that was not `pt`/`px`.
  /// * **Rotation is the true bounding box**, not a 90/270 axis swap. That
  ///   matches what `convert -rotate` actually writes to disk for an oblique
  ///   angle. It is ordered relative to scaling by key order, as Perl and
  ///   graphicx do — see `parse_graphicx_options`. Witness for the rotation
  ///   mattering at all: 1303.5091 Figs 5-7, `[angle=90,scale=0.75]`, which
  ///   rendered upside-down before any of it — still correct here: a uniform
  ///   scale commutes with a rotation, so its order does not change the box.
  ///
  /// Witness for the width-only path: astro-ph0005397 Fig 11 (sfh_burst), where
  /// feeding the unscaled raw height back through displayed square sources as
  /// 4:1 ribbons.
  fn apply_graphicx_transforms(raw_w: u32, raw_h: u32, options: &str, dpi: u32) -> (u32, u32) {
    let ops = latexml_core::util::image::parse_graphicx_options(options);
    let (w, h) = latexml_core::util::image::apply_graphicx_ops(
      raw_w as f64,
      raw_h as f64,
      &ops,
      dpi as f64 / 72.27,
      true,
    );
    // An image attribute of 0 is useless to a browser; keep at least one pixel.
    (w.max(1.0) as u32, h.max(1.0) as u32)
  }

  /// Physically rotate a rasterized image via `convert -rotate N`.
  /// Called after the rasterizer produces a PNG when graphicx
  /// options include `angle=N`. Returns true on success.
  /// Pre-condition: `dest` exists. Post-condition: `dest` is
  /// in-place rotated.
  /// Content fingerprint for graphics-asset deduplication. SipHash
  /// (`std::collections::hash_map::DefaultHasher`) over the file's
  /// raw bytes. Returns `None` if the file can't be opened.
  ///
  /// Collisions are theoretically possible but astronomically unlikely
  /// for paper-sized graphics dirs (worst case: a few hundred files
  /// per paper, all under 50 MB). We use a u64 hash as the dedup key.
  ///
  /// Purpose: byte-identical files `x1.pdf` and `x2.pdf` (e.g. shared
  /// figures across subsections, or duplicated by the author) should
  /// share one rasterized PNG/SVG in the output bundle. Both `<img>`
  /// tags then reference the first-seen filename's stem — saves both
  /// conversion time AND output-bundle disk space.
  fn hash_file_content(path: &str) -> Option<u64> {
    use std::{hash::Hasher, io::Read};
    let mut file = std::fs::File::open(path).ok()?;
    let mut hasher = std::collections::hash_map::DefaultHasher::new();
    let mut buf = [0u8; 65536];
    loop {
      let n = file.read(&mut buf).ok()?;
      if n == 0 {
        break;
      }
      hasher.write(&buf[..n]);
    }
    Some(hasher.finish())
  }

  /// Derive the destination stem for a CONVERTED graphic.
  ///
  /// The first job for a given source keeps the source's basename stem, for
  /// readable output URLs (`figures/mock1/plot.pdf` → `plot.png`). But two
  /// *different* sources that share a basename must NOT collapse onto one output
  /// file: `figures/mock1/plot.pdf` and `figures/jackpot/plot.pdf` would both
  /// claim `plot.png`, and the first write would silently replace one figure
  /// with the other. When the stem-based destination is already claimed by
  /// another source (`used_dests`), or this source already produced a job
  /// (`page=`/subsequent), fall back to a unique `xN` — mirroring Perl's
  /// `generateResourcePathname` (`Graphics.pm` L299/L319), which never collapses
  /// distinct sources. `used_dests` keys on the full `stem.ext`, so `plot.png`
  /// and `plot.svg` (different *primary* output files) don't count as a
  /// collision. The `xN` fallback is likewise registered and skips any already
  /// claimed name, so a source literally named `xN` and a generated `xN` can't
  /// clobber each other. (A PDF's opt-in vector-SVG *alternate* `{stem}.svg` is
  /// not tracked here — a separate, pre-existing edge, not this collision.)
  /// Witness arXiv 2606.30620 (arXiv/html_feedback#6922): Figures 2/4/5 all used
  /// `figures/{mock1,mock3,jackpot}/chi2_residuals.pdf`.
  fn assign_dest_name(
    source: &str,
    dest_type: &str,
    has_page: bool,
    prior_source_jobs: u32,
    used_dests: &mut HashMap<String, String>,
    resource_counter: &mut u32,
  ) -> String {
    let stem = Path::new(source)
      .file_stem()
      .and_then(|s| s.to_str())
      .unwrap_or("image");
    let stem_dest = format!("{}.{}", stem, dest_type);
    let stem_taken = used_dests
      .get(&stem_dest)
      .is_some_and(|owner| owner != source);
    if has_page || prior_source_jobs > 0 || stem_taken {
      // Advance to a counter name whose output file isn't already claimed by
      // another source, and register it — else a real source named `xK` (which
      // took the stem branch) could be silently overwritten by this fallback.
      loop {
        *resource_counter += 1;
        let name = format!("x{}", resource_counter);
        let dest = format!("{}.{}", name, dest_type);
        if let std::collections::hash_map::Entry::Vacant(slot) = used_dests.entry(dest) {
          slot.insert(source.to_string());
          return name;
        }
      }
    } else {
      used_dests.insert(stem_dest, source.to_string());
      stem.to_string()
    }
  }

  fn rotate_image_inplace(dest: &str, angle_deg: f64) -> bool {
    // Sibling temp file to avoid IM's flaky in-place rewrite semantics.
    let dest_path = Path::new(dest);
    let parent = dest_path.parent().unwrap_or_else(|| Path::new("."));
    let stem = dest_path
      .file_name()
      .and_then(|s| s.to_str())
      .unwrap_or("image");
    let unique = std::time::SystemTime::now()
      .duration_since(std::time::UNIX_EPOCH)
      .map(|d| d.as_nanos())
      .unwrap_or(0);
    let tmp = parent.join(format!(".{}.{}.rotated", stem, unique));
    let mut cmd = std::process::Command::new(im_convert_program());
    cmd
      .arg(dest)
      .arg("-rotate")
      .arg(format!("{}", angle_deg))
      .arg(&tmp);
    let timeout = std::time::Duration::from_secs(30);
    let cmd_ok = Self::run_with_timeout(cmd, timeout)
      .map(|s| s.success())
      .unwrap_or(false)
      && tmp.exists();
    if !cmd_ok {
      let _ = std::fs::remove_file(&tmp);
      return false;
    }
    let renamed = std::fs::rename(&tmp, dest)
      .or_else(|_| std::fs::copy(&tmp, dest).map(|_| ()))
      .is_ok();
    let _ = std::fs::remove_file(&tmp);
    renamed
  }

  /// Copy a source image to the destination directory, preserving relative paths.
  /// Returns the destination path (relative to dest_dir).
  fn copy_to_destination(source: &str, source_dir: &str, dest_dir: &str) -> Option<String> {
    // Relativize like Perl's pathname_relative (→ File::Spec->abs2rel): a
    // source OUTSIDE source_dir comes back as `../…`, never the raw absolute
    // path. A bare `strip_prefix` used to leak the absolute path for a graphic
    // reached through `\subimport*{../A/child/}` (issue #698 class).
    let rel = latexml_core::util::pathname::relative(source, source_dir);
    let rel_path = Path::new(&rel);

    // Build absolute destination path
    let abs_dest = PathBuf::from(dest_dir).join(rel_path);

    // Create parent directories if needed
    if let Some(parent) = abs_dest.parent() {
      std::fs::create_dir_all(parent).ok()?;
    }

    // Copy the file (skip if same path)
    let source_canonical = std::fs::canonicalize(source).ok();
    let dest_canonical = std::fs::canonicalize(&abs_dest).ok();
    if source_canonical != dest_canonical || dest_canonical.is_none() {
      std::fs::copy(source, &abs_dest).ok()?;
    }

    // Return relative path for imagesrc attribute
    Some(rel_path.to_string_lossy().to_string())
  }

  /// Extract `page=N` from graphicx options string.
  /// Returns 1-based page number (matching graphicx convention), or None.
  fn parse_page_option(options: &str) -> Option<u32> {
    for opt in options.split(',') {
      let opt = opt.trim();
      if let Some((key, val)) = opt.split_once('=') {
        if key.trim() == "page" {
          // Strip braces: page={2} → 2
          let val = val.trim().trim_matches('{').trim_matches('}');
          return val.parse::<u32>().ok();
        }
      }
    }
    None
  }

  /// Try to convert a PDF to plain SVG, preserving vector content. Returns
  /// `true` on success. Tracks upstream brucemiller/LaTeXML#902.
  ///
  /// Caller decides when to attempt this — typically only for PDF sources
  /// below a file-size threshold (`should_try_svg_path`), because vector
  /// converters on raster-embedded PDFs produce massive output (>100 MB).
  /// On any failure the function returns `false` and the worker falls back
  /// to the raster (PNG) path — so a PDF that no vector tool can handle is
  /// never lost, just rasterized instead.
  ///
  /// `page` is 1-based (graphicx convention).
  ///
  /// Each converter is guarded by a **hard timeout** (15 s default; see
  /// `svg_convert_timeout_secs`) and an output-size cap
  /// (`MAX_SVG_OUTPUT_BYTES`): a converter still running after the deadline
  /// is SIGKILLed, and oversized output is discarded — either way we fall
  /// through to the next converter, then to raster.
  fn convert_image_svg(source: &str, dest: &str, page: Option<u32>) -> bool {
    // Try the two fast vector converters in order of measured speed +
    // gzip-compressibility on the canvas slow-tail. Each is gated by
    // `MAX_SVG_OUTPUT_BYTES`; pathological vector-heavy PDFs (e.g.
    // R-Graphics `W.pdf`) can emit >100 MB SVG which we discard so the
    // caller falls back to raster.
    //
    // Order (subprocess; library license doesn't propagate):
    //   1. mutool (MuPDF CLI) — fastest, plus ~4× more gzip-compressible SVG output than pdftocairo
    //      (1.5 MB vs 6.0 MB gz on matplotlib scatter).
    //   2. pdftocairo (poppler) — universally available with TeX Live; parses vector PDFs directly,
    //      so it's fast even on the inputs that make ImageMagick/gs rasterization crawl.
    //
    // A heavyweight third resort (inkscape) was removed deliberately: it
    // pulls a GTK/X11 stack, is 20-40× slower, and is timeout-prone, while
    // adding no real coverage — when both converters above fail, the worker
    // rasterizes to PNG anyway.
    if Self::convert_image_svg_mutool(source, dest, page) {
      return true;
    }
    if Self::convert_image_svg_pdftocairo(source, dest, page) {
      return true;
    }
    false
  }

  /// Maximum acceptable SVG output size from a vector conversion. Above
  /// this we discard the SVG and force the raster fallback — it's nearly
  /// always cheaper to ship a 30 KB PNG than a 100 MB SVG even when both
  /// are technically valid. Tuned from observed cases: well-behaved
  /// matplotlib plots are ~500 KB - 2 MB; W.pdf-class explodes to
  /// 70-115 MB across all known PDF→SVG tools.
  const MAX_SVG_OUTPUT_BYTES: u64 = 8 * 1024 * 1024; // 8 MB

  fn svg_output_too_large(path: &str) -> bool {
    std::fs::metadata(path)
      .map(|md| md.len() > Self::MAX_SVG_OUTPUT_BYTES)
      .unwrap_or(false)
  }
  /// `mutool convert -F svg` (MuPDF CLI) — first-choice SVG vector
  /// converter. Faster than `pdftocairo -svg` on vector-heavy PDFs
  /// (~2×), AND produces output that gzip-compresses ~4× better when
  /// served as `.svgz`. Subprocess invocation — no MuPDF code linked.
  ///
  /// Measured 2026-05-12 on matplotlib AugmentedMSRA10K…pos.pdf:
  ///   pdftocairo -svg: 1.17 s, 29.9 MB raw, 6.0 MB gz
  ///   mutool convert:  0.52 s, 29.7 MB raw, 1.5 MB gz
  ///
  /// mutool's `convert` emits one file per page via a printf-style
  /// pattern. We use `%d` to capture the requested page and rename
  /// the result to the caller's `dest`.
  fn convert_image_svg_mutool(source: &str, dest: &str, page: Option<u32>) -> bool {
    let dest_path = Path::new(dest);
    let parent = dest_path.parent().unwrap_or_else(|| Path::new("."));
    let stem = dest_path
      .file_name()
      .and_then(|s| s.to_str())
      .unwrap_or("image");
    let unique = std::time::SystemTime::now()
      .duration_since(std::time::UNIX_EPOCH)
      .map(|d| d.as_nanos())
      .unwrap_or(0);
    let tmp_pattern = parent.join(format!(".{}.{}.mutool_svg%d.svg", stem, unique));
    let tmp_pattern_str = tmp_pattern.to_string_lossy().to_string();
    let p1 = page.map(|p| p.max(1)).unwrap_or(1);
    let tmp_actual = parent.join(format!(".{}.{}.mutool_svg{}.svg", stem, unique, p1));
    let cleanup = || {
      let _ = std::fs::remove_file(&tmp_actual);
    };

    let mut cmd = std::process::Command::new("mutool");
    cmd
      .arg("convert")
      .arg("-F")
      .arg("svg")
      .arg("-o")
      .arg(&tmp_pattern_str)
      .arg(source)
      .arg(p1.to_string());
    let timeout = std::time::Duration::from_secs(Self::svg_convert_timeout_secs());
    let ok = Self::run_with_timeout(cmd, timeout)
      .map(|status| status.success())
      .unwrap_or(false)
      && tmp_actual.exists();
    if !ok {
      cleanup();
      return false;
    }
    if std::fs::metadata(&tmp_actual)
      .map(|md| md.len() > Self::MAX_SVG_OUTPUT_BYTES)
      .unwrap_or(true)
    {
      cleanup();
      return false;
    }
    let _ = std::fs::remove_file(dest);
    let installed = std::fs::rename(&tmp_actual, dest)
      .or_else(|_| std::fs::copy(&tmp_actual, dest).map(|_| ()))
      .is_ok()
      && dest_path.exists();
    cleanup();
    installed
  }

  /// `pdftocairo -svg` rasterizes the page's vector content to SVG via
  /// poppler/cairo — the second-choice vector converter after mutool, and
  /// universally available with TeX Live. Returns true ONLY if the output
  /// is reasonably-sized; otherwise we discard it and the caller falls
  /// through to the raster (PNG) path.
  fn convert_image_svg_pdftocairo(source: &str, dest: &str, page: Option<u32>) -> bool {
    let mut cmd = std::process::Command::new("pdftocairo");
    cmd.arg("-svg");
    if let Some(p) = page {
      let p1 = p.max(1);
      cmd
        .arg("-f")
        .arg(p1.to_string())
        .arg("-l")
        .arg(p1.to_string());
    } else {
      cmd.arg("-f").arg("1").arg("-l").arg("1");
    }
    cmd.arg(source).arg(dest);
    let timeout = std::time::Duration::from_secs(Self::svg_convert_timeout_secs());
    match Self::run_with_timeout(cmd, timeout) {
      Some(status) => {
        if !(status.success() && Path::new(dest).exists()) {
          let _ = std::fs::remove_file(dest);
          return false;
        }
        if Self::svg_output_too_large(dest) {
          let _ = std::fs::remove_file(dest);
          return false;
        }
        true
      },
      None => {
        let _ = std::fs::remove_file(dest);
        false
      },
    }
  }

  /// Hard timeout (seconds) for a vector-SVG converter subprocess (mutool /
  /// pdftocairo). Overridable via the `LATEXML_SVG_CONVERT_TIMEOUT_SECS`
  /// environment variable for debugging; defaults to 15 s — enough for all
  /// benign vector-authored plots we've measured (< 1 s typical), strict
  /// enough to cut off the Fade.pdf-class 40 s+ runaway cases.
  fn svg_convert_timeout_secs() -> u64 { SVG_CONVERT_TIMEOUT_SECS.unwrap_or(15) }

  /// Run `cmd` and enforce a wall-clock timeout. Returns `Some(status)` on
  /// clean exit, `None` if the child was killed on timeout or spawn
  /// failed. Polls every 50 ms — cheap compared to the subprocess cost.
  ///
  /// On Unix, each child runs in its OWN session (setsid via pre_exec)
  /// so a timeout kill targets the entire process group with `killpg`.
  /// Without that, ImageMagick's `convert` was spawning `gs` and dying
  /// on SIGKILL while leaving gs orphaned — those gs processes held on
  /// for 10+ minutes per pathological PDF and stalled large sandbox
  /// runs. The same hardening protects mutool / pdftocairo / ps2pdf.
  fn run_with_timeout(
    mut cmd: std::process::Command,
    timeout: std::time::Duration,
  ) -> Option<std::process::ExitStatus> {
    // Capture the program name for the failure diagnostic before `cmd` is moved.
    let prog = cmd.get_program().to_string_lossy().into_owned();
    // stdout is uninteresting (null); stderr is PIPED so a converter's error text
    // (gs `/undefinedfilename`, an ImageMagick policy block, a missing delegate)
    // can be surfaced into the failed_to_convert Error. A draining reader thread
    // (below) keeps the child from blocking on a full stderr pipe.
    cmd
      .stdout(std::process::Stdio::null())
      .stderr(std::process::Stdio::piped());
    #[cfg(unix)]
    {
      use std::os::unix::process::CommandExt;
      // SAFETY: setsid(2) is async-signal-safe and is the documented way
      // to make a child process group leader between fork() and exec().
      unsafe {
        cmd.pre_exec(|| {
          // SAFETY: same as above — async-signal-safe call permitted here.
          if libc::setsid() == -1 {
            // Fall back: setpgid(0, 0). If both fail we proceed anyway.
            let _ = libc::setpgid(0, 0);
          }
          // Die-with-watcher: `setsid` detaches this converter from every
          // process group, so if the process running `run_with_timeout` is
          // itself killed (e.g. the LSP server SIGKILLs a preempted body
          // child mid-post-processing), nothing would ever time out or kill
          // a runaway gs/convert — the exact orphan pathology this
          // function's group-kill solves, reintroduced one level up.
          // PR_SET_PDEATHSIG makes the kernel SIGKILL the converter when its
          // spawning thread dies; it survives execve, so setting it here
          // (between fork and exec) covers the exec'd tool. Linux-only —
          // elsewhere the orphan window simply remains. prctl is
          // async-signal-safe. Guard the fork→prctl race: if the watcher
          // died before prctl took effect we are already reparented (to
          // init or a subreaper) — exit instead of running unwatched.
          #[cfg(target_os = "linux")]
          {
            libc::prctl(libc::PR_SET_PDEATHSIG, libc::SIGKILL);
            if libc::getppid() == 1 {
              libc::_exit(127);
            }
          }
          Ok(())
        });
      }
    }
    let mut child = match cmd.spawn() {
      Ok(c) => c,
      Err(e) => {
        // Spawn failure is the "converter not installed / not on PATH" case
        // (e.g. `gs` absent in a minimal image): record it so the Error names
        // the missing tool instead of a bare "failed to convert". When the
        // binary is simply absent, append the package/install hint so the user
        // learns which dependency to install (these tools are NOT bundled — the
        // host provides them).
        let mut msg = format!("could not start `{prog}`: {e}");
        if e.kind() == std::io::ErrorKind::NotFound {
          if let Some(hint) = missing_tool_hint(&prog) {
            msg.push_str(" — ");
            msg.push_str(hint);
          }
        }
        record_converter_diag(msg);
        return None;
      },
    };
    // Drain stderr concurrently into a bounded (8 KiB) buffer so the child never
    // blocks on a full pipe; joined after it exits.
    // The drained text comes back over a channel so the parent can WAIT
    // BOUNDED: a converter descendant that survives the kill while holding
    // stderr open must not hang the worker past the timeout (the reader
    // thread is simply abandoned; it exits at pipe EOF).
    let (stderr_tx, stderr_rx) = std::sync::mpsc::channel::<String>();
    let stderr_reader = child.stderr.take().map(|mut se| {
      std::thread::spawn(move || {
        use std::io::Read;
        let mut kept: Vec<u8> = Vec::new();
        let mut chunk = [0u8; 4096];
        loop {
          match se.read(&mut chunk) {
            Ok(0) => break,
            Ok(n) => {
              if kept.len() < 8192 {
                let room = 8192 - kept.len();
                kept.extend_from_slice(&chunk[..n.min(room)]);
              }
            },
            // EINTR is not EOF — treating it as terminal stopped the drain
            // and let a chatty converter block on the full pipe.
            Err(e) if e.kind() == std::io::ErrorKind::Interrupted => continue,
            Err(_) => break,
          }
        }
        let _ = stderr_tx.send(String::from_utf8_lossy(&kept).trim().to_string());
      })
    });
    let pid = child.id() as i32;
    let kill_group = || {
      #[cfg(unix)]
      {
        // SIGTERM the whole group first (graceful), then SIGKILL after
        // a brief grace if the leader is still alive. This matches what
        // `timeout(1) --kill-after` does for the bench script's outer
        // guard.
        // SAFETY: killpg(2) on a known pid is documented + safe.
        unsafe {
          libc::killpg(pid, libc::SIGTERM);
        }
        std::thread::sleep(std::time::Duration::from_millis(200));
        // SAFETY: pgid is the child's own process group (set via setpgid in
        // pre_exec); killpg only signals that group.
        unsafe {
          libc::killpg(pid, libc::SIGKILL);
        }
      }
      #[cfg(windows)]
      {
        // Windows analogue of the killpg group-kill: `taskkill /T` walks
        // the child-process tree from the given PID, so a timed-out
        // `magick` also takes down the `gs` it spawned (the exact orphan
        // scenario the Unix setsid+killpg design exists for). /F because
        // there is no SIGTERM-style graceful tier on Windows consoles
        // without a console-event dance; the subsequent child.kill() is
        // then a no-op backstop.
        let _ = std::process::Command::new("taskkill")
          .args(["/PID", &pid.to_string(), "/T", "/F"])
          .output();
      }
      #[cfg(not(any(unix, windows)))]
      {
        // Other platforms: best-effort PID kill only (child.kill() below).
        let _ = pid;
      }
    };
    let start = std::time::Instant::now();
    let status = loop {
      match child.try_wait() {
        Ok(Some(status)) => break Some(status),
        Ok(None) => {
          if start.elapsed() >= timeout {
            kill_group();
            let _ = child.kill();
            let _ = child.wait();
            break None;
          }
          std::thread::sleep(std::time::Duration::from_millis(50));
        },
        Err(_) => {
          kill_group();
          let _ = child.kill();
          let _ = child.wait();
          break None;
        },
      }
    };
    // Join the stderr drainer and record a diagnostic. gs can print a fatal
    // error (e.g. `/undefinedfilename` under an AppArmor denial) to stderr yet
    // still exit 0, so a non-empty stderr is always worth surfacing — not only
    // on a non-zero exit.
    let stderr_text = if stderr_reader.is_some() {
      // Exited child → EOF imminent; killed child → give the drain a short
      // grace, then abandon the reader rather than hang the worker.
      let grace = if status.is_some() {
        std::time::Duration::from_secs(10)
      } else {
        std::time::Duration::from_secs(2)
      };
      stderr_rx.recv_timeout(grace).unwrap_or_default()
    } else {
      String::new()
    };
    if !stderr_text.is_empty() {
      // Flatten newlines: gs prints `Error: ...` at column 0 mid-diagnostic,
      // which would inflate line-anchored ^Error: log counts.
      let flat = stderr_text.replace('\n', "; ");
      record_converter_diag(format!("`{prog}`: {flat}"));
    } else if status.map(|s| !s.success()).unwrap_or(true) {
      let how = match status {
        Some(s) => format!("exited {s}"),
        None => format!("timed out after {}s / killed", timeout.as_secs()),
      };
      record_converter_diag(format!("`{prog}`: {how}, no stderr"));
    }
    status
  }

  /// The SVG viewport in pixels — the root `width`/`height`, else the `viewBox`
  /// extent (issue #696). `None` when the geometry can't be recovered, so
  /// callers omit the dimension attributes entirely (a browser then sizes the
  /// image itself, which beats writing a wrong number).
  ///
  /// Delegates to `latexml_core::util::image`, which owns the SVG root-tag
  /// parsing for both the engine and this pass — Perl likewise keeps one
  /// `Util::Image` shared by `Core` and `Post`. The former local parser read
  /// only double-quoted attributes, matched `stroke-width` as `width`, and
  /// truncated units (`10cm` → 10 px); it also slurped the entire file to find
  /// a root tag that lives in its first few hundred bytes. Witness for the
  /// bounded, lossy read: 1307.4573 (xfig-pstex_t paper, multi-byte characters
  /// in the SVG preamble) — a FATAL_101 panic when a fixed 2048-byte slice cut
  /// a UTF-8 sequence.
  fn read_svg_dimensions(path: &str) -> Option<(u32, u32)> {
    latexml_core::util::image::read_svg_viewport_px(Path::new(path))
  }

  /// Decide whether the vector-SVG path should be attempted for this PDF
  /// source.
  ///
  /// Two modes, in priority order:
  ///
  /// 1. **Explicit threshold** (`threshold_kb > 0`): legacy `--graphics-svg-threshold-kb N`
  ///    behaviour — try SVG for PDFs at most `N` KB, regardless of content. Preserved for
  ///    back-compat and as the manual override on canvases where the auto-detector misclassifies.
  /// 2. **Auto-detect default** (`threshold_kb == 0`): scan the PDF header for `/Subtype /Image`
  ///    and `/Subtype/Image` (the two typical formattings of an image XObject declaration). If NONE
  ///    is present in the first 256 KB and the file size is at most 500 KB → try SVG. This is the
  ///    per-paper relief case documented in PERFORMANCE.md (130× speedup on the 41 KB pgfplots
  ///    fixture).
  ///
  /// Both modes can be globally disabled via
  /// `LATEXML_GRAPHICS_VECTOR_AUTO_OFF=1` (auto-detect only — leaves
  /// the explicit-threshold path active).
  ///
  /// Safety net: any false positive falls back to the raster path when a
  /// vector converter emits >`MAX_SVG_OUTPUT_BYTES` (8 MB) of SVG, so a
  /// misread raster PDF degrades to "tried SVG, got too-big output, used
  /// convert" instead of a stuck pipeline.
  fn should_try_svg_path(source: &str, threshold_kb: u32) -> bool {
    if !source.to_lowercase().ends_with(".pdf") {
      return false;
    }
    if threshold_kb > 0 {
      // Legacy explicit-threshold path: bytes-only decision.
      return match std::fs::metadata(source) {
        Ok(md) => md.len() <= (threshold_kb as u64) * 1024,
        Err(_) => false,
      };
    }
    // Auto-detect path. Honour the opt-out.
    if Self::vector_auto_detect_disabled() {
      return false;
    }
    let len = match std::fs::metadata(source) {
      Ok(md) => md.len(),
      Err(_) => return false,
    };
    // Hard upper bound: even if the detector misses an image
    // somewhere deeper in the file, a 500 KB cap keeps the
    // worst-case wasted vector-conversion work bounded (~1-2 s before the
    // 8 MB output cap kicks in or the conversion finishes anyway).
    const AUTO_MAX_BYTES: u64 = 500 * 1024;
    if len > AUTO_MAX_BYTES {
      return false;
    }
    !Self::pdf_has_image_xobject(source).unwrap_or(true)
  }

  /// Has `LATEXML_GRAPHICS_VECTOR_AUTO_OFF` been set? Memoised on
  /// first call so the env var is read once.
  fn vector_auto_detect_disabled() -> bool {
    use std::sync::OnceLock;
    static CELL: OnceLock<bool> = OnceLock::new();
    *CELL.get_or_init(|| {
      matches!(
        std::env::var("LATEXML_GRAPHICS_VECTOR_AUTO_OFF")
          .ok()
          .as_deref()
          .map(|s| s.trim()),
        Some("1") | Some("true") | Some("yes")
      )
    })
  }

  /// Scan a PDF for `/Subtype /Image` (with or without whitespace
  /// between the tokens) — the canonical marker of an image XObject.
  /// Returns `Some(true)` when found, `Some(false)` when absent in the
  /// scanned range, `None` on I/O error.
  ///
  /// Reads at most `SCAN_LIMIT` bytes from the start of the file. PDF
  /// objects are written sequentially; for small files (≤500 KB,
  /// guarded by `should_try_svg_path`'s outer size check) the entire
  /// stream fits comfortably within the limit. Pure-vector PDFs scan
  /// in well under a millisecond on modern hardware.
  fn pdf_has_image_xobject(source: &str) -> Option<bool> {
    use std::io::Read;
    const SCAN_LIMIT: usize = 256 * 1024;
    let mut f = std::fs::File::open(source).ok()?;
    let mut buf = vec![0u8; SCAN_LIMIT];
    let n = f.read(&mut buf).ok()?;
    let head = &buf[..n];
    // Both spelling variants seen in the wild: `/Subtype /Image` (PDFs
    // from inkscape / cairo / latex+dvips) and `/Subtype/Image` (more
    // common in pdflatex output and ImageMagick-produced PDFs).
    Some(twoway_contains(head, b"/Subtype /Image") || twoway_contains(head, b"/Subtype/Image"))
  }

  fn raster_density_for_source(source: &str) -> u32 {
    // `LATEXML_RASTER_DENSITY` overrides the default DPI globally for
    // benchmarking and quality/perf tradeoff exploration. Clamped to
    // [50, 600]. Unset → default (matches Perl `Util/Image.pm` 100).
    let base = std::env::var("LATEXML_RASTER_DENSITY")
      .ok()
      .and_then(|s| s.parse::<u32>().ok())
      .map(|d| d.clamp(50, 600))
      .unwrap_or(Self::DEFAULT_RASTER_DENSITY);
    let source_lc = source.to_lowercase();
    let is_postscript = source_lc.ends_with(".eps")
      || source_lc.ends_with(".epsi")
      || source_lc.ends_with(".epsf")
      || source_lc.ends_with(".ps")
      || source_lc.ends_with(".ai");
    let is_pdf = source_lc.ends_with(".pdf");
    let page_box = if is_postscript {
      read_postscript_bounding_box(source)
    } else if is_pdf {
      latexml_core::util::image::read_pdf_page_box(Path::new(source))
    } else {
      None
    };
    let Some((w_pt, h_pt)) = page_box else {
      return base;
    };
    let max_pt = w_pt.max(h_pt);
    if max_pt <= 0.0 {
      return base;
    }

    let max_density = ((Self::MAX_RASTER_DIMENSION_PX as f64) * 72.0 / max_pt).floor() as u32;
    base.min(max_density.max(1))
  }

  /// Returns true when the PS / EPS file's DSC header declares
  /// `%%Orientation: Landscape`. PGPLOT and a handful of older
  /// scientific renderers emit landscape PS files with a portrait
  /// `%%BoundingBox` — content is drawn rotated 90° on the page, and
  /// PS-level renderers (gs, IM) ignore the Orientation hint, producing
  /// visibly upside-down output. ps2pdf is the one tool in the chain
  /// that honors the comment by writing `/Rotate 90` into the PDF
  /// header; pdftocairo then renders the rotated PDF correctly.
  ///
  /// Witness: astro-ph0103041 NickMorgan.fig2.ps. Only the first ~80
  /// lines of the DSC prologue are scanned because all conforming PS
  /// files emit `%%Orientation:` early.
  fn postscript_is_landscape(source: &str) -> bool {
    let Ok(file) = std::fs::File::open(source) else {
      return false;
    };
    use std::io::BufRead;
    let reader = std::io::BufReader::new(file);
    for line in reader.lines().take(80).map_while(Result::ok) {
      if let Some(rest) = line.strip_prefix("%%Orientation:") {
        return rest.trim().eq_ignore_ascii_case("Landscape");
      }
    }
    false
  }

  fn should_try_eps_pdf_path(source: &str, page: Option<u32>) -> bool {
    // DISABLED 2026-05-12 after 1303.5091 regression.
    //
    // The `ps2pdf -dEPSCrop` step injects `/Rotate N` PDF annotations
    // based on EPS internal orientation hints. PDF's `/Rotate` is
    // CLOCKWISE (per PDF spec), but graphicx `angle=N` is
    // COUNTER-CLOCKWISE — these are OPPOSITE conventions. After
    // pdftocairo respects /Rotate, applying our `angle` rotation on
    // top yields content that's 180° off (upside-down).
    //
    // Perl LaTeXML doesn't use ps2pdf — it uses ImageMagick `convert`
    // (which spawns Ghostscript via the EPS delegate) directly, and
    // ImageMagick's Rotate takes degrees in CCW = matches graphicx.
    //
    // Match that: route EPS through the `convert` path, which is
    // slower than ps2pdf+pdftocairo but produces correctly-oriented
    // output. The performance hit only affects EPS-source documents
    // (rare in the canvas — PDF dominates modern arXiv).
    let _ = (source, page);
    false
  }

  /// Whether to attempt the poppler `pdftocairo --png` fast-path for a PDF
  /// source. The page argument cooperates with pdftocairo's 1-based
  /// `-f`/`-l` page selector. Empirical: for vector-heavy PDFs (e.g.
  /// R-Graphics output) `pdftocairo` rasterizes 25× faster than
  /// ImageMagick-via-Ghostscript and produces a clean PNG, where the
  /// vector-SVG path explodes to >100 MB and `convert`/`gs` runs into
  /// tens of seconds on a single page.
  fn should_try_pdf_cairo_path(source: &str) -> bool { source.to_lowercase().ends_with(".pdf") }

  /// Rasterize a PDF via the `mutool draw` subprocess (MuPDF CLI).
  /// ~1.7× faster than `pdftocairo` on vector-heavy matplotlib /
  /// pgfplots scatter PDFs (the canvas slow-tail).
  ///
  /// Subprocess invocation only — we do NOT link the MuPDF C library
  /// or the `mupdf-rs` Rust crate into our binary, so MuPDF's AGPL-3.0
  /// license does not propagate. Same legal pattern as invoking
  /// `/bin/git` or `ffmpeg` from a non-GPL program.
  ///
  /// Measured 2026-05-12 on AugmentedMSRA10KExperimentVIIIpos.pdf
  /// (894 KB matplotlib scatter):
  ///   mutool draw:    0.48 s
  ///   pdftocairo:     0.86 s
  ///
  /// Returns true only when the destination file was actually written.
  /// Optional dep: graceful fallthrough when `mutool` is not on PATH.
  fn convert_pdf_via_mutool(source: &str, dest: &str, density: u32, page: Option<u32>) -> bool {
    let dest_path = Path::new(dest);
    let parent = dest_path.parent().unwrap_or_else(|| Path::new("."));
    let stem = dest_path
      .file_name()
      .and_then(|s| s.to_str())
      .unwrap_or("image");
    let unique = std::time::SystemTime::now()
      .duration_since(std::time::UNIX_EPOCH)
      .map(|d| d.as_nanos())
      .unwrap_or(0);
    let tmp = parent.join(format!(".{}.{}.mutool.png", stem, unique));
    let timeout = std::time::Duration::from_secs(20);

    let mut cmd = std::process::Command::new("mutool");
    cmd
      .arg("draw")
      .arg("-o")
      .arg(&tmp)
      .arg("-r")
      .arg(density.to_string())
      .arg("-F")
      .arg("png");
    let p1 = page.map(|p| p.max(1)).unwrap_or(1);
    cmd.arg(source).arg(p1.to_string());

    let mutool_ok = Self::run_with_timeout(cmd, timeout)
      .map(|status| status.success())
      .unwrap_or(false)
      && tmp.exists();
    if !mutool_ok {
      let _ = std::fs::remove_file(&tmp);
      return false;
    }

    let _ = std::fs::remove_file(dest);
    let installed = std::fs::rename(&tmp, dest)
      .or_else(|_| std::fs::copy(&tmp, dest).map(|_| ()))
      .is_ok()
      && dest_path.exists();
    let _ = std::fs::remove_file(&tmp);
    installed
  }

  /// Rasterize a PDF directly via `pdftocairo --png`. Much faster than
  /// `convert`/Ghostscript for vector-heavy PDFs. Returns true only when
  /// the destination file was actually written.
  fn convert_pdf_via_pdftocairo(source: &str, dest: &str, density: u32, page: Option<u32>) -> bool {
    let dest_path = Path::new(dest);
    let parent = dest_path.parent().unwrap_or_else(|| Path::new("."));
    let stem = dest_path
      .file_name()
      .and_then(|s| s.to_str())
      .unwrap_or("image");
    let unique = std::time::SystemTime::now()
      .duration_since(std::time::UNIX_EPOCH)
      .map(|d| d.as_nanos())
      .unwrap_or(0);
    let tmp_prefix = parent.join(format!(".{}.{}.pdftocairo", stem, unique));
    let tmp_png = PathBuf::from(format!("{}.png", tmp_prefix.to_string_lossy()));
    let timeout = std::time::Duration::from_secs(20);

    let cleanup = |tmp_png: &Path| {
      let _ = std::fs::remove_file(tmp_png);
    };

    let mut pdftocairo = std::process::Command::new("pdftocairo");
    pdftocairo
      .arg("-singlefile")
      .arg("-png")
      .arg("-r")
      .arg(density.to_string());
    // graphicx page is 1-based; pdftocairo also uses 1-based.
    if let Some(p) = page {
      let p1 = p.max(1);
      pdftocairo
        .arg("-f")
        .arg(p1.to_string())
        .arg("-l")
        .arg(p1.to_string());
    } else {
      // Default to first page (matches Perl/`convert` `[0]` behavior).
      pdftocairo.arg("-f").arg("1").arg("-l").arg("1");
    }
    pdftocairo.arg(source).arg(&tmp_prefix);

    let cairo_ok = Self::run_with_timeout(pdftocairo, timeout)
      .map(|status| status.success())
      .unwrap_or(false)
      && tmp_png.exists();
    if !cairo_ok {
      cleanup(&tmp_png);
      return false;
    }

    let _ = std::fs::remove_file(dest);
    let installed = std::fs::rename(&tmp_png, dest)
      .or_else(|_| std::fs::copy(&tmp_png, dest).map(|_| ()))
      .is_ok()
      && dest_path.exists();
    cleanup(&tmp_png);
    installed
  }

  /// Some EPS files make ImageMagick/Ghostscript spend tens of seconds in
  /// direct rasterization. Converting EPS to a cropped PDF first and then
  /// rasterizing the PDF via poppler is much faster for those cases, while
  /// still falling back to ImageMagick if either helper is unavailable.
  fn convert_eps_via_pdf(source: &str, dest: &str, density: u32) -> bool {
    let dest_path = Path::new(dest);
    let parent = dest_path.parent().unwrap_or_else(|| Path::new("."));
    let stem = dest_path
      .file_name()
      .and_then(|s| s.to_str())
      .unwrap_or("image");
    let unique = std::time::SystemTime::now()
      .duration_since(std::time::UNIX_EPOCH)
      .map(|d| d.as_nanos())
      .unwrap_or(0);
    let tmp_pdf = parent.join(format!(".{}.{}.pdf", stem, unique));
    let tmp_prefix = parent.join(format!(".{}.{}.pdftocairo", stem, unique));
    let tmp_png = PathBuf::from(format!("{}.png", tmp_prefix.to_string_lossy()));
    let timeout = std::time::Duration::from_secs(20);

    let cleanup = |tmp_pdf: &Path, tmp_png: &Path| {
      let _ = std::fs::remove_file(tmp_pdf);
      let _ = std::fs::remove_file(tmp_png);
    };

    let mut ps2pdf = std::process::Command::new("ps2pdf");
    ps2pdf.arg("-dEPSCrop").arg(source).arg(&tmp_pdf);
    let ps2pdf_ok = Self::run_with_timeout(ps2pdf, timeout)
      .map(|status| status.success())
      .unwrap_or(false)
      && tmp_pdf.exists();
    if !ps2pdf_ok {
      cleanup(&tmp_pdf, &tmp_png);
      return false;
    }

    let mut pdftocairo = std::process::Command::new("pdftocairo");
    pdftocairo
      .arg("-singlefile")
      .arg("-png")
      .arg("-r")
      .arg(density.to_string())
      .arg(&tmp_pdf)
      .arg(&tmp_prefix);
    let cairo_ok = Self::run_with_timeout(pdftocairo, timeout)
      .map(|status| status.success())
      .unwrap_or(false)
      && tmp_png.exists();
    if !cairo_ok {
      cleanup(&tmp_pdf, &tmp_png);
      return false;
    }

    let _ = std::fs::remove_file(dest);
    let installed = std::fs::rename(&tmp_png, dest)
      .or_else(|_| std::fs::copy(&tmp_png, dest).map(|_| ()))
      .is_ok()
      && dest_path.exists();
    cleanup(&tmp_pdf, &tmp_png);
    installed
  }

  /// Direct Ghostscript rasterization for EPS/PS sources, bypassing
  /// ImageMagick's wrapper.
  ///
  /// `convert` for EPS already shells out to `gs` internally, so by
  /// invoking `gs` ourselves we save the IM read-pipeline overhead
  /// (~50-200 ms per image on the canvas). gs's `Rotate` direction is
  /// CCW — same as graphicx and IM — so this matches the Perl
  /// `image_graphicx_complex` semantics exactly. No /Rotate metadata
  /// is produced (gs writes PNG/JPG directly), so we don't inherit
  /// the rotation-mismatch bug from the disabled ps2pdf path.
  fn convert_eps_via_gs(source: &str, dest: &str, density: u32) -> bool {
    let dest_path = Path::new(dest);
    let parent = dest_path.parent().unwrap_or_else(|| Path::new("."));
    let stem = dest_path
      .file_name()
      .and_then(|s| s.to_str())
      .unwrap_or("image");
    let unique = std::time::SystemTime::now()
      .duration_since(std::time::UNIX_EPOCH)
      .map(|d| d.as_nanos())
      .unwrap_or(0);
    // gs picks its output extension from the device, not the path, so
    // we pass it whatever name and rename atomically at the end.
    let tmp = parent.join(format!(".{}.{}.gs", stem, unique));
    let timeout = std::time::Duration::from_secs(30);
    let dest_lc = dest.to_lowercase();
    // pngalpha matches IM's `ps:alpha` delegate (the default EPS→PNG
    // path). It produces an RGBA PNG where blank canvas is transparent
    // — important for plot backgrounds matching document background.
    // png16m would force a white background regardless of source.
    let device = if dest_lc.ends_with(".jpg") || dest_lc.ends_with(".jpeg") {
      "jpeg"
    } else {
      "pngalpha"
    };

    let mut cmd = std::process::Command::new(gs_program());
    cmd
      .arg("-q")
      .arg("-dNOPAUSE")
      .arg("-dBATCH")
      .arg("-dSAFER")
      // Antialiasing — IM passes these through its delegate by
      // default. Without them gs produces aliased, jagged output
      // that's visibly worse than `convert`. 4 = max quality;
      // 2 = balanced; 1 = off. Matches IM's delegate.xml defaults.
      .arg("-dTextAlphaBits=4")
      .arg("-dGraphicsAlphaBits=4")
      // Render the entire page in memory rather than band-by-band.
      // Eliminates seam artifacts on large pages. Mirrors IM's
      // delegate.xml: -dMaxBitmap=500000000.
      .arg("-dMaxBitmap=500000000")
      .arg("-dAlignToPixels=0")
      .arg("-dGridFitTT=2")
      // -dEPSCrop here means "honor the EPS BoundingBox when rendering"
      // (a gs rendering flag), NOT the ps2pdf flag that injected
      // /Rotate in the earlier disabled path. gs writing PNG never
      // produces PDF metadata, so this is safe.
      .arg("-dEPSCrop");
    // When the EPS declares a `%%BoundingBox`, force the device
    // page-size to match it AND lock it via `-dFIXEDMEDIA`. Some EPS
    // files (notably `pswrite`-output, e.g. AFPL Ghostscript-generated
    // figures like astro-ph0503029/figure7.eps) embed their own
    // `setpagedevice` calls that override `-dEPSCrop` and force a full
    // US-Letter page (612 × 792 pt), so the content lands at the bottom
    // of a 1020 × 1320 px canvas with a 968-pixel blank above it.
    // `-dFIXEDMEDIA` makes gs ignore the embedded `setpagedevice` and
    // honour our explicit dimensions. Witness: astro-ph0503029 fig 7.
    //
    // When the BoundingBox is offset from origin (e.g.
    // `%%BoundingBox: 117 242 524 567` in hep-ph0608319/data6.ps),
    // FIXED page-size alone isn't enough — content drawn at PS
    // (117, 242) lands OUTSIDE a (407, 325) page. Translate via
    // PostScript `-c "<x0_neg> <y0_neg> translate"` BEFORE the EPS
    // file is interpreted, shifting the content to origin (0, 0).
    // PS `-c` snippet executes after the device init but before the
    // file load. Witness: hep-ph0608319/data6.ps (`(atend)` header,
    // real BBox `117 242 524 567`) — without translate the rendered
    // 992 × 1403 letter page has a tiny content blob; with translate
    // we get a tight 407 × 325 pt crop matching what convert produces.
    // Device init flags must precede `-c` / `-f` because gs `-f`
    // takes the NEXT argument as a file to interpret; anything after
    // `-f` is no longer parsed as an option.
    cmd
      .arg(format!("-sDEVICE={}", device))
      .arg(format!("-r{}", density))
      .arg(format!("-sOutputFile={}", tmp.display()));
    let bbox_full = read_postscript_bounding_box_full(source);
    if let Some((x0, y0, w_pt, h_pt)) = bbox_full {
      let w = w_pt.max(1.0).ceil() as u32;
      let h = h_pt.max(1.0).ceil() as u32;
      cmd
        .arg("-dFIXEDMEDIA")
        .arg(format!("-dDEVICEWIDTHPOINTS={}", w))
        .arg(format!("-dDEVICEHEIGHTPOINTS={}", h));
      if x0.abs() > 0.5 || y0.abs() > 0.5 {
        cmd
          .arg("-c")
          .arg(format!("{} {} translate", -x0, -y0))
          .arg("-f");
      }
    }
    cmd.arg(source);
    let gs_ok = Self::run_with_timeout(cmd, timeout)
      .map(|s| s.success())
      .unwrap_or(false)
      && tmp.exists();
    if !gs_ok {
      let _ = std::fs::remove_file(&tmp);
      return false;
    }
    let _ = std::fs::remove_file(dest);
    let installed = std::fs::rename(&tmp, dest)
      .or_else(|_| std::fs::copy(&tmp, dest).map(|_| ()))
      .is_ok()
      && dest_path.exists();
    let _ = std::fs::remove_file(&tmp);
    installed
  }

  /// Convert a graphics file using ImageMagick's `convert` command.
  /// Perl: image_graphicx_complex via Image::Magick / convert CLI.
  /// `page` is 1-based (graphicx convention); converted to 0-based for ImageMagick.
  fn convert_image(source: &str, dest: &str, _dpi: u32, page: Option<u32>) -> bool {
    // Build the source argument with optional page selector
    // Perl: image_read reads "$source[$page]" where $page = ($page // 1) - 1
    let source_arg = if let Some(p) = page {
      format!("{}[{}]", source, p.saturating_sub(1))
    } else {
      // No page specified: use [0] for PDFs to avoid converting all pages
      if source.to_lowercase().ends_with(".pdf") {
        format!("{}[0]", source)
      } else {
        source.to_string()
      }
    };
    // Shell out to convert (matching Perl's approach)
    // -define pdf:use-cropbox=true matches Perl's Image::Magick option (line 466)
    let density = Self::raster_density_for_source(source);
    if Self::should_try_eps_pdf_path(source, page)
      && Self::convert_eps_via_pdf(source, dest, density)
    {
      return true;
    }
    // Fast EPS/PS path: skip the ImageMagick wrapper and call `gs`
    // directly. Same renderer, same CCW Rotate convention; ~50-200 ms
    // saved per image. Falls through to `convert` on any failure.
    // Only attempted when no page selector is present (EPS is
    // single-page; PS multi-page handled by `convert`'s `[N]` syntax).
    //
    // EXCEPT: when the PS file declares `%%Orientation: Landscape` in
    // its header comments — typical of PGPLOT output, e.g.
    // astro-ph0103041 NickMorgan.fig2.ps. Direct gs / convert ignore
    // the Orientation comment and render at literal portrait BBox
    // coordinates, producing visibly upside-down output. ps2pdf
    // honors %%Orientation and writes `/Rotate 90` into the resulting
    // PDF; pdftocairo then honors the PDF rotation and emits
    // correctly-oriented landscape pixels. Route those through the
    // pdf-intermediate path. The earlier disabled `should_try_eps_pdf_path`
    // was about an ORTHOGONAL bug (graphicx angle= compounding with
    // ps2pdf-injected /Rotate on portrait files) — the 1303.5091 EPS
    // files have NO `%%Orientation:` comment, so they go through the
    // gs path as before.
    let src_lc = source.to_lowercase();
    let is_postscript = src_lc.ends_with(".eps")
      || src_lc.ends_with(".epsi")
      || src_lc.ends_with(".epsf")
      || src_lc.ends_with(".ps");
    if is_postscript && page.is_none() {
      if Self::postscript_is_landscape(source) && Self::convert_eps_via_pdf(source, dest, density) {
        return true;
      }
      if Self::convert_eps_via_gs(source, dest, density) {
        return true;
      }
    }
    // For PDF sources, try fast subprocess rasterizers in measured-
    // speed order. Subprocess (not linked) so library license doesn't
    // propagate — same legal pattern as invoking `git` or `ffmpeg`.
    // In-process Rust crates were evaluated 2026-05-12 and rejected
    // (mupdf-rs AGPL, poppler-rs GPL, pdfium-render single-threaded).
    //
    //   1. mutool (MuPDF CLI) — ~1.7× faster than pdftocairo on the canvas slow-tail
    //      (matplotlib/pgfplots scatter PDFs).
    //   2. pdftocairo (poppler) — universally available with TeX Live; 25× faster than convert/gs.
    //   3. convert/gs — last-resort, hard-timeout-bounded.
    if Self::should_try_pdf_cairo_path(source) && dest.to_lowercase().ends_with(".png") {
      if Self::convert_pdf_via_mutool(source, dest, density, page) {
        return true;
      }
      if Self::convert_pdf_via_pdftocairo(source, dest, density, page) {
        return true;
      }
    }
    // Wall-clock timeout to bound `gs`-via-`convert` runaways on
    // pathological PDFs (raster-heavy or with broken xref tables).
    // Matches the vector-SVG path's defensive bound; without this, an
    // arbitrary `convert` invocation could run for minutes and stall
    // the entire post-processing phase. 60 s is enough for any
    // reasonably-sized graphic; tune via `LATEXML_CONVERT_TIMEOUT_SECS`.
    //
    // Crucially: `run_with_timeout` puts convert in its own process
    // group via setsid+pre_exec (Unix), so killing convert on timeout
    // also kills the gs grandchild. Without that, gs orphaned by a
    // dying convert kept running 10+ min and stalled the sandbox.
    let mut cmd = std::process::Command::new(im_convert_program());
    cmd
      .arg("-define")
      .arg("pdf:use-cropbox=true")
      .arg("-density")
      .arg(density.to_string())
      .arg(&source_arg)
      .arg(dest);
    let timeout = std::time::Duration::from_secs(Self::convert_timeout_secs());
    match Self::run_with_timeout(cmd, timeout) {
      Some(status) => {
        // A clean exit is NOT sufficient: ImageMagick `convert` (and the `gs`
        // it drives) exits 0 on some corrupt/unrenderable inputs while writing
        // no file. Require an actual non-empty output so a genuine "no image"
        // failure surfaces (returns false → the caller's imageprocessing
        // Error) instead of being mistaken for success and emitting a
        // broken/empty <img>. The fast PDF/EPS paths already verify their
        // output (mutool/pdftocairo check `dest.exists()`); this brings the
        // final `convert` fallback in line.
        if status.success() && Self::produced_output(dest) {
          true
        } else {
          let _ = std::fs::remove_file(dest); // drop any partial/empty output
          false
        }
      },
      None => {
        Warn!(
          "shell",
          "convert",
          "Graphics: convert/gs for {} exceeded {} s — killed",
          source,
          timeout.as_secs()
        );
        let _ = std::fs::remove_file(dest);
        false
      },
    }
  }

  /// True iff `dest` was actually written as a usable (non-empty) file. Used to
  /// validate a subprocess conversion whose exit code alone is unreliable
  /// (`convert`/`gs` can exit 0 having produced nothing). A 0-byte file counts
  /// as failure — it would render as a broken image.
  fn produced_output(dest: &str) -> bool {
    std::fs::metadata(dest)
      .map(|m| m.len() > 0)
      .unwrap_or(false)
  }

  /// Hard timeout (seconds) for the `convert` subprocess. Mirrors
  /// `svg_convert_timeout_secs`; default 60 s. Override via
  /// `LATEXML_CONVERT_TIMEOUT_SECS` for debugging.
  fn convert_timeout_secs() -> u64 { CONVERT_TIMEOUT_SECS.unwrap_or(60) }
}

/// Byte-substring search. Used by `pdf_has_image_xobject` to scan a
/// PDF prefix for the `/Subtype /Image` marker. Linear in `hay.len()`
/// times `needle.len()`; both bounded so adequate.
fn twoway_contains(hay: &[u8], needle: &[u8]) -> bool {
  if needle.is_empty() || needle.len() > hay.len() {
    return false;
  }
  hay.windows(needle.len()).any(|w| w == needle)
}

/// Map a destination path to a `&'static str` extension suitable for
/// `graphics_cache::RenderKey::ext`. Only common image targets need to
/// round-trip through the cache; anything else collapses to `""` and
/// still keys correctly (the cache file simply lacks an extension).
fn ext_from_path(path: &str) -> &'static str {
  let lower = path.rsplit('/').next().unwrap_or(path);
  if let Some(idx) = lower.rfind('.') {
    let tail = &lower[idx + 1..];
    if tail.eq_ignore_ascii_case("png") {
      "png"
    } else if tail.eq_ignore_ascii_case("svg") {
      "svg"
    } else if tail.eq_ignore_ascii_case("jpg") || tail.eq_ignore_ascii_case("jpeg") {
      "jpg"
    } else if tail.eq_ignore_ascii_case("gif") {
      "gif"
    } else if tail.eq_ignore_ascii_case("webp") {
      "webp"
    } else {
      ""
    }
  } else {
    ""
  }
}

/// Returns the EPS BoundingBox as `(x0, y0, w, h)` where (x0, y0) is
/// the lower-left corner of the content in PS coords and (w, h) is
/// the content extent. Callers needing only the extent can ignore the
/// origin via `_`-destructuring or `.map(|(_, _, w, h)| (w, h))`.
///
/// Handles three DSC variants:
///  1. `%%BoundingBox: x0 y0 x1 y1` in the header (most files).
///  2. `%%BoundingBox: (atend)` in the header, real values in the Trailer at end-of-file (some
///     HIGZ, PAW, certain pswrite output).
///  3. `%%HiResBoundingBox: x0.x y0.y x1.x y1.y` — used when literal `%%BoundingBox:` is missing.
fn read_postscript_bounding_box_full(source: &str) -> Option<(f64, f64, f64, f64)> {
  let content = std::fs::read_to_string(source).ok()?;
  let mut header_lines = content.lines().take(80);
  let mut atend = false;
  let mut hi_res: Option<(f64, f64, f64, f64)> = None;
  for line in &mut header_lines {
    if let Some(rest) = line.strip_prefix("%%BoundingBox:") {
      let rest_trim = rest.trim();
      if rest_trim.eq_ignore_ascii_case("(atend)") {
        atend = true;
        continue;
      }
      if let Some(b) = parse_bbox_quadruple(rest) {
        return Some(b);
      }
    } else if let Some(rest) = line.strip_prefix("%%HiResBoundingBox:") {
      hi_res = hi_res.or_else(|| parse_bbox_quadruple(rest));
    }
  }
  if atend {
    // Scan the last ~80 lines for a Trailer-section BoundingBox.
    let tail: Vec<&str> = content.lines().rev().take(80).collect();
    for line in tail {
      if let Some(rest) = line.strip_prefix("%%BoundingBox:") {
        let rest_trim = rest.trim();
        if rest_trim.eq_ignore_ascii_case("(atend)") {
          continue;
        }
        if let Some(b) = parse_bbox_quadruple(rest) {
          return Some(b);
        }
      }
    }
  }
  hi_res
}

fn parse_bbox_quadruple(s: &str) -> Option<(f64, f64, f64, f64)> {
  let mut vals = s.split_whitespace().filter_map(|s| s.parse::<f64>().ok());
  let (Some(x0), Some(y0), Some(x1), Some(y1)) =
    (vals.next(), vals.next(), vals.next(), vals.next())
  else {
    return None;
  };
  let w = (x1 - x0).abs();
  let h = (y1 - y0).abs();
  Some((x0, y0, w, h))
}

/// Legacy width/height-only accessor for callers that don't need the
/// origin offset. Use `read_postscript_bounding_box_full` when you
/// need to translate the content to PS origin (0, 0).
fn read_postscript_bounding_box(source: &str) -> Option<(f64, f64)> {
  read_postscript_bounding_box_full(source).map(|(_, _, w, h)| (w, h))
}

impl Processor for Graphics {
  fn get_name(&self) -> &str { &self.name }

  fn to_process(&self, doc: &PostDocument) -> Vec<Node> {
    doc.findnodes("//ltx:graphics[not(@imagesrc)]")
  }

  fn process(&mut self, doc: PostDocument, nodes: Vec<Node>) -> ProcessResult {
    let mut search_paths = self.find_graphics_paths(&doc);
    search_paths.extend(doc.get_search_paths().iter().cloned());
    // Also add source directory
    let source_dir = doc.get_source_directory().to_string();
    if !source_dir.is_empty() && !search_paths.contains(&source_dir) {
      search_paths.push(source_dir.clone());
    }
    // Add current directory as fallback
    if !search_paths.contains(&".".to_string()) {
      search_paths.push(".".to_string());
    }

    let dest_dir = doc.get_destination_directory().unwrap_or(".").to_string();
    // Read DPI/magnify/zoomout from processing instructions (set by latexml.sty)
    let dpi = self
      .get_parameter(&doc, "DPI")
      .map(|v| v as u32)
      .or(self.dpi)
      .unwrap_or(100);
    let magnify = self.get_parameter(&doc, "magnify").unwrap_or(self.magnify);
    let _zoomout = self.get_parameter(&doc, "zoomout").unwrap_or(self.zoomout);
    // Perl: effective DPI = DPI * magnify / zoomout (used for scale-to transforms)
    let effective_dpi = ((dpi as f64) * magnify / _zoomout) as u32;
    let n_to_process = nodes.len();
    latexml_core::telemetry::set_graphics_assets(n_to_process as u32);

    // Counter for generating unique resource names (like Perl's generateResourcePathname)
    let mut resource_counter: u32 = 0;

    // Two-phase plan so the slow per-image `convert` subprocess and
    // `read_image_dimensions` calls can run in parallel without touching
    // the libxml DOM off-thread.
    //
    // Phase 1 (serial): read each node's attributes, resolve source path,
    // decide the conversion kind, and allocate resource-name counters.
    //   - `Plan::NotFound` — apply fallback on the main thread later
    //   - `Plan::Copy { .. }` — apply on the main thread later (cheap)
    //   - `Plan::Convert { .. }` — independent; run in parallel.
    // Phase 2 (parallel): run convert_image + read_image_dimensions for
    // `Plan::Convert` entries. Produces `JobResult`s keyed by node index.
    // Phase 3 (serial): apply DOM mutations on the main thread in original
    // node order so attribute writes happen on the libxml-owning thread.
    enum Plan {
      NotFound {
        idx:     usize,
        graphic: String,
      },
      Copy {
        idx:     usize,
        source:  String,
        options: String,
      },
      Convert {
        idx:     usize,
        options: String,
        job_id:  usize,
      },
    }
    struct ConvertJob {
      job_id:       usize,
      source:       String,
      page:         Option<u32>,
      rel_dest:     String,
      abs_dest_str: String,
      /// `Some((rel_svg, abs_svg_str))` when the worker should
      /// first attempt the vector-SVG path and only fall back
      /// to the raster `convert` path on failure. `None` means
      /// the classic raster-only path.
      svg_paths:    Option<(String, String)>,
    }
    struct ConvertOutcome {
      job_id:   usize,
      /// Path to write into `imagesrc`; `None` if both convert and copy-fallback failed.
      imagesrc: Option<String>,
      /// Raw (pre-transform) dimensions read from whichever file we ended up with.
      raw_dims: Option<(u32, u32)>,
    }

    let mut plans: Vec<Plan> = Vec::with_capacity(n_to_process);
    let mut convert_jobs: Vec<ConvertJob> = Vec::new();
    // Dedup key uses content-hash when readable, else falls back to
    // (source-path, page, options). Two byte-identical files with the
    // same options share one conversion + one output bundle entry.
    // The first-seen source's stem names the dest. Both <img> tags
    // end up pointing to that same rel_dest.
    #[derive(Hash, Eq, PartialEq)]
    enum JobKey {
      Hashed(u64, Option<u32>, String),
      Pathy(String, Option<u32>, String),
    }
    let mut convert_job_ids: HashMap<JobKey, usize> = HashMap::default();
    // Plan::Copy uses the same (hash, options) dedup so byte-identical
    // raster sources point at one output. `options` is part of the key
    // because angle= mutates the dest in-place — different rotations of
    // the same source need different dest files.
    #[derive(Hash, Eq, PartialEq)]
    enum CopyKey {
      Hashed(u64, String),
      Pathy(String, String),
    }
    let mut copy_dedup: HashMap<CopyKey, String> = HashMap::default();
    let mut convert_source_counts: HashMap<String, u32> = HashMap::default();
    // Maps a stem-based destination file (`stem.ext`) to the source that claimed
    // it, so two different sources sharing a basename don't collide (#6922).
    let mut used_dests: HashMap<String, String> = HashMap::default();
    for (idx, node) in nodes.iter().enumerate() {
      let options = node.get_attribute("options").unwrap_or_default();
      let page = Self::parse_page_option(&options);
      let Some(source) = self.find_graphic_file(&doc, node, &search_paths) else {
        let graphic = node
          .get_attribute("graphic")
          .unwrap_or_else(|| "none".to_string());
        plans.push(Plan::NotFound { idx, graphic });
        continue;
      };
      let src_ext = Path::new(&source)
        .extension()
        .and_then(|e| e.to_str())
        .unwrap_or("")
        .to_lowercase();
      let props = self.type_properties.get(&src_ext).cloned();
      // Robustness guard (surpass-Perl; user directive 2026-06-22). A source
      // type with no explicit `destination_type` defaults to a WEB-NATIVE
      // target: keep web-native sources (svg/png/gif/jpg/jpeg) as-is, but
      // rasterize anything else to `png`. This guarantees a non-web-native
      // source is ALWAYS routed through Plan::Convert and never Plan::Copy'd
      // verbatim — closing the hole for the unmapped `.postscript` graphics
      // type (and any future addition) where a raw .ps/.eps/.pdf/.ai could
      // otherwise reach the web. Perl defaults dest_type to srctype here
      // (Graphics.pm:244, `$type = $properties{destination_type} || $srctype`),
      // which would copy such a source raw; we deliberately diverge so the web
      // output is never a raw .eps/.ps/.pdf the browser can't render.
      const WEB_NATIVE: &[&str] = &["svg", "png", "gif", "jpg", "jpeg"];
      let dest_type = props
        .as_ref()
        .and_then(|p| p.destination_type.as_ref())
        .cloned()
        .unwrap_or_else(|| {
          if WEB_NATIVE.contains(&src_ext.as_str()) {
            src_ext.clone()
          } else {
            "png".to_string()
          }
        });
      let needs_conversion = dest_type != src_ext;
      let has_page = page.is_some();
      if needs_conversion || has_page {
        let content_hash = Self::hash_file_content(&source);
        let job_key = match content_hash {
          Some(h) => JobKey::Hashed(h, page, options.clone()),
          None => JobKey::Pathy(source.clone(), page, options.clone()),
        };
        let job_id = if let Some(&job_id) = convert_job_ids.get(&job_key) {
          job_id
        } else {
          let prior_source_jobs = convert_source_counts.get(&source).copied().unwrap_or(0);
          let dest_name = Self::assign_dest_name(
            &source,
            &dest_type,
            has_page,
            prior_source_jobs,
            &mut used_dests,
            &mut resource_counter,
          );
          convert_source_counts.insert(source.clone(), prior_source_jobs + 1);
          // Vector-SVG path: opt-in for small PDFs only. We prepare an
          // alternate `.svg` destination path alongside the normal raster
          // destination so the worker can try the vector-SVG path first, then fall
          // back. The file-size heuristic gates this — see
          // `should_try_svg_path`.
          let try_svg = Self::should_try_svg_path(&source, self.svg_threshold_kb);
          let rel_dest = format!("{}.{}", dest_name, dest_type);
          let abs_dest = PathBuf::from(&dest_dir).join(&rel_dest);
          if let Some(parent) = abs_dest.parent() {
            std::fs::create_dir_all(parent).ok();
          }
          let abs_dest_str = abs_dest.to_string_lossy().to_string();
          let svg_paths = if try_svg {
            let rel_svg = format!("{}.svg", dest_name);
            let abs_svg = PathBuf::from(&dest_dir).join(&rel_svg);
            let abs_svg_str = abs_svg.to_string_lossy().to_string();
            Some((rel_svg, abs_svg_str))
          } else {
            None
          };
          let job_id = convert_jobs.len();
          convert_jobs.push(ConvertJob {
            job_id,
            source: source.clone(),
            page,
            rel_dest,
            abs_dest_str,
            svg_paths,
          });
          convert_job_ids.insert(job_key, job_id);
          job_id
        };
        plans.push(Plan::Convert { idx, options, job_id });
      } else {
        plans.push(Plan::Copy { idx, source, options });
      }
    }

    // Phase 2: parallel conversions. Bounded worker count to avoid
    // oversubscribing when many images are in flight. `convert` itself
    // is single-threaded per invocation, so the ceiling is useful CPU
    // parallelism — capped at a reasonable limit to avoid fork/memory
    // storms with many-image papers.
    let convert_count = convert_jobs.len();
    // Worker cap controls fork-fan-out of mutool / pdftocairo / convert.
    // Each spawn pulls libgs + libpoppler + libpng into a fresh
    // address space (~30 ms ambient), so on graphics-heavy papers
    // (e.g. LHCb 2402.01336 with 17 unique PDFs) sub-batches at
    // cap = 8 added wasted batch boundaries on a 28-CPU host. 22 is
    // a measured sweet spot on 28-core machines under the canvas
    // sweep workload: high enough to one-shot the typical tail-
    // paper graphics fan, low enough to leave headroom for the
    // outer cortex_worker pool (12-16 workers) without the kernel
    // scheduler thrashing — 12 × 32 ≈ 384 inflight subprocs trips
    // the internal 60 s watchdog and produces the "sweep flake"
    // pattern in stages 2/4/5. 12 × 22 ≈ 264 stays under the
    // measured starvation threshold. The 1910.01256 mini-bench
    // (5 PDFs) is unaffected because it is already <= cap.
    let worker_cap = std::thread::available_parallelism()
      .map(|n| n.get())
      .unwrap_or(4)
      .clamp(1, 22);
    let n_workers = convert_count.min(worker_cap).max(1);
    let mut outcomes: Vec<ConvertOutcome> = Vec::with_capacity(convert_count);
    if convert_count > 0 {
      use std::sync::atomic::{AtomicU32, AtomicUsize, Ordering};
      let next = AtomicUsize::new(0);
      // Subprocess tally: telemetry's thread_local! STATE is per-thread,
      // and worker threads exit before `phase_us[graphics]` aggregation,
      // so worker increments would be lost. Accumulate in a shared
      // AtomicU32 here and merge into telemetry once the scope joins.
      // One increment per `Self::convert_image_svg` / `Self::convert_image`
      // call (the EPS-via-PDF internal pair counts as one).
      let subproc_count = AtomicU32::new(0);
      let subproc_ref = &subproc_count;
      // Copy out of `self` before the scope: the worker closures must not
      // borrow `self` (it is `&mut` here), and `CachePolicy` is `Copy`.
      let cache_policy = self.cache_policy;
      // Unique conversion jobs only. Repeated nodes with the same
      // source/page/options share one subprocess result, while distinct
      // options keep separate outputs.
      let jobs: Vec<&ConvertJob> = convert_jobs.iter().collect();
      // Each worker accumulates into a thread-local Vec returned from
      // its closure; the main thread merges them after scope join. No
      // shared mutable state during the parallel phase — replaces the
      // previous `Mutex<Vec<…>>` per project policy (thread_local-only
      // for in-memory state, no `Mutex`).
      // R35.C: spawn workers with a small (2 MB) stack via
      // `spawn_scoped`, which returns Result; if a spawn fails with
      // EAGAIN/WouldBlock (canvas + 6 GB ulimit can run out of address
      // space on graphics-heavy papers — witness hep-ph0012156, 12778
      // formulas, R35.C), drop the failure and let the surviving
      // workers pick up the remaining jobs via the shared `next`
      // counter. If every spawn fails, run all jobs on the current
      // thread instead of crashing.
      type WorkerResult = (
        Vec<ConvertOutcome>,
        latexml_core::util::logger::CapturedDiagnostics,
      );
      let worker_outcomes: Vec<WorkerResult> = std::thread::scope(|s| {
        let handles: Vec<_> = (0..n_workers)
          .filter_map(|_| {
            std::thread::Builder::new()
              .stack_size(2 * 1024 * 1024)
              .spawn_scoped(s, || {
                // Capture this worker's diagnostics and hand them back on join.
                // LOG_BUFFER + REPORT are #[thread_local], so an Error!/Warn! a
                // conversion raises on this worker would otherwise be lost from
                // cortex.log AND from status_code. The main thread replays them
                // (text + count deltas) in worker order after the scope joins.
                latexml_core::util::logger::capture(|| {
                  let mut local = Vec::<ConvertOutcome>::new();
                  loop {
                    let i = next.fetch_add(1, Ordering::Relaxed);
                    if i >= jobs.len() {
                      break;
                    }
                    let ConvertJob {
                      job_id,
                      source,
                      page,
                      rel_dest,
                      abs_dest_str,
                      svg_paths,
                    } = jobs[i];
                    // Fresh converter-diagnostic slate for this node, so the
                    // failed_to_convert Error (if it fires) reports THIS asset's
                    // converter error, not a previous job's.
                    take_converter_diag();
                    // Try vector-SVG path first if requested for this source.
                    // The cache layer (graphics_cache) hardlinks/copies a
                    // matching cached output before any subprocess fires and
                    // round-trips the dimensions through a .dims sidecar so
                    // hits skip the `read_*_dimensions` re-measure too.
                    // Misses fall through to the real conversion + measure
                    // and write back on success. Disable via
                    // LATEXML_GRAPHICS_CACHE_OFF=1.
                    let svg_outcome = if let Some((rel_svg, abs_svg)) = svg_paths {
                      let svg_key = crate::graphics_cache::RenderKey {
                        page:    *page,
                        density: 0,
                        ext:     "svg",
                      };
                      let svg_res = crate::graphics_cache::with_cache_dims(
                        cache_policy,
                        source,
                        abs_svg,
                        svg_key,
                        || {
                          subproc_ref.fetch_add(1, Ordering::Relaxed);
                          Self::convert_image_svg(source, abs_svg, *page)
                        },
                        || {
                          Self::read_svg_dimensions(abs_svg).map(|(w, h)| {
                            crate::graphics_cache::CachedDims { width: w, height: h }
                          })
                        },
                      );
                      match svg_res {
                        crate::graphics_cache::ConvertResult::Ok { dims } => Some(ConvertOutcome {
                          job_id:   *job_id,
                          imagesrc: Some(rel_svg.clone()),
                          raw_dims: dims.map(|d| (d.width, d.height)),
                        }),
                        crate::graphics_cache::ConvertResult::Failed => {
                          Warn!(
                            "shell",
                            "svg",
                            "Graphics: vector-SVG path failed for {}, falling back to raster",
                            source
                          );
                          None
                        },
                      }
                    } else {
                      None
                    };
                    let raster_res = if svg_outcome.is_none() {
                      let raster_key = crate::graphics_cache::RenderKey {
                        page:    *page,
                        density: Self::raster_density_for_source(source),
                        ext:     ext_from_path(abs_dest_str),
                      };
                      crate::graphics_cache::with_cache_dims(
                        cache_policy,
                        source,
                        abs_dest_str,
                        raster_key,
                        || {
                          subproc_ref.fetch_add(1, Ordering::Relaxed);
                          Self::convert_image(source, abs_dest_str, dpi, *page)
                        },
                        || {
                          Self::read_image_dimensions(abs_dest_str).map(|(w, h)| {
                            crate::graphics_cache::CachedDims { width: w, height: h }
                          })
                        },
                      )
                    } else {
                      crate::graphics_cache::ConvertResult::Failed
                    };
                    let outcome = if let Some(o) = svg_outcome {
                      o
                    } else if raster_res.is_ok() {
                      ConvertOutcome {
                        job_id:   *job_id,
                        imagesrc: Some(rel_dest.clone()),
                        raw_dims: raster_res.dims().map(|d| (d.width, d.height)),
                      }
                    } else {
                      // Final-failure: every conversion path exhausted. Mirror
                      // Perl Graphics.pm L324-329 (Error + `return` with NO
                      // imagesrc) — do NOT fall back to copying the raw source.
                      // A raw .eps/.ps/.pdf is never usable on the web; copying it
                      // would emit a broken `<img src="fig.eps">`. Leaving
                      // @imagesrc unset makes the HTML5 XSLT
                      // (LaTeXML-misc-xhtml.xsl L154) render the node as
                      // `class="ltx_missing ltx_missing_image"` (empty src) — the
                      // correct "couldn't render" signal. (User directive
                      // 2026-06-22; raw .eps/.pdf are never web-native.)
                      // Error class/object mirror Perl Graphics.pm:274 so the
                      // harness aggregates with engine/package emissions.
                      // Object is the failure TYPE (not the filename) so the
                      // harness can aggregate by failure mode. The message marks
                      // the SOURCE asset (the input that failed) as the subject —
                      // NOT the target — so the log clearly identifies which
                      // input could not be rendered; the intended target is
                      // secondary context.
                      // Surface the last converter's stderr / spawn error so an
                      // environment failure (gs not installed, AppArmor denial,
                      // ImageMagick policy block) is self-diagnosing in the log.
                      let why = take_converter_diag()
                        .unwrap_or_else(|| "no converter diagnostic captured".to_string());
                      Error!(
                        "imageprocessing",
                        "failed_to_convert",
                        "Graphics: failed to convert source asset {} — every converter \
                         failed, no usable image produced (intended target {}); last \
                         converter error: {}",
                        source,
                        abs_dest_str,
                        why
                      );
                      ConvertOutcome {
                        job_id:   *job_id,
                        imagesrc: None,
                        raw_dims: None,
                      }
                    };
                    local.push(outcome);
                  }
                  local
                })
              })
              .ok()
          })
          .collect();
        // Note: if EVERY spawn failed (extreme memory pressure), no
        // jobs run and graphics will be missing from the output. That
        // is much less destructive than panicking the whole worker
        // and losing the entire conversion. Surviving workers always
        // race for the same `next` counter, so a single survivor is
        // enough to complete all jobs.
        //
        // The same degradation policy applies to a worker that PANICS
        // mid-run (observed under fleet memory pressure: 15 papers in
        // the 2026-07 full-arXiv run, where join().unwrap() escalated
        // a thread panic into a whole-conversion Fatal). Surface the
        // payload as a conversion Error and keep the survivors'
        // outcomes — a casualty's unfinished job stays unconverted
        // (the outcomes_by_job lookups below tolerate missing ids).
        handles
          .into_iter()
          .filter_map(|h| match h.join() {
            Ok(res) => Some(res),
            Err(payload) => {
              let msg = payload
                .downcast_ref::<&'static str>()
                .map(|s| (*s).to_string())
                .or_else(|| payload.downcast_ref::<String>().cloned())
                .unwrap_or_else(|| "opaque panic payload".to_string());
              Error!(
                "imageprocessing",
                "worker_panicked",
                "Graphics: a conversion worker thread panicked ({}); its \
                 unfinished jobs are skipped and their graphics left \
                 unconverted",
                msg
              );
              None
            },
          })
          .collect()
      });
      // Merge each worker's outcomes AND replay its captured diagnostics on the
      // main thread (in worker order), so any conversion Error!/Warn! reaches the
      // bound cortex.log and registers in the main REPORT / status_code.
      for (v, diags) in worker_outcomes {
        outcomes.extend(v);
        latexml_core::util::logger::replay_captured(diags);
      }
      outcomes.sort_by_key(|o| o.job_id);
      latexml_core::telemetry::add_graphics_subprocess(subproc_count.load(Ordering::Relaxed));
    }
    let outcomes_by_job: HashMap<usize, ConvertOutcome> =
      outcomes.into_iter().map(|o| (o.job_id, o)).collect();

    // Phase 3: serial DOM mutations. Preserves original node order.
    let apply_transforms =
      |options: &str, raw_dims: Option<(u32, u32)>| -> (Option<u32>, Option<u32>) {
        match raw_dims {
          Some((w, h)) if !options.is_empty() => {
            let (tw, th) = Self::apply_graphicx_transforms(w, h, options, effective_dpi);
            (Some(tw), Some(th))
          },
          Some((w, h)) => (Some(w), Some(h)),
          None => (None, None),
        }
      };
    for plan in &plans {
      match plan {
        Plan::NotFound { idx: _, graphic } => {
          // Perl `Post/Graphics.pm:216-219`: Warn + `return` WITHOUT setting
          // @imagesrc. An earlier Rust-only promotion to Error (2026-05-08)
          // was reverted once the missing `doc.get_search_paths()` half of
          // `find_graphics_paths` was fixed; with sources findable this branch
          // hits only when the .tex references a genuinely non-existent file.
          // We must NOT then set `imagesrc` to the raw `graphic` path: that
          // emits a broken `<img src="missing.eps">` (and leaks a raw
          // .eps/.pdf to the web). Leaving @imagesrc unset makes the HTML5
          // XSLT (LaTeXML-misc-xhtml.xsl L154) render the node as
          // `class="ltx_missing ltx_missing_image"` (empty src) — the correct
          // "couldn't render" signal, matching Perl (user directive
          // 2026-06-22; raw .eps/.pdf are never web-native).
          Warn!(
            "expected",
            "source",
            "No graphic source found; skipping (source was '{}')",
            graphic
          );
        },
        Plan::Copy { idx, source, options } => {
          let mut node_mut = nodes[*idx].clone();
          // Content-hash dedup: if a byte-identical source with the
          // same options was already copied (and rotated), point this
          // node at the same rel. Avoids both duplicate I/O and a
          // duplicate output file in the bundle. Fall back to source-
          // path keying when the file can't be hashed.
          let hash_opt = Self::hash_file_content(source);
          let key = match hash_opt {
            Some(h) => CopyKey::Hashed(h, options.clone()),
            None => CopyKey::Pathy(source.clone(), options.clone()),
          };
          let rel = if let Some(existing) = copy_dedup.get(&key) {
            existing.clone()
          } else {
            let rel_opt = Self::copy_to_destination(source, &source_dir, &dest_dir);
            // If the copy itself failed, still emit a RELATIVE URL (abs2rel),
            // never the raw absolute source path (issue #698 class).
            let rel = rel_opt
              .unwrap_or_else(|| latexml_core::util::pathname::relative(source, &source_dir));
            // Plan::Copy fires for web-native sources (PNG / JPG / GIF
            // / SVG) where `dest_type == src_ext`. graphicx `angle=`
            // rotation IS meaningful here — the source carries no PDF
            // /Rotate metadata to pre-rotate from. Apply via convert.
            // Perl semantics (Util/Image.pm:image_graphicx_complex
            // L390-394): IM `Rotate` with `degrees => -$a1` — graphicx
            // angle is CCW; convert -rotate is CW; negate to match.
            //
            // ... but ONLY for a raster source. Perl `Post/Graphics.pm`
            // L264-271 refuses every non-scaling transform on a type
            // whose `raster` property is false, warns `limitation`, and
            // trivializes the transform so plain scaling still applies.
            // Rotating an SVG here would hand `convert` a vector source
            // and a `.svg` destination: IM rasterizes through its SVG
            // delegate and writes that raster back out under the .svg
            // name, so the bundle ends up with a file that is no longer
            // the drawing it claims to be. The scaling half is unaffected
            // — `apply_transforms` below still runs.
            let angle = Self::parse_angle_option(options).unwrap_or(0.0);
            let is_raster = self
              .type_properties
              .get(ext_from_path(source))
              .and_then(|p| p.raster)
              .unwrap_or(true);
            if angle.abs() > 0.5 && !is_raster {
              Warn!(
                "limitation",
                "graphics",
                "Cannot (yet) apply complex transforms to non-raster images: dropping angle={} \
                 for {}",
                angle,
                source
              );
            } else if angle.abs() > 0.5 {
              let dest_full = PathBuf::from(&dest_dir).join(&rel);
              Self::rotate_image_inplace(&dest_full.to_string_lossy(), -angle);
            }
            copy_dedup.insert(key, rel.clone());
            rel
          };
          let raw_dims = Self::read_source_dimensions(source);
          if raw_dims.is_none() {
            // Perl Graphics.pm L310-312 (triv_scaling, image module present
            // but size unusable): warn rather than silently omitting.
            Warn!(
              "expected",
              "image",
              "Couldn't get usable image size for {}",
              source
            );
          }
          let (w, h) = apply_transforms(options, raw_dims);
          Self::set_graphic_src(&mut node_mut, &rel, w, h);
        },
        Plan::Convert { idx, options, job_id } => {
          if let Some(out) = outcomes_by_job.get(job_id) {
            let mut node_mut = nodes[*idx].clone();
            if let Some(imagesrc) = &out.imagesrc {
              // Plan::Convert handles non-raster sources (EPS, PS, PDF,
              // AI). With ps2pdf's /Rotate-injection path disabled (see
              // should_try_eps_pdf_path), all of these now go through
              // ImageMagick `convert` (or pdftocairo for plain .pdf),
              // neither of which pre-applies graphicx rotation. So
              // apply the graphicx angle uniformly here.
              //
              // Perl semantics (Util/Image.pm:image_graphicx_complex
              // L390-394): `image_internalop('Rotate', degrees => -$a1)`.
              // ImageMagick Rotate is CCW (matches graphicx); from CLI
              // it's CW → pass -angle to match Perl's intent.
              let angle = Self::parse_angle_option(options).unwrap_or(0.0);
              if angle.abs() > 0.5 {
                let dest_full = PathBuf::from(&dest_dir).join(imagesrc);
                Self::rotate_image_inplace(&dest_full.to_string_lossy(), -angle);
              }
              let (w, h) = apply_transforms(options, out.raw_dims);
              Self::set_graphic_src(&mut node_mut, imagesrc, w, h);
            }
          }
        },
      }
    }

    Info!(
      "graphics",
      "process",
      "Graphics {} {} to process",
      doc.get_destination().unwrap_or("?"),
      n_to_process
    );
    Ok(vec![doc])
  }
}

#[cfg(test)]
mod tests {
  use super::*;
  // `EnvGuard` (env mutation, serialised + restored) and `TempDir` (unique
  // name, removed on drop including on panic) are shared with
  // `graphics_cache::tests`; see that module for the rationale. `EnvGuard` is
  // only referenced by the `#[cfg(unix)]` density test below, so gate its
  // import the same way or it reads as unused on Windows (`-D warnings`).
  #[cfg(unix)]
  use crate::test_env::EnvGuard;
  use crate::test_env::TempDir;

  /// #6922: two DIFFERENT sources that share a basename must map to DISTINCT
  /// converted-output files. Before the fix, the first job of each source used
  /// its `file_stem()`, so `figs/a/plot.pdf` and `figs/b/plot.pdf` both became
  /// `plot.png` and the first write won — one figure silently replaced by the
  /// other (arXiv 2606.30620, Figures 2/4/5). The colliding second source now
  /// falls back to a unique `xN`.
  #[test]
  fn convert_dest_names_avoid_basename_collision() {
    let mut used: HashMap<String, String> = HashMap::default();
    let mut ctr: u32 = 0;
    let a = Graphics::assign_dest_name("figs/a/plot.pdf", "png", false, 0, &mut used, &mut ctr);
    let b = Graphics::assign_dest_name("figs/b/plot.pdf", "png", false, 0, &mut used, &mut ctr);
    assert_eq!(a, "plot", "first source keeps the readable stem");
    assert_ne!(
      a, b,
      "distinct sources sharing basename 'plot' must not collide"
    );
    assert!(
      b.starts_with('x'),
      "colliding source falls back to a unique xN, got {b}"
    );

    // A distinct stem is unaffected — keeps its readable name.
    let c = Graphics::assign_dest_name("figs/c/other.pdf", "png", false, 0, &mut used, &mut ctr);
    assert_eq!(c, "other");

    // Same stem but a DIFFERENT output extension is a different file, not a collision.
    let d = Graphics::assign_dest_name("figs/d/plot.eps", "svg", false, 0, &mut used, &mut ctr);
    assert_eq!(d, "plot", "plot.svg does not collide with plot.png");

    // A second job of the SAME source (e.g. `page=`) is still unique.
    let e = Graphics::assign_dest_name("figs/a/plot.pdf", "png", true, 1, &mut used, &mut ctr);
    assert!(
      e.starts_with('x'),
      "a second job of one source stays unique, got {e}"
    );

    // The SAME source is never treated as a self-collision (the `owner != source`
    // guard). In the real caller a repeat reference is deduped upstream by content
    // hash, and any genuine second job carries `prior_source_jobs > 0`; this pins
    // the guard's own contract directly.
    let mut used2: HashMap<String, String> = HashMap::default();
    let mut ctr2: u32 = 0;
    let f1 = Graphics::assign_dest_name("figs/a/plot.pdf", "png", false, 0, &mut used2, &mut ctr2);
    let f2 = Graphics::assign_dest_name("figs/a/plot.pdf", "png", false, 0, &mut used2, &mut ctr2);
    assert_eq!(f1, "plot");
    assert_eq!(f2, "plot", "the same source is not a self-collision");

    // Three distinct sources sharing a stem → three distinct outputs.
    let mut u3: HashMap<String, String> = HashMap::default();
    let mut c3: u32 = 0;
    let g: Vec<String> = ["m1/chi2.pdf", "m3/chi2.pdf", "jk/chi2.pdf"]
      .iter()
      .map(|s| Graphics::assign_dest_name(s, "png", false, 0, &mut u3, &mut c3))
      .collect();
    assert_eq!(g[0], "chi2");
    assert_eq!(
      g.iter().collect::<std::collections::HashSet<_>>().len(),
      3,
      "3 same-stem sources must yield 3 distinct dest names, got {g:?}"
    );
  }

  /// #6922 finding (reviewer): the `xN` fallback must not clobber a real source
  /// literally named `xN`. The tricky ordering is when the GENERATED `x1` is
  /// claimed FIRST (by a basename collision) and a real `figs/a/x1.pdf` arrives
  /// LAST — its stem `x1` is already taken, so it too must fall through to a
  /// fresh name rather than overwrite the generated `x1.png`.
  #[test]
  fn generated_xn_survives_a_later_literal_xn_source() {
    let mut used: HashMap<String, String> = HashMap::default();
    let mut ctr: u32 = 0;
    let base = Graphics::assign_dest_name("figs/b/plot.pdf", "png", false, 0, &mut used, &mut ctr);
    let coll = Graphics::assign_dest_name("figs/c/plot.pdf", "png", false, 0, &mut used, &mut ctr);
    let lit = Graphics::assign_dest_name("figs/a/x1.pdf", "png", false, 0, &mut used, &mut ctr);
    assert_eq!(base, "plot");
    assert_eq!(coll, "x1", "the colliding source takes the generated x1");
    assert_ne!(
      lit, coll,
      "a real source named x1 must not reuse the generated x1.png"
    );
    assert_eq!(lit, "x2", "the literal-x1 source falls through to x2");
  }

  // ---- cross-platform child-process fixtures for run_with_timeout ----
  // Unix `true`/`sh`/`sleep` don't exist on Windows; use cmd/ping there so the
  // kill / exit-status / stderr-capture logic gets real coverage on both.

  /// A child that runs far longer than any test deadline (so the timeout kills
  /// it). `ping` is a bare exe — no shell wrapper — so `kill()` reaps it with no
  /// orphaned grandchild.
  fn spawn_slow_child() -> std::process::Command {
    let mut cmd;
    if cfg!(windows) {
      cmd = std::process::Command::new("ping");
      cmd.args(["-n", "11", "127.0.0.1"]);
    } else {
      cmd = std::process::Command::new("sleep");
      cmd.arg("10");
    }
    cmd
  }

  /// A child that exits 0 immediately (Unix `true` / Windows `cmd /C exit 0`).
  fn spawn_fast_ok() -> std::process::Command {
    let mut cmd = std::process::Command::new(if cfg!(windows) { "cmd" } else { "true" });
    if cfg!(windows) {
      cmd.args(["/C", "exit 0"]);
    }
    cmd
  }

  /// A child that writes to stderr and exits non-zero. Returns the command and
  /// its program name (for the diagnostic assertion).
  fn spawn_stderr_fail() -> (std::process::Command, &'static str) {
    if cfg!(windows) {
      let mut cmd = std::process::Command::new("cmd");
      cmd.args(["/C", "echo boom on stderr 1>&2 & exit 3"]);
      (cmd, "cmd")
    } else {
      let mut cmd = std::process::Command::new("sh");
      cmd.arg("-c").arg("echo 'boom on stderr' >&2; exit 3");
      (cmd, "sh")
    }
  }

  /// `run_with_timeout` kills the child and returns `None` when the
  /// process exceeds the deadline. The slow child stands in for any
  /// runaway subprocess (convert, gs, mutool, …).
  #[test]
  fn run_with_timeout_kills_slow_child() {
    let start = std::time::Instant::now();
    let cmd = spawn_slow_child();
    let result = Graphics::run_with_timeout(cmd, std::time::Duration::from_millis(200));
    let elapsed = start.elapsed();
    assert!(
      result.is_none(),
      "run_with_timeout should return None on kill"
    );
    // We expect around 200 ms (+ ≤ 50 ms poll interval + SIGKILL reap
    // overhead). Give it 2 s of slack for CI noise.
    assert!(
      elapsed < std::time::Duration::from_secs(2),
      "killed run should return quickly, took {:?}",
      elapsed
    );
  }

  /// Fast-completing child returns its real exit status, not a kill.
  #[test]
  fn run_with_timeout_returns_status_for_fast_child() {
    let cmd = spawn_fast_ok();
    let result = Graphics::run_with_timeout(cmd, std::time::Duration::from_secs(5));
    let status = result.expect("expected clean exit");
    assert!(status.success(), "a fast child should exit successfully");
  }

  /// Missing binary → `None`, not a panic.
  #[test]
  fn run_with_timeout_handles_spawn_failure() {
    let cmd = std::process::Command::new("/this/binary/does/not/exist/12345");
    let result = Graphics::run_with_timeout(cmd, std::time::Duration::from_secs(1));
    assert!(result.is_none());
  }

  /// Explicit-threshold heuristic: PDF under threshold triggers SVG
  /// attempt, large PDF does not, non-PDF is always skipped.
  #[test]
  fn should_try_svg_path_explicit_threshold() {
    let tmp = TempDir::new("svg_gate");
    let small_pdf = tmp.join("small.pdf");
    let big_pdf = tmp.join("big.pdf");
    let png = tmp.join("raster.png");
    std::fs::write(&small_pdf, vec![0u8; 10 * 1024]).unwrap(); // 10 KB
    std::fs::write(&big_pdf, vec![0u8; 500 * 1024]).unwrap(); // 500 KB
    std::fs::write(&png, vec![0u8; 10 * 1024]).unwrap(); // PNG, irrelevant size

    // Under explicit threshold → true.
    assert!(Graphics::should_try_svg_path(
      small_pdf.to_str().unwrap(),
      200
    ));
    // At/over explicit threshold → false.
    assert!(!Graphics::should_try_svg_path(
      big_pdf.to_str().unwrap(),
      200
    ));
    // Non-PDF → always false even under threshold.
    assert!(!Graphics::should_try_svg_path(png.to_str().unwrap(), 200));
    // Missing file → false, not panic.
    assert!(!Graphics::should_try_svg_path("/no/such/file.pdf", 200));
  }

  /// Auto-detect path (`threshold_kb == 0`): vector-only PDFs trigger
  /// the SVG attempt, PDFs containing image XObjects do NOT. Uses the
  /// real fixtures (`cifar10_vector.pdf`, `pathological_vector.pdf`,
  /// `raster_with_image.pdf`) under `latexml_post/tests/fixtures/`.
  #[test]
  fn should_try_svg_path_auto_detect() {
    let fixtures = Path::new(env!("CARGO_MANIFEST_DIR")).join("tests/fixtures");
    let cifar = fixtures.join("cifar10_vector.pdf");
    let pathological = fixtures.join("pathological_vector.pdf");
    let raster = fixtures.join("raster_with_image.pdf");
    assert!(cifar.exists(), "fixture missing: {}", cifar.display());
    assert!(
      pathological.exists(),
      "fixture missing: {}",
      pathological.display()
    );
    assert!(raster.exists(), "fixture missing: {}", raster.display());

    // Vector PDFs (no /Subtype /Image marker) → SVG path activated.
    assert!(
      Graphics::should_try_svg_path(cifar.to_str().unwrap(), 0),
      "vector-only PDF must trigger SVG path under auto-detect"
    );
    assert!(
      Graphics::should_try_svg_path(pathological.to_str().unwrap(), 0),
      "pgfplots-style vector PDF must trigger SVG path under auto-detect"
    );

    // Raster PDF (has /Subtype /Image) → SVG path SKIPPED.
    assert!(
      !Graphics::should_try_svg_path(raster.to_str().unwrap(), 0),
      "raster-containing PDF must skip auto-detect SVG path"
    );

    // Direct detector sanity check.
    assert_eq!(
      Graphics::pdf_has_image_xobject(cifar.to_str().unwrap()),
      Some(false)
    );
    assert_eq!(
      Graphics::pdf_has_image_xobject(raster.to_str().unwrap()),
      Some(true)
    );
  }

  #[test]
  fn postscript_density_caps_huge_bounding_box() {
    let tmp = TempDir::new("ps_density");
    let normal = tmp.join("normal.eps");
    let huge = tmp.join("huge.eps");
    std::fs::write(
      &normal,
      "%!PS-Adobe-3.0 EPSF-3.0\n%%BoundingBox: 0 0 567 567\n",
    )
    .unwrap();
    std::fs::write(
      &huge,
      "%!PS-Adobe-3.0 EPSF-3.0\n%%BoundingBox: 14 14 11353 11353\n",
    )
    .unwrap();

    assert_eq!(
      Graphics::raster_density_for_source(normal.to_str().unwrap()),
      Graphics::DEFAULT_RASTER_DENSITY
    );
    assert_eq!(
      Graphics::raster_density_for_source(huge.to_str().unwrap()),
      13
    );
    assert_eq!(
      read_postscript_bounding_box(huge.to_str().unwrap()),
      Some((11339.0, 11339.0))
    );
  }

  #[test]
  fn pdf_density_caps_huge_page_box() {
    let dir = TempDir::new("pdf_density");
    let tmp = dir.join("page.pdf");
    std::fs::write(
      &tmp,
      b"%PDF-1.4
1 0 obj
<< /Type /Page /MediaBox [0 0 4218 2437] >>
endobj
",
    )
    .unwrap();

    assert_eq!(
      latexml_core::util::image::read_pdf_page_box(Path::new(tmp.to_str().unwrap())),
      Some((4218.0, 2437.0))
    );
    assert_eq!(
      Graphics::raster_density_for_source(tmp.to_str().unwrap()),
      34
    );
  }

  /// The viewport dimensions come from the root `width`/`height`, the way a
  /// browser sizes an SVG — the `viewBox` is only a fallback (issue #696). Here
  /// `10cm`/`7.5cm` convert to 378×283 px (96 dpi); the disagreeing `viewBox`
  /// `0 0 640 480` is ignored for sizing. When the root carries no lengths, the
  /// viewBox is what remains.
  #[test]
  fn read_svg_dimensions_sizes_from_root_lengths() {
    let dir = TempDir::new("svg_dim");
    let tmp = dir.join("dims.svg");
    std::fs::write(
      &tmp,
      r#"<?xml version="1.0"?>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 640 480" width="10cm" height="7.5cm">
  <rect width="640" height="480" fill="black"/>
</svg>"#,
    )
    .unwrap();
    let dims = Graphics::read_svg_dimensions(tmp.to_str().unwrap()).expect("dims");
    assert_eq!(dims, (378, 283));
    // No root lengths → the viewBox is the fallback.
    let vb = dir.join("vb.svg");
    std::fs::write(
      &vb,
      r#"<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 640 480"><rect/></svg>"#,
    )
    .unwrap();
    assert_eq!(
      Graphics::read_svg_dimensions(vb.to_str().unwrap()).expect("viewbox fallback"),
      (640, 480)
    );
  }

  /// A unit-bearing root length must be **converted**, not truncated. `123.7pt`
  /// is 123.7/72 in = 164.9 px; the previous reader dropped the `pt` and called
  /// it 124 px, so a `\includegraphics` of this file rendered at three quarters
  /// of its size (and, for `cm`/`in` sources, at a small fraction of it — issue
  /// 498 follow-up).
  #[test]
  fn read_svg_dimensions_falls_back_to_width_height() {
    let dir = TempDir::new("svg_dim_fallback");
    let tmp = dir.join("dims.svg");
    std::fs::write(
      &tmp,
      r#"<svg xmlns="http://www.w3.org/2000/svg" width="123.7pt" height="99.4pt">
  <rect/>
</svg>"#,
    )
    .unwrap();
    let dims = Graphics::read_svg_dimensions(tmp.to_str().unwrap()).expect("dims");
    assert_eq!(dims, (165, 133));
  }

  /// The no-usable-geometry case must stay `None` all the way through, so the
  /// caller writes no `imagewidth`/`imageheight` at all. Emitting a bogus
  /// number here is worse than emitting nothing: with no attributes the browser
  /// uses the SVG's own intrinsic size, which is right.
  #[test]
  fn read_svg_dimensions_declines_a_percentage_sized_root() {
    let dir = TempDir::new("svg_dim_pct");
    let tmp = dir.join("dims.svg");
    std::fs::write(
      &tmp,
      r#"<svg xmlns="http://www.w3.org/2000/svg" width="100%" height="100%"><rect/></svg>"#,
    )
    .unwrap();
    assert_eq!(Graphics::read_svg_dimensions(tmp.to_str().unwrap()), None);
  }

  /// Three `<graphics>` nodes over one source: two share `options`, one
  /// differs. `process` must coalesce the matching pair into a single
  /// conversion and run a second one for the differing options — proven by
  /// counting the lines a fake `convert` on `PATH` appends to its log.
  ///
  /// **The cache must be bypassed for this to mean anything.** The
  /// observable here is "how many converter subprocesses ran", and
  /// `graphics_cache` is content-addressed against a *host-persistent* root
  /// (`$XDG_CACHE_HOME/latexml-oxide/graphics`). With the cache live this
  /// test was self-poisoning: the first run stored the shim's output under a
  /// key derived from these fixed source bytes, and every later run was
  /// served from that entry, spawned nothing, and died on a missing log
  /// (issue 401). The two jobs also share one cache key — same bytes, page,
  /// density and extension, differing only in destination name — so even a
  /// pristine cache could serve job two from job one and see a single log
  /// line. `CachePolicy::Bypass` removes both, without touching any env var.
  #[test]
  #[cfg(unix)]
  fn process_coalesces_only_matching_conversion_options() {
    use std::os::unix::fs::PermissionsExt;

    use crate::{
      document::{PostDocument, PostDocumentOptions},
      graphics_cache::CachePolicy,
    };

    let tmp = TempDir::new("graphics_dedupe");
    let source = tmp.join("plot.ai");
    std::fs::write(&source, "%!PS-Adobe-3.0\n%%BoundingBox: 0 0 100 100\n").unwrap();
    let log = tmp.join("convert.log");
    let fake_convert = tmp.join("convert");
    // Log the args AND write a non-empty file at the dest (the last positional
    // arg) — `convert_image` now requires actual output, not just exit 0.
    // The log path is derived from `$0` (the kernel hands a shebang script its
    // resolved path, so PATH lookup still yields an absolute `dirname`) rather
    // than from an env var: one less process-global to synchronise.
    std::fs::write(
      &fake_convert,
      "#!/bin/sh\nprintf '%s\\n' \"$*\" >> \"$(dirname \"$0\")/convert.log\"\n\
       for a in \"$@\"; do d=\"$a\"; done\nprintf x > \"$d\"\nexit 0\n",
    )
    .unwrap();
    let mut perms = std::fs::metadata(&fake_convert).unwrap().permissions();
    perms.set_mode(0o755);
    std::fs::set_permissions(&fake_convert, perms).unwrap();

    let old_path = std::env::var("PATH").unwrap_or_default();
    let mut env = EnvGuard::acquire();
    env.set("PATH", &format!("{}:{}", tmp.path().display(), old_path));
    let xml = format!(
      r#"<?xml version="1.0"?>
<document xmlns="http://dlmf.nist.gov/LaTeXML" xml:id="d">
  <graphics graphic="plot.ai" candidates="{0}" options="width=20pt"/>
  <graphics graphic="plot.ai" candidates="{0}" options="width=40pt"/>
  <graphics graphic="plot.ai" candidates="{0}" options="width=20pt"/>
</document>"#,
      source.display()
    );
    let doc_opts = PostDocumentOptions {
      destination: Some(tmp.join("out.html").display().to_string()),
      source_directory: Some(tmp.path().display().to_string()),
      ..Default::default()
    };
    let doc = PostDocument::new_from_string(&xml, doc_opts).unwrap();
    let mut graphics = Graphics::new(None, true).with_cache_policy(CachePolicy::Bypass);
    let nodes = graphics.to_process(&doc);
    assert_eq!(nodes.len(), 3);

    let docs = graphics.process(doc, nodes).unwrap();
    let out = docs[0].to_xml_string();
    let log_contents = std::fs::read_to_string(&log).unwrap_or_else(|e| {
      panic!(
        "fake `convert` never ran: no log at {} ({e}). The shim is on PATH and the cache is \
         bypassed, so `process` should have spawned it.",
        log.display()
      )
    });
    assert_eq!(
      log_contents.lines().count(),
      2,
      "matching source/page/options should coalesce, but different options need separate \
       conversions; convert log was:\n{log_contents}"
    );
    assert_eq!(out.matches(r#"imagesrc="plot.png""#).count(), 2);
    assert_eq!(out.matches(r#"imagesrc="x1.png""#).count(), 1);
  }

  /// `angle=` on a **non-raster** source must not reach `convert`.
  ///
  /// Perl `Post/Graphics.pm` L264-271 refuses non-scaling transforms on a type
  /// whose `raster` property is false, warns `limitation`, and trivializes the
  /// transform. Rust's `svg` entry carries `raster: Some(false)` but nothing
  /// read it, so `Plan::Copy` handed IM a vector source and a `.svg`
  /// destination — IM rasterizes via its SVG delegate and writes the raster
  /// back under the `.svg` name, leaving the bundle with a file that is no
  /// longer the drawing it claims to be.
  ///
  /// A fake `convert` on PATH makes this observable without ImageMagick: it
  /// logs its arguments and overwrites its destination, so "never invoked" is
  /// the absence of a log AND an unchanged destination file. The raster half of
  /// the contract still has to hold, so the same document rotates a PNG.
  #[test]
  #[cfg(unix)]
  fn rotation_is_dropped_for_non_raster_sources_but_kept_for_raster() {
    use std::os::unix::fs::PermissionsExt;

    use crate::{
      document::{PostDocument, PostDocumentOptions},
      graphics_cache::CachePolicy,
    };

    let tmp = TempDir::new("graphics_nonraster_rotate");
    let svg_body = r#"<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 60 40"><rect/></svg>"#;
    let svg = tmp.join("draw.svg");
    std::fs::write(&svg, svg_body).unwrap();
    // A 1×1 PNG: enough for `imagesize`, and a raster type, so it MUST rotate.
    let png = tmp.join("dot.png");
    std::fs::write(&png, ONE_PIXEL_PNG).unwrap();

    let log = tmp.join("convert.log");
    let fake_convert = tmp.join("convert");
    std::fs::write(
      &fake_convert,
      "#!/bin/sh\nprintf '%s\\n' \"$*\" >> \"$(dirname \"$0\")/convert.log\"\n\
       for a in \"$@\"; do d=\"$a\"; done\nprintf x > \"$d\"\nexit 0\n",
    )
    .unwrap();
    let mut perms = std::fs::metadata(&fake_convert).unwrap().permissions();
    perms.set_mode(0o755);
    std::fs::set_permissions(&fake_convert, perms).unwrap();

    let old_path = std::env::var("PATH").unwrap_or_default();
    let mut env = EnvGuard::acquire();
    env.set("PATH", &format!("{}:{}", tmp.path().display(), old_path));

    let dest = tmp.join("sub").join("out.html");
    std::fs::create_dir_all(dest.parent().unwrap()).unwrap();
    let xml = format!(
      r#"<?xml version="1.0"?>
<document xmlns="http://dlmf.nist.gov/LaTeXML" xml:id="d">
  <graphics graphic="draw" candidates="{}" options="angle=90" xml:id="g1"/>
  <graphics graphic="dot" candidates="{}" options="angle=90" xml:id="g2"/>
</document>"#,
      svg.display(),
      png.display()
    );
    let doc_opts = PostDocumentOptions {
      destination: Some(dest.display().to_string()),
      source_directory: Some(tmp.path().display().to_string()),
      ..Default::default()
    };
    let doc = PostDocument::new_from_string(&xml, doc_opts).unwrap();
    let mut graphics = Graphics::new(None, true).with_cache_policy(CachePolicy::Bypass);
    let nodes = graphics.to_process(&doc);
    assert_eq!(nodes.len(), 2);
    graphics.process(doc, nodes).unwrap();

    let out_svg = dest.parent().unwrap().join("draw.svg");
    assert_eq!(
      std::fs::read_to_string(&out_svg).ok().as_deref(),
      Some(svg_body),
      "the copied SVG must be the original drawing, not a `convert` rewrite"
    );
    // One line per invocation; the rotate line names its source AND its
    // `.rotated` scratch file, so match lines rather than occurrences.
    let invocations = std::fs::read_to_string(&log).unwrap_or_default();
    let calls_for = |name: &str| invocations.lines().filter(|l| l.contains(name)).count();
    assert_eq!(
      calls_for("draw.svg"),
      0,
      "`convert` must not be invoked for a non-raster source; log was:\n{invocations}"
    );
    assert_eq!(
      calls_for("dot.png"),
      1,
      "a raster source with angle= must still be rotated; log was:\n{invocations}"
    );
  }

  /// Characterization matrix for the post-side graphicx algebra.
  ///
  /// **Pins behaviour, not correctness.** `apply_graphicx_transforms` works in
  /// device pixels at the effective DPI (100 unless a `<?latexml DPI=?>` PI
  /// says otherwise) and is a *separate* implementation from the engine's
  /// `image_graphicx_sizer`; the two disagree, and the disagreements are
  /// recorded here so the planned unification has to resolve them deliberately.
  ///
  /// Source is 200x100 px throughout, DPI 100. Notes on individual rows:
  ///
  /// * `width=100pt` -> 138 px: 100pt = 99.6265bp, x 100/72.27 = 137.85, ceil.
  ///   Until 2026-08-04 this read 139, because the local parser skipped Perl's
  ///   pt->bp step and multiplied the raw 100 — so the HTML pixel count and the
  ///   engine's reserved box disagreed by a pixel on every explicit size.
  /// * `width=1in` / `width=2cm` are honoured since the same date; the local
  ///   parser only knew `pt` and `px` and silently dropped anything else. This
  ///   is unreachable from ordinary LaTeX either way — `graphicx_sty`
  ///   normalizes to pt first (`width=2cm` arrives as `width=56.9055pt`,
  ///   verified) — so it is defensive behaviour, pinned to stay honest about
  ///   what the parser accepts.
  /// * `angle=90` swaps the box, and now does so via the true rotated bounding
  ///   box rather than a 90/270 special case, which is also what
  ///   `convert -rotate` writes for an oblique angle.
  /// * The `width=137.9979pt` row is issue 498's own witness: 191 px, unmoved
  ///   by any of the above.
  #[test]
  fn apply_graphicx_transforms_matrix() {
    #[rustfmt::skip]
    let matrix: &[(&str, u32, u32)] = &[
      ("",                                     200, 100),
      ("width=100pt",                          138,  69),
      ("width=100pt,keepaspectratio=true",     138,  69),
      ("scale=0.5",                            100,  50),
      ("height=25pt,keepaspectratio=true",      69,  35),
      ("width=100pt,height=80pt",              138, 111),
      ("width=1in,keepaspectratio=true",       100,  50), // 1in at DPI 100
      ("width=2cm",                             79,  40), // 2cm = 0.787in
      ("angle=90",                             100, 200),
      ("width=137.9979pt,keepaspectratio=true", 191,  96), // issue 498 witness
    ];
    // Report every divergence at once: when this matrix moves it is normally
    // because a shared rule changed, and the whole delta is the signal.
    let mut deltas = Vec::new();
    for (opts, want_w, want_h) in matrix {
      let got = Graphics::apply_graphicx_transforms(200, 100, opts, 100);
      if got != (*want_w, *want_h) {
        deltas.push(format!(
          "  [{opts}] pinned ({want_w}, {want_h})  got {got:?}"
        ));
      }
    }
    assert!(
      deltas.is_empty(),
      "{} of {} pinned rows moved:\n{}",
      deltas.len(),
      matrix.len(),
      deltas.join("\n")
    );
  }

  /// brucemiller/LaTeXML#2392: a graphics `<img>` carries width/height that
  /// give the *requested* aspect ratio (from `\includegraphics`). The flex
  /// subfigure CSS caps `max-width`, which changes the width but not the
  /// height, so a square picture renders as a vertical ellipsoid. `set_graphic_src`
  /// now also emits an explicit `aspect-ratio:W/H` in `cssstyle`, so a width-only
  /// CSS cap (paired with `height:auto`) preserves the requested ratio — and the
  /// *requested* ratio, not the file's, per Bruce Miller's requirement in the
  /// thread. Beyond Perl 0.8.8, which emits no aspect-ratio (OXIDIZED_DESIGN #139).
  #[test]
  fn set_graphic_src_emits_requested_aspect_ratio_2392() {
    let doc = libxml::tree::Document::new().unwrap();
    for (w, h, bucket) in [
      (200u32, 100u32, "ltx_img_landscape"),
      (476, 476, "ltx_img_square"),
    ] {
      let mut node = Node::new("graphics", None, &doc).unwrap();
      Graphics::set_graphic_src(&mut node, "fig.png", Some(w), Some(h));
      let style = node.get_attribute("cssstyle").unwrap_or_default();
      assert!(
        style.contains(&format!("aspect-ratio:{w}/{h}")),
        "expected the requested aspect-ratio {w}/{h} in cssstyle, got {style:?}"
      );
      assert!(
        node
          .get_attribute("class")
          .unwrap_or_default()
          .contains(bucket)
      );
    }
  }

  /// The #2392 fix is two coupled halves: the emitted `aspect-ratio` (guarded
  /// above) and `height:auto` on flex/minipage images, so that ratio governs
  /// when the `flex_size` `max-width` caps the width. Guard the CSS half — the
  /// embedded `LaTeXML.css` — so removing it can't silently re-introduce the
  /// distortion while the emission test stays green.
  #[test]
  fn flex_graphics_css_frees_height_for_aspect_ratio_2392() {
    let css = include_str!("../resources/CSS/LaTeXML.css");
    assert!(
      css.contains(".ltx_flex_figure .ltx_graphics { height: auto; }"),
      "the flex-graphics height:auto companion to #2392's aspect-ratio is missing from LaTeXML.css"
    );
  }

  /// `parse_angle_option`'s doc claims it normalizes to {0,90,180,270} when
  /// within 5 degrees. It does not — every value comes back raw. Pinned as it
  /// behaves; the doc comment is the thing that is wrong.
  #[test]
  fn parse_angle_option_returns_the_raw_angle() {
    for (opts, want) in [
      ("angle=90", Some(90.0)),
      ("angle=-90", Some(-90.0)),
      ("angle=88", Some(88.0)), // NOT snapped to 90
      ("angle=45", Some(45.0)),
      ("angle=180", Some(180.0)),
      ("angle=0.2", Some(0.2)), // below the 0.5 threshold callers apply
      ("angle=272", Some(272.0)),
      ("", None),
      ("width=100pt", None),
    ] {
      assert_eq!(Graphics::parse_angle_option(opts), want, "options {opts:?}");
    }
  }

  /// Which reader a source reaches, and what it can measure. EPS answers
  /// `None` here: the post raster reader is the `imagesize` crate, which has no
  /// PostScript support, so an EPS is never sized on the trivial-copy path — it
  /// always goes through `Plan::Convert` and is measured from the produced PNG.
  #[test]
  fn read_source_dimensions_dispatch_matrix() {
    let tmp = TempDir::new("post_dispatch");
    let svg = tmp.join("a.svg");
    std::fs::write(&svg, r#"<svg viewBox="0 0 200 100"><rect/></svg>"#).unwrap();
    let svg_upper = tmp.join("B.SVG");
    std::fs::write(&svg_upper, r#"<svg viewBox="0 0 60 40"><rect/></svg>"#).unwrap();
    let png = tmp.join("c.png");
    std::fs::write(&png, ONE_PIXEL_PNG).unwrap();
    let eps = tmp.join("d.eps");
    std::fs::write(
      &eps,
      "%!PS-Adobe-3.0 EPSF-3.0\n%%BoundingBox: 0 0 200 100\n",
    )
    .unwrap();

    let dims = |p: &Path| Graphics::read_source_dimensions(p.to_str().unwrap());
    assert_eq!(dims(&svg), Some((200, 100)), "svg via viewBox");
    assert_eq!(
      dims(&svg_upper),
      Some((60, 40)),
      "extension match is case-insensitive"
    );
    assert_eq!(dims(&png), Some((1, 1)), "png via imagesize");
    assert_eq!(dims(&eps), None, "EPS is unmeasurable here, by design");
  }

  /// The three `%%BoundingBox` shapes the PS reader accepts. Values are bp; the
  /// two-value form returns the extent, the full form the raw corners.
  #[test]
  fn postscript_bounding_box_forms() {
    let tmp = TempDir::new("post_psbbox");
    let offset = tmp.join("o.eps");
    std::fs::write(
      &offset,
      "%!PS-Adobe-3.0 EPSF-3.0\n%%BoundingBox: 10 20 210 120\n",
    )
    .unwrap();
    assert_eq!(
      read_postscript_bounding_box(offset.to_str().unwrap()),
      Some((200.0, 100.0)),
      "extent, not corners"
    );
    assert_eq!(
      read_postscript_bounding_box_full(offset.to_str().unwrap()),
      Some((10.0, 20.0, 200.0, 100.0)),
      "full form is (llx, lly, width, height) — NOT (llx,lly,urx,ury)"
    );
    // The deferred `(atend)` form: the real numbers appear later in the file.
    let atend = tmp.join("a.eps");
    std::fs::write(
      &atend,
      "%!PS-Adobe-3.0 EPSF-3.0\n%%BoundingBox: (atend)\nstuff\n%%BoundingBox: 0 0 300 150\n",
    )
    .unwrap();
    assert_eq!(
      read_postscript_bounding_box(atend.to_str().unwrap()),
      Some((300.0, 150.0))
    );
  }

  /// Rasterization density is a *quality* knob, independent of the sizing DPI:
  /// `DEFAULT_RASTER_DENSITY` (120) unless the source's own box is large enough
  /// that rendering at 120 would exceed `MAX_RASTER_DIMENSION_PX`.
  #[test]
  fn raster_density_is_capped_by_source_box_size() {
    let tmp = TempDir::new("post_density");
    let small = tmp.join("s.eps");
    std::fs::write(
      &small,
      "%!PS-Adobe-3.0 EPSF-3.0\n%%BoundingBox: 0 0 200 100\n",
    )
    .unwrap();
    assert_eq!(
      Graphics::raster_density_for_source(small.to_str().unwrap()),
      120
    );

    let pdf = tmp.join("s.pdf");
    std::fs::write(&pdf, "%PDF-1.4\n<< /MediaBox [0 0 200 100] >>\n").unwrap();
    assert_eq!(
      Graphics::raster_density_for_source(pdf.to_str().unwrap()),
      120
    );

    // No measurable box (a raster source) — the default stands.
    let png = tmp.join("s.png");
    std::fs::write(&png, ONE_PIXEL_PNG).unwrap();
    assert_eq!(
      Graphics::raster_density_for_source(png.to_str().unwrap()),
      120
    );

    // A 2000bp-wide source at 120 dpi would be 3333 px, over the 2048 cap, so
    // the density drops to floor(2048 * 72 / 2000) = 73.
    let big = tmp.join("b.eps");
    std::fs::write(
      &big,
      "%!PS-Adobe-3.0 EPSF-3.0\n%%BoundingBox: 0 0 2000 1000\n",
    )
    .unwrap();
    assert_eq!(
      Graphics::raster_density_for_source(big.to_str().unwrap()),
      73
    );
  }

  /// Smallest valid PNG: 1×1, 8-bit RGB. `imagesize` reads its IHDR, so the
  /// sizing half of `Plan::Copy` succeeds and no `expected:image` warn fires.
  const ONE_PIXEL_PNG: &[u8] = &[
    0x89, b'P', b'N', b'G', 0x0d, 0x0a, 0x1a, 0x0a, // signature
    0x00, 0x00, 0x00, 0x0d, b'I', b'H', b'D', b'R', // IHDR length + type
    0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x01, // 1 × 1
    0x08, 0x02, 0x00, 0x00, 0x00, 0x90, 0x77, 0x53, 0xde, // bit depth/colour + CRC
    0x00, 0x00, 0x00, 0x0c, b'I', b'D', b'A', b'T', // IDAT length + type
    0x08, 0xd7, 0x63, 0xf8, 0xcf, 0xc0, 0x00, 0x00, 0x03, 0x01, 0x01, 0x00, 0x18, 0xdd, 0x8d,
    0xb0, // deflate stream + CRC
    0x00, 0x00, 0x00, 0x00, b'I', b'E', b'N', b'D', 0xae, 0x42, 0x60, 0x82,
  ];

  /// A post-processing diagnostic raised on a WORKER THREAD must reach the MAIN
  /// thread's bound log AND register in the main `REPORT` status counters — both
  /// `LOG_BUFFER` and `REPORT` are `#[thread_local]`, so a worker's `Error!`
  /// would otherwise be lost from cortex.log and from `status_code`. This
  /// exercises the exact "thread join + fold" the graphics pool uses: each
  /// worker returns its [`CapturedDiagnostics`] from `logger::capture`, and the
  /// main thread folds them in via `replay_captured` after join — no shared
  /// writeable state, no lock, no env mutation. (Companion: the real pipeline is
  /// validated end-to-end by converting a document with an unconvertible image;
  /// see docs and the manual `--preload`/`--dest` smoke.)
  #[test]
  fn worker_diagnostics_fold_into_main_thread_on_join() {
    // The `log` macros are inert until a logger + level are installed (the
    // CLI/cortex do this at startup). `init` is process-global + idempotent
    // across tests; force the level since `init` skips it if already installed.
    let _ = latexml_core::util::logger::init(log::LevelFilter::Info);
    log::set_max_level(log::LevelFilter::Info);

    latexml_core::util::logger::bind_log();
    let before = latexml_core::common::error::snapshot_report_counts();

    // Two workers, each emitting a post Error! under capture (so the diagnostic
    // lands in the worker's own thread-local buffer + REPORT), returning their
    // CapturedDiagnostics on join — exactly the graphics pool's pattern.
    let captured: Vec<latexml_core::util::logger::CapturedDiagnostics> = std::thread::scope(|s| {
      (0..2)
        .map(|i| {
          s.spawn(move || {
            latexml_core::util::logger::capture(|| {
              Error!(
                "imageprocessing",
                "failed_to_convert",
                "Graphics: Failed to convert {} to {}",
                format!("w{i}.pdf"),
                format!("w{i}.png")
              );
            })
            .1
          })
        })
        .collect::<Vec<_>>()
        .into_iter()
        .map(|h| h.join().unwrap())
        .collect()
    });

    // Fold the per-worker diagnostics into the main thread.
    for diags in captured {
      latexml_core::util::logger::replay_captured(diags);
    }

    let after = latexml_core::common::error::snapshot_report_counts();
    let log = latexml_core::util::logger::flush_log();

    assert!(
      log.contains("imageprocessing:failed_to_convert") && log.contains("Failed to convert"),
      "worker Error! must reach the main-thread log; got: {log:?}"
    );
    assert_eq!(
      after.error,
      before.error + 2,
      "both workers' Error! must increment the main REPORT error count via the fold"
    );
  }

  /// `produced_output` is the guard that turns a `convert`/`gs` exit-0-but-no-file
  /// into a reported failure: a usable conversion is a non-empty file, not just a
  /// clean exit. Missing OR empty (0-byte) => not output.
  #[test]
  fn produced_output_requires_a_nonempty_file() {
    let tmp = std::env::temp_dir().join(format!("latexml_produced_{}", std::process::id()));
    std::fs::create_dir_all(&tmp).unwrap();
    let missing = tmp.join("missing.png");
    let empty = tmp.join("empty.png");
    let real = tmp.join("real.png");
    std::fs::write(&empty, b"").unwrap();
    std::fs::write(&real, b"\x89PNG").unwrap();
    assert!(
      !Graphics::produced_output(&missing.to_string_lossy()),
      "a missing file is not usable output"
    );
    assert!(
      !Graphics::produced_output(&empty.to_string_lossy()),
      "a 0-byte file is not usable output (would render as a broken image)"
    );
    assert!(
      Graphics::produced_output(&real.to_string_lossy()),
      "a non-empty file is usable output"
    );
    std::fs::remove_dir_all(&tmp).ok();
  }

  /// A converter that fails must leave its stderr in the thread-local diagnostic,
  /// so the failed_to_convert Error can name WHY (e.g. gs `/undefinedfilename`).
  #[test]
  fn run_with_timeout_captures_stderr_into_diag() {
    take_converter_diag(); // clear
    let (cmd, prog) = spawn_stderr_fail();
    let status = Graphics::run_with_timeout(cmd, std::time::Duration::from_secs(5));
    assert!(
      status.map(|s| !s.success()).unwrap_or(false),
      "command should report failure"
    );
    let diag = take_converter_diag().expect("a diagnostic must be recorded");
    assert!(
      diag.contains("boom on stderr") && diag.contains(prog),
      "diag should name the program + its stderr; got: {diag}"
    );
  }

  /// A converter that can't be spawned (not installed / not on PATH — e.g. `gs`
  /// missing in a minimal image) must record a "could not start" diagnostic.
  #[test]
  fn run_with_timeout_records_spawn_failure() {
    take_converter_diag();
    let cmd = std::process::Command::new("definitely_not_a_real_binary_xyz_123");
    let status = Graphics::run_with_timeout(cmd, std::time::Duration::from_secs(5));
    assert!(status.is_none(), "spawn failure returns None");
    let diag = take_converter_diag().expect("a spawn diagnostic must be recorded");
    assert!(
      diag.contains("could not start") && diag.contains("definitely_not_a_real_binary_xyz_123"),
      "diag should name the missing tool; got: {diag}"
    );
  }

  /// Every graphics/image tool the cascade shells out to maps to an install
  /// hint that names the OS package, so a missing-dependency diagnostic is
  /// self-fixing; an unknown program yields no hint.
  #[test]
  fn missing_tool_hint_names_packages() {
    assert!(missing_tool_hint("mutool").unwrap().contains("mupdf-tools"));
    assert!(
      missing_tool_hint("pdftocairo")
        .unwrap()
        .contains("poppler-utils")
    );
    assert!(missing_tool_hint("gs").unwrap().contains("ghostscript"));
    assert!(missing_tool_hint("ps2pdf").unwrap().contains("ghostscript"));
    assert!(
      missing_tool_hint("convert")
        .unwrap()
        .contains("imagemagick")
    );
    assert!(missing_tool_hint("dvisvgm").unwrap().contains("dvisvgm"));
    assert!(missing_tool_hint("dvipng").unwrap().contains("dvipng"));
    assert!(missing_tool_hint("kpsewhich").unwrap().contains("TeX Live"));
    assert!(missing_tool_hint("some_unknown_tool").is_none());
  }
}