pdf_engine/

text.rs

//! Text extraction via a custom Device implementation.

// Copyright (c) 2026 Innovation Trigger B.V.
//
// PDFluent is available under two licences, at your option: the GNU AGPLv3, or
// the PDFluent Commercial Licence. See the LICENSE file in this repository --
// that file travels with the copy you received, which a URL does not.

use kurbo::{Affine, BezPath, PathEl, Point, Shape};
use pdf_render::pdf_interpret::cmap::BfString;
use pdf_render::pdf_interpret::font::Glyph;
use pdf_render::pdf_interpret::{
    BlendMode, ClipPath, Device, GlyphDrawMode, Image, Paint, PathDrawMode, SoftMask,
};
use std::borrow::Cow;
use std::cmp::Ordering;

/// Minimum Y tolerance for grouping spans into horizontal bands. The
/// effective tolerance is typically `median_font_size * BAND_Y_FRACTION`
/// per ANN[r17/TEX4]; this constant acts as the absolute floor.
const BAND_Y_TOLERANCE: f64 = 5.0;
/// Fraction of the page's median font size used as the band-Y
/// tolerance. Empirically 0.30× works across common typography —
/// below typical leading (~1.2×) so adjacent lines never collapse,
/// above sub-pixel baseline drift.
const BAND_Y_FRACTION: f64 = 0.30;
/// Multiplier applied to median line spacing to derive the horizontal
/// paragraph-break cut threshold. Normal line-to-line progression is
/// ~1.0× the median; paragraph breaks typically show 1.5× or more.
const PARAGRAPH_BREAK_LINE_SPACING_MULTIPLIER: f64 = 1.8;

// ANN[r17/TEX1] Multi-signal consensus thresholds.
// The previous single-threshold scheme (gap > 0.15 * font_size) missed
// word boundaries when kerning or narrow fonts produced small measured
// gaps even though the PDF emitted an explicit TJ backward shift, and
// over-emitted spaces for condensed fonts where 0.15em of kerning is
// well below an actual word space. The consensus system weights three
// signals and inserts a space when the combined confidence exceeds
// SPACE_CONSENSUS_THRESHOLD.
/// Raw TJ backward adjustment (positive in PDF TJ units) that is
/// definitively a word break. Matches pdftotext / MuPDF heuristics —
/// a space glyph is typically emitted as either a literal 0x20 or as
/// a TJ adjustment of around 250 1/1000 em. 100 units is a safely
/// conservative floor.
const TJ_SPACE_THRESHOLD_UNITS: f32 = 100.0;
/// Weight of the TJ offset signal when confidence is high.
const TJ_SIGNAL_WEIGHT: f64 = 0.95;
/// Weight of the purely geometric gap signal.
const GAP_SIGNAL_WEIGHT: f64 = 0.80;
/// Weight of character-heuristic signals (CamelCase, digit↔letter).
const HEURISTIC_SIGNAL_WEIGHT: f64 = 0.60;
/// Combined weight at which a space is inserted.
const SPACE_CONSENSUS_THRESHOLD: f64 = 0.75;
/// Fraction of a median character width above which a gap contributes
/// to the geometric signal (pdf_oxide uses ~0.30).
const GAP_TO_MEDIAN_CHAR_FRACTION: f64 = 0.30;
/// Fallback gap fraction relative to `font_size` when the running
/// median character width has not yet been established.
const GAP_TO_FONT_SIZE_FALLBACK_FRACTION: f64 = 0.15;

/// Minimum horizontal gap treated as a column gutter (adaptive fallback).
const COLUMN_GAP_THRESHOLD_MIN: f64 = 10.0;
/// Maximum adaptive column gap threshold.
const COLUMN_GAP_THRESHOLD_MAX: f64 = 40.0;
/// Multiplier applied to median inter-word gap to derive column threshold.
const COLUMN_GAP_MEDIAN_MULTIPLIER: f64 = 3.0;
/// Fallback column gap threshold when median cannot be computed.
const COLUMN_GAP_THRESHOLD_FALLBACK: f64 = 20.0;
/// Maximum drift allowed when matching gutters across neighboring bands.
const COLUMN_GAP_MATCH_TOLERANCE: f64 = 12.0;
/// Minimum number of gapped bands required before we enable column mode.
const MIN_COLUMN_GAPPED_BANDS: usize = 3;
/// Minimum fraction of bands in a region that must expose the shared gutters.
const MIN_COLUMN_GAP_SUPPORT: f64 = 0.80;
/// Minimum fraction of non-empty column slices that must look like prose.
const MIN_DENSE_SLICE_RATIO: f64 = 0.35;

/// Two span starts this far apart are the same cell edge (#434). A cell's
/// wrapped line is set from the cell's own left edge, so the two lines start on
/// the same coordinate up to the rounding of the text matrix.
const CELL_EDGE_TOLERANCE: f64 = 2.0;
/// How far below its row a line may sit and still be that row's continuation,
/// as a multiple of the row's tallest glyph. One line of leading is ~1.2; the
/// next row of a table sits further down than this.
const WRAPPED_CELL_LINE_GAP_FACTOR: f64 = 1.8;
/// How far above the row the band that corroborates the grid may sit, counted
/// in bands. The lines between are the wrapped cells of the row above, so a
/// couple of them is all a row can put in the way.
const TABLE_GRID_MAX_LOOKBACK: usize = 4;
/// The share of the grid's own row pitch a continuation may sit below the line
/// it continues. A row's pitch is one line plus the cell's padding and a
/// wrapped line is one line, so a line at the full pitch is the next row.
const WRAPPED_CELL_MAX_PITCH_FRACTION: f64 = 0.9;
/// A grid is a claim about columns, so the band that corroborates it has to
/// carry at least this many of them. Two, because a row of the table is
/// allowed an empty cell.
const TABLE_GRID_MIN_COLUMNS: usize = 2;
/// A drawn path this flat is a line and not a box (#545). The ruling lines of
/// the Isartor manual's appendix are 0.18 pt of ink; a hairline stroke is a
/// path of no height at all, and a table's cell shading is eighteen points.
const RULE_MAX_THICKNESS: f64 = 3.0;
/// A line shorter than this separates nothing: it is a tick, a bullet or the
/// underline of a word.
const RULE_MIN_LENGTH: f64 = 24.0;
/// How many rules are kept. A chart draws thousands of short flat segments and
/// none of them rules a row; the cap bounds the memory a pathological page can
/// ask for without changing what any real table looks like.
const MAX_RECORDED_RULES: usize = 512;
/// The share of a region's width a rule has to cross before it counts as
/// separating that region's rows. A rule between two rows runs the whole table;
/// a rule under one cell does not.
const RULE_SPAN_FRACTION: f64 = 0.9;
/// How many of a region's band gaps have to carry a rule before the region is
/// a ruled table. Two, so that a single horizontal line -- a header rule, the
/// line above a footnote -- never speaks for the page, while a region the
/// recursion has already cut down to three rows can still be recognised as the
/// table it is. Each of the two has to cross the whole region and lie between
/// two bands that follow each other, which one rule under a headline does not.
const MIN_RULED_ROW_SEPARATORS: usize = 2;
/// The share of a region's band gaps that have to carry such a rule. Half,
/// because a row whose cell wraps puts a band inside itself, and that gap has
/// no rule in it.
const MIN_RULED_GAP_SUPPORT: f64 = 0.5;

/// How many cells the row itself has to fill before a line under it is read as
/// one of its cells running on.
///
/// Three, because two is what a page set in columns looks like: its lines
/// start on the same two edges as a two-cell row does, one of its columns ends
/// before the other, and the line left over then reads exactly like a wrapped
/// cell. On `tracemonkey` p13 it is one -- and the page is two columns of
/// prose, where moving a line into "its cell" is the column cut of #389 class
/// O-B done on one band instead of the region. A two-column table pays for
/// that: its wrapped cells are the other half of #545.
const TABLE_ROW_MIN_CELLS: usize = 3;

/// Whether a text span's width was computed from real font metrics or estimated.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
#[cfg_attr(feature = "serde", derive(serde::Serialize))]
pub enum WidthSource {
    /// Width derived from the font's actual glyph advance (hmtx, CFF, Type1 charstring).
    Metric,
    /// Width estimated at 50 % of font size — no glyph metric was available.
    #[default]
    Estimate,
}

impl WidthSource {
    /// Stable label used across SDK bindings and the JSON wire form
    /// (`"Metric"` / `"Estimate"`). Single source of truth for the string; the
    /// `serde` derive on the enum produces identical values.
    pub fn as_str(&self) -> &'static str {
        match self {
            WidthSource::Metric => "Metric",
            WidthSource::Estimate => "Estimate",
        }
    }
}

/// Controls the richness of per-glyph geometry extraction.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum GeometryMode {
    /// Advance-based bounds only (current default).
    #[default]
    Basic,
    /// Full tight glyph bounds from outline paths.
    RichGeometry,
}

/// Provenance of per-glyph bounding boxes.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum BoundsSource {
    /// Advance bounds.
    #[default]
    Advance,
    /// Path-derived tight bounds.
    Tight,
    /// Fallback (no outline available).
    Estimate,
}

/// Vertical font metrics in /1000 em (1000 units-per-em), sourced from the
/// embedded font's OS/2 / hhea tables via skrifa. `ascent` is positive (above
/// the baseline); `descent` is negative (below it). The whole struct is `None`
/// on a span when no embedded font binary exposes metrics (non-embedded
/// standard-14, CFF, Type1, Type3).
#[derive(Debug, Clone, Copy, PartialEq, Default)]
#[cfg_attr(feature = "serde", derive(serde::Serialize))]
pub struct FontMetrics {
    /// Ascent above the baseline, in /1000 em.
    pub ascent: f64,
    /// Descent below the baseline (negative), in /1000 em.
    pub descent: f64,
    /// Cap height in /1000 em, when present in the font.
    #[cfg_attr(
        feature = "serde",
        serde(rename = "capHeight", skip_serializing_if = "Option::is_none")
    )]
    pub cap_height: Option<f64>,
    /// x-height in /1000 em, when present in the font.
    #[cfg_attr(
        feature = "serde",
        serde(rename = "xHeight", skip_serializing_if = "Option::is_none")
    )]
    pub x_height: Option<f64>,
}

/// A single text span at a specific position.
#[derive(Debug, Clone, Default)]
pub struct TextSpan {
    /// The extracted text.
    pub text: String,
    /// X position in user space.
    pub x: f64,
    /// Y position in user space.
    pub y: f64,
    /// Approximate bounding-box width in user space.
    pub width: f64,
    /// Approximate bounding-box height in user space.
    pub height: f64,
    /// Font size (approximate, from transform).
    pub font_size: f64,

    // ---- G1 read-only metadata (added 2026-05; backward-compatible) ----
    /// PostScript name of the font, with any 6-character subset prefix stripped
    /// (e.g. `Helvetica-Bold`, `TimesNewRomanPS-BoldMT`). `None` for Type1
    /// standard-14 fonts and Type3 fonts where no embedded font data is
    /// available through the public `pdf-interpret` API.
    pub font_name: Option<String>,
    /// Inferred bold style: `weight >= 700` or PostScript name suggests bold
    /// ("bold", "demi", "semibold", "heavy", "black"). Defaults `false` when
    /// no descriptor data is reachable.
    pub is_bold: bool,
    /// Inferred italic style: FontDescriptor /Italic flag set or PostScript
    /// name suggests italic/oblique/slant. Defaults `false` when no descriptor
    /// data is reachable.
    pub is_italic: bool,
    /// Fill color as sRGB RGBA, derived from `Paint::Color(c).to_rgba().to_rgba8()`
    /// at the moment of glyph paint. `None` for `Paint::Pattern` (tiling /
    /// shading) — the editor falls back to "auto" in that case.
    pub color: Option<[u8; 4]>,

    // ---- G2 glyph-level metrics (added 2026-05) ----
    /// Whether glyph widths were measured from real font advance data or estimated.
    pub width_source: WidthSource,
    /// Per-glyph bounding boxes in user-space, one entry per source glyph.
    /// `[x0, y0, x1, y1]` with y0 < y1 (PDF coordinate frame).
    pub char_bounds: Vec<[f64; 4]>,

    // ---- M3 rich geometry (added 2026-06; backward-compatible) ----
    #[doc(hidden)]
    pub geometry_mode: GeometryMode,
    #[doc(hidden)]
    pub bounds_source: BoundsSource,
    #[doc(hidden)]
    pub tight_char_bounds: Vec<[f64; 4]>,
    #[doc(hidden)]
    pub glyph_advances: Vec<f64>,
    #[doc(hidden)]
    pub glyph_bounds_sources: Vec<BoundsSource>,

    // ---- Golf 1 typographic metadata (added 2026-06; backward-compatible) ----
    /// Full affine transform of the span's first glyph in user space,
    /// `[a, b, c, d, e, f]` (kurbo coeffs of CTM × text-matrix). Captures
    /// rotation and shear that `(x, y, font_size)` discards. Text placed by a
    /// rectangle rather than drawn by a glyph (a form field's value with no
    /// appearance stream, #549) carries the placement in the same form.
    /// `None` for spans built from neither (e.g. synthetic markers).
    pub transform: Option<[f64; 6]>,
    /// Numeric font weight (~100–900) from the embedded font's OS/2 table when
    /// available. `None` for non-embedded / standard-14 fonts.
    pub font_weight: Option<u16>,
    /// Whether the font is serif, when determinable from embedded font data.
    /// `None` when no embedded descriptor is reachable.
    pub is_serif: Option<bool>,
    /// Whether the font is monospace, when determinable from embedded font data.
    /// `None` when no embedded descriptor is reachable.
    pub is_monospace: Option<bool>,
    /// Coarse PDF text render mode: `0` fill, `1` stroke, `3` invisible — the
    /// only three values the renderer's `GlyphDrawMode` expresses (the
    /// fill+stroke / clip modes 2 and 4–7 are not distinguished). Reflects the
    /// span's first glyph, and `0` for text placed by a rectangle rather than
    /// drawn (#549). `None` for spans built from neither.
    pub render_mode: Option<u8>,

    // ---- Golf 2 font metrics (added 2026-06; backward-compatible) ----
    /// Vertical font metrics (ascent/descent, optional cap/x-height) in /1000
    /// em from the embedded font binary. `None` for non-embedded fonts.
    pub font_metrics: Option<FontMetrics>,
}

impl TextSpan {
    /// Conservative right edge using whichever is wider: measured or estimated.
    /// Used by column detection to avoid underestimating span extent.
    fn right(&self) -> f64 {
        self.x + self.width.max(self.estimated_width())
    }

    /// Right edge from measured glyph positions only.
    fn measured_right(&self) -> f64 {
        self.x + self.width
    }

    fn estimated_width(&self) -> f64 {
        let char_count = self.text.chars().count() as f64;
        if char_count <= 0.0 {
            self.font_size * 0.5
        } else {
            self.font_size * 0.5 * char_count
        }
    }
}

/// A block of text (grouped by reading order).
#[derive(Debug, Clone)]
pub struct TextBlock {
    /// Spans within this block, sorted by position.
    pub spans: Vec<TextSpan>,
}

impl TextBlock {
    /// Concatenate all spans into a single string, in reading order.
    ///
    /// Spans that are close together are joined without a separator;
    /// a space is inserted when the gap between spans exceeds half
    /// the average character width.
    ///
    /// ANN[r17/TEX5] The spans are in the order the page draws them, left to
    /// right, and for Arabic or Hebrew that is the reverse of the order they
    /// are read in (#436, class R-H of #389). The assembled line therefore goes
    /// through [`crate::bidi::logical_order`] before it is returned: a line
    /// with no right-to-left character comes back untouched, and one that has
    /// them comes back with each of its runs the way a reader would type it.
    /// The spans themselves are left alone -- they carry the geometry, and the
    /// geometry is visual.
    pub fn text(&self) -> String {
        crate::bidi::logical_order(&self.visual_text()).into_owned()
    }

    /// The line as the page draws it, left to right. The order every geometric
    /// decision above this point was made in.
    fn visual_text(&self) -> String {
        if self.spans.is_empty() {
            return String::new();
        }
        let mut result = self.spans[0].text.clone();
        // ANN[r17/TEX5] Where the line got to, which is not always the span
        // before this one: a combining mark is drawn on the glyph before it and
        // moves the pen nowhere, so its right edge sits an advance short and
        // the letter after it looks a word apart. A Hebrew word with points
        // came out `שָׁל וֹם` -- one word, two "words" (#436). A span that is
        // nothing but marks does not say where the pen is, so the last one that
        // does answers instead.
        let mut anchor = &self.spans[0];
        for pair in self.spans.windows(2) {
            let prev = &pair[0];
            let curr = &pair[1];
            if !crate::bidi::is_only_marks(&prev.text) {
                anchor = prev;
            }
            // The gap is measured along the baseline the anchor was drawn on:
            // for upright text that is `curr.x - anchor.measured_right()` to
            // the last bit, for a rotated run it is the distance the reader
            // sees between the two (#435).
            let direction = span_direction(anchor);
            let (curr_along, _) = baseline_coordinates(curr, direction);
            let gap = curr_along - baseline_end(anchor, direction);
            if gap <= prev.font_size * 0.12 && second_run_carries_on_from_the_first(prev, curr) {
                if let Some(trimmed) = trim_overlapping_word_prefix(&prev.text, &curr.text) {
                    result.push_str(&trimmed);
                    continue;
                }
            }
            if gap > prev.font_size * 0.25 {
                result.push(' ');
            }
            result.push_str(&curr.text);
        }
        result
    }
}

#[derive(Debug, Clone)]
struct TextBand {
    y: f64,
    spans: Vec<TextSpan>,
}

impl TextBand {
    fn new(span: TextSpan) -> Self {
        Self {
            y: span.y,
            spans: vec![span],
        }
    }

    fn sort_spans(&mut self) {
        self.spans.sort_by(|a, b| {
            a.x.partial_cmp(&b.x)
                .unwrap_or(Ordering::Equal)
                .then_with(|| b.y.partial_cmp(&a.y).unwrap_or(Ordering::Equal))
        });
        collapse_overprinted_spans(&mut self.spans);
    }

    fn row_block(&self) -> TextBlock {
        let mut spans = self.spans.clone();
        spans.sort_by(|a, b| a.x.partial_cmp(&b.x).unwrap_or(Ordering::Equal));
        TextBlock { spans }
    }

    fn left(&self) -> f64 {
        self.spans
            .iter()
            .map(|span| span.x)
            .fold(f64::INFINITY, f64::min)
    }

    fn right(&self) -> f64 {
        self.spans
            .iter()
            .map(TextSpan::right)
            .fold(f64::NEG_INFINITY, f64::max)
    }

    fn width(&self) -> f64 {
        (self.right() - self.left()).max(0.0)
    }

    fn gap_midpoints(&self, column_gap_threshold: f64) -> Vec<f64> {
        self.gaps(column_gap_threshold)
            .into_iter()
            .map(|gap| (gap.start + gap.end) * 0.5)
            .collect()
    }

    fn gaps(&self, column_gap_threshold: f64) -> Vec<BandGap> {
        if self.spans.len() < 2 {
            return Vec::new();
        }

        let mut spans = self.spans.clone();
        spans.sort_by(|a, b| a.x.partial_cmp(&b.x).unwrap_or(Ordering::Equal));

        let mut gaps = Vec::new();
        let mut prev_right = spans[0].right();
        for span in spans.iter().skip(1) {
            let gap = span.x - prev_right;
            if gap >= column_gap_threshold {
                gaps.push(BandGap {
                    start: prev_right,
                    end: span.x,
                });
            }
            prev_right = prev_right.max(span.right());
        }

        gaps
    }

    fn split_by_boundaries(&self, boundaries: &[f64]) -> Vec<Vec<TextSpan>> {
        let mut columns = vec![Vec::new(); boundaries.len() + 1];
        for span in &self.spans {
            let center_x = span.x + span.width.max(span.estimated_width()) * 0.5;
            let column_idx = boundaries
                .iter()
                .position(|boundary| center_x < *boundary)
                .unwrap_or(boundaries.len());
            columns[column_idx].push(span.clone());
        }

        for spans in &mut columns {
            spans.sort_by(|a, b| a.x.partial_cmp(&b.x).unwrap_or(Ordering::Equal));
        }

        columns
    }

    fn fits_single_column(
        &self,
        boundaries: &[f64],
        region_left: f64,
        region_right: f64,
    ) -> Option<usize> {
        let mut column_idx: Option<usize> = None;
        for span in &self.spans {
            let left = span.x;
            let right = span.right();
            if boundaries
                .iter()
                .any(|boundary| left < *boundary && right > *boundary)
            {
                return None;
            }

            let center_x = left + (right - left) * 0.5;
            let idx = boundaries
                .iter()
                .position(|boundary| center_x < *boundary)
                .unwrap_or(boundaries.len());
            match column_idx {
                Some(existing) if existing != idx => return None,
                Some(_) => {}
                None => column_idx = Some(idx),
            }
        }
        let idx = column_idx?;
        let mut edges = Vec::with_capacity(boundaries.len() + 2);
        edges.push(region_left);
        edges.extend_from_slice(boundaries);
        edges.push(region_right);

        let column_width = (edges[idx + 1] - edges[idx]).max(0.0);
        if column_width <= 0.0 || self.width() > column_width * 0.8 {
            return None;
        }

        Some(idx)
    }
}

#[derive(Debug, Clone, Copy)]
struct BandGap {
    start: f64,
    end: f64,
}

/// The points a path segment is built from, in the order the segment draws
/// them. Control points included: a cubic lies inside the hull of its four
/// points, so a bound taken over all of them is never too small.
fn element_points(element: &PathEl) -> impl Iterator<Item = Point> {
    let mut points = [Point::ZERO; 3];
    let count = match *element {
        PathEl::MoveTo(p) | PathEl::LineTo(p) => {
            points[0] = p;
            1
        }
        PathEl::QuadTo(a, b) => {
            points[0] = a;
            points[1] = b;
            2
        }
        PathEl::CurveTo(a, b, c) => {
            points[0] = a;
            points[1] = b;
            points[2] = c;
            3
        }
        PathEl::ClosePath => 0,
    };
    points.into_iter().take(count)
}

/// A horizontal rule the page draws, in the page space the spans are measured
/// in (#545).
///
/// This is the one thing on the page that says "table" without guessing at it
/// from the text's own geometry. A width heuristic cannot tell a table from a
/// paper set in two columns -- both are slices of a band with a gutter between
/// them -- and the discriminator tried on slice width fixed the Isartor table
/// by breaking `tracemonkey`. The ruling lines are drawn by the document
/// itself, and a page of prose does not draw one between every pair of lines.
#[derive(Clone, Copy, Debug)]
struct HorizontalRule {
    left: f64,
    right: f64,
    y: f64,
}

/// A Device implementation that captures text from draw_glyph calls.
///
/// ANN[r17/TEX1][r17/TEX3] Space detection uses a multi-signal consensus
/// rather than a single geometric threshold. Three signals vote:
///   1. `pending_tj_offset`  — raw TJ backward shift surfaced by the
///      interpreter (confidence 0.95). This is the definitive word-break
///      signal used by pdftotext / MuPDF.
///   2. geometric gap        — measured horizontal distance between the
///      previous glyph's right edge and this glyph's origin (confidence
///      0.80). Compared against the running median glyph width rather
///      than a flat em-fraction so condensed/wide fonts are handled
///      uniformly.
///   3. character heuristic  — CamelCase transition or digit↔letter
///      transition at the merge point (confidence 0.60). Catches cases
///      where the writer relied on typography (e.g. table cells glued
///      with zero gap: `Qty1Price$5`).
///
/// A space is inserted when the weighted sum meets SPACE_CONSENSUS_THRESHOLD.
/// Span accumulation still merges adjacent glyphs into one TextSpan (TEX3)
/// so downstream reading-order logic sees logical text runs, not individual
/// character positions.
#[doc(hidden)]
pub struct TextExtractionDevice {
    spans: Vec<TextSpan>,
    last_y: f64,
    last_end_x: f64,
    /// TJ adjustment in raw 1/1000 em units since the last glyph was
    /// drawn. Positive values = backward shift (i.e., explicit horizontal
    /// space). Reset every time a glyph is drawn.
    pending_tj_offset: f32,
    /// Running sample of measured glyph widths used as the adaptive
    /// reference for the geometric gap signal. Cheap to maintain and
    /// avoids having to re-walk all spans per decision.
    glyph_widths: Vec<f64>,
    /// Cached median glyph width (kept fresh every `MEDIAN_REFRESH`
    /// insertions). Zero = not yet established, caller falls back to
    /// font-size scaling.
    cached_median_char_width: f64,
    /// Geometry extraction mode — Basic (advance bounds) or RichGeometry (tight bounds).
    geometry_mode: GeometryMode,
    /// Per-glyph data recorded during extraction for deferred tight-bounds
    /// computation. Only populated in RichGeometry mode. The index into this
    /// vec corresponds 1:1 with the glyph order across all spans.
    deferred_rich_glyphs: Vec<DeferredGlyph>,
    /// Hand back the ligature code points a font declared instead of the
    /// letters they stand for. Off, because a search box compares characters
    /// and U+FB03 is not `ffi` (#437); see [`crate::ligatures`].
    keep_ligatures: bool,
    /// The horizontal rules the page draws, in page space (#545).
    rules: Vec<HorizontalRule>,
    /// The clip boxes in force, innermost last, in page space (#545). Each
    /// entry is already intersected with the one below it, so the last is the
    /// box a path drawn now can reach.
    clip_stack: Vec<kurbo::Rect>,
    /// The marked-content sequences open right now, innermost last, and for
    /// each the `/ActualText` it carries -- `None` for the great majority
    /// that carry none (#550). The stack exists because the sequences nest:
    /// `6-2-11-7-3-t01-pass-e.pdf` opens a `/Span` with an MCID and a second
    /// `/Span` with the replacement inside it.
    marked_content: Vec<MarkedContent>,
    /// How many of the open sequences carry an `/ActualText`. Zero on all but
    /// a handful of documents, and the per-glyph bookkeeping below is skipped
    /// while it is.
    open_actual_texts: usize,
}

/// One open marked-content sequence.
#[derive(Clone, Debug)]
struct MarkedContent {
    /// The `/ActualText` it carries -- `None` for the great majority that
    /// carry none.
    actual: Option<ActualText>,
    /// Whether the content of this sequence has already been answered for --
    /// by a glyph drawn while it was open (through
    /// [`TextExtractionDevice::draw_glyph`]), or by a sequence nested in it
    /// whose own replacement was read at its `EMC`. A sequence that neither
    /// has is read at its own `EMC` (#549).
    ///
    /// The nested case is the one that is easy to miss: a glyphless
    /// replacement inside a glyphless replacement resolves at the inner `EMC`,
    /// and the outer sequence's characters stand for the same marks. Emitting
    /// both puts two conflicting readings of one thing in the text, and the
    /// innermost is the more specific statement. (codex, #549)
    content_spoken_for: bool,
}

/// An `/ActualText` replacement, and whether it has been spent.
///
/// The characters stand for the whole sequence, not for each glyph in it, so
/// they are emitted once -- at the first glyph, which is where the sequence
/// starts on the page -- and every later glyph of the sequence contributes
/// nothing to the text.
///
/// A sequence that draws no glyph at all is not a sequence with nothing to
/// say. `8.10.1-t02-fail-a.pdf` is two text widgets sharing one appearance
/// stream whose whole content is a filled rectangle inside
/// `/Form <</ActualText (some_value)>> BDC ... EMC`: the value is in the
/// replacement and nothing paints it, so a reader that waits for a glyph
/// comes away with nothing (#549). Such a sequence is emitted at its `EMC`,
/// at the place the page gives it.
#[derive(Clone, Debug)]
struct ActualText {
    text: String,
    spent: bool,
}

/// Lightweight glyph data recorded during extraction for deferred tight-bounds
/// computation. Avoids computing bounds on the hot path.
#[derive(Clone)]
struct DeferredGlyph {
    /// Transform coefficients [a,b,c,d,e,f] from composed (CTM * glyph_transform)
    coeffs: [f64; 6],
    /// Font size in points
    font_size: f64,
    /// Advance width in page-space points
    glyph_width: f64,
    /// Whether this glyph needs transform-then-bound (rotation/shear)
    needs_exact: bool,
    /// The glyph outline path in raw glyph space. Retained ONLY for
    /// rotated/sheared glyphs (`needs_exact`), where a tight bound requires
    /// bounding the transformed path; `None` for axis-aligned glyphs (the
    /// `font_bbox` suffices) and for ink-less glyphs (spaces, Type3).
    outline: Option<BezPath>,
    /// Pre-computed bounding box of the outline in raw glyph space. `None` when
    /// the glyph has no ink (space, Type3, or empty outline) → Estimate.
    font_bbox: Option<kurbo::Rect>,
}

const MEDIAN_REFRESH: usize = 32;

impl Default for TextExtractionDevice {
    fn default() -> Self {
        Self::new()
    }
}

impl TextExtractionDevice {
    /// Create a new text extraction device with Basic geometry (default).
    pub fn new() -> Self {
        Self::with_mode(GeometryMode::Basic)
    }

    /// Create a new text extraction device with the given geometry mode.
    pub fn with_mode(geometry_mode: GeometryMode) -> Self {
        Self {
            spans: Vec::new(),
            last_y: f64::NEG_INFINITY,
            last_end_x: f64::NEG_INFINITY,
            pending_tj_offset: 0.0,
            glyph_widths: Vec::new(),
            cached_median_char_width: 0.0,
            geometry_mode,
            deferred_rich_glyphs: Vec::new(),
            keep_ligatures: false,
            rules: Vec::new(),
            clip_stack: Vec::new(),
            marked_content: Vec::new(),
            open_actual_texts: 0,
        }
    }

    /// The `/ActualText` that stands in for the glyph about to be drawn, if
    /// an open marked-content sequence carries one that has not been used yet.
    ///
    /// The innermost sequence wins: a replacement inside a replacement is the
    /// more specific statement about those glyphs.
    fn take_actual_text(&mut self) -> Option<String> {
        let actual = self
            .marked_content
            .iter_mut()
            .rev()
            .find_map(|entry| entry.actual.as_mut())?;
        if actual.spent {
            return Some(String::new());
        }
        actual.spent = true;
        Some(actual.text.clone())
    }

    /// Where to put text the page carries without drawing a glyph for it.
    ///
    /// The innermost clip box when there is one: a Form XObject clips to its
    /// `/BBox`, so inside an annotation's appearance stream that box is the
    /// widget's own rectangle, which is exactly where the value belongs and
    /// what keeps two widgets sharing one appearance stream from landing on
    /// top of each other.
    ///
    /// Failing that, the pen: the text goes where the last glyph left off,
    /// which is where the document was drawing when the sequence opened.
    /// Dropping it instead would be the silent loss this whole change is
    /// about, and a page that has drawn nothing yet has no position to offer,
    /// so that one is left alone.
    fn place_for_glyphless_text(&self) -> Option<kurbo::Rect> {
        if let Some(clip) = self.clip_stack.last() {
            return Some(*clip);
        }

        let last = self.spans.last()?;

        if !self.last_end_x.is_finite() || !self.last_y.is_finite() {
            return None;
        }

        let height = last.font_size.max(1.0);

        Some(kurbo::Rect::new(
            self.last_end_x,
            self.last_y,
            self.last_end_x,
            self.last_y + height,
        ))
    }

    /// Record text that belongs to a place on the page rather than to a glyph.
    ///
    /// The box is all the geometry there is, so it is all the span claims: the
    /// width is the box's and the font size its height, which is the only size
    /// statement a rectangle makes. `char_bounds` stays empty -- there were no
    /// glyphs to bound -- and the readers of that field already fall back to
    /// the character count.
    fn push_placed_span(&mut self, text: &str, rect: kurbo::Rect) {
        if text.is_empty() {
            return;
        }

        let height = if rect.height().is_finite() && rect.height() > 0.0 {
            rect.height()
        } else {
            0.0
        };
        let width = if rect.width().is_finite() && rect.width() > 0.0 {
            rect.width()
        } else {
            0.0
        };

        self.spans.push(TextSpan {
            text: text.to_string(),
            x: rect.x0,
            y: rect.y0,
            width,
            height,
            font_size: height,
            font_name: None,
            is_bold: false,
            is_italic: false,
            color: None,
            width_source: WidthSource::Estimate,
            char_bounds: Vec::new(),
            // The placement is a real statement about where these characters
            // are, in the same form a glyph's is -- scale on the diagonal,
            // position in the last pair -- so a caller that lays the text back
            // out has what it needs, and the coverage gate over these two
            // fields stays a gate rather than acquiring an exception.
            transform: Some([height / 1000.0, 0.0, 0.0, height / 1000.0, rect.x0, rect.y0]),
            font_weight: None,
            is_serif: None,
            is_monospace: None,
            // Filled: a field value is painted, not stroked and not hidden.
            render_mode: Some(0),
            font_metrics: None,
            geometry_mode: self.geometry_mode,
            bounds_source: BoundsSource::Estimate,
            tight_char_bounds: Vec::new(),
            glyph_advances: Vec::new(),
            glyph_bounds_sources: Vec::new(),
        });

        // The pen follows, so that anything drawn after this reads its gap
        // against where the placed text ended rather than against a glyph
        // three widgets back.
        self.last_y = rect.y0;
        self.last_end_x = rect.x1;
        self.pending_tj_offset = 0.0;
    }

    /// Hand back the ligature code points the font declared -- `ffi` rather than
    /// `ffi` -- from [`Self::into_text`].
    ///
    /// The default folds, because the extracted string is read by a search
    /// index, a RAG chunker or a person pasting a word into a search box, and
    /// none of them will match a ligature code point against the letters
    /// somebody types. Set this when the caller wants the file's own
    /// characters back: a typesetting tool, or a comparison against the
    /// content stream. Structured output ([`Self::into_blocks`]) is unfolded
    /// either way.
    #[must_use]
    pub fn keep_ligatures(mut self, keep: bool) -> Self {
        self.keep_ligatures = keep;
        self
    }

    /// Refresh the cached median char width. Called lazily from
    /// `draw_glyph` to keep the hot path cheap.
    fn refresh_median_char_width(&mut self) {
        if self.glyph_widths.is_empty() {
            self.cached_median_char_width = 0.0;
            return;
        }
        let mut sorted = self.glyph_widths.clone();
        sorted.sort_by(|a, b| a.partial_cmp(b).unwrap_or(Ordering::Equal));
        self.cached_median_char_width = sorted[sorted.len() / 2];
    }

    /// Move the pen to the end of the glyph just drawn.
    ///
    /// ANN[r17/TEX5] A combining mark -- a Hebrew point, an Arabic harakat --
    /// is drawn on the glyph before it and leaves the pen where it was. Letting
    /// it move the pen back to its own origin makes the next letter look an
    /// advance away, and that gap then reads as a word break: `שָׁלוֹם` came
    /// apart into `שָׁל` and `וֹם` (#436). The declared advance cannot answer
    /// this, because `glyph_width_and_source` clamps a zero one up to a quarter
    /// of the font size before anything sees it.
    fn advance_pen(&mut self, text: &str, glyph_end_x: f64) {
        if !crate::bidi::is_only_marks(text) {
            self.last_end_x = glyph_end_x;
        }
    }

    /// Decide whether a space should be glued between two glyphs within
    /// the same span. Returns (insert_space, start_new_span).
    fn evaluate_space_consensus(
        &self,
        gap: f64,
        font_size: f64,
        prev_text: &str,
        next_text: &str,
    ) -> bool {
        let mut confidence = 0.0;

        // Signal 1 — TJ offset (highest confidence). Raw units; a full
        // space is ~250. Anything over TJ_SPACE_THRESHOLD_UNITS counts.
        if self.pending_tj_offset.abs() >= TJ_SPACE_THRESHOLD_UNITS {
            confidence += TJ_SIGNAL_WEIGHT;
        }

        // Signal 2 — geometric gap. Prefer the adaptive median-char-width
        // reference; fall back to font-size when the median hasn't been
        // established yet (first few glyphs on a page).
        let gap_reference = if self.cached_median_char_width > 0.0 {
            self.cached_median_char_width * GAP_TO_MEDIAN_CHAR_FRACTION
        } else {
            font_size * GAP_TO_FONT_SIZE_FALLBACK_FRACTION
        };
        if gap > gap_reference {
            confidence += GAP_SIGNAL_WEIGHT;
        }

        // Signal 3 — character-class transitions. Only checked when the
        // previous span ends with a character and the incoming text starts
        // with one; avoids double-counting with punctuation.
        if let (Some(prev_last), Some(next_first)) =
            (prev_text.chars().last(), next_text.chars().next())
        {
            let camel = prev_last.is_lowercase() && next_first.is_uppercase();
            let digit_to_letter = prev_last.is_ascii_digit() && next_first.is_alphabetic();
            let letter_to_digit = prev_last.is_alphabetic() && next_first.is_ascii_digit();
            if camel || digit_to_letter || letter_to_digit {
                confidence += HEURISTIC_SIGNAL_WEIGHT;
            }
        }

        confidence >= SPACE_CONSENSUS_THRESHOLD
    }

    /// Keep a drawn path when it is a horizontal rule (#545).
    ///
    /// The whole of the page's graphics arrives here and almost none of it is
    /// kept: what is, is ink that is a line -- flat enough not to be a box and
    /// long enough to separate two rows -- recorded in the page space the
    /// spans already live in, so the two can be compared without a second
    /// coordinate system to keep in step. The box is the transformed bounding
    /// box, which for a rotated path is the box around it and therefore too
    /// tall to be a rule: a rule on a turned page is not read as one, and that
    /// is the safe way round.
    ///
    /// A stroke is measured on its centreline, since that is the path the
    /// device is given and the weight is a property of the pen. A heavy rule is
    /// still a rule, and it still lies where its centreline lies.
    fn record_rule(&mut self, path: &BezPath, transform: Affine) {
        // The cap is asked at the door AND at every push. One path may hold
        // hundreds of subpaths, so a check that runs once per call is not a
        // bound on anything: it lets a single compound path put thousands of
        // entries in a vector `region_is_ruled` then walks per band.
        if self.rules.len() >= MAX_RECORDED_RULES {
            return;
        }
        // SUBPATH BY SUBPATH, because a producer is free to draw all of a
        // table's rules in one path, and a box around the lot of them is a box
        // and not a line. The bound is taken over the points a segment is made
        // of, curve controls included -- a curve lies inside its own hull, so
        // the box is never too small, and the arithmetic is a comparison per
        // point rather than solving each curve for its extremes. On the slowest
        // document of the gate set, which draws a figure of several thousand
        // segments, exact curve bounds cost 7% of its 3.3 s; this costs 1.6%.
        // WHAT IS DRAWN IS NOT WHAT IS SEEN. A Form XObject's `/BBox` reaches
        // this device as a clip and the geometry inside it unclipped, so a line
        // ruled across one cell of a form can arrive as a line across the page.
        // Two of those are enough for `region_is_ruled` to refuse a column cut
        // that should have been taken, so the extent recorded is the visible
        // one.
        let clip = self.clip_stack.last().copied();
        let mut lo = (f64::INFINITY, f64::INFINITY);
        let mut hi = (f64::NEG_INFINITY, f64::NEG_INFINITY);
        let flush = |lo: &mut (f64, f64), hi: &mut (f64, f64), rules: &mut Vec<HorizontalRule>| {
            let (mut left, mut right) = (lo.0, hi.0);
            let (mut bottom, mut top) = (lo.1, hi.1);
            if let Some(clip) = clip {
                left = left.max(clip.x0);
                right = right.min(clip.x1);
                bottom = bottom.max(clip.y0);
                top = top.min(clip.y1);
            }
            if lo.0.is_finite()
                && rules.len() < MAX_RECORDED_RULES
                && bottom <= top
                && hi.1 - lo.1 <= RULE_MAX_THICKNESS
                && right - left >= RULE_MIN_LENGTH
            {
                rules.push(HorizontalRule {
                    left,
                    right,
                    y: (lo.1 + hi.1) * 0.5,
                });
            }
            *lo = (f64::INFINITY, f64::INFINITY);
            *hi = (f64::NEG_INFINITY, f64::NEG_INFINITY);
        };

        for element in path.elements() {
            if matches!(element, PathEl::MoveTo(_) | PathEl::ClosePath) {
                flush(&mut lo, &mut hi, &mut self.rules);
            }
            for point in element_points(element) {
                let p = transform * point;
                lo = (lo.0.min(p.x), lo.1.min(p.y));
                hi = (hi.0.max(p.x), hi.1.max(p.y));
            }
        }
        flush(&mut lo, &mut hi, &mut self.rules);
    }

    /// Consume the device and return extracted text as a single string.
    pub fn into_text(mut self) -> String {
        if self.geometry_mode == GeometryMode::RichGeometry {
            self.compute_tight_bounds();
        }
        let keep_ligatures = self.keep_ligatures;
        let rules = std::mem::take(&mut self.rules);
        let blocks = group_spans_into_blocks(self.spans, &rules);
        let lines: Vec<String> = blocks.iter().map(|b| b.text()).collect();
        let stitched = stitch_hyphenated_lines(&lines);
        let text = normalize_text_output(&stitched);
        if keep_ligatures {
            return text;
        }
        // Folding last, on the assembled page: the spans keep the characters
        // their glyphs declared, so `into_blocks` is untouched by any of this.
        match crate::ligatures::fold(&text) {
            Cow::Borrowed(_) => text,
            Cow::Owned(folded) => folded,
        }
    }

    /// Consume the device and return text blocks.
    pub fn into_blocks(mut self) -> Vec<TextBlock> {
        if self.geometry_mode == GeometryMode::RichGeometry {
            self.compute_tight_bounds();
        }
        let rules = std::mem::take(&mut self.rules);
        group_spans_into_blocks(self.spans, &rules)
    }

    /// Consume the device and return raw spans.
    #[allow(dead_code)]
    pub(crate) fn into_spans(mut self) -> Vec<TextSpan> {
        if self.geometry_mode == GeometryMode::RichGeometry {
            self.compute_tight_bounds();
        }
        self.spans
    }

    /// Record glyph-level data for deferred tight-bounds computation.
    /// Called from draw_glyph in RichGeometry mode only.
    fn record_deferred_glyph(
        &mut self,
        glyph: &Glyph<'_>,
        composed: &Affine,
        font_size: f64,
        glyph_width: f64,
    ) {
        let coeffs = composed.as_coeffs();
        let is_rotated = coeffs[1].abs() > ROTATION_EPSILON || coeffs[2].abs() > ROTATION_EPSILON;
        let is_sheared = (coeffs[0] - coeffs[3]).abs() > SHEAR_EPSILON;
        let needs_exact = is_rotated || is_sheared;

        // Capture the glyph's ink bbox in raw glyph space. The full outline path
        // is retained only when `needs_exact` (rotated/sheared), so a tight bound
        // can bound the transformed path; axis-aligned glyphs keep only the bbox
        // (enveloping its transformed corners is exact) to bound memory on large
        // pages. Ink-less glyphs (spaces, Type3) carry no bbox → Estimate later.
        let (outline, font_bbox) = match glyph {
            Glyph::Outline(o) => {
                let path = o.outline();
                let bb = path.bounding_box();
                if bb.width() <= 0.0 && bb.height() <= 0.0 {
                    (None, None)
                } else if needs_exact {
                    (Some(path), Some(bb))
                } else {
                    (None, Some(bb))
                }
            }
            Glyph::Type3(_) => (None, None),
        };

        self.deferred_rich_glyphs.push(DeferredGlyph {
            coeffs,
            font_size,
            glyph_width,
            needs_exact,
            outline,
            font_bbox,
        });
    }

    /// Compute tight bounds for all recorded glyphs and populate the spans.
    /// Called once after all glyphs have been extracted.
    fn compute_tight_bounds(&mut self) {
        let deferred = std::mem::take(&mut self.deferred_rich_glyphs);
        if deferred.is_empty() {
            return;
        }

        let mut idx = 0usize;

        for span in &mut self.spans {
            let n = span.char_bounds.len();
            if n == 0 {
                continue;
            }

            let mut span_bounds_source = BoundsSource::Advance;

            for _gi in 0..n {
                if idx >= deferred.len() {
                    break;
                }
                let dg = &deferred[idx];
                idx += 1;

                let composed = Affine::new(dg.coeffs);
                let (tight_bound, source) = if let Some(font_bbox) = dg.font_bbox {
                    // Glyph has ink. The outline/bbox is in raw glyph space and
                    // `composed` (CTM * glyph_transform) maps it straight to page
                    // space — exactly as the renderer fills the raw outline, with
                    // NO upem pre-scaling. Applying any extra font_size/1000 here
                    // would double-scale the bound.
                    if dg.needs_exact {
                        // Rotated/sheared: bound the transformed outline path so
                        // the box stays tight (the transformed bbox would be
                        // looser). Falls back to enveloping the bbox corners if
                        // the path was not retained.
                        let page_bbox = match dg.outline {
                            Some(ref path) => (composed * path.clone()).bounding_box(),
                            None => {
                                let raw = [font_bbox.x0, font_bbox.y0, font_bbox.x1, font_bbox.y1];
                                let b = transform_bbox_corners(&raw, &composed);
                                kurbo::Rect::new(b[0], b[1], b[2], b[3])
                            }
                        };
                        (
                            [page_bbox.x0, page_bbox.y0, page_bbox.x1, page_bbox.y1],
                            BoundsSource::Tight,
                        )
                    } else {
                        // Axis-aligned scale + translate: enveloping the
                        // transformed bbox corners is exact.
                        let raw = [font_bbox.x0, font_bbox.y0, font_bbox.x1, font_bbox.y1];
                        (transform_bbox_corners(&raw, &composed), BoundsSource::Tight)
                    }
                } else {
                    // No ink (space, Type3, missing outline): fall back to the
                    // advance box in page space, in the same frame as the span's
                    // char_bounds ([x, y, x + advance, y + font_size]).
                    let x = dg.coeffs[4];
                    let y = dg.coeffs[5];
                    (
                        [x, y, x + dg.glyph_width, y + dg.font_size],
                        BoundsSource::Estimate,
                    )
                };

                span.tight_char_bounds.push(tight_bound);
                span.glyph_advances.push(dg.glyph_width);
                span.glyph_bounds_sources.push(source);

                if source == BoundsSource::Tight && span_bounds_source != BoundsSource::Estimate {
                    span_bounds_source = BoundsSource::Tight;
                } else if source == BoundsSource::Estimate {
                    span_bounds_source = BoundsSource::Estimate;
                }
            }

            span.bounds_source = span_bounds_source;
        }
    }
}

impl Device<'_> for TextExtractionDevice {
    fn set_soft_mask(&mut self, _: Option<SoftMask<'_>>) {}
    fn set_blend_mode(&mut self, _: BlendMode) {}
    fn draw_path(&mut self, path: &BezPath, transform: Affine, _: &Paint<'_>, _: &PathDrawMode) {
        self.record_rule(path, transform);
    }
    fn push_clip_path(&mut self, clip_path: &ClipPath) {
        // The clip arrives in page space already -- `render.rs` applies it
        // under the identity transform -- so its box needs no transform here.
        // The box and not the region: a clip shaped like a star still reaches
        // only its own bounding box, so this over-states what is visible and
        // never under-states it, which is the direction that cannot invent a
        // rule.
        let box_of_clip = clip_path.path.bounding_box();
        let effective = match self.clip_stack.last() {
            Some(outer) => outer.intersect(box_of_clip),
            None => box_of_clip,
        };
        self.clip_stack.push(effective);
    }
    fn push_transparency_group(&mut self, _: f32, _: Option<SoftMask<'_>>, _: BlendMode) {}
    fn draw_image(&mut self, _: Image<'_, '_>, _: Affine) {}
    fn pop_clip_path(&mut self) {
        self.clip_stack.pop();
    }
    fn pop_transparency_group(&mut self) {}
    fn begin_marked_content(&mut self, _tag: &[u8], _mcid: Option<i32>, actual_text: Option<&str>) {
        let actual = actual_text.map(|text| ActualText {
            text: text.to_string(),
            spent: false,
        });

        if actual.is_some() {
            self.open_actual_texts += 1;
        }

        self.marked_content.push(MarkedContent {
            actual,
            content_spoken_for: false,
        });
    }
    fn end_marked_content(&mut self) {
        // A content stream may close a sequence it never opened -- the
        // operators are not balanced by anything that checks. Popping an
        // empty stack is the only safe reading of that.
        let Some(entry) = self.marked_content.pop() else {
            return;
        };

        let Some(actual) = entry.actual else {
            return;
        };

        self.open_actual_texts -= 1;

        // Said already by a glyph of this sequence, or by a sequence nested in
        // it -- in which case this replacement covers marks that have had
        // their say and a second copy here would double or contradict them.
        if actual.spent || entry.content_spoken_for {
            return;
        }

        // This sequence's content is answered for here, so every sequence it
        // sits inside is too: their characters stand for the same marks, and
        // the innermost statement is the specific one. Marked before the empty
        // check below, because `/ActualText ()` is an answer -- "these marks
        // stand for nothing" -- and not an absence of one.
        for open in &mut self.marked_content {
            open.content_spoken_for = true;
        }

        // `/ActualText ()` is a producer saying this content stands for no
        // characters at all, and that answer is kept.
        if actual.text.is_empty() {
            return;
        }

        if let Some(rect) = self.place_for_glyphless_text() {
            self.push_placed_span(&actual.text, rect);
        }
    }

    fn draw_placed_text(&mut self, text: &str, rect: kurbo::Rect) {
        self.push_placed_span(text, rect);
    }

    fn draw_glyph(
        &mut self,
        glyph: &Glyph<'_>,
        transform: Affine,
        glyph_transform: Affine,
        paint: &Paint<'_>,
        draw_mode: &GlyphDrawMode,
    ) {
        // Every sequence open right now has a glyph in it, whichever of them
        // the replacement below is taken from. Skipped entirely while nothing
        // open carries a replacement, which is every page of almost every
        // document.
        if self.open_actual_texts > 0 {
            for entry in &mut self.marked_content {
                entry.content_spoken_for = true;
            }
        }

        let own_text = || match glyph.as_unicode() {
            Some(BfString::Char(c)) => Some(c.to_string()),
            Some(BfString::String(s)) => Some(s),
            None => None,
        };

        // A marked-content sequence carrying /ActualText says what its glyphs
        // stand for, and that statement outranks whatever they decode to
        // (#550). The first glyph of the sequence carries the whole
        // replacement; the rest of them carry nothing, so the characters are
        // not repeated once per glyph.
        //
        // A glyph carrying nothing is still a glyph. It was drawn, it took
        // width, and the text after the sequence is placed against where it
        // ended -- so it runs the pen and the TJ bookkeeping below and only
        // then leaves, rather than returning here. Measuring the next word's
        // gap from the first glyph of a three-glyph replacement is how a
        // spurious space gets into the text.
        let (text, suppressed) = match self.take_actual_text() {
            Some(replacement) if replacement.is_empty() => (own_text().unwrap_or_default(), true),
            Some(replacement) => (replacement, false),
            None => match own_text() {
                Some(text) => (text, false),
                None => return,
            },
        };

        let composed = transform * glyph_transform;
        let coeffs = composed.as_coeffs();
        let x = coeffs[4];
        let y = coeffs[5];
        let glyph_scale = (coeffs[0].powi(2) + coeffs[1].powi(2)).sqrt().abs();
        let font_size = glyph_scale * 1000.0;

        // G2: distinguish real advance (Metric) from estimate (Estimate).
        let (glyph_width, glyph_ws) = glyph_width_and_source(glyph, font_size);
        let glyph_end_x = x + glyph_width;
        let glyph_bound = [x, y, glyph_end_x, y + font_size];

        let style = derive_glyph_style(glyph);
        let color = paint_to_rgba(paint);

        // M3: record glyph data for deferred tight-bounds computation.
        if self.geometry_mode == GeometryMode::RichGeometry {
            self.record_deferred_glyph(glyph, &composed, font_size, glyph_width);
        }

        // ANN[r17/TEX4] Feed the running sample used to derive the adaptive
        // median character width. Capped to protect against pathological
        // pages with hundreds of thousands of glyphs.
        if self.glyph_widths.len() < 4096 {
            self.glyph_widths.push(glyph_width);
            if self.glyph_widths.len().is_multiple_of(MEDIAN_REFRESH) {
                self.refresh_median_char_width();
            }
        }

        // The glyph whose characters an /ActualText already spoke for: the pen
        // moves, the TJ signal is consumed, and no span is touched.
        if suppressed {
            self.last_y = y;
            self.advance_pen(&text, glyph_end_x);
            self.pending_tj_offset = 0.0;
            return;
        }

        let same_line = (y - self.last_y).abs() <= font_size.max(BAND_Y_TOLERANCE) * 0.35;
        let gap = x - self.last_end_x;
        let adjacent = same_line && gap >= -font_size * 0.25 && gap < font_size * 0.5;

        // G1: only merge into the previous span when font + style + color
        // match. Otherwise the editor's style toolbar would render the wrong
        // state for the cursor position.
        let style_matches = self
            .spans
            .last()
            .map(|last| {
                last.font_name == style.font_name
                    && last.is_bold == style.is_bold
                    && last.is_italic == style.is_italic
                    && last.color == color
            })
            .unwrap_or(false);

        if adjacent && !self.spans.is_empty() && style_matches {
            // ANN[r17/TEX1] Multi-signal consensus replaces the prior
            // single-threshold rule (`gap > 0.15 * font_size`). The
            // consensus evaluates TJ offset, geometric gap, and
            // character-class transitions; a space is inserted only
            // when the weighted sum meets SPACE_CONSENSUS_THRESHOLD.
            // Decision is computed before the mutable borrow of `last`
            // to keep the borrow checker happy.
            let want_space = {
                let last = self.spans.last().expect("checked non-empty");
                !last.text.ends_with(' ')
                    && !text.starts_with(' ')
                    && self.evaluate_space_consensus(gap, font_size, &last.text, &text)
            };
            let last = self.spans.last_mut().expect("checked non-empty");
            if want_space {
                last.text.push(' ');
            }
            last.text.push_str(&text);
            last.width = last.width.max(glyph_end_x - last.x);
            last.height = last.height.max(font_size);
            // G2: append char_bound; downgrade width_source if this glyph is Estimate.
            last.char_bounds.push(glyph_bound);
            if glyph_ws == WidthSource::Estimate {
                last.width_source = WidthSource::Estimate;
            }
            self.last_y = y;
            self.advance_pen(&text, glyph_end_x);
            // ANN[r17/TEX1] Consume the TJ signal: it only counts for
            // the one merge it preceded.
            self.pending_tj_offset = 0.0;
            return;
        }

        self.last_y = y;
        self.advance_pen(&text, glyph_end_x);
        // ANN[r17/TEX1] Non-adjacent glyph starts a fresh span, so any
        // pending TJ offset is about within-span word breaks and no longer
        // meaningful here.
        self.pending_tj_offset = 0.0;

        let span = TextSpan {
            text,
            x,
            y,
            width: glyph_width,
            height: font_size,
            font_size,
            font_name: style.font_name,
            is_bold: style.is_bold,
            is_italic: style.is_italic,
            color,
            width_source: glyph_ws,
            char_bounds: vec![glyph_bound],
            transform: Some(coeffs),
            font_weight: style.font_weight,
            is_serif: style.is_serif,
            is_monospace: style.is_monospace,
            render_mode: Some(render_mode_from_draw_mode(draw_mode)),
            font_metrics: style.font_metrics,
            geometry_mode: self.geometry_mode,
            bounds_source: BoundsSource::Advance,
            tight_char_bounds: Vec::new(),
            glyph_advances: Vec::new(),
            glyph_bounds_sources: Vec::new(),
        };

        self.spans.push(span);
    }

    // ANN[r17/TEX1] Record TJ offsets. Accumulate because a single
    // inter-substring gap may be expressed as multiple numeric entries
    // (rare, but legal per PDF §9.4.3). The next draw_glyph consumes
    // the sum.
    fn text_adjustment(&mut self, amount: f32) {
        self.pending_tj_offset += amount;
    }
}

/// Style metadata derived from a `Glyph` for the G1 text-run extension.
#[derive(Debug, Default, Clone)]
struct GlyphStyle {
    font_name: Option<String>,
    is_bold: bool,
    is_italic: bool,
    /// Numeric weight from embedded font data, if available.
    font_weight: Option<u16>,
    /// Serif flag from embedded font data, if available.
    is_serif: Option<bool>,
    /// Monospace flag from embedded font data, if available.
    is_monospace: Option<bool>,
    /// Vertical font metrics from embedded font data, if available.
    font_metrics: Option<FontMetrics>,
}

/// Strip a 6-character subset prefix (e.g. `AAAAAA+Helvetica` → `Helvetica`).
fn strip_subset_prefix(name: &str) -> &str {
    match name.split_once('+') {
        Some((prefix, rest)) if prefix.len() == 6 => rest,
        _ => name,
    }
}

/// Heuristic style inference from a PostScript name when no descriptor
/// flags are reachable. Matches the same rules `pdf-interpret` uses in
/// `FallbackFontQuery::new`.
fn name_style_hints(name: &str) -> (bool, bool) {
    let lower = name.to_ascii_lowercase();
    let italic = lower.contains("italic") || lower.contains("oblique") || lower.contains("slant");
    let bold = lower.contains("bold")
        || lower.contains("demi")
        || lower.contains("semibold")
        || lower.contains("heavy")
        || lower.contains("black");
    (bold, italic)
}

fn derive_glyph_style(glyph: &Glyph<'_>) -> GlyphStyle {
    match glyph {
        Glyph::Outline(outline) => {
            if let Some(data) = outline.font_data() {
                let raw = data.postscript_name.as_deref().unwrap_or("");
                let name = strip_subset_prefix(raw).to_string();
                let weight_bold = data.weight.is_some_and(|w| w >= 700);
                let (name_bold, name_italic) = name_style_hints(&name);
                GlyphStyle {
                    font_name: if name.is_empty() { None } else { Some(name) },
                    is_bold: weight_bold || name_bold,
                    is_italic: data.is_italic || name_italic,
                    font_weight: data.weight.map(|w| w.clamp(1, 1000) as u16),
                    is_serif: Some(data.is_serif),
                    is_monospace: Some(data.is_monospace),
                    font_metrics: match (data.ascent, data.descent) {
                        (Some(ascent), Some(descent)) => Some(FontMetrics {
                            ascent,
                            descent,
                            cap_height: data.cap_height,
                            x_height: data.x_height,
                        }),
                        _ => None,
                    },
                }
            } else {
                // Type1 / non-embedded font — descriptor not surfaced
                // via font_data(). Fall back to the name-only
                // accessor which works for standard-14 fallbacks,
                // and use the canonical Standard-14 AFM metrics
                // when the outline font resolves to a known face.
                let raw = outline.postscript_name().unwrap_or_default();
                let name = strip_subset_prefix(&raw).to_string();
                let (name_bold, name_italic) = name_style_hints(&name);
                let metrics = outline.font_metrics().map(|(a, d, c, x)| FontMetrics {
                    ascent: a,
                    descent: d,
                    cap_height: c,
                    x_height: x,
                });
                GlyphStyle {
                    font_name: if name.is_empty() { None } else { Some(name) },
                    is_bold: name_bold,
                    is_italic: name_italic,
                    // Non-embedded font: descriptor metrics are not reachable.
                    font_weight: None,
                    is_serif: None,
                    is_monospace: None,
                    font_metrics: metrics,
                }
            }
        }
        Glyph::Type3(_) => GlyphStyle::default(),
    }
}

fn paint_to_rgba(paint: &Paint<'_>) -> Option<[u8; 4]> {
    match paint {
        Paint::Color(c) => Some(c.to_rgba().to_rgba8()),
        Paint::Pattern(_) => None,
    }
}

/// Map the renderer's coarse glyph draw mode to a PDF text render-mode code.
///
/// NOTE: the interpreter collapses the eight PDF text render modes (Tr 0–7)
/// into three visibility classes, so only `{0, 1, 3}` are representable here —
/// fill (0), stroke (1), and invisible (3). The fill+stroke and clip modes
/// (2, 4–7) are not distinguished. This is sufficient to identify and filter
/// invisible (mode-3) OCR/overlay text; recovering the full `Tr` range would
/// require threading it through the `Device` trait (out of scope).
fn render_mode_from_draw_mode(mode: &GlyphDrawMode) -> u8 {
    match mode {
        GlyphDrawMode::Fill => 0,
        GlyphDrawMode::Stroke(_) => 1,
        GlyphDrawMode::Invisible => 3,
    }
}

#[cfg(test)]
mod render_mode_tests {
    use super::render_mode_from_draw_mode;
    use pdf_render::pdf_interpret::{GlyphDrawMode, StrokeProps};

    #[test]
    fn render_mode_is_only_zero_one_three() {
        assert_eq!(render_mode_from_draw_mode(&GlyphDrawMode::Fill), 0);
        assert_eq!(
            render_mode_from_draw_mode(&GlyphDrawMode::Stroke(StrokeProps::default())),
            1
        );
        assert_eq!(render_mode_from_draw_mode(&GlyphDrawMode::Invisible), 3);
        // Exhaustive: the mapping only ever yields 0, 1, or 3 — never 2 or 4–7.
        for m in [
            GlyphDrawMode::Fill,
            GlyphDrawMode::Stroke(StrokeProps::default()),
            GlyphDrawMode::Invisible,
        ] {
            assert!(matches!(render_mode_from_draw_mode(&m), 0 | 1 | 3));
        }
    }
}

/// Returns `(advance_in_user_space, WidthSource)` for a glyph.
///
/// Uses the real advance from `OutlineGlyph::advance_width()` when available
/// (returns `WidthSource::Metric`); falls back to 50% em otherwise
/// (`WidthSource::Estimate`). The result is clamped to at least 25% em so
/// invisible-glyph outliers do not collapse spans.
fn glyph_width_and_source(glyph: &Glyph<'_>, font_size: f64) -> (f64, WidthSource) {
    match glyph {
        Glyph::Outline(outline) => {
            if let Some(w) = outline.advance_width() {
                let advance = (w as f64 / 1000.0 * font_size).max(font_size * 0.25);
                (advance, WidthSource::Metric)
            } else {
                (font_size * 0.5, WidthSource::Estimate)
            }
        }
        Glyph::Type3(_) => (font_size * 0.5, WidthSource::Estimate),
    }
}

/// Two baselines run in the same direction when they are within half a degree
/// of each other. A page draws a run of text with one text matrix, so the
/// glyphs of one run agree to the last bit; the tolerance is there for the
/// rounding a document writes its matrix with (`0.7071 -0.7071`), not for
/// telling two angles apart.
const DIRECTION_TOLERANCE_RAD: f64 = 0.008_727; // 0.5 degrees

/// A baseline direction: a unit vector in page space.
type Direction = (f64, f64);

/// A span taken out of the page's blocks, carrying the position in the page's
/// order that the block it came from held.
type PlacedSpan = (usize, TextSpan);

/// The direction the baseline of a glyph runs in, as a unit vector in page
/// space: the first column of its composed transform, normalised.
///
/// This is what the text matrix rotates. `(1, 0)` for upright text, `(0, 1)`
/// for a page's 90-degree marginalia, `(0.7071, -0.7071)` for the diagonal
/// watermark of pdfjs issue17069 -- and `(1, 0)` again for a degenerate
/// transform, which has no direction to speak of and may as well read as the
/// page's own (#435).
fn baseline_direction(coeffs: &[f64; 6]) -> Direction {
    let (a, b) = (coeffs[0], coeffs[1]);
    let length = (a * a + b * b).sqrt();
    if length <= f64::EPSILON {
        (1.0, 0.0)
    } else {
        (a / length, b / length)
    }
}

/// The direction a span's baseline runs in. A span not built from a glyph
/// carries no transform and reads as upright.
fn span_direction(span: &TextSpan) -> Direction {
    span.transform
        .as_ref()
        .map(baseline_direction)
        .unwrap_or((1.0, 0.0))
}

/// The angle between two unit vectors, in radians, without a sign.
fn direction_gap(lhs: Direction, rhs: Direction) -> f64 {
    let cross = lhs.0 * rhs.1 - lhs.1 * rhs.0;
    let dot = lhs.0 * rhs.0 + lhs.1 * rhs.1;
    cross.atan2(dot).abs()
}

fn directions_agree(lhs: Direction, rhs: Direction) -> bool {
    direction_gap(lhs, rhs) <= DIRECTION_TOLERANCE_RAD
}

/// How far along its own baseline, and how far across it, a span's origin sits.
///
/// The pair is the page's `(x, y)` seen from the baseline: `along` grows in
/// reading direction, `across` grows to the left of it, so a line of rotated
/// text has one `across` and a range of `along` exactly as an upright line has
/// one `y` and a range of `x`.
fn baseline_coordinates(span: &TextSpan, direction: Direction) -> (f64, f64) {
    (
        span.x * direction.0 + span.y * direction.1,
        -span.x * direction.1 + span.y * direction.0,
    )
}

/// Where a span stops along its own baseline.
///
/// `width` is the widest a glyph of the span reached in PAGE x, which is the
/// along-baseline extent only while the text is upright: a run drawn at thirty
/// degrees advances `cos 30` of its length in x, and reading that as the length
/// leaves an eighth of the run behind it as phantom gap -- enough to put a
/// space in the middle of a word where a style change ends one span and starts
/// the next. So the last glyph's own bound says where the run stopped, and
/// `width` answers only when there are no bounds to ask (every hand-built span)
/// or when it reaches further, which is what an overprinted or backwards-drawn
/// run does and what the seam allowance of #432 is measured against (#435).
fn baseline_end(span: &TextSpan, direction: Direction) -> f64 {
    let start = baseline_coordinates(span, direction).0;
    let from_width = start + span.width;
    match span.char_bounds.last() {
        Some(bound) => {
            let last = bound[0] * direction.0 + bound[1] * direction.1;
            let advance = bound[2] - bound[0];
            (last + advance).max(from_width)
        }
        None => from_width,
    }
}

/// Threshold for detecting rotation or shear in the composed transform.
/// Any |b| or |c| above this is treated as rotation; any difference between
/// a and d above this is treated as non-uniform scale (= shear potential).
const ROTATION_EPSILON: f64 = 1e-6;
const SHEAR_EPSILON: f64 = 1e-3;

/// Transform a bounding-box `[x0,y0,x1,y1]` (in local space) to page space
/// by applying the affine to its four corners and taking the envelope.
fn transform_bbox_corners(local_bbox: &[f64; 4], affine: &Affine) -> [f64; 4] {
    use kurbo::Point;
    let corners = [
        *affine * Point::new(local_bbox[0], local_bbox[1]),
        *affine * Point::new(local_bbox[2], local_bbox[1]),
        *affine * Point::new(local_bbox[2], local_bbox[3]),
        *affine * Point::new(local_bbox[0], local_bbox[3]),
    ];
    let x0 = corners.iter().map(|p| p.x).fold(f64::INFINITY, f64::min);
    let y0 = corners.iter().map(|p| p.y).fold(f64::INFINITY, f64::min);
    let x1 = corners
        .iter()
        .map(|p| p.x)
        .fold(f64::NEG_INFINITY, f64::max);
    let y1 = corners
        .iter()
        .map(|p| p.y)
        .fold(f64::NEG_INFINITY, f64::max);
    [x0, y0, x1, y1]
}

/// Collapse fake-bold / overprint duplicates inside one band.
///
/// Real-word corpus failures such as 0105.pdf draw the same text several times
/// with sub-point x drift to simulate heavier weight. Text extraction should
/// keep the most informative span once rather than concatenate every overprint.
fn collapse_overprinted_spans(spans: &mut Vec<TextSpan>) {
    if spans.len() < 2 {
        return;
    }

    let mut deduped: Vec<TextSpan> = Vec::with_capacity(spans.len());
    for span in spans.drain(..) {
        if let Some(last) = deduped.last_mut() {
            if spans_are_overprint_duplicates(last, &span) {
                let choose_incoming = span.text.chars().count() > last.text.chars().count()
                    || (span.text.chars().count() == last.text.chars().count()
                        && span.width > last.width);
                let preferred_text = if choose_incoming {
                    span.text.clone()
                } else {
                    last.text.clone()
                };
                let left = last.x.min(span.x);
                let right = last.right().max(span.right());
                last.x = left;
                last.y = (last.y + span.y) * 0.5;
                last.width = (right - left).max(last.width).max(span.width);
                last.height = last.height.max(span.height);
                last.font_size = last.font_size.max(span.font_size);
                last.text = preferred_text;
                continue;
            }
        }

        deduped.push(span);
    }

    *spans = deduped;
}

fn spans_are_overprint_duplicates(lhs: &TextSpan, rhs: &TextSpan) -> bool {
    let lhs_text = lhs.text.trim();
    let rhs_text = rhs.text.trim();
    if lhs_text.is_empty() || rhs_text.is_empty() {
        return false;
    }

    let same_baseline = (lhs.y - rhs.y).abs() <= lhs.font_size.max(rhs.font_size) * 0.12;
    if !same_baseline {
        return false;
    }

    let lhs_left = lhs.x;
    let lhs_right = lhs.right();
    let rhs_left = rhs.x;
    let rhs_right = rhs.right();
    let overlap = (lhs_right.min(rhs_right) - lhs_left.max(rhs_left)).max(0.0);
    let min_width = (lhs_right - lhs_left).min(rhs_right - rhs_left).max(1.0);
    let heavily_overlaps = overlap / min_width >= 0.85;
    if !heavily_overlaps {
        return false;
    }

    lhs_text == rhs_text || lhs_text.starts_with(rhs_text) || rhs_text.starts_with(lhs_text)
}

/// Does `curr` carry on from `prev`, or does it lie under it?
///
/// The join in `TextBlock::text` drops a word `curr` repeats from the end of
/// `prev`, because a document that draws that word twice at the seam between
/// two runs holds it once (0105.pdf, #1014). That reading needs `curr` to
/// begin where `prev` stopped. A run that begins a whole character *inside*
/// its predecessor is not the continuation of it: a text field draws its value
/// with the advance the font asks for, which is regularly wider than the field
/// box, so each of three fields on one row of a form reaches tens of points
/// into the next field's column. With the same value in all three -- a
/// repeated date, a column of `N/A`, or Acroform-PDFBOX-2333's own value -- the
/// second and the third read as the first one's tail said again, and dropping
/// them loses two filled fields. On a form that is the loss of entered data
/// (#432, class R-E of #389).
///
/// One glyph of `curr`'s own mean advance is the allowance, and it is there
/// for the seam itself: a measured width carries the last glyph's side bearing
/// and a rounding, never a column of another field.
///
/// The mean is per GLYPH, not per character, and `char_bounds` holds one entry
/// per glyph drawn. A glyph that decodes to several characters -- a `fi`
/// ligature, any `bfrange` that names a string -- would otherwise divide one
/// advance by two or three characters and shrink the allowance below the seam
/// it exists for. The character count answers only for a span that carries no
/// bounds, which is every hand-built one.
fn second_run_carries_on_from_the_first(prev: &TextSpan, curr: &TextSpan) -> bool {
    let glyphs = if curr.char_bounds.is_empty() {
        curr.text.chars().count()
    } else {
        curr.char_bounds.len()
    };
    if glyphs == 0 {
        return false;
    }

    let mean_advance = curr.width / glyphs as f64;
    // Along the previous run's baseline, so that a rotated seam is measured in
    // the direction the two runs actually overlap in (#435).
    let direction = span_direction(prev);
    let (curr_along, _) = baseline_coordinates(curr, direction);
    baseline_end(prev, direction) - curr_along <= mean_advance
}

fn trim_overlapping_word_prefix(prev: &str, curr: &str) -> Option<String> {
    let prev_chars: Vec<char> = prev.trim_end().chars().collect();
    let curr_chars: Vec<char> = curr.trim_start().chars().collect();
    let max = prev_chars.len().min(curr_chars.len());

    for len in (4..=max).rev() {
        let prev_start = prev_chars.len() - len;
        if prev_chars[prev_start..] != curr_chars[..len] {
            continue;
        }

        if !curr_chars[..len].iter().all(|ch| ch.is_alphanumeric()) {
            continue;
        }

        let prev_boundary = prev_start == 0 || !prev_chars[prev_start - 1].is_alphanumeric();
        let curr_boundary = len == curr_chars.len() || !curr_chars[len].is_alphanumeric();
        if !prev_boundary || !curr_boundary {
            continue;
        }

        return Some(curr_chars[len..].iter().collect());
    }

    None
}

/// Compute an adaptive column gap threshold from a set of bands.
///
/// Collects all positive inter-span gaps within each band, computes the
/// median, and returns `COLUMN_GAP_MEDIAN_MULTIPLIER × median`, clamped to
/// `[COLUMN_GAP_THRESHOLD_MIN, COLUMN_GAP_THRESHOLD_MAX]`.  Falls back to
/// `COLUMN_GAP_THRESHOLD_FALLBACK` when there are no measurable gaps.
fn compute_adaptive_column_gap(bands: &[TextBand]) -> f64 {
    let mut all_gaps: Vec<f64> = Vec::new();

    for band in bands {
        if band.spans.len() < 2 {
            continue;
        }
        let mut sorted = band.spans.clone();
        sorted.sort_by(|a, b| a.x.partial_cmp(&b.x).unwrap_or(Ordering::Equal));
        let mut prev_right = sorted[0].right();
        for span in sorted.iter().skip(1) {
            let gap = span.x - prev_right;
            if gap > 0.0 {
                all_gaps.push(gap);
            }
            prev_right = prev_right.max(span.right());
        }
    }

    if all_gaps.is_empty() {
        return COLUMN_GAP_THRESHOLD_FALLBACK;
    }

    all_gaps.sort_by(|a, b| a.partial_cmp(b).unwrap_or(Ordering::Equal));

    let min_gap = all_gaps[0];

    // When all inter-span gaps are already large (> MIN threshold), they are
    // likely all column gaps — the draw_glyph merger absorbed word-level
    // spaces into span text.  Use a fraction of the smallest gap so that
    // ALL column gaps exceed the threshold.
    if min_gap > COLUMN_GAP_THRESHOLD_MIN {
        return (min_gap * 0.75).clamp(COLUMN_GAP_THRESHOLD_MIN, COLUMN_GAP_THRESHOLD_MAX);
    }

    // Look for a natural break: the largest relative jump between consecutive
    // sorted gaps separates word-level gaps from column gaps.
    let mut best_break_threshold = 0.0f64;
    let mut best_ratio = 1.5f64; // require at least 1.5× jump
    for pair in all_gaps.windows(2) {
        if pair[0] > 0.5 {
            let ratio = pair[1] / pair[0];
            if ratio > best_ratio {
                best_ratio = ratio;
                best_break_threshold = (pair[0] + pair[1]) * 0.5;
            }
        }
    }

    if best_break_threshold > 0.0 {
        return best_break_threshold.clamp(COLUMN_GAP_THRESHOLD_MIN, COLUMN_GAP_THRESHOLD_MAX);
    }

    // Fallback: median × multiplier.
    let mid = all_gaps.len() / 2;
    let median = if all_gaps.len().is_multiple_of(2) {
        (all_gaps[mid - 1] + all_gaps[mid]) * 0.5
    } else {
        all_gaps[mid]
    };

    (median * COLUMN_GAP_MEDIAN_MULTIPLIER)
        .clamp(COLUMN_GAP_THRESHOLD_MIN, COLUMN_GAP_THRESHOLD_MAX)
}

/// Group spans into reading-order blocks, using column-aware reordering when
/// a contiguous region repeatedly exposes the same gutters.
/// Per-page adaptive parameters derived from the span set before any
/// grouping happens. Centralising these here (TEX4) means the rest of
/// the pipeline — band grouping, XY-Cut cuts, in-block space insertion
/// — all speak the same typographic baseline for this specific page,
/// rather than each helper reaching for an independent fixed constant.
#[derive(Debug, Clone, Copy)]
struct PageStats {
    /// Median font size across all spans (pt).
    median_font_size: f64,
    /// Median measured character width (pt). Zero-guarded fallback is
    /// 0.5 × median_font_size when there aren't enough samples.
    /// Currently populated for diagnostics / future tuning; allow dead_code
    /// under `-D warnings` until a reader is added.
    #[allow(dead_code)]
    median_char_width: f64,
    /// Tight line-to-line spacing (25th percentile of pairwise band
    /// gaps), representing the body-text leading on this page. The
    /// quartile is used instead of the median so large paragraph /
    /// zone gaps don't inflate the baseline. Zero if the page has
    /// only one band.
    median_line_spacing: f64,
}

impl PageStats {
    fn from_spans(spans: &[TextSpan]) -> Self {
        if spans.is_empty() {
            return Self {
                median_font_size: 12.0,
                median_char_width: 6.0,
                median_line_spacing: 0.0,
            };
        }

        // Median font size.
        let mut sizes: Vec<f64> = spans.iter().map(|s| s.font_size).collect();
        sizes.sort_by(|a, b| a.partial_cmp(b).unwrap_or(Ordering::Equal));
        let median_font_size = sizes[sizes.len() / 2];

        // Median char width — measured width / char count, per span.
        let mut char_widths: Vec<f64> = spans
            .iter()
            .filter_map(|s| {
                let chars = s.text.chars().count();
                if chars > 0 && s.width > 0.0 {
                    Some(s.width / chars as f64)
                } else {
                    None
                }
            })
            .collect();
        let median_char_width = if char_widths.is_empty() {
            median_font_size * 0.5
        } else {
            char_widths.sort_by(|a, b| a.partial_cmp(b).unwrap_or(Ordering::Equal));
            char_widths[char_widths.len() / 2]
        };

        // Median line spacing — pairwise gaps between consecutive band
        // y-values.
        let band_tolerance = (median_font_size * BAND_Y_FRACTION).max(BAND_Y_TOLERANCE);
        let mut ys: Vec<f64> = spans.iter().map(|s| s.y).collect();
        ys.sort_by(|a, b| b.partial_cmp(a).unwrap_or(Ordering::Equal));
        let mut band_ys: Vec<f64> = Vec::new();
        for y in ys {
            if band_ys
                .last()
                .map(|prev: &f64| (prev - y).abs() > band_tolerance)
                .unwrap_or(true)
            {
                band_ys.push(y);
            }
        }
        // ANN[r17/TEX4] "Line spacing" here means the TIGHT line-to-line
        // gap inside a text block — not the median of all gaps. Using
        // the median drags the estimate up when the page has
        // paragraph / zone breaks (which are the very gaps the
        // paragraph-break threshold is supposed to EXCEED). The 25th
        // percentile is the smallest gap that still shows up in more
        // than one place on the page; it captures body-text leading
        // robustly even when large zone gaps dominate.
        let median_line_spacing = if band_ys.len() < 2 {
            0.0
        } else {
            let mut spacings: Vec<f64> = band_ys
                .windows(2)
                .map(|pair| (pair[0] - pair[1]).abs())
                .collect();
            spacings.sort_by(|a, b| a.partial_cmp(b).unwrap_or(Ordering::Equal));
            let q1_index = spacings.len() / 4;
            spacings[q1_index]
        };

        Self {
            median_font_size,
            median_char_width,
            median_line_spacing,
        }
    }
}

// ANN[r17/TEX2] Maximum recursion depth for XY-Cut. Any real page layout
// is decomposable in well under 10 alternating cuts; the cap guards
// against pathological inputs where the cut predicate keeps triggering
// due to floating-point drift.
const XY_CUT_MAX_DEPTH: usize = 12;
// THE GUTTER IS MEASURED AGAINST THE TYPE, NOT AGAINST THE PAGE. There was a
// third rail here -- a vertical gap had to reach 4% of the region's width --
// and on the page it was written for it is the only rail that ever binds. A
// two-column paper is set in 9pt type inside a 500pt text block, so 4% asks for
// 20pt of white where the typographer left 13pt: wider than the gutter of every
// journal that ever printed two columns, which is what "narrow-gutter academic
// layouts are still detected" in the comment below was meant to allow and did
// not. It refused the cut on tracemonkey's pages 2 and 13 and on the same pages
// of highlights and tracemonkey_with_editable_annotations -- six of the eleven
// pages that were left under 95% on the gate set (#389).
//
// What separates a gutter from a word space is the type, and that is what the
// two remaining rails say: the median font size (a word space is a quarter of
// an em, a gutter is more than a whole one) and a 10pt absolute floor. A page
// four times as wide does not get four times the word spaces, so scaling the
// question with the page was never measuring the thing it asked about.
/// Floor (in pt) for vertical gap regardless of region width. Matches
/// the previous `COLUMN_GAP_THRESHOLD_MIN` and keeps XY-Cut conservative
/// on narrow regions (sidebars, tall columns).
const XY_CUT_VERTICAL_GAP_FLOOR: f64 = 10.0;
/// Multiplier applied to median font size to produce the horizontal-gap
/// threshold. 1.8 × line-height matches typical paragraph spacing.
const XY_CUT_HORIZONTAL_GAP_FONT_MULTIPLIER: f64 = 1.8;
/// Minimum number of spans a column must contain before it is eligible
/// for acceptance — one-span "columns" are almost always sidebar noise
/// or table-cell fragments.
const XY_CUT_MIN_SPANS_PER_COLUMN: usize = 2;
/// Average characters per band a column must have before it's accepted
/// as dense prose (vs. a short-cell table column).
const XY_CUT_MIN_CHARS_PER_BAND: f64 = 8.0;

/// The page's spans as blocks, in reading order, given the horizontal rules the
/// page drew (#545): a region the document itself rules into rows is a table,
/// and a table is not read column by column.
///
/// ANN[r17/TEX2][r17/TEX4] Top-level grouping uses recursive XY-Cut
/// with a density guard. Per-page stats are computed once up front so
/// every decision downstream speaks the same typographic baseline.
fn group_spans_into_blocks(spans: Vec<TextSpan>, rules: &[HorizontalRule]) -> Vec<TextBlock> {
    if spans.is_empty() {
        return Vec::new();
    }
    // A page that is itself turned is read in the frame it was written in, and
    // an upright page is turned by nothing at all (#546).
    let turn = PageTurn::of(&spans);
    let spans = turn.into_frame(spans);
    let stats = PageStats::from_spans(&spans);
    let rules = turn.rules_in_frame(rules);
    let blocks = xy_cut_recursive(spans, 0, &stats, &rules);
    let blocks = reassemble_cross_direction_runs(blocks);
    turn.back(blocks)
}

/// The quarter turn that puts a page which is itself turned back in the frame
/// it was written in (#546).
///
/// A page carries a `/Rotate`, of its own or inherited from the `Pages` tree,
/// and `Page::initial_transform` turns every glyph on it with the page: the
/// text device sees a page of lines running up, down or backwards. Bands are
/// horizontal and they read one direction, so on such a page they lie ACROSS
/// its lines: each glyph of a line lands in a band of its own and the page
/// reads as letter salad -- `ro t a ti o n  9 0` where pdfbox `PDFBOX-6049`
/// says `rotation 90`, and `081 noitator` on its half-turned page. This is the
/// same failure #435 fixed for a run drawn against the direction of its page,
/// and it stayed on the pages where the turned direction is the MAJORITY: what
/// #435 assembles there is the upright text on a turned page.
///
/// So the layout runs in the frame the page was written in. Every span is
/// turned into the direction most of the page's glyphs are drawn in before
/// `PageStats`, the cut and the bands, and the blocks are turned back before
/// they are returned, which leaves the spans the caller gets in page space to
/// the bit.
///
/// QUARTER TURNS ONLY, and the reason is exactness rather than taste: the sine
/// and cosine of a quarter turn are 0 and ±1, so the turn and its inverse move
/// no coordinate by a single bit, and a page this pass declines to turn comes
/// out of it byte for byte as it went in. A page `/Rotate` is a multiple of 90
/// by §7.7.3.3, which is the whole of what this is about; a page drawn entirely
/// at a free angle keeps its own bands, exactly as it did before (they read it:
/// `a_page_written_entirely_at_an_angle_keeps_its_own_bands`).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum PageTurn {
    /// The page reads left to right already, or in no direction this undoes.
    None,
    /// Its lines run up the page: `/Rotate 90`.
    Quarter,
    /// Its lines run right to left: `/Rotate 180`.
    Half,
    /// Its lines run down the page: `/Rotate 270`.
    ThreeQuarter,
}

impl PageTurn {
    /// The turn that makes the direction the page is WRITTEN in upright.
    ///
    /// Written in, and not merely the heaviest of: this turns the layout of a
    /// whole page, so the direction has to carry more than half its glyphs.
    /// The plurality rule #435 picks its cross-direction runs by is the right
    /// one there -- whatever is not the page's direction is a run on it -- and
    /// the wrong one here, because a page with no majority direction has no
    /// frame to be read in and turning it by a 26% plurality moves every block
    /// on it. pdfbox `AcroFormsRotation` is that page: four blocks of form
    /// fields at the four rotations, a quarter of the glyphs each, and the
    /// plurality rule turned its UPRIGHT page and put its fields in an order
    /// neither mutool nor poppler reads them in (order agreement 100 -> 50 on
    /// the gate set, where nothing else on 500 documents moved at all).
    /// A REFLECTION IS NOT A TURN, and only the determinant says which it is
    /// (codex, review round 2). `heaviest_direction` reads the baseline vector,
    /// and a horizontal reflection such as `[-1, 0, 0, 1, e, f]` runs its
    /// baseline in `(-1, 0)` exactly as a half turn does. Classifying that page
    /// as `Half` makes [`Self::into_frame`] negate BOTH coordinates, so a
    /// mirrored block whose lines descend the page comes back bottom to top --
    /// a reading order this pass invented out of a page nobody turned.
    ///
    /// Reflected glyphs are therefore counted in the page's total and in no
    /// direction's share. A page mostly drawn mirrored cannot reach a majority
    /// and comes out of this pass byte for byte as it went in, which is what
    /// `Self::None` means here.
    fn of(spans: &[TextSpan]) -> Self {
        let page_total: usize = spans.iter().map(glyph_weight).sum();
        if page_total == 0 {
            return Self::None;
        }
        let turned: Vec<&TextSpan> = spans
            .iter()
            .filter(|span| is_a_proper_rotation(span))
            .collect();
        let turned_total: usize = turned.iter().copied().map(glyph_weight).sum();
        let Some((page, share_of_turned)) = heaviest_direction(turned.into_iter()) else {
            return Self::None;
        };
        // The share is of the WHOLE page, mirrored glyphs included: measured
        // against the rotations alone, one upright line on a mirrored page
        // would carry 100 % of the vote.
        let share = share_of_turned * turned_total as f64 / page_total as f64;
        if share <= 0.5 {
            return Self::None;
        }
        [Self::Quarter, Self::Half, Self::ThreeQuarter]
            .into_iter()
            .find(|turn| directions_agree(page, turn.direction()))
            .unwrap_or(Self::None)
    }

    /// The direction a page this turn undoes is written in.
    fn direction(self) -> Direction {
        match self {
            Self::None => (1.0, 0.0),
            Self::Quarter => (0.0, 1.0),
            Self::Half => (-1.0, 0.0),
            Self::ThreeQuarter => (0.0, -1.0),
        }
    }

    /// The `(cos, sin)` of the rotation into the frame: the one that takes
    /// [`Self::direction`] to `(1, 0)`.
    fn rotation(self) -> (f64, f64) {
        match self {
            Self::None => (1.0, 0.0),
            Self::Quarter => (0.0, -1.0),
            Self::Half => (-1.0, 0.0),
            Self::ThreeQuarter => (0.0, 1.0),
        }
    }

    /// Every span in the frame the page was written in.
    fn into_frame(self, mut spans: Vec<TextSpan>) -> Vec<TextSpan> {
        if self == Self::None {
            return spans;
        }
        let rotation = self.rotation();
        for span in &mut spans {
            // In its own frame a run is as wide as it advances along its
            // baseline, and that is not what `draw_glyph` accumulated: `width`
            // is the furthest a glyph reached in PAGE x, which for a run
            // drawn up the page is one advance however long the run is. Every
            // reader of `width` above this point -- the column gutters, the
            // band gaps, the cell edges -- would take a line of a turned page
            // for a single word.
            let along = baseline_extent(span);
            turn_span(span, rotation);
            span.width = along;
        }
        spans
    }

    /// The ruling lines of #545 in the frame the page is read in.
    ///
    /// The device records horizontal rules and no others, and only the half
    /// turn maps a horizontal line to a horizontal line -- mirrored, which is
    /// why the two ends swap. A quarter turn maps one to a vertical line:
    /// what the device caught on such a page are its column separators, and
    /// its row rules were never horizontal to begin with, so they were never
    /// recorded at all. Those pages are cut without rules, exactly as every
    /// page was before #545, rather than with rules that mean the other thing
    /// (#546, review round 2).
    fn rules_in_frame(self, rules: &[HorizontalRule]) -> Cow<'_, [HorizontalRule]> {
        let rotation = self.rotation();
        match self {
            Self::None => Cow::Borrowed(rules),
            Self::Half => Cow::Owned(
                rules
                    .iter()
                    .map(|rule| {
                        let (left, y) = turn_point(rule.left, rule.y, rotation);
                        let (right, _) = turn_point(rule.right, rule.y, rotation);
                        HorizontalRule {
                            left: left.min(right),
                            right: left.max(right),
                            y,
                        }
                    })
                    .collect(),
            ),
            Self::Quarter | Self::ThreeQuarter => Cow::Owned(Vec::new()),
        }
    }

    /// The blocks back in page space, with every span's geometry the caller's
    /// own again.
    fn back(self, mut blocks: Vec<TextBlock>) -> Vec<TextBlock> {
        if self == Self::None {
            return blocks;
        }
        let (cos, sin) = self.rotation();
        for span in blocks.iter_mut().flat_map(|block| block.spans.iter_mut()) {
            turn_span(span, (cos, -sin));
            span.width = page_space_width(span);
        }
        blocks
    }
}

/// How far a span reaches along its own baseline, from its origin.
fn baseline_extent(span: &TextSpan) -> f64 {
    let direction = span_direction(span);
    baseline_end(span, direction) - baseline_coordinates(span, direction).0
}

/// The width `draw_glyph` measures: the furthest any of the span's glyphs
/// reaches in page x, from the span's origin.
///
/// This is what [`PageTurn::back`] restores, so that a caller of
/// `extract_text_blocks` on a turned page reads the same `width` off a span as
/// one on an upright page does. It is derived from the bounds rather than
/// remembered because the bounds are the same measurements `draw_glyph`
/// accumulated it from; a span with no bounds -- every hand-built one -- keeps
/// the width it came with.
fn page_space_width(span: &TextSpan) -> f64 {
    span.char_bounds
        .iter()
        .map(|bound| bound[2] - span.x)
        .reduce(f64::max)
        .unwrap_or(span.width)
}

/// Turn one span's geometry by `(cos, sin)`.
///
/// What turns is what the layout reads as a position: the span's origin, the
/// baseline its transform names, and the origin of each glyph bound.
///
/// What does not turn is what is measured along that baseline and means the
/// same in either frame. A `char_bound` is one of those: `draw_glyph` writes
/// it as `[x, y, x + advance, y + font size]` around a PAGE-space origin, so
/// it is an advance and a font size hung off a point rather than the rectangle
/// a turned glyph covers -- which is what `baseline_end` reads back out of it.
/// Turning the two numbers as if the entry were a rectangle would turn a
/// measurement that was never in page space to begin with.
///
/// `tight_char_bounds` is deliberately left alone. That one IS a page-space
/// rectangle, and it is ink rather than layout: nothing between here and the
/// blocks reads it, so leaving it where it is keeps it exact for the caller who
/// does (`GeometryMode::RichGeometry`).
fn turn_span(span: &mut TextSpan, rotation: (f64, f64)) {
    let (x, y) = turn_point(span.x, span.y, rotation);
    span.x = x;
    span.y = y;
    if let Some(coeffs) = span.transform.as_mut() {
        let (a, b) = turn_point(coeffs[0], coeffs[1], rotation);
        let (c, d) = turn_point(coeffs[2], coeffs[3], rotation);
        let (e, f) = turn_point(coeffs[4], coeffs[5], rotation);
        *coeffs = [a, b, c, d, e, f];
    }
    for bound in &mut span.char_bounds {
        let (advance, size) = (bound[2] - bound[0], bound[3] - bound[1]);
        let (x0, y0) = turn_point(bound[0], bound[1], rotation);
        *bound = [x0, y0, x0 + advance, y0 + size];
    }
}

/// A point turned by `(cos, sin)`.
fn turn_point(x: f64, y: f64, (cos, sin): (f64, f64)) -> (f64, f64) {
    (x * cos - y * sin, x * sin + y * cos)
}

/// Take the runs drawn in another direction than the page's out of the blocks
/// the page's own layout put them in, and give each one back as the line it is
/// (#435).
///
/// Bands are horizontal, and they read one direction. The letters of a diagonal
/// watermark, of a rotated table header, of the marginalia down the side of a
/// page each land in a band of their own, interleaved with whatever upright text
/// shares that band, and the reader gets `rk Xa Orm test value aBte D df wN t pA
/// sS te` where pdfjs issue17069 says `test pdf watermark` and `SANDBOX`.
///
/// WHERE THE PAGE'S OWN DIRECTION COMES FROM. The direction most of the page's
/// glyphs are drawn in keeps the page's bands, and on a page that is ITSELF
/// turned -- a `/Rotate 90` page, whose every glyph reaches the device turned
/// with it -- those bands would lie across its lines and read it as badly as a
/// watermark read before this pass (pdfbox `PDFBOX-6049`, `AcroFormsRotation`).
/// Such a page is turned back into the frame it was written in before the cut
/// and the bands ever see it ([`PageTurn`], #546), so by the time this pass
/// runs the page's own direction is upright again and what is left for it is
/// what it is for: the run drawn against the direction of the page it is on.
///
/// This runs AFTER the page's cut and takes nothing away from it. Where the
/// page's columns and zones are is decided by every glyph on it, rotated ones
/// included -- a run of marginalia down the left edge is part of why a page
/// splits where it does, and a version of this that cut the page without them
/// moved the reading order of `issue6127` by sixteen points. So the layout is
/// the layout, and what changes here is only which line each rotated glyph is
/// read as part of.
fn reassemble_cross_direction_runs(blocks: Vec<TextBlock>) -> Vec<TextBlock> {
    let Some(page) = page_direction(&blocks) else {
        return blocks;
    };

    let mut kept: Vec<TextBlock> = Vec::with_capacity(blocks.len());
    // Each cross-direction span, with the position in the page's order that the
    // block it was taken from held.
    let mut cross: Vec<PlacedSpan> = Vec::new();
    for block in blocks {
        let at = kept.len();
        let mut page_spans = Vec::with_capacity(block.spans.len());
        for span in block.spans {
            if directions_agree(page, span_direction(&span)) {
                page_spans.push(span);
            } else {
                cross.push((at, span));
            }
        }
        if !page_spans.is_empty() {
            kept.push(TextBlock { spans: page_spans });
        }
    }

    if cross.is_empty() {
        return kept;
    }

    // `lines_along_their_own_baselines` returns the runs in the order they are
    // to be read. They are inserted back to front -- so that inserting one
    // never moves the position another was measured at -- and two runs that
    // share a position are inserted in the reverse of their order, because each
    // insertion at the same index pushes the last one down (#435, review round
    // 2).
    let runs = lines_along_their_own_baselines(cross);
    for (at, run) in runs.into_iter().rev() {
        let at = at.min(kept.len());
        kept.insert(at, run);
    }
    kept
}

/// The direction most of a page's glyphs are drawn in, or `None` for a page
/// with no text at all.
fn page_direction(blocks: &[TextBlock]) -> Option<Direction> {
    dominant_direction(blocks.iter().flat_map(|block| block.spans.iter()))
}

/// The direction most of a set of spans' glyphs are drawn in, or `None` for no
/// spans at all.
///
/// Weighted by glyphs and not by spans: one word of upright text is not the
/// page's direction because a rotated run happened to arrive as three spans.
/// And by GLYPHS and not by characters, which are not the same count: a
/// ligature decodes to two or three of them, and the spaces the space consensus
/// puts between two glyphs are characters that were never drawn. Either would
/// let a minority direction outvote the page's own on a page where the two are
/// close. `char_bounds` holds one entry per glyph drawn; the character count
/// answers only for a span that carries no bounds, which is every hand-built
/// one (#435, review round 2).
fn dominant_direction<'a>(spans: impl Iterator<Item = &'a TextSpan>) -> Option<Direction> {
    heaviest_direction(spans).map(|(direction, _)| direction)
}

/// What one span weighs in a vote about direction: the glyphs it drew, or its
/// characters when it carries no bounds. One definition, because two of them
/// would let the same page have two majorities.
fn glyph_weight(span: &TextSpan) -> usize {
    if span.char_bounds.is_empty() {
        span.text.chars().count().max(1)
    } else {
        span.char_bounds.len()
    }
}

/// Whether a span was drawn by a proper rotation rather than a reflection.
///
/// A baseline vector cannot tell the two apart. `[-1, 0, 0, 1, e, f]` mirrors
/// the page about its vertical axis and leaves the baseline running in `(-1,
/// 0)` -- the same direction a half turn produces -- while the page's vertical
/// axis stays upright and nothing has turned. The determinant is what separates
/// them: it is positive for a rotation and negative for a reflection.
///
/// A span with no transform is hand-built and reads upright, which is a proper
/// rotation by the identity.
fn is_a_proper_rotation(span: &TextSpan) -> bool {
    match span.transform {
        None => true,
        Some([a, b, c, d, _, _]) => a * d - b * c > 0.0,
    }
}

/// The heaviest direction and the share of the glyphs drawn in it, weighed by
/// the rule [`dominant_direction`] documents.
fn heaviest_direction<'a>(spans: impl Iterator<Item = &'a TextSpan>) -> Option<(Direction, f64)> {
    let mut directions: Vec<(Direction, usize)> = Vec::new();
    for span in spans {
        let direction = span_direction(span);
        let weight = glyph_weight(span);
        match directions
            .iter_mut()
            .find(|(known, _)| directions_agree(*known, direction))
        {
            Some(entry) => entry.1 += weight,
            None => directions.push((direction, weight)),
        }
    }
    let total: usize = directions.iter().map(|(_, weight)| *weight).sum();
    // The first of the heaviest, so that a page whose two directions carry the
    // same number of glyphs reads in the one it was drawn in first rather than
    // in whichever the iterator saw last.
    let mut winner: Option<(Direction, usize)> = None;
    for (direction, weight) in directions {
        if winner.map(|(_, best)| weight > best).unwrap_or(true) {
            winner = Some((direction, weight));
        }
    }
    winner.map(|(direction, weight)| (direction, weight as f64 / total as f64))
}

/// Assemble cross-direction spans into lines along their own baselines.
///
/// The rule the page's bands follow, in each run's own frame: spans within the
/// band tolerance of each other across the baseline are one line, ordered along
/// it. A line is placed where the page's order held the first of its spans, so
/// a watermark drawn across the middle of a page is read there and not after
/// the footer.
fn lines_along_their_own_baselines(spans: Vec<PlacedSpan>) -> Vec<(usize, TextBlock)> {
    // One group per direction: two runs at two angles never join, however close
    // their glyphs land.
    let mut groups: Vec<(Direction, Vec<PlacedSpan>)> = Vec::new();
    for (at, span) in spans {
        let direction = span_direction(&span);
        match groups
            .iter_mut()
            .find(|(known, _)| directions_agree(*known, direction))
        {
            Some((_, group)) => group.push((at, span)),
            None => groups.push((direction, vec![(at, span)])),
        }
    }

    let mut lines: Vec<(usize, TextBlock)> = Vec::new();
    for (direction, group) in groups {
        let mut rows: Vec<(f64, usize, Vec<TextSpan>)> = Vec::new();
        for (at, span) in group {
            let across = baseline_coordinates(&span, direction).1;
            let tolerance = (span.height * BAND_Y_FRACTION).max(BAND_Y_TOLERANCE);
            match rows
                .iter_mut()
                .find(|(row_across, _, _)| (row_across - across).abs() <= tolerance)
            {
                Some((_, first, row)) => {
                    *first = (*first).min(at);
                    row.push(span);
                }
                None => rows.push((across, at, vec![span])),
            }
        }

        // Read in the order the page's own order first held them, and where
        // two lines start at the same place -- which is what a block of
        // rotated text does -- from the top of the run's own frame down.
        rows.sort_by(|a, b| {
            a.1.cmp(&b.1)
                .then_with(|| b.0.partial_cmp(&a.0).unwrap_or(Ordering::Equal))
        });
        for (_, at, mut row) in rows {
            row.sort_by(|a, b| {
                baseline_coordinates(a, direction)
                    .0
                    .partial_cmp(&baseline_coordinates(b, direction).0)
                    .unwrap_or(Ordering::Equal)
            });
            lines.push((at, TextBlock { spans: row }));
        }
    }
    // Across directions too: the page's order decides, and a stable sort keeps
    // each direction's own line order inside it.
    lines.sort_by(|a, b| a.0.cmp(&b.0));
    lines
}

fn xy_cut_recursive(
    spans: Vec<TextSpan>,
    depth: usize,
    stats: &PageStats,
    rules: &[HorizontalRule],
) -> Vec<TextBlock> {
    if spans.is_empty() {
        return Vec::new();
    }
    if depth >= XY_CUT_MAX_DEPTH {
        return band_based_blocks(spans, stats, rules);
    }

    // ANN[r17/TEX2] Pick whichever direction has the largest qualifying
    // gap. Always cutting vertically first breaks layouts where a
    // footer sits in the mid-x range — it would attach to the left
    // column instead of being recognized as a page-level zone. The
    // "largest gap wins" rule is the standard XY-Cut tie-breaker used
    // by academic OCR literature and matches pdf_oxide.
    let vcut = try_vertical_cut(&spans, stats, rules);
    let hcut = try_horizontal_cut(&spans, stats);

    let (chosen, _) = match (vcut, hcut) {
        (Some((v_groups, v_gap)), Some((h_groups, h_gap))) => {
            if v_gap >= h_gap {
                (Some(v_groups), v_gap)
            } else {
                (Some(h_groups), h_gap)
            }
        }
        (Some((v_groups, v_gap)), None) => (Some(v_groups), v_gap),
        (None, Some((h_groups, h_gap))) => (Some(h_groups), h_gap),
        (None, None) => (None, 0.0),
    };

    if let Some(groups) = chosen {
        let mut out = Vec::new();
        for group in groups {
            out.extend(xy_cut_recursive(group, depth + 1, stats, rules));
        }
        return out;
    }

    band_based_blocks(spans, stats, rules)
}

/// Emit per-band row blocks without any column detection. Used as the
/// leaf of XY-Cut recursion — at this point the region either has no
/// further cuts or the density guard refused them.
fn band_based_blocks(
    spans: Vec<TextSpan>,
    stats: &PageStats,
    rules: &[HorizontalRule],
) -> Vec<TextBlock> {
    // XY-Cut can miss recurring gutters when a small number of bands span the
    // full page width (e.g. a running header above a 3-column body). In that
    // case, fall back to the older band/gutter detector inside the leaf region
    // instead of flattening everything row-major.
    group_spans_into_blocks_legacy_with_stats(spans, stats, rules)
}

/// Median font-size helper. Currently unreferenced after `PageStats` took over
/// the typography baseline computation; kept available for future tuning paths.
#[allow(dead_code)]
fn median_font_size(spans: &[TextSpan]) -> f64 {
    if spans.is_empty() {
        return 12.0;
    }
    let mut sizes: Vec<f64> = spans.iter().map(|s| s.font_size).collect();
    sizes.sort_by(|a, b| a.partial_cmp(b).unwrap_or(Ordering::Equal));
    sizes[sizes.len() / 2]
}

/// Attempt a vertical (column) cut. Returns the span groups plus the
/// gap size (in pt) if a suitable gutter is found AND the density +
/// alignment guards accept.
///
/// ANN[r17/TEX2] Three guards together avoid false-positive columns:
///   1. `min_gap` is the MAX of (median_font, 10pt) — deliberately
///      lower than `median_font * 2` so narrow-gutter academic papers
///      (12pt gutters, common in print) are still detected. It does not
///      scale with the region: see the note on the constants above.
///   2. `columns_are_dense` rejects column splits where either side
///      has <2 spans or <8 chars/band — catches table cells.
///   3. `columns_are_band_aligned` rejects cuts where any band would
///      end up on only one side of the cut while being wider than
///      ~70% of that side's column width — catches full-width
///      paragraphs (Intro / Outro) that accidentally sit in the
///      left-column x-range.
fn try_vertical_cut(
    spans: &[TextSpan],
    stats: &PageStats,
    rules: &[HorizontalRule],
) -> Option<(Vec<Vec<TextSpan>>, f64)> {
    if spans.len() < 2 * XY_CUT_MIN_SPANS_PER_COLUMN {
        return None;
    }

    let region_left = spans.iter().map(|s| s.x).fold(f64::INFINITY, f64::min);
    let region_right = spans
        .iter()
        .map(TextSpan::right)
        .fold(f64::NEG_INFINITY, f64::max);
    let region_width = region_right - region_left;
    if region_width <= 0.0 {
        return None;
    }

    // ANN[r17/TEX2][r17/TEX4] Threshold uses the ADAPTIVE median-word-gap
    // from the bands rather than a flat font-size multiple. Narrow-gutter
    // academic layouts have 12pt gutters next to 4pt word spaces — the
    // adaptive threshold scales with the actual typography used on this
    // page. Clamped to `XY_CUT_VERTICAL_GAP_FLOOR` to avoid firing on
    // ordinary inter-word spaces when character advance data is noisy.
    // median_font and the width fraction act only as safety rails for
    // pathological inputs.
    let bands = group_spans_into_bands_with_stats(spans.to_vec(), stats);
    // THE PAGE'S OWN RULING LINES COME FIRST. A region the document rules into
    // rows is a table, and a table read down its columns is the defect this
    // guard exists for (#545). Asked here as well as in the leaf below because
    // a table with a wide gutter is taken by this cut and never reaches the
    // leaf at all.
    let all_bands: Vec<usize> = (0..bands.len()).collect();
    if region_is_ruled(&bands, &all_bands, rules) {
        return None;
    }
    let adaptive = compute_adaptive_column_gap(&bands);
    let floor = stats.median_font_size.max(XY_CUT_VERTICAL_GAP_FLOOR);
    let min_gap = adaptive.min(floor).max(XY_CUT_VERTICAL_GAP_FLOOR);

    // Intervals [x_left, x_right] of every span; we look for an x value
    // that is free of ALL intervals (full-height gap).
    // MEASURED EDGES ONLY. `right()` returns x + width.max(estimated_width()),
    // and the estimate is a character count times a nominal advance -- on
    // tracemonkey's abstract it overshoots the measured edge by 61pt, which is
    // wider than the gutter it then covers. A gap scan that asks "is any x free
    // of every span" cannot use an edge that is deliberately generous.
    // Unmeasured spans (width 0) keep the estimate, since a point-wide interval
    // would open a gap where there is text.
    let mut intervals: Vec<(f64, f64)> = spans
        .iter()
        .map(|s| {
            let r = if s.width > 0.0 {
                s.measured_right()
            } else {
                s.right()
            };
            (s.x, r.max(s.x + 0.001))
        })
        .collect();
    intervals.sort_by(|a, b| a.0.partial_cmp(&b.0).unwrap_or(Ordering::Equal));

    let mut cursor = intervals[0].1;
    let mut best_gap: Option<(f64, f64)> = None; // (gap_size, cut_x)
    for (left, right) in intervals.iter().skip(1) {
        if *left > cursor {
            let gap = *left - cursor;
            if gap >= min_gap {
                match best_gap {
                    Some((best, _)) if best >= gap => {}
                    _ => {
                        let cut_x = (cursor + *left) * 0.5;
                        best_gap = Some((gap, cut_x));
                    }
                }
            }
        }
        cursor = cursor.max(*right);
    }

    let (gap_size, cut_x) = best_gap?;

    // Split spans around the cut. A span whose midpoint is < cut_x
    // belongs to the left group.
    let mut left_group = Vec::new();
    let mut right_group = Vec::new();
    for span in spans {
        let midpoint = span.x + (span.right() - span.x) * 0.5;
        if midpoint < cut_x {
            left_group.push(span.clone());
        } else {
            right_group.push(span.clone());
        }
    }

    if !columns_are_dense(&left_group, &right_group, stats) {
        return None;
    }
    if !columns_are_band_aligned(spans, cut_x, region_left, region_right, stats) {
        return None;
    }

    Some((vec![left_group, right_group], gap_size))
}

/// ANN[r17/TEX2] Reject a vertical cut when any band sits on only one
/// side of the cut AND occupies more than ~70% of that side's column
/// width. Such bands are almost certainly full-width paragraphs that
/// happened to align with the left margin of one column, and forcing
/// them into that column re-orders them relative to text that follows.
fn columns_are_band_aligned(
    spans: &[TextSpan],
    cut_x: f64,
    region_left: f64,
    region_right: f64,
    stats: &PageStats,
) -> bool {
    let left_width = (cut_x - region_left).max(1.0);
    let right_width = (region_right - cut_x).max(1.0);

    // Threshold chosen empirically: paragraph bodies in columnar
    // layouts usually fill ~60-70% of their column; anything wider
    // than 0.7× is a page-level element masquerading as column
    // content.
    const MAX_SINGLE_SIDE_FRACTION: f64 = 0.70;

    let _ = (left_width, right_width, MAX_SINGLE_SIDE_FRACTION);
    // ONE SPAN'S INK REACHING ACROSS THE CUT is what "a full-width element
    // masquerading as column content" actually looks like. The guard used to
    // ask a different question -- is a band that sits on one side wider than
    // 0.70 of that side -- and on a real two-column page the answer is yes for
    // any ordinary line of body text, because a line fills about 0.9 of its
    // column. Every such page has single-sided bands (a heading, a column that
    // ends short, a figure), so the old test refused the canonical academic
    // page every time (#429).
    //
    // Width was a proxy for crossing, and it is a proxy that cannot tell a
    // banner from a column line. Its own fixture shows why: the banner runs
    // x 40..320 against a cut at 200, which is ink on both sides. It counted as
    // "one side" only because sides were decided on each span's midpoint.
    for span in spans {
        if span.x < cut_x && span.measured_right() > cut_x {
            return false;
        }
    }

    // A LINE CANNOT BE HALF AGAIN AS WIDE AS THE TYPICAL LINE IN ITS OWN COLUMN
    // and still be a line of that column. That is the second way a full-width
    // element hides: `Intro paragraph` and `Outro paragraph` in
    // mixed_single_and_multi_column_regions_preserve_shared_bands are wider
    // than the column they sit above but still stop short of the gutter, so no
    // ink of theirs crosses the cut. Swallowed into the left column they would
    // read Intro, L1..L3, Outro, R1..R3 -- the outro before the right column it
    // precedes.
    //
    // Measured against the MEDIAN LINE OF THAT SIDE, not against the width of
    // the side. The old test used cut_x - region_left, which is a column plus
    // half a gutter, so an ordinary body line at ~0.9 of its column tripped it
    // and the canonical two-column page was refused every time (#429). The
    // median calibrates itself: on a real column most lines run full width, so
    // the median IS the column width and nothing legitimate exceeds it.
    const OUTLIER: f64 = 1.3;
    // EVERY band's per-side extent, not only the single-sided ones. Measuring
    // the typical line from the single-sided bands alone compares the outliers
    // with themselves: in the Intro/Outro fixture those two ARE the only
    // single-sided bands, so their median is their own width and nothing ever
    // stands out.
    let bands = group_spans_into_bands_with_stats(spans.to_vec(), stats);
    let mut widths: (Vec<f64>, Vec<f64>) = (Vec::new(), Vec::new());
    let mut single: Vec<(bool, f64)> = Vec::new();
    for band in &bands {
        let mut left_lo = f64::INFINITY;
        let mut left_hi = f64::NEG_INFINITY;
        let mut right_lo = f64::INFINITY;
        let mut right_hi = f64::NEG_INFINITY;
        for span in &band.spans {
            let r = span.measured_right();
            if span.x + (r - span.x) * 0.5 < cut_x {
                left_lo = left_lo.min(span.x);
                left_hi = left_hi.max(r);
            } else {
                right_lo = right_lo.min(span.x);
                right_hi = right_hi.max(r);
            }
        }
        let has_left = left_hi > left_lo || left_lo.is_finite();
        let has_right = right_hi > right_lo || right_lo.is_finite();
        if has_left {
            widths.0.push((left_hi - left_lo).max(0.0));
        }
        if has_right {
            widths.1.push((right_hi - right_lo).max(0.0));
        }
        match (has_left, has_right) {
            (true, false) => single.push((true, (left_hi - left_lo).max(0.0))),
            (false, true) => single.push((false, (right_hi - right_lo).max(0.0))),
            _ => {}
        }
    }
    let median = |v: &mut Vec<f64>| -> Option<f64> {
        if v.is_empty() {
            return None;
        }
        v.sort_by(|a, b| a.partial_cmp(b).unwrap_or(Ordering::Equal));
        Some(v[v.len() / 2])
    };
    let left_median = median(&mut widths.0);
    let right_median = median(&mut widths.1);
    for (is_left, w) in single {
        let m = if is_left { left_median } else { right_median };
        if let Some(m) = m {
            if m > 0.0 && w > m * OUTLIER {
                return false;
            }
        }
    }
    true
}

/// Density guard — reject column splits that look like tables (few,
/// short spans per column). A column is "dense" when it has at least
/// MIN_SPANS_PER_COLUMN spans and the average character count per band
/// exceeds MIN_CHARS_PER_BAND.
fn columns_are_dense(left: &[TextSpan], right: &[TextSpan], stats: &PageStats) -> bool {
    for col in [left, right] {
        if col.len() < XY_CUT_MIN_SPANS_PER_COLUMN {
            return false;
        }
        let bands = group_spans_into_bands_with_stats(col.to_vec(), stats);
        if bands.is_empty() {
            return false;
        }
        let total_chars: usize = col.iter().map(|s| s.text.chars().count()).sum();
        let chars_per_band = total_chars as f64 / bands.len() as f64;
        if chars_per_band < XY_CUT_MIN_CHARS_PER_BAND {
            return false;
        }
    }
    true
}

/// Attempt a horizontal (zone / paragraph) cut. Unlike vertical cuts
/// this does NOT need a density guard — splitting top-from-bottom
/// cannot re-order content.
fn try_horizontal_cut(spans: &[TextSpan], stats: &PageStats) -> Option<(Vec<Vec<TextSpan>>, f64)> {
    if spans.len() < 2 {
        return None;
    }
    // Sort by descending y (PDF y grows upward).
    let mut sorted = spans.to_vec();
    sorted.sort_by(|a, b| {
        b.y.partial_cmp(&a.y)
            .unwrap_or(Ordering::Equal)
            .then_with(|| a.x.partial_cmp(&b.x).unwrap_or(Ordering::Equal))
    });

    // ANN[r17/TEX4] Paragraph / zone cuts scale with MEDIAN LINE
    // SPACING when available — this is the typographically correct
    // baseline (paragraph break ≈ 1.8 × line-spacing). When the page
    // has only one band, or stats haven't observed spacing yet, fall
    // back to the font-size multiple the legacy path used.
    let min_gap = if stats.median_line_spacing > 0.0 {
        stats.median_line_spacing * PARAGRAPH_BREAK_LINE_SPACING_MULTIPLIER
    } else {
        stats.median_font_size * XY_CUT_HORIZONTAL_GAP_FONT_MULTIPLIER
    };

    // Look for the largest gap between consecutive span y-values.
    let mut best: Option<(f64, f64)> = None; // (gap_size, cut_y)
    let tolerance = stats.median_font_size * BAND_Y_FRACTION;
    let mut band_bottom = sorted[0].y;

    for span in sorted.iter().skip(1) {
        if (band_bottom - span.y).abs() <= tolerance {
            band_bottom = band_bottom.min(span.y);
            continue;
        }
        let gap = band_bottom - span.y;
        if gap >= min_gap {
            let cut_y = (band_bottom + span.y) * 0.5;
            match best {
                Some((best_gap, _)) if best_gap >= gap => {}
                _ => best = Some((gap, cut_y)),
            }
        }
        band_bottom = span.y;
    }

    let (gap_size, cut_y) = best?;

    let mut top_group = Vec::new();
    let mut bottom_group = Vec::new();
    for span in spans {
        if span.y > cut_y {
            top_group.push(span.clone());
        } else {
            bottom_group.push(span.clone());
        }
    }
    if top_group.is_empty() || bottom_group.is_empty() {
        return None;
    }
    Some((vec![top_group, bottom_group], gap_size))
}

/// Legacy band+column-detection path, kept for reference and as the
/// fallback inside `band_based_blocks` test coverage. Not currently
/// used — XY-Cut supersedes it.
#[allow(dead_code)]
fn group_spans_into_blocks_legacy(spans: Vec<TextSpan>) -> Vec<TextBlock> {
    let bands = group_spans_into_bands(spans);
    group_spans_into_blocks_legacy_from_bands(bands, &[])
}

fn group_spans_into_blocks_legacy_with_stats(
    spans: Vec<TextSpan>,
    stats: &PageStats,
    rules: &[HorizontalRule],
) -> Vec<TextBlock> {
    let bands = group_spans_into_bands_with_stats(spans, stats);
    group_spans_into_blocks_legacy_from_bands(bands, rules)
}

fn group_spans_into_blocks_legacy_from_bands(
    bands: Vec<TextBand>,
    rules: &[HorizontalRule],
) -> Vec<TextBlock> {
    if bands.is_empty() {
        return Vec::new();
    }

    let column_gap_threshold = compute_adaptive_column_gap(&bands);

    let mut blocks = Vec::new();
    let mut idx = 0;

    while idx < bands.len() {
        let gap_midpoints = bands[idx].gap_midpoints(column_gap_threshold);
        if gap_midpoints.is_empty() {
            idx = push_row(&bands, idx, &mut blocks);
            continue;
        }

        let mut boundaries = gap_midpoints.clone();
        let mut band_indices = vec![idx];
        let mut gapped_band_count = 1usize;
        let mut region_left = bands[idx].left();
        let mut region_right = bands[idx].right();
        let mut next_idx = idx + 1;

        while next_idx < bands.len() {
            let next_band = &bands[next_idx];
            let next_gap_midpoints = next_band.gap_midpoints(column_gap_threshold);
            if next_gap_midpoints.is_empty() {
                if next_band
                    .fits_single_column(&boundaries, region_left, region_right)
                    .is_some()
                {
                    band_indices.push(next_idx);
                    next_idx += 1;
                    continue;
                }
                break;
            }

            if !boundaries_match(&boundaries, &next_gap_midpoints, column_gap_threshold) {
                break;
            }

            update_boundaries(&mut boundaries, &next_gap_midpoints, gapped_band_count);
            gapped_band_count += 1;
            band_indices.push(next_idx);
            region_left = region_left.min(next_band.left());
            region_right = region_right.max(next_band.right());
            next_idx += 1;
        }

        if region_is_columnar(&bands, &band_indices, &boundaries, gapped_band_count)
            && !region_is_ruled(&bands, &band_indices, rules)
        {
            append_column_region_blocks(&bands, &band_indices, &boundaries, &mut blocks);
            idx = next_idx;
        } else {
            idx = push_row(&bands, idx, &mut blocks);
        }
    }

    blocks
}

/// Emit the band at `idx` and return the index of the first band after what was
/// emitted.
///
/// A band is normally one line of the page and becomes one block. The exception
/// is the row of a table one of whose cells wraps: the wrapped cell's second
/// line is a band of its own, and emitting the bands in turn puts it after the
/// row's remaining cells instead of after the text it continues (#434).
fn push_row(bands: &[TextBand], idx: usize, blocks: &mut Vec<TextBlock>) -> usize {
    if let Some(next) = append_wrapped_table_row(bands, idx, blocks) {
        return next;
    }
    blocks.push(bands[idx].row_block());
    idx + 1
}

/// The left edges of the cells the band at `idx` draws, as the row itself
/// states them: one edge per span start, and two starts within
/// `CELL_EDGE_TOLERANCE` are one edge.
///
/// Cell edges are taken from starts rather than from the gaps between spans
/// because a cell's measured extent is not a column boundary: `8.2.5.26-t05`
/// draws four of its five columns less than 16 pt apart, which no gutter
/// threshold that leaves ordinary word spacing alone would ever see.
fn cell_edges(band: &TextBand) -> Vec<f64> {
    let mut edges: Vec<f64> = band.spans.iter().map(|span| span.x).collect();
    edges.sort_by(|a, b| a.partial_cmp(b).unwrap_or(Ordering::Equal));
    edges.dedup_by(|a, b| (*a - *b).abs() <= CELL_EDGE_TOLERANCE);
    edges
}

/// The cell a span belongs to: the edge it starts on, when it also stops before
/// the next edge. A span that starts between two edges, or that reaches into the
/// next cell, belongs to no cell of this grid and refuses the whole row.
///
/// The extent asked for is the measured one. A span's nominal width is the sum
/// of the advances the font asks for, which regularly overshoots the ink and so
/// the cell: `t05`'s wrapped cell advances 78 pt past its own text and into the
/// column after it.
fn cell_of(span: &TextSpan, edges: &[f64]) -> Option<usize> {
    let idx = edges
        .iter()
        .rposition(|edge| span.x >= edge - CELL_EDGE_TOLERANCE)?;
    if (span.x - edges[idx]).abs() > CELL_EDGE_TOLERANCE {
        return None;
    }
    if let Some(next_edge) = edges.get(idx + 1) {
        if span.measured_right() > next_edge - CELL_EDGE_TOLERANCE {
            return None;
        }
    }
    Some(idx)
}

/// The tallest glyph of the band, which is the unit both vertical distances
/// below are measured in.
fn band_line_height(band: &TextBand) -> f64 {
    band.spans
        .iter()
        .map(|span| span.height.max(span.font_size))
        .fold(0.0_f64, f64::max)
}

/// Whether `band` is another row of the same grid: every one of its spans sits
/// in a cell of `edges`, and it carries at least `TABLE_GRID_MIN_COLUMNS` of
/// them.
///
/// This is what separates a table row from two lines of prose that happen to
/// break in the right place. One line's spans always align with themselves; a
/// grid is only a grid when a second row draws the same edges.
/// The single cell of the grid a band fills, when it fills exactly one.
///
/// This is what a wrapped line looks like from above, and what the next row of
/// a table does not look like: a row with an empty cell still fills two of
/// them, so it is not mistaken for the line of a cell that ran on.
fn band_fills_one_cell(band: &TextBand, edges: &[f64]) -> Option<usize> {
    let mut filled: Option<usize> = None;
    for span in &band.spans {
        let cell = cell_of(span, edges)?;
        match filled {
            Some(seen) if seen != cell => return None,
            _ => filled = Some(cell),
        }
    }
    filled
}

fn band_matches_grid(band: &TextBand, edges: &[f64]) -> bool {
    let mut occupied = vec![false; edges.len()];
    for span in &band.spans {
        match cell_of(span, edges) {
            Some(cell) => occupied[cell] = true,
            None => return false,
        }
    }
    occupied.iter().filter(|seen| **seen).count() >= TABLE_GRID_MIN_COLUMNS
}

/// Emit the row at `idx` cell by cell when one of its cells wraps, and return
/// the index of the first band after the row. `None` when the band is not such
/// a row, which is the ordinary case.
///
/// The row is emitted slice-major: every cell in turn, and within a cell its
/// own lines in the order they are drawn. That is what both readers do, and it
/// is the only order in which a wrapped cell reads as one piece of text.
///
/// A wrapped line and the next row of the table look alike from above -- both
/// are a band under the row with some of its cells filled -- and telling them
/// apart is the whole of the work here. Two things say "line" rather than
/// "row": it fills a single cell of the grid, and it sits closer to the row
/// than the rows of the grid sit to each other.
///
/// What it does not do, deliberately:
///   * a row two of whose cells wrap onto the same line is a line that fills
///     two cells, which is what the next row of the table looks like, so it
///     stays row-major;
///   * so does a row every one of whose cells has a line under it: nothing
///     there says which line continues the row and which one begins the next,
///     and it is also the shape a two-column region takes when one column runs
///     on alone -- reordering that would be the column cut of #389 class O-B
///     done badly;
///   * a row of two cells is left alone, because that is also what a page set
///     in columns looks like -- see `TABLE_ROW_MIN_CELLS`;
///   * the first row of a table is left alone, because a single line's cell
///     edges are also the word boundaries of a sentence and no row above it
///     corroborates them;
///   * a continuation that is indented, centred or right-aligned inside its
///     cell does not start on the cell's edge and is not recognised.
fn append_wrapped_table_row(
    bands: &[TextBand],
    idx: usize,
    blocks: &mut Vec<TextBlock>,
) -> Option<usize> {
    let head = &bands[idx];
    if head.spans.len() < TABLE_ROW_MIN_CELLS {
        return None;
    }
    let edges = cell_edges(head);
    if edges.len() < TABLE_ROW_MIN_CELLS {
        return None;
    }
    let line_height = band_line_height(head);
    if line_height <= 0.0 {
        return None;
    }

    let head_cells: Vec<usize> = head
        .spans
        .iter()
        .map(|span| cell_of(span, &edges))
        .collect::<Option<Vec<usize>>>()?;

    // The pitch of the grid, from the band directly above: one line plus
    // whatever the cells are padded by. Nothing below may sit that far from
    // what it continues, or it is the next row rather than a wrapped line.
    let above = idx.checked_sub(1)?;
    let row_pitch = bands[above].y - head.y;
    if row_pitch <= 0.0 {
        return None;
    }
    let max_line_gap = (line_height * WRAPPED_CELL_LINE_GAP_FACTOR)
        .min(row_pitch * WRAPPED_CELL_MAX_PITCH_FRACTION);

    // The nearest row above that draws the same cell edges. It is what says
    // this is a grid at all: one line's spans always align with themselves, so
    // only a second row makes the edges evidence of anything. The bands stepped
    // over on the way are the wrapped lines of that row.
    let mut corroborator = above;
    loop {
        if band_matches_grid(&bands[corroborator], &edges) {
            break;
        }
        if band_fills_one_cell(&bands[corroborator], &edges).is_none()
            || idx - corroborator >= TABLE_GRID_MAX_LOOKBACK
            || corroborator == 0
        {
            return None;
        }
        corroborator -= 1;
    }

    // The continuation lines: each fills one cell of the grid that the row
    // itself fills, and sits less than the grid's pitch below the last line of
    // *that cell*.
    //
    // Per cell, and not below the line before it whichever cell that was: a
    // cell's lines are consecutive, so its third line is two gaps below the row
    // while another cell's second line is one. Measuring against the last line
    // accepted would let the row after a wrapped one -- if it happens to fill a
    // single cell -- sit one gap below that wrapped line and be read as a third
    // line of the row it follows.
    let mut continuations: Vec<(&TextBand, usize)> = Vec::new();
    let mut last_line_in_cell = vec![head.y; edges.len()];
    let mut next_idx = idx + 1;
    while next_idx < bands.len() {
        let band = &bands[next_idx];
        // One cell's line cannot carry more runs than the whole row it
        // continues; a band that does is a row of its own.
        if band.spans.len() >= head.spans.len() {
            break;
        }
        let Some(cell) = band_fills_one_cell(band, &edges) else {
            break;
        };
        if !head_cells.contains(&cell) {
            break;
        }
        let line_gap = last_line_in_cell[cell] - band.y;
        if line_gap <= 0.0 || line_gap > max_line_gap {
            break;
        }
        last_line_in_cell[cell] = band.y;
        continuations.push((band, cell));
        next_idx += 1;
    }
    if continuations.is_empty() {
        return None;
    }

    let wrapped_cells: Vec<usize> = continuations.iter().map(|(_, cell)| *cell).collect();
    if head_cells.iter().all(|cell| wrapped_cells.contains(cell)) {
        return None;
    }

    for cell in 0..edges.len() {
        let row_spans: Vec<TextSpan> = head
            .spans
            .iter()
            .zip(&head_cells)
            .filter(|(_, span_cell)| **span_cell == cell)
            .map(|(span, _)| span.clone())
            .collect();
        if !row_spans.is_empty() {
            blocks.push(TextBlock { spans: row_spans });
        }
        for (band, wrapped_cell) in &continuations {
            if *wrapped_cell == cell {
                blocks.push(band.row_block());
            }
        }
    }

    Some(next_idx)
}

/// Legacy wrapper used by call sites that haven't been handed PageStats.
/// It derives stats locally. Prefer `group_spans_into_bands_with_stats`
/// inside the XY-Cut pipeline to avoid recomputing the stats per call.
fn group_spans_into_bands(spans: Vec<TextSpan>) -> Vec<TextBand> {
    let stats = PageStats::from_spans(&spans);
    group_spans_into_bands_with_stats(spans, &stats)
}

fn group_spans_into_bands_with_stats(mut spans: Vec<TextSpan>, stats: &PageStats) -> Vec<TextBand> {
    if spans.is_empty() {
        return Vec::new();
    }

    spans.sort_by(|a, b| {
        b.y.partial_cmp(&a.y)
            .unwrap_or(Ordering::Equal)
            .then_with(|| a.x.partial_cmp(&b.x).unwrap_or(Ordering::Equal))
    });

    // ANN[r17/TEX4] Band tolerance scales with this page's median font
    // size rather than a fixed 5pt floor. Single-page spreads with
    // huge display fonts (24pt+) previously merged unrelated lines; a
    // fractional threshold keeps that from happening without hurting
    // body-text pages.
    let page_tolerance = (stats.median_font_size * BAND_Y_FRACTION).max(BAND_Y_TOLERANCE);

    let mut bands: Vec<TextBand> = Vec::new();

    for span in spans {
        let tolerance = (span.height * BAND_Y_FRACTION)
            .max(page_tolerance)
            .max(BAND_Y_TOLERANCE);
        if let Some(band) = bands
            .iter_mut()
            .find(|band| (band.y - span.y).abs() <= tolerance)
        {
            let span_count = band.spans.len() as f64;
            band.y = (band.y * span_count + span.y) / (span_count + 1.0);
            band.spans.push(span);
        } else {
            bands.push(TextBand::new(span));
        }
    }

    for band in &mut bands {
        band.sort_spans();
    }

    bands.sort_by(|a, b| b.y.partial_cmp(&a.y).unwrap_or(Ordering::Equal));
    bands
}

fn boundaries_match(boundaries: &[f64], gap_midpoints: &[f64], column_gap_threshold: f64) -> bool {
    let tolerance = (column_gap_threshold * 1.5).clamp(COLUMN_GAP_MATCH_TOLERANCE, 60.0);
    boundaries.len() == gap_midpoints.len()
        && boundaries
            .iter()
            .zip(gap_midpoints)
            .all(|(lhs, rhs)| (lhs - rhs).abs() <= tolerance)
}

fn update_boundaries(boundaries: &mut [f64], gap_midpoints: &[f64], seen_gapped_bands: usize) {
    for (boundary, midpoint) in boundaries.iter_mut().zip(gap_midpoints) {
        *boundary =
            (*boundary * seen_gapped_bands as f64 + midpoint) / (seen_gapped_bands as f64 + 1.0);
    }
}

fn region_is_columnar(
    bands: &[TextBand],
    band_indices: &[usize],
    boundaries: &[f64],
    gapped_band_count: usize,
) -> bool {
    if boundaries.is_empty()
        || gapped_band_count < MIN_COLUMN_GAPPED_BANDS
        || band_indices.is_empty()
        || (gapped_band_count as f64 / band_indices.len() as f64) < MIN_COLUMN_GAP_SUPPORT
    {
        return false;
    }

    let mut non_empty_slices = 0usize;
    let mut dense_slices = 0usize;
    let mut slices_per_column = vec![0usize; boundaries.len() + 1];

    for &band_idx in band_indices {
        let slices = bands[band_idx].split_by_boundaries(boundaries);
        for (column_idx, slice) in slices.iter().enumerate() {
            if slice.is_empty() {
                continue;
            }

            non_empty_slices += 1;
            slices_per_column[column_idx] += 1;

            let char_count = slice
                .iter()
                .map(|span| span.text.chars().count())
                .sum::<usize>();
            if slice.len() >= 2 || char_count >= 8 {
                dense_slices += 1;
            }
        }
    }

    if non_empty_slices < boundaries.len() + 2 {
        return false;
    }

    if slices_per_column.contains(&0) {
        return false;
    }

    (dense_slices as f64 / non_empty_slices as f64) >= MIN_DENSE_SLICE_RATIO
}

/// Whether the page rules this region into rows (#545).
///
/// A rule counts when it crosses the region -- `RULE_SPAN_FRACTION` of the
/// region's own width, so a line under a single cell does not speak for the
/// table -- and lies between the baselines of two bands that follow each other
/// in the region. Enough of the region's band gaps carrying such a rule is the
/// document saying, in its own graphics, that these bands are rows; and rows
/// are read across, never down.
///
/// What it does not claim: a table drawn without ruling lines is invisible
/// here, and this is deliberately the whole of the claim. The alternative
/// offered for that case was a width heuristic, and a width heuristic cannot
/// tell a table from a paper set in two columns -- it fixed the Isartor
/// appendix and cost `tracemonkey` p2 and p13, which is the class O-B danger
/// the #389 report names for exactly this defect.
fn region_is_ruled(bands: &[TextBand], band_indices: &[usize], rules: &[HorizontalRule]) -> bool {
    if rules.is_empty() || band_indices.len() < MIN_RULED_ROW_SEPARATORS + 1 {
        return false;
    }

    let mut left = f64::INFINITY;
    let mut right = f64::NEG_INFINITY;
    for &band_idx in band_indices {
        for span in &bands[band_idx].spans {
            left = left.min(span.x);
            right = right.max(span.measured_right());
        }
    }
    let width = right - left;
    if width <= 0.0 {
        return false;
    }

    let mut gaps = 0usize;
    let mut ruled = 0usize;
    for pair in band_indices.windows(2) {
        let upper = bands[pair[0]].y;
        let lower = bands[pair[1]].y;
        if upper <= lower {
            continue;
        }
        gaps += 1;
        let crossed = rules.iter().any(|rule| {
            rule.y > lower
                && rule.y < upper
                && (rule.right.min(right) - rule.left.max(left)) >= width * RULE_SPAN_FRACTION
        });
        if crossed {
            ruled += 1;
        }
    }

    gaps > 0
        && ruled >= MIN_RULED_ROW_SEPARATORS
        && (ruled as f64 / gaps as f64) >= MIN_RULED_GAP_SUPPORT
}

fn append_column_region_blocks(
    bands: &[TextBand],
    band_indices: &[usize],
    boundaries: &[f64],
    blocks: &mut Vec<TextBlock>,
) {
    let column_count = boundaries.len() + 1;
    let mut column_bands = vec![Vec::<TextSpan>::new(); column_count];

    for &band_idx in band_indices {
        let slices = bands[band_idx].split_by_boundaries(boundaries);
        for (column_idx, slice) in slices.into_iter().enumerate() {
            if slice.is_empty() {
                continue;
            }
            column_bands[column_idx].push(TextSpan::default());
            let marker_idx = column_bands[column_idx].len() - 1;
            column_bands[column_idx][marker_idx] = TextSpan {
                x: f64::NEG_INFINITY,
                y: bands[band_idx].y,
                ..TextSpan::default()
            };
            column_bands[column_idx].extend(slice);
        }
    }

    for spans in column_bands {
        let mut current: Vec<TextSpan> = Vec::new();
        for span in spans {
            if span.x == f64::NEG_INFINITY {
                if !current.is_empty() {
                    current.sort_by(|a, b| a.x.partial_cmp(&b.x).unwrap_or(Ordering::Equal));
                    blocks.push(TextBlock {
                        spans: std::mem::take(&mut current),
                    });
                }
                continue;
            }
            current.push(span);
        }
        if !current.is_empty() {
            current.sort_by(|a, b| a.x.partial_cmp(&b.x).unwrap_or(Ordering::Equal));
            blocks.push(TextBlock { spans: current });
        }
    }
}

/// Join per-block lines, stitching end-of-line hyphenated word-wraps the
/// way pdftotext / MuPDF / PDFBox do.
///
/// Trigger conditions (all must hold):
/// 1. Previous line ends with `-` preceded by an alphabetic character.
/// 2. The alphabetic suffix before the `-` has >= 3 characters.
/// 3. The next line (trimmed) starts with an ASCII lowercase letter.
/// 4. The lowercase prefix of the next line has >= 3 characters.
///
/// When triggered, the trailing `-` is removed and the two halves are
/// concatenated without a space or newline.
///
/// This avoids false positives on compound words ("real-time"), bullet
/// lists, numeric ranges ("42-"), and short fragments.
fn stitch_hyphenated_lines(lines: &[String]) -> String {
    let mut out = String::new();
    for (idx, line) in lines.iter().enumerate() {
        if idx == 0 {
            out.push_str(line);
            continue;
        }

        let next_trimmed = line.trim_start();

        // Check the accumulated output for end-of-line hyphen pattern
        let should_merge = is_hyphen_wrap_candidate(&out, next_trimmed);

        if should_merge {
            out.pop(); // drop the trailing '-'
            out.push_str(next_trimmed);
        } else {
            out.push('\n');
            out.push_str(line);
        }
    }
    out
}

/// Check if the accumulated text ends with a hyphen-wrap pattern and the
/// continuation is a valid merge target.
fn is_hyphen_wrap_candidate(accumulated: &str, next_trimmed: &str) -> bool {
    // Must end with '-'
    if !accumulated.ends_with('-') {
        return false;
    }

    // Character before '-' must be alphabetic
    let before_hyphen = accumulated.chars().rev().nth(1);
    if !before_hyphen.is_some_and(|c| c.is_alphabetic()) {
        return false;
    }

    // Count consecutive alphabetic chars before the '-' (the word fragment)
    let alpha_prefix_len = accumulated
        .chars()
        .rev()
        .skip(1) // skip the '-'
        .take_while(|c| c.is_alphabetic())
        .count();
    if alpha_prefix_len < 3 {
        return false;
    }

    // Next line must start with lowercase ASCII
    let first_next = next_trimmed.chars().next();
    if !first_next.is_some_and(|c| c.is_ascii_lowercase()) {
        return false;
    }

    // Count consecutive lowercase chars at start of next line
    let next_alpha_len = next_trimmed
        .chars()
        .take_while(|c| c.is_ascii_lowercase())
        .count();
    if next_alpha_len < 3 {
        return false;
    }

    true
}

/// Normalize extracted text to match pdftotext conventions.
///
/// 1. Trim trailing whitespace from each line.
/// 2. Collapse runs of more than two consecutive newlines into exactly two.
/// 3. Preserve form-feed characters (`\x0C`) as page separators.
/// 4. End with a single trailing newline (or empty for empty input).
pub(crate) fn normalize_text_output(text: &str) -> String {
    if text.is_empty() {
        return String::new();
    }

    let mut lines: Vec<&str> = Vec::new();
    for line in text.split('\n') {
        lines.push(line.trim_end());
    }

    // Remove trailing empty lines (we'll add exactly one \n at the end)
    while lines.last() == Some(&"") {
        lines.pop();
    }

    if lines.is_empty() {
        return String::new();
    }

    let mut result = String::with_capacity(text.len());
    let mut consecutive_empty = 0u32;

    for (i, line) in lines.iter().enumerate() {
        if line.is_empty() || *line == "\x0C" {
            if line.is_empty() {
                consecutive_empty += 1;
                // Collapse >2 consecutive blank lines to 2
                if consecutive_empty <= 2 {
                    result.push('\n');
                }
            } else {
                // Bare form-feed line
                consecutive_empty = 0;
                result.push_str(line);
                if i + 1 < lines.len() {
                    result.push('\n');
                }
            }
        } else {
            // Both form-feed-prefixed and regular lines are emitted as-is.
            consecutive_empty = 0;
            result.push_str(line);
            if i + 1 < lines.len() {
                result.push('\n');
            }
        }
    }

    // Ensure single trailing newline
    if !result.is_empty() && !result.ends_with('\n') {
        result.push('\n');
    }

    result
}

#[cfg(test)]
mod tests {
    use super::*;

    fn span(text: &str, x: f64, y: f64, width: f64) -> TextSpan {
        TextSpan {
            text: text.into(),
            x,
            y,
            width,
            height: 12.0,
            font_size: 12.0,
            ..TextSpan::default()
        }
    }

    /// A two-column academic page, the shape #429 is about: a full-width title,
    /// then two columns of body text whose right column ends one line short of
    /// the left. Every line is a realistic fraction of its column width.
    ///
    /// Returned in reading order — title, all of column one, then all of column
    /// two — so the test can say what the right answer is instead of guessing.
    ///
    /// The lines are prose-length on purpose. `estimated_width()` is
    /// `font_size * 0.5 * chars`, so a realistic line of about fifty characters
    /// estimates wider than it measures, and `right()` — which takes the larger
    /// of the two — then reaches across the gutter. Short labels would make a
    /// tidier fixture that never reproduces the defect.
    fn two_column_page() -> Vec<TextSpan> {
        const LEFT_X: f64 = 40.0;
        const RIGHT_X: f64 = 320.0;
        const COLUMN_WIDTH: f64 = 250.0;
        const TOP: f64 = 700.0;
        const LEADING: f64 = 14.0;
        const LINES: usize = 20;

        let mut out = vec![span(
            "A Trace-based Just-in-Time Compiler",
            40.0,
            740.0,
            530.0,
        )];
        for i in 0..LINES {
            out.push(span(
                &format!("left line {i:02} of the two-column academic body text"),
                LEFT_X,
                TOP - (i as f64) * LEADING,
                COLUMN_WIDTH,
            ));
        }
        // One line short: the right column ends above the left, which leaves the
        // left column's last band alone on its side of the gutter. Every real
        // two-column page has such bands -- a heading, a column that ends early,
        // a figure -- and the guard this test is about used to refuse the cut
        // for exactly that reason.
        for i in 0..(LINES - 1) {
            out.push(span(
                &format!("right line {i:02} of the two-column academic body text"),
                RIGHT_X,
                TOP - (i as f64) * LEADING,
                COLUMN_WIDTH,
            ));
        }
        out
    }

    /// #429: a two-column body is read column by column.
    ///
    /// The whole page in one assertion, because reading order is a property of
    /// the whole page and a per-block check would pass while the columns were
    /// interleaved. Revert either half of the fix and this goes red: with the
    /// gap scan on `right()` no gutter is found at all, and with the old
    /// band-aligned guard the cut is refused once it is.
    #[test]
    fn a_two_column_body_is_read_column_by_column() {
        let spans = two_column_page();
        let expected: Vec<String> = spans.iter().map(|s| s.text.clone()).collect();

        let produced: Vec<String> = group_spans_into_blocks(spans, &[])
            .into_iter()
            .flat_map(|b| b.spans.into_iter().map(|s| s.text))
            .collect();

        assert_eq!(produced, expected);
    }

    /// A JOURNAL GUTTER IS NARROWER THAN FOUR PERCENT OF THE PAGE (#389).
    ///
    /// The shape that the region-width rail refused: 9 pt type, a 493 pt text
    /// block, and the 13.2 pt gutter tracemonkey is actually set with. Four
    /// percent of that block is 19.7 pt, which is wider than the gutter of any
    /// journal, and the cut was refused on pages 2 and 13 of tracemonkey,
    /// highlights and tracemonkey_with_editable_annotations -- six of the eleven
    /// pages left under 95 % order agreement on the gate set.
    ///
    /// Returned in reading order, so the test says what the right answer is.
    fn narrow_gutter_page() -> Vec<TextSpan> {
        narrow_gutter_page_with_gutter(13.2)
    }

    /// The same page with the gutter set by the caller, so a test can ask for a
    /// gap that is not a gutter.
    fn narrow_gutter_page_with_gutter(gutter: f64) -> Vec<TextSpan> {
        const LEFT_X: f64 = 54.0;
        const COLUMN_WIDTH: f64 = 240.0;
        const FONT_SIZE: f64 = 9.0;
        const TOP: f64 = 700.0;
        const LEADING: f64 = 11.0;
        const LINES: usize = 20;

        let right_x = LEFT_X + COLUMN_WIDTH + gutter;
        let line = |text: &str, x: f64, y: f64| TextSpan {
            text: text.into(),
            x,
            y,
            width: COLUMN_WIDTH,
            height: FONT_SIZE,
            font_size: FONT_SIZE,
            ..TextSpan::default()
        };

        let mut out = vec![TextSpan {
            text: "Trace-based Just-in-Time Type Specialization".into(),
            x: LEFT_X,
            y: 740.0,
            width: 490.0,
            height: 14.0,
            font_size: 14.0,
            ..TextSpan::default()
        }];
        // PROSE-LENGTH LINES, for the same reason `two_column_page` gives them:
        // `estimated_width()` is font_size * 0.5 * chars, so a real line of
        // sixty characters overshoots its measured width and the overshoot
        // swallows the gutter -- which is how a page ends up with no measurable
        // word gaps at all and the adaptive threshold falls back to 20 pt.
        for i in 0..LINES {
            out.push(line(
                &format!("left line {i:02} of the two-column academic body of this paper"),
                LEFT_X,
                TOP - (i as f64) * LEADING,
            ));
        }
        for i in 0..(LINES - 1) {
            out.push(line(
                &format!("right line {i:02} of the two-column academic body of this paper"),
                right_x,
                TOP - (i as f64) * LEADING,
            ));
        }
        out
    }

    /// Red the moment a gutter has to be a fraction of the region again.
    ///
    /// Asked of `try_vertical_cut` itself, so that it names the cut and not the
    /// page: the reading order below is the consequence and this is the cause.
    #[test]
    fn a_thirteen_point_gutter_in_nine_point_type_is_a_gutter() {
        let spans = narrow_gutter_page();
        let body: Vec<TextSpan> = spans.iter().filter(|s| s.y < 720.0).cloned().collect();
        let stats = PageStats::from_spans(&body);

        let (groups, gap) = try_vertical_cut(&body, &stats, &[])
            .expect("no column cut found on a 13.2 pt gutter in 9 pt type");

        assert_eq!(groups.len(), 2);
        assert!(
            (gap - 13.2).abs() < 0.5,
            "the cut was taken on a gap of {gap}, not on the gutter"
        );
        assert!(
            groups[0].iter().all(|s| s.text.starts_with("left")),
            "the left group holds text from the right column"
        );
        assert!(
            groups[1].iter().all(|s| s.text.starts_with("right")),
            "the right group holds text from the left column"
        );
    }

    /// And the whole page, in reading order, through the path a document takes.
    /// Red with the rail back as well: the leaf's own band-by-band gutter
    /// detector does not rescue a page whose lines overshoot their measured
    /// width, which is every page set in a proportional face.
    #[test]
    fn the_narrow_gutter_page_reads_column_by_column() {
        let spans = narrow_gutter_page();
        let expected: Vec<String> = spans.iter().map(|s| s.text.clone()).collect();

        let produced: Vec<String> = group_spans_into_blocks(spans, &[])
            .into_iter()
            .flat_map(|b| b.spans.into_iter().map(|s| s.text))
            .collect();

        assert_eq!(produced, expected);
    }

    /// And the floor still does its work: the same page whose columns are six
    /// points apart is not two columns, because six points is a word space in
    /// nine point type. Red if the floor is dropped along with the rail.
    #[test]
    fn a_gap_narrower_than_the_type_is_not_a_gutter() {
        let spans = narrow_gutter_page_with_gutter(6.0);
        let body: Vec<TextSpan> = spans.iter().filter(|s| s.y < 720.0).cloned().collect();
        let stats = PageStats::from_spans(&body);

        assert!(
            try_vertical_cut(&body, &stats, &[]).is_none(),
            "a six point gap in nine point type was taken for a column gutter"
        );
    }

    /// The gutter is only there in the MEASURED edges. `right()` returns
    /// x + width.max(estimated_width()), and on tracemonkey's abstract that
    /// estimate overshoots the measured edge by 61pt -- wider than the gutter
    /// it then covers, so the scan finds no corridor and the guards never run.
    #[test]
    fn a_column_gap_is_found_on_measured_edges_not_estimated_ones() {
        let spans = two_column_page();
        let body: Vec<TextSpan> = spans.iter().filter(|s| s.y < 720.0).cloned().collect();
        let stats = PageStats::from_spans(&body);

        let overshoots = body.iter().any(|s| s.right() > s.measured_right() + 1.0);
        assert!(
            overshoots,
            "fixture no longer exercises the overshoot; right() must exceed measured_right()              for this test to mean anything"
        );

        let cut = try_vertical_cut(&body, &stats, &[]);
        assert!(
            cut.is_some(),
            "no column cut found on a clean two-column body"
        );
    }

    fn block_texts(spans: Vec<TextSpan>) -> Vec<String> {
        block_texts_with_rules(spans, &[])
    }

    /// The same, with the horizontal rules the page drew (#545).
    fn block_texts_with_rules(spans: Vec<TextSpan>, rules: &[HorizontalRule]) -> Vec<String> {
        group_spans_into_blocks(spans, rules)
            .into_iter()
            .map(|block| block.text())
            .collect()
    }

    /// The same, but only the leaf of the XY-cut: the bands as
    /// `group_spans_into_blocks_legacy_from_bands` sees them.
    ///
    /// Some of the shapes below are refused by the leaf and taken by the column
    /// cut above it instead, which proves nothing about the leaf. This says what
    /// the leaf does with them.
    fn leaf_texts(spans: Vec<TextSpan>) -> Vec<String> {
        let bands = group_spans_into_bands(spans);
        group_spans_into_blocks_legacy_from_bands(bands, &[])
            .iter()
            .map(TextBlock::text)
            .collect()
    }

    #[test]
    fn empty_device_produces_empty_text() {
        let dev = TextExtractionDevice::new();
        assert!(dev.into_text().is_empty());
    }

    #[test]
    fn single_column_stays_row_major() {
        let texts = block_texts(vec![
            span("Single Column Line 1", 40.0, 700.0, 140.0),
            span("Single Column Line 2", 40.0, 684.0, 140.0),
            span("Single Column Line 3", 40.0, 668.0, 140.0),
        ]);

        assert_eq!(
            texts,
            vec![
                "Single Column Line 1",
                "Single Column Line 2",
                "Single Column Line 3",
            ]
        );
    }

    /// A header, three bands each of which draws two slices with a gutter
    /// between them, and a footer. Read as columns unless the page says
    /// otherwise, which is what the three tests after this one are about.
    fn two_column_region_spans() -> Vec<TextSpan> {
        vec![
            span("Header", 200.0, 740.0, 80.0),
            span("Left column line one", 40.0, 700.0, 115.0),
            span("Right column line one", 320.0, 700.0, 120.0),
            span("Left column line two", 40.0, 684.0, 115.0),
            span("Right column line two", 320.0, 684.0, 120.0),
            span("Left column line three", 40.0, 668.0, 125.0),
            span("Right column line three", 320.0, 668.0, 130.0),
            span("Footer", 200.0, 620.0, 80.0),
        ]
    }

    #[test]
    fn two_column_region_reads_column_major() {
        let texts = block_texts(two_column_region_spans());

        assert_eq!(
            texts,
            vec![
                "Header",
                "Left column line one",
                "Left column line two",
                "Left column line three",
                "Right column line one",
                "Right column line two",
                "Right column line three",
                "Footer",
            ]
        );
    }

    /// The rules the page draws between its rows, for the fixture above: a
    /// horizontal line across the whole table, in every gap between two rows.
    fn rules_between_the_rows() -> Vec<HorizontalRule> {
        [692.0, 676.0]
            .into_iter()
            .map(|y| HorizontalRule {
                left: 35.0,
                right: 445.0,
                y,
            })
            .collect()
    }

    /// The same three bands that read column by column above, with a ruling
    /// line between each pair of them, read across instead (#545). This is the
    /// Isartor appendix: two columns of text that are the two cells of a row,
    /// and nothing but the page's own graphics says so.
    #[test]
    fn a_ruled_two_column_region_is_read_row_by_row() {
        let texts = block_texts_with_rules(two_column_region_spans(), &rules_between_the_rows());

        assert_eq!(
            texts,
            vec![
                "Header",
                "Left column line one Right column line one",
                "Left column line two Right column line two",
                "Left column line three Right column line three",
                "Footer",
            ]
        );
    }

    /// A rule under one cell is not a rule between two rows. Widening the test
    /// to any line that happens to sit in the gap turns every underlined cell
    /// into a table, so the rule has to cross the region it claims to divide.
    #[test]
    fn a_rule_that_crosses_only_one_column_leaves_the_columns_alone() {
        let short: Vec<HorizontalRule> = rules_between_the_rows()
            .into_iter()
            .map(|rule| HorizontalRule {
                right: 160.0,
                ..rule
            })
            .collect();

        let texts = block_texts_with_rules(two_column_region_spans(), &short);

        assert_eq!(
            texts,
            vec![
                "Header",
                "Left column line one",
                "Left column line two",
                "Left column line three",
                "Right column line one",
                "Right column line two",
                "Right column line three",
                "Footer",
            ]
        );
    }

    /// One rule is a headline's underline, a footnote's separator, the line
    /// above a page number -- every document has them, and none of them makes
    /// the text below a table.
    ///
    /// Asked of the predicate rather than of the page, because a region of
    /// three bands with one rule in it is refused by the column cut above the
    /// leaf for its own reasons, and a page-level assertion would be green
    /// whatever this rule said.
    #[test]
    fn a_single_rule_does_not_make_a_region_a_table() {
        let bands = group_spans_into_bands(two_column_region_spans());
        let rows: Vec<usize> = bands
            .iter()
            .enumerate()
            .filter(|(_, band)| band.y < 720.0 && band.y > 640.0)
            .map(|(idx, _)| idx)
            .collect();
        assert_eq!(
            rows.len(),
            3,
            "the fixture's three rows are the region here"
        );

        let both = rules_between_the_rows();
        assert!(
            region_is_ruled(&bands, &rows, &both),
            "a rule in every gap of the region is a ruled table"
        );
        assert!(
            !region_is_ruled(&bands, &rows, &both[..1]),
            "one rule is not a table"
        );
    }

    /// One path may hold every rule a table draws, so a cap asked once per
    /// `draw_path` bounds nothing. The vector it would grow is walked per band
    /// by `region_is_ruled`, which is why the bound is on the vector and not on
    /// the call.
    #[test]
    fn one_path_of_many_rules_still_stops_at_the_cap() {
        let mut path = BezPath::new();
        for row in 0..(MAX_RECORDED_RULES * 2) {
            let y = 700.0 - row as f64;
            path.move_to((40.0, y));
            path.line_to((440.0, y));
            path.close_path();
        }

        let mut device = TextExtractionDevice::new();
        device.record_rule(&path, Affine::IDENTITY);

        assert_eq!(device.rules.len(), MAX_RECORDED_RULES);
    }

    /// A Form XObject's `/BBox` reaches this device as a clip, with the
    /// geometry inside it unclipped. A line ruled across one cell of such a
    /// form therefore arrives as a line across the page, and two of those are
    /// enough to refuse a column cut that should have been taken.
    #[test]
    fn a_rule_is_recorded_at_the_width_the_clip_leaves_it() {
        let mut wide = BezPath::new();
        wide.move_to((40.0, 600.0));
        wide.line_to((440.0, 600.0));

        let mut device = TextExtractionDevice::new();
        device.push_clip_path(&ClipPath {
            path: kurbo::Rect::new(40.0, 500.0, 160.0, 700.0).to_path(0.1),
            fill: pdf_render::pdf_interpret::FillRule::NonZero,
        });
        device.record_rule(&wide, Affine::IDENTITY);

        assert_eq!(device.rules.len(), 1, "the visible part is still a rule");
        assert!(
            device.rules[0].right < 161.0,
            "the rule was recorded past its clip: {:?}",
            device.rules[0]
        );

        let mut above = BezPath::new();
        above.move_to((40.0, 800.0));
        above.line_to((440.0, 800.0));
        device.record_rule(&above, Affine::IDENTITY);
        assert_eq!(
            device.rules.len(),
            1,
            "a rule the clip cuts away entirely was recorded: {:?}",
            device.rules
        );

        device.pop_clip_path();
        device.record_rule(&wide, Affine::IDENTITY);
        assert_eq!(
            device.rules[1].right, 440.0,
            "the clip outlived the pop: {:?}",
            device.rules[1]
        );
    }

    /// A table rules most of its gaps and a page of prose rules a couple: the
    /// share is what separates them, and it is measured rather than assumed.
    /// The Isartor appendix rules 26 of its 28 gaps; the two it leaves are the
    /// rows whose cell wraps, which is why the share is a half and not all.
    #[test]
    fn a_region_with_a_rule_in_a_minority_of_its_gaps_is_not_a_table() {
        let mut spans = Vec::new();
        for row in 0..6 {
            let y = 700.0 - row as f64 * 16.0;
            spans.push(span("Left column line", 40.0, y, 115.0));
            spans.push(span("Right column line", 320.0, y, 120.0));
        }
        let bands = group_spans_into_bands(spans);
        let rows: Vec<usize> = (0..bands.len()).collect();
        assert_eq!(bands.len(), 6, "six rows, so five gaps between them");

        let rule_at = |y: f64| HorizontalRule {
            left: 35.0,
            right: 445.0,
            y,
        };
        let two = vec![rule_at(692.0), rule_at(676.0)];
        let three = vec![rule_at(692.0), rule_at(676.0), rule_at(660.0)];

        assert!(
            !region_is_ruled(&bands, &rows, &two),
            "two of five is prose"
        );
        assert!(
            region_is_ruled(&bands, &rows, &three),
            "three of five is a table"
        );
    }

    #[test]
    fn mixed_single_and_multi_column_regions_preserve_shared_bands() {
        let texts = block_texts(vec![
            span("Intro paragraph", 40.0, 740.0, 180.0),
            span("L1 words here", 40.0, 700.0, 110.0),
            span("R1 words here", 320.0, 700.0, 110.0),
            span("L2 words here", 40.0, 684.0, 110.0),
            span("R2 words here", 320.0, 684.0, 110.0),
            span("L3 words here", 40.0, 668.0, 110.0),
            span("R3 words here", 320.0, 668.0, 110.0),
            span("Outro paragraph", 40.0, 620.0, 180.0),
        ]);

        assert_eq!(
            texts,
            vec![
                "Intro paragraph",
                "L1 words here",
                "L2 words here",
                "L3 words here",
                "R1 words here",
                "R2 words here",
                "R3 words here",
                "Outro paragraph",
            ]
        );
    }

    #[test]
    fn short_table_like_rows_fall_back_to_row_major() {
        let texts = block_texts(vec![
            span("Name", 40.0, 700.0, 30.0),
            span("Age", 320.0, 700.0, 20.0),
            span("Alice", 40.0, 684.0, 35.0),
            span("30", 320.0, 684.0, 15.0),
            span("Bob", 40.0, 668.0, 24.0),
            span("25", 320.0, 668.0, 15.0),
        ]);

        assert_eq!(texts, vec!["Name Age", "Alice 30", "Bob 25"]);
    }

    /// A three-column table row whose middle cell wraps, at the block level:
    /// the reordering happens in the leaf of the XY-cut, and this is the leaf's
    /// own view of `8.2.5.26-t05-pass-d.pdf`'s second row (#434).
    #[test]
    fn a_wrapped_cell_is_emitted_with_its_own_cell() {
        let texts = block_texts(vec![
            span("Index", 60.0, 700.0, 30.0),
            span("Failure condition", 200.0, 700.0, 100.0),
            span("Section", 400.0, 700.0, 42.0),
            span("15-003", 60.0, 680.0, 36.0),
            span("In a table not organized", 200.0, 680.0, 144.0),
            span("UA1:7.5-2", 400.0, 680.0, 54.0),
            span("a cell without a Scope", 200.0, 668.0, 132.0),
        ]);

        assert_eq!(
            texts,
            vec![
                "Index Failure condition Section",
                "15-003",
                "In a table not organized",
                "a cell without a Scope",
                "UA1:7.5-2",
            ]
        );
    }

    /// The failure case the fix names: when every cell of the row has a line
    /// under it, nothing says which of those lines continues the row and which
    /// one begins the next -- the same shape a two-column region takes when one
    /// column runs on alone. Such a row keeps today's row-major order rather
    /// than being guessed at.
    /// The leading is deliberately tight, so that all three lines pass the
    /// distance test in their own cell and it is the last guard -- every cell
    /// of the row having a line under it -- that has to refuse the row. At that
    /// leading the column cut above the leaf takes the page, so this one asks
    /// the leaf directly.
    #[test]
    fn a_row_whose_every_cell_wraps_stays_row_major() {
        let texts = leaf_texts(vec![
            span("Index", 60.0, 700.0, 30.0),
            span("Failure condition", 200.0, 700.0, 100.0),
            span("Section", 400.0, 700.0, 42.0),
            span("15-003", 60.0, 680.0, 36.0),
            span("In a table not organized", 200.0, 680.0, 144.0),
            span("UA1:7.5-2", 400.0, 680.0, 54.0),
            span("is the index", 60.0, 674.0, 72.0),
            span("a cell without a Scope", 200.0, 668.0, 132.0),
            span("of the suite", 400.0, 662.0, 72.0),
        ]);

        assert_eq!(
            texts,
            vec![
                "Index Failure condition Section",
                "15-003 In a table not organized UA1:7.5-2",
                "is the index",
                "a cell without a Scope",
                "of the suite",
            ]
        );
    }

    /// The next row of a table with an empty cell also has fewer spans than the
    /// row above it and also starts on the same edges. It is the next row all
    /// the same, and what says so is that it fills two cells where a wrapped
    /// line fills one. The header of this table is padded, so the body's rows
    /// sit closer together than the pitch under the header and the distance
    /// alone would let this one pass.
    #[test]
    fn a_row_with_an_empty_cell_is_a_row_and_not_a_wrap() {
        let texts = block_texts(vec![
            span("Index", 60.0, 700.0, 30.0),
            span("Type", 200.0, 700.0, 24.0),
            span("How", 400.0, 700.0, 18.0),
            span("15-003", 60.0, 680.0, 36.0),
            span("Object", 200.0, 680.0, 36.0),
            span("Machine", 400.0, 680.0, 42.0),
            span("15-004", 60.0, 666.0, 36.0),
            span("Rope", 400.0, 666.0, 24.0),
        ]);

        assert_eq!(
            texts,
            vec!["Index Type How", "15-003 Object Machine", "15-004 Rope"]
        );
    }

    /// A row that fills a single cell, one line under a wrapped one. Measured
    /// against the wrapped line it is a line's distance away; measured against
    /// the cell it would join -- which has no line under it yet, so the row
    /// itself -- it is two, and it is a row.
    #[test]
    fn a_single_cell_row_under_a_wrapped_line_is_still_a_row() {
        let texts = block_texts(vec![
            span("Index", 60.0, 700.0, 30.0),
            span("Type", 200.0, 700.0, 24.0),
            span("How", 400.0, 700.0, 18.0),
            span("15-003", 60.0, 680.0, 36.0),
            span("In a table not organized", 200.0, 680.0, 144.0),
            span("UA1:7.5-2", 400.0, 680.0, 54.0),
            span("a cell without a Scope", 200.0, 668.0, 132.0),
            span("15-004", 60.0, 656.0, 36.0),
        ]);

        assert_eq!(
            texts,
            vec![
                "Index Type How",
                "15-003",
                "In a table not organized",
                "a cell without a Scope",
                "UA1:7.5-2",
                "15-004",
            ]
        );
    }

    /// The same, with a row that fills a single cell: nothing but the pitch
    /// separates it from a wrapped line, and the pitch is what says it.
    #[test]
    fn a_line_a_whole_row_pitch_down_is_a_row_and_not_a_wrap() {
        let texts = block_texts(vec![
            span("Index", 60.0, 700.0, 30.0),
            span("Type", 200.0, 700.0, 24.0),
            span("How", 400.0, 700.0, 18.0),
            span("15-003", 60.0, 680.0, 36.0),
            span("Object", 200.0, 680.0, 36.0),
            span("Machine", 400.0, 680.0, 42.0),
            span("Rope", 200.0, 660.0, 24.0),
        ]);

        assert_eq!(
            texts,
            vec!["Index Type How", "15-003 Object Machine", "Rope"]
        );
    }

    #[test]
    fn three_column_regions_are_supported() {
        let texts = block_texts(vec![
            span("Column one line one", 40.0, 700.0, 105.0),
            span("Column two line one", 220.0, 700.0, 105.0),
            span("Column three line one", 400.0, 700.0, 120.0),
            span("Column one line two", 40.0, 684.0, 105.0),
            span("Column two line two", 220.0, 684.0, 105.0),
            span("Column three line two", 400.0, 684.0, 120.0),
            span("Column one line three", 40.0, 668.0, 120.0),
            span("Column two line three", 220.0, 668.0, 120.0),
            span("Column three line three", 400.0, 668.0, 135.0),
        ]);

        assert_eq!(
            texts,
            vec![
                "Column one line one",
                "Column one line two",
                "Column one line three",
                "Column two line one",
                "Column two line two",
                "Column two line three",
                "Column three line one",
                "Column three line two",
                "Column three line three",
            ]
        );
    }

    #[test]
    fn text_block_concatenation_spaced() {
        let block = TextBlock {
            spans: vec![span("A", 0.0, 0.0, 6.0), span("B", 20.0, 0.0, 6.0)],
        };
        assert_eq!(block.text(), "A B");
    }

    #[test]
    fn adaptive_column_gap_fallback_for_no_gaps() {
        // Single-span bands produce no measurable gaps → fallback
        let bands = vec![
            TextBand::new(span("Hello", 40.0, 700.0, 80.0)),
            TextBand::new(span("World", 40.0, 684.0, 80.0)),
        ];
        let threshold = compute_adaptive_column_gap(&bands);
        assert!((threshold - COLUMN_GAP_THRESHOLD_FALLBACK).abs() < 0.01);
    }

    #[test]
    fn adaptive_column_gap_uses_median() {
        // Three bands with word gaps of ~4pt each → median ≈ 4, threshold = 12
        let mut bands = Vec::new();
        for y in [700.0, 684.0, 668.0] {
            let mut band = TextBand::new(span("word1", 40.0, y, 30.0));
            band.spans.push(span("word2", 74.0, y, 30.0)); // gap = 4
            band.spans.push(span("word3", 108.0, y, 30.0)); // gap = 4
            bands.push(band);
        }
        let threshold = compute_adaptive_column_gap(&bands);
        // median gap = 4, × 3 = 12, clamped to [10, 40] → 12
        assert!(
            (10.0..=14.0).contains(&threshold),
            "expected ~12, got {threshold}"
        );
    }

    #[test]
    fn adaptive_column_gap_clamps_to_min() {
        // Tight gaps (2pt) across many bands → median = 2, 3×2 = 6 → clamped to 10
        let mut bands = Vec::new();
        for y in [700.0, 684.0, 668.0, 652.0] {
            let mut band = TextBand::new(span("abc", 0.0, y, 18.0));
            // right of "abc" = max(18, 12*0.5*3=18) = 18; gap = 20-18 = 2
            band.spans.push(span("def", 20.0, y, 18.0));
            bands.push(band);
        }
        let threshold = compute_adaptive_column_gap(&bands);
        assert!(
            (threshold - COLUMN_GAP_THRESHOLD_MIN).abs() < 0.01,
            "expected {COLUMN_GAP_THRESHOLD_MIN}, got {threshold}"
        );
    }

    #[test]
    fn adaptive_column_gap_all_large_gaps_uses_fraction_of_min() {
        // When all gaps are large (> MIN), threshold = 0.75 × min_gap.
        let mut band = TextBand::new(span("Left", 0.0, 700.0, 30.0));
        band.spans.push(span("Right", 80.0, 700.0, 30.0)); // gap = 50
        let bands = vec![band];
        let threshold = compute_adaptive_column_gap(&bands);
        assert!(
            (threshold - 37.5).abs() < 0.01,
            "expected 37.5 (0.75×50), got {threshold}"
        );
    }

    #[test]
    fn normalize_trims_trailing_whitespace_per_line() {
        assert_eq!(
            normalize_text_output("hello   \nworld  \n"),
            "hello\nworld\n"
        );
    }

    #[test]
    fn normalize_collapses_excess_newlines() {
        // >2 blank lines collapse to 2 (meaning 3 \n in a row: line, blank, blank)
        assert_eq!(
            normalize_text_output("hello\n\n\n\n\nworld\n"),
            "hello\n\n\nworld\n"
        );
    }

    #[test]
    fn normalize_preserves_double_newline() {
        assert_eq!(
            normalize_text_output("paragraph one\n\nparagraph two\n"),
            "paragraph one\n\nparagraph two\n"
        );
    }

    #[test]
    fn normalize_preserves_form_feed() {
        assert_eq!(
            normalize_text_output("page1\n\n\x0Cpage2\n"),
            "page1\n\n\x0Cpage2\n"
        );
    }

    #[test]
    fn normalize_adds_trailing_newline() {
        assert_eq!(normalize_text_output("hello"), "hello\n");
    }

    #[test]
    fn normalize_empty_input() {
        assert_eq!(normalize_text_output(""), "");
    }

    #[test]
    fn normalize_only_whitespace() {
        assert_eq!(normalize_text_output("   \n  \n"), "");
    }

    // --- Hyphen stitching tests ---

    #[test]
    fn hyphen_stitch_joins_wrapped_word() {
        let lines = vec!["the aver-".into(), "age rainfall".into()];
        assert_eq!(stitch_hyphenated_lines(&lines), "the average rainfall");
    }

    #[test]
    fn hyphen_stitch_handles_leading_whitespace() {
        let lines = vec!["pre-".into(), "   dict the outcome".into()];
        // "pre" is only 3 chars → meets >= 3 guard
        assert_eq!(stitch_hyphenated_lines(&lines), "predict the outcome");
    }

    #[test]
    fn hyphen_stitch_capital_continuation_not_stitched() {
        let lines = vec!["Section three-".into(), "Summary here".into()];
        assert_eq!(
            stitch_hyphenated_lines(&lines),
            "Section three-\nSummary here"
        );
    }

    #[test]
    fn hyphen_stitch_bullet_dash_not_stitched() {
        // "-" alone: char before hyphen is not alphabetic
        let lines = vec!["Items:".into(), "-".into(), "milk".into()];
        assert_eq!(stitch_hyphenated_lines(&lines), "Items:\n-\nmilk");
    }

    #[test]
    fn hyphen_stitch_numeric_range_not_stitched() {
        // "42-" — char before hyphen is digit, not alphabetic
        let lines = vec!["page 42-".into(), "seventy".into()];
        assert_eq!(stitch_hyphenated_lines(&lines), "page 42-\nseventy");
    }

    #[test]
    fn hyphen_stitch_short_prefix_not_stitched() {
        // "re-" only 2 alpha chars before hyphen → below 3-char guard
        let lines = vec!["re-".into(), "organize".into()];
        assert_eq!(stitch_hyphenated_lines(&lines), "re-\norganize");
    }

    #[test]
    fn hyphen_stitch_short_continuation_not_stitched() {
        // Next line starts with "an" (2 chars) → below 3-char guard
        let lines = vec!["counter-".into(), "an example".into()];
        assert_eq!(stitch_hyphenated_lines(&lines), "counter-\nan example");
    }

    #[test]
    fn hyphen_stitch_compound_word_midline_preserved() {
        // "real-time" is mid-line, not end-of-line — no stitching applies
        // because stitch only operates on line boundaries
        let lines = vec!["real-time system".into()];
        assert_eq!(stitch_hyphenated_lines(&lines), "real-time system");
    }

    #[test]
    fn hyphen_stitch_single_line_unchanged() {
        let lines = vec!["only line".into()];
        assert_eq!(stitch_hyphenated_lines(&lines), "only line");
    }

    #[test]
    fn hyphen_stitch_empty_input() {
        let lines: Vec<String> = vec![];
        assert_eq!(stitch_hyphenated_lines(&lines), "");
    }

    // --- TEX1 multi-signal space consensus tests ---

    fn make_device_with_median(median: f64) -> TextExtractionDevice {
        let mut dev = TextExtractionDevice::new();
        // Seed enough samples for the median to resolve to `median`.
        for _ in 0..MEDIAN_REFRESH {
            dev.glyph_widths.push(median);
        }
        dev.refresh_median_char_width();
        assert!((dev.cached_median_char_width - median).abs() < 1e-9);
        dev
    }

    #[test]
    fn consensus_inserts_space_on_strong_tj_offset_alone() {
        // Gap is below the geometric threshold, but the TJ offset is large
        // enough that the consensus must still fire.
        let mut dev = make_device_with_median(6.0);
        dev.pending_tj_offset = 250.0; // full em-space
        assert!(dev.evaluate_space_consensus(0.5, 12.0, "Hello", "World"));
    }

    #[test]
    fn consensus_inserts_space_on_geometric_gap_alone() {
        // No TJ, no character transition, but a clearly wide geometric gap.
        let dev = make_device_with_median(6.0);
        // gap > 0.3 * 6.0 = 1.8 → fires gap signal (0.80), below threshold
        // on its own? 0.80 < 0.75 threshold? No, 0.80 > 0.75, so it fires.
        assert!(dev.evaluate_space_consensus(2.5, 12.0, "hello", "world"));
    }

    #[test]
    fn consensus_no_space_on_kerning_gap() {
        // Small kerning-size gap with no other signals must not inject a
        // space (regression guard against false-positive spaces inside
        // tightly kerned words).
        let dev = make_device_with_median(6.0);
        assert!(!dev.evaluate_space_consensus(0.5, 12.0, "fi", "lm"));
    }

    #[test]
    fn consensus_inserts_space_on_camel_case_plus_gap() {
        // CamelCase heuristic (0.60) alone doesn't reach threshold, but a
        // moderate gap (0.60 gap + 0.60 heuristic if gap fires) should.
        // Here gap = 2.5 > 1.8 → gap fires → total 0.80 + 0.60 = 1.40.
        let dev = make_device_with_median(6.0);
        assert!(dev.evaluate_space_consensus(2.5, 12.0, "helloWorld", "Inc"));
    }

    #[test]
    fn consensus_inserts_space_on_digit_letter_transition_with_gap() {
        let dev = make_device_with_median(6.0);
        assert!(dev.evaluate_space_consensus(2.5, 12.0, "123", "abc"));
    }

    #[test]
    fn consensus_heuristic_alone_is_insufficient() {
        // Heuristic (0.60) on its own is below the 0.75 threshold — the
        // design deliberately requires a second corroborating signal to
        // avoid gluing spaces into existing CamelCase identifiers that
        // have no geometric break.
        let dev = make_device_with_median(6.0);
        assert!(!dev.evaluate_space_consensus(0.5, 12.0, "camel", "Case"));
    }

    #[test]
    fn consensus_falls_back_to_font_size_when_no_median() {
        // No samples → median is 0; geometric reference uses font-size.
        let dev = TextExtractionDevice::new();
        // gap 1.9 > 0.15 * 12.0 = 1.8 → gap signal fires
        assert!(dev.evaluate_space_consensus(1.9, 12.0, "a", "b"));
        // gap 1.5 < 1.8 → no signal
        assert!(!dev.evaluate_space_consensus(1.5, 12.0, "a", "b"));
    }

    #[test]
    fn consensus_ignores_tiny_tj_offsets() {
        // TJ offsets below the threshold are kerning, not word breaks.
        let mut dev = make_device_with_median(6.0);
        dev.pending_tj_offset = 50.0;
        assert!(!dev.evaluate_space_consensus(0.5, 12.0, "Hello", "World"));
    }

    #[test]
    fn consensus_accepts_negative_tj_offsets() {
        // A negative TJ offset still represents an explicit inter-substring
        // shift and counts toward the consensus (|amount| check).
        let mut dev = make_device_with_median(6.0);
        dev.pending_tj_offset = -250.0;
        assert!(dev.evaluate_space_consensus(0.5, 12.0, "Hello", "World"));
    }

    #[test]
    fn text_adjustment_accumulates_until_glyph() {
        let mut dev = TextExtractionDevice::new();
        dev.text_adjustment(120.0);
        dev.text_adjustment(140.0);
        assert!((dev.pending_tj_offset - 260.0).abs() < 1e-6);
    }

    // --- TEX2 XY-Cut tests ---

    #[test]
    fn xy_cut_header_body_footer_with_two_columns() {
        // Header and footer sit in the mid-x range that would
        // accidentally fall into a left-column bucket with a naive
        // vertical-first cut. The largest-gap-first rule plus the
        // alignment guard ensure header and footer bracket the
        // columnar body.
        let texts = block_texts(vec![
            span("HEADLINE TITLE", 180.0, 760.0, 120.0),
            span("Left col line A", 40.0, 700.0, 110.0),
            span("Right col line A", 320.0, 700.0, 115.0),
            span("Left col line B", 40.0, 684.0, 110.0),
            span("Right col line B", 320.0, 684.0, 115.0),
            span("Left col line C", 40.0, 668.0, 110.0),
            span("Right col line C", 320.0, 668.0, 115.0),
            span("FOOTER LINE TEXT", 180.0, 600.0, 120.0),
        ]);
        assert_eq!(texts.first().map(String::as_str), Some("HEADLINE TITLE"));
        assert_eq!(texts.last().map(String::as_str), Some("FOOTER LINE TEXT"));
        // Left column lines all come before right column lines.
        let left_c_idx = texts.iter().position(|s| s == "Left col line C").unwrap();
        let right_a_idx = texts.iter().position(|s| s == "Right col line A").unwrap();
        assert!(
            left_c_idx < right_a_idx,
            "expected column-major ordering in body: {texts:?}"
        );
    }

    #[test]
    fn xy_cut_rejects_column_split_on_table_rows() {
        // The density guard must still reject the 280pt inter-cell gap
        // in a short-cell table, preserving row-major reading order.
        let texts = block_texts(vec![
            span("Name", 40.0, 700.0, 30.0),
            span("Age", 320.0, 700.0, 20.0),
            span("Alice", 40.0, 684.0, 35.0),
            span("30", 320.0, 684.0, 15.0),
        ]);
        assert_eq!(texts, vec!["Name Age", "Alice 30"]);
    }

    #[test]
    fn xy_cut_rejects_column_split_when_one_band_is_full_width() {
        // The alignment guard catches a full-width paragraph that
        // would otherwise be forced into the left column of a 2-column
        // region below it.
        let texts = block_texts(vec![
            span(
                "Full width intro spanning both columns here",
                40.0,
                740.0,
                360.0,
            ),
            span("Left A", 40.0, 700.0, 50.0),
            span("Right A", 320.0, 700.0, 50.0),
            span("Left B", 40.0, 684.0, 50.0),
            span("Right B", 320.0, 684.0, 50.0),
        ]);
        assert!(
            texts[0].contains("Full width intro"),
            "expected full-width intro first: {texts:?}"
        );
    }

    #[test]
    fn xy_cut_horizontal_split_for_zone_boundaries() {
        // Pure horizontal cut on a single-column page with a big
        // vertical gap between paragraphs — the cut fires and both
        // paragraphs stay in their own blocks.
        let texts = block_texts(vec![
            span("First paragraph body text", 40.0, 740.0, 200.0),
            span("Second paragraph body", 40.0, 680.0, 180.0),
        ]);
        assert_eq!(texts.len(), 2);
        assert!(texts[0].starts_with("First"));
        assert!(texts[1].starts_with("Second"));
    }

    #[test]
    fn xy_cut_recursion_terminates_with_single_span() {
        let texts = block_texts(vec![span("Only one span on the page", 40.0, 700.0, 180.0)]);
        assert_eq!(texts, vec!["Only one span on the page"]);
    }

    #[test]
    fn median_font_size_handles_mixed_sizes() {
        let spans = vec![
            TextSpan {
                text: "small".into(),
                width: 10.0,
                height: 8.0,
                font_size: 8.0,
                ..TextSpan::default()
            },
            TextSpan {
                text: "medium".into(),
                width: 10.0,
                height: 12.0,
                font_size: 12.0,
                ..TextSpan::default()
            },
            TextSpan {
                text: "large".into(),
                width: 10.0,
                height: 24.0,
                font_size: 24.0,
                ..TextSpan::default()
            },
        ];
        assert!((median_font_size(&spans) - 12.0).abs() < 1e-9);
    }

    #[test]
    fn columns_band_aligned_accepts_aligned_columns() {
        let spans = vec![
            span("L1", 40.0, 700.0, 60.0),
            span("R1", 300.0, 700.0, 60.0),
            span("L2", 40.0, 684.0, 60.0),
            span("R2", 300.0, 684.0, 60.0),
        ];
        let stats = PageStats::from_spans(&spans);
        // cut_x between 100 and 300 → 200. Every band straddles the cut.
        assert!(columns_are_band_aligned(&spans, 200.0, 40.0, 360.0, &stats));
    }

    #[test]
    fn columns_band_aligned_rejects_wide_single_side_band() {
        let spans = vec![
            span("Wide banner line across top", 40.0, 740.0, 280.0),
            span("L1", 40.0, 700.0, 60.0),
            span("R1", 300.0, 700.0, 60.0),
        ];
        let stats = PageStats::from_spans(&spans);
        // cut_x = 200. Banner only in left group (midpoint < 200). Width
        // exceeds 0.7 × left column width → rejected.
        assert!(!columns_are_band_aligned(
            &spans, 200.0, 40.0, 360.0, &stats
        ));
    }

    #[test]
    fn page_stats_computes_median_values() {
        let spans = vec![
            span("one", 40.0, 700.0, 30.0),
            span("two", 40.0, 680.0, 30.0),
            span("three", 40.0, 660.0, 50.0),
        ];
        let stats = PageStats::from_spans(&spans);
        assert!((stats.median_font_size - 12.0).abs() < 1e-9);
        // char width = width / chars. one=30/3=10, two=30/3=10, three=50/5=10. median=10.
        assert!((stats.median_char_width - 10.0).abs() < 1e-9);
        // line spacing: bands at 700, 680, 660. gaps = 20, 20. median = 20.
        assert!((stats.median_line_spacing - 20.0).abs() < 1e-9);
    }

    #[test]
    fn page_stats_handles_empty_input() {
        let stats = PageStats::from_spans(&[]);
        assert!((stats.median_font_size - 12.0).abs() < 1e-9);
        assert!((stats.median_char_width - 6.0).abs() < 1e-9);
        assert_eq!(stats.median_line_spacing, 0.0);
    }

    #[test]
    fn narrow_gutter_detected_with_adaptive_threshold() {
        // Academic paper layout: 12pt gutter between columns.
        // With old fixed 20pt threshold, this was not detected as columnar.
        // With adaptive: median word gap ~4pt, threshold = 12pt → detects 12pt gutter.
        let mut spans = Vec::new();
        for y in [700.0, 684.0, 668.0] {
            // Left column: two words with 4pt gap, ending at x=145
            spans.push(span("Lorem ipsum", 40.0, y, 100.0));
            spans.push(span("dolor sit", 144.0, y, 80.0));
            // Right column starts at 236 (gap = 12pt from 224)
            spans.push(span("amet consec", 236.0, y, 100.0));
            spans.push(span("tetur adipi", 340.0, y, 80.0));
        }
        let texts = block_texts(spans);
        // Should detect 2-column layout and read column-major
        assert!(
            texts.len() >= 6,
            "expected column-major output, got {texts:?}"
        );
        // First three blocks should be left column lines
        assert!(
            texts[0].contains("Lorem"),
            "first block should be left column: {texts:?}"
        );
    }

    #[test]
    fn xy_cut_leaf_falls_back_to_legacy_columns_for_header_plus_three_columns() {
        let texts = block_texts(vec![
            span("73022", 45.0, 750.0, 70.0),
            span("Federal Register banner", 125.6, 750.0, 260.0),
            span("Left column line one", 45.0, 725.0, 140.0),
            span("Middle column line one", 222.0, 725.0, 140.0),
            span("Right column line one", 399.0, 725.0, 120.0),
            span("Left column line two", 45.0, 715.0, 140.0),
            span("Middle column line two", 210.0, 715.0, 152.0),
            span("Right column line two", 388.0, 715.0, 132.0),
            span("Left column line three", 45.0, 705.0, 140.0),
            span("Middle column line three", 235.0, 705.0, 135.0),
            span("Right column line three", 408.0, 705.0, 118.0),
        ]);

        assert_eq!(
            texts,
            vec![
                "73022 Federal Register banner",
                "Left column line one",
                "Left column line two",
                "Left column line three",
                "Middle column line one",
                "Middle column line two",
                "Middle column line three",
                "Right column line one",
                "Right column line two",
                "Right column line three",
            ]
        );
    }

    #[test]
    fn overlapping_fake_bold_spans_collapse_to_single_copy() {
        let texts = block_texts(vec![
            span("1 This is fakebold text.", 25.9, 785.3, 320.0),
            span("1 This is fakebold text.", 26.2, 785.3, 320.0),
            span("1 This is fakebold text.", 26.4, 785.3, 320.0),
            span("1 This is fakebold text.", 26.7, 785.3, 320.0),
            span("2 This is a fakebold", 27.0, 714.8, 142.0),
            span(" fakebold", 169.8, 714.8, 70.0),
            span(" fakebold", 170.1, 714.8, 70.0),
            span(" fakebold word.", 170.4, 714.8, 110.0),
        ]);

        assert_eq!(
            texts,
            vec!["1 This is fakebold text.", "2 This is a fakebold word.",]
        );
    }

    /// A span drawn at `degrees`, with the transform a text matrix at that
    /// angle composes and the origin the glyphs start from.
    fn turned_span(text: &str, degrees: f64, x: f64, y: f64, width: f64) -> TextSpan {
        let (sin, cos) = degrees.to_radians().sin_cos();
        let scale = 12.0 / 1000.0;
        TextSpan {
            transform: Some([cos * scale, sin * scale, -sin * scale, cos * scale, x, y]),
            ..span(text, x, y, width)
        }
    }

    /// Two lines of one rotated block share the place the page's order held
    /// them, and they must come back in the order they are read in. Each is
    /// inserted at the same index, and an insertion there pushes the last one
    /// down -- so inserting them front to back would emit the block backwards
    /// (#435, review round 2).
    #[test]
    fn two_lines_at_one_place_come_back_in_reading_order() {
        // A 90-degree run reads up the page, and its next line is a leading
        // further along +x: text space moves down, and down is +x once the
        // matrix has turned a quarter turn.
        let mut spans = vec![span("the page itself", 100.0, 700.0, 80.0)];
        for (index, text) in ["first", "second"].iter().enumerate() {
            let x = 60.0 + 14.0 * index as f64;
            spans.push(turned_span(text, 90.0, x, 200.0, 30.0));
        }
        let blocks = vec![TextBlock { spans }];

        let out = reassemble_cross_direction_runs(blocks);

        let lines: Vec<String> = out.iter().map(|block| block.text()).collect();
        assert_eq!(
            lines,
            vec!["first", "second", "the page itself"],
            "a rotated block came back with its lines the wrong way round"
        );
    }

    /// The page's direction is weighed in glyphs, and a span holds more
    /// characters than glyphs whenever a glyph decodes to several of them or
    /// the space consensus put a space between two -- neither of which was
    /// drawn. Counting characters lets a minority direction outvote the page's
    /// own (#435, review round 2).
    #[test]
    fn the_pages_direction_is_weighed_in_glyphs_and_not_characters() {
        // Eight characters drawn as two glyphs: a pair of ligatures.
        let mut upright = span("fifffifl", 72.0, 700.0, 24.0);
        upright.char_bounds = vec![[0.0; 4]; 2];
        // Five characters drawn as five glyphs.
        let mut turned = turned_span("TURNS", 90.0, 300.0, 300.0, 30.0);
        turned.char_bounds = vec![[0.0; 4]; 5];

        let direction = page_direction(&[TextBlock {
            spans: vec![upright, turned],
        }])
        .expect("a direction");

        assert!(
            (direction.1).abs() > 0.5,
            "two ligature glyphs outvoted five drawn ones, so the count is of characters"
        );
    }

    /// A run drawn at an angle stops where its last glyph stops, and that is
    /// further along its baseline than its page-space width says: a 30-degree
    /// run advances `cos 30` of its length in x. Measuring the gap to the next
    /// span from `x + width` leaves an eighth of the run as phantom gap, which
    /// at a style boundary in the middle of a word puts a space there (#435,
    /// review round 1).
    #[test]
    fn a_turned_run_ends_where_its_last_glyph_ends() {
        const DEGREES: f64 = 30.0;
        const ADVANCE: f64 = 7.2; // Courier at 12 pt
        let (sin, cos) = DEGREES.to_radians().sin_cos();

        // "HELLO", five glyphs from (100, 400) along the 30-degree baseline,
        // as `draw_glyph` accumulates them: page-space bounds per glyph, and a
        // width that is the widest reach in page x.
        let mut hello = turned_span("HELLO", DEGREES, 100.0, 400.0, 0.0);
        for index in 0..5 {
            let x = 100.0 + cos * ADVANCE * index as f64;
            let y = 400.0 + sin * ADVANCE * index as f64;
            hello.char_bounds.push([x, y, x + ADVANCE, y + 12.0]);
            hello.width = hello.width.max(x + ADVANCE - 100.0);
        }
        // "WORLD" begins exactly where the fifth glyph's advance ended.
        let world = turned_span(
            "WORLD",
            DEGREES,
            100.0 + cos * ADVANCE * 5.0,
            400.0 + sin * ADVANCE * 5.0,
            ADVANCE * 5.0,
        );

        let block = TextBlock {
            spans: vec![hello, world],
        };
        assert_eq!(
            block.text(),
            "HELLOWORLD",
            "a space was invented at a seam the document draws closed"
        );
    }

    /// A page written entirely at an angle is a page of upright text seen
    /// turned, and its own bands read it correctly. Nothing is taken out of
    /// them: the direction most of the glyphs are drawn in IS the page's,
    /// whatever that direction is (#435).
    #[test]
    fn a_page_written_entirely_at_an_angle_keeps_its_own_bands() {
        let blocks = vec![
            TextBlock {
                spans: vec![
                    turned_span("first line", 90.0, 100.0, 100.0, 60.0),
                    turned_span("carried on", 90.0, 100.0, 160.0, 60.0),
                ],
            },
            TextBlock {
                spans: vec![turned_span("second line", 90.0, 120.0, 100.0, 66.0)],
            },
        ];

        let out = reassemble_cross_direction_runs(blocks.clone());

        let shape: Vec<Vec<&str>> = out
            .iter()
            .map(|b| b.spans.iter().map(|s| s.text.as_str()).collect())
            .collect();
        assert_eq!(
            shape,
            vec![vec!["first line", "carried on"], vec!["second line"]],
            "a page in one direction was rearranged by a rule that is about two"
        );
    }

    /// The page's direction is the one most of its GLYPHS are drawn in, and a
    /// tie goes to the direction that was drawn first -- a rule the answer to
    /// which must not depend on which way an iterator happens to walk (#435).
    #[test]
    fn the_pages_direction_is_the_heaviest_and_a_tie_goes_to_the_first() {
        let upright = TextBlock {
            spans: vec![span("eight ch", 0.0, 700.0, 48.0)],
        };
        let turned = TextBlock {
            spans: vec![turned_span("ninety deg", 90.0, 300.0, 300.0, 60.0)],
        };

        let heavier = page_direction(&[upright.clone(), turned.clone()]).expect("a direction");
        assert!(
            (heavier.1).abs() > 0.5,
            "ten glyphs at ninety degrees outweigh eight upright ones, and did not"
        );

        let tie = TextBlock {
            spans: vec![span("ninety deg", 0.0, 700.0, 60.0)],
        };
        let first = page_direction(&[tie, turned]).expect("a direction");
        assert!(
            (first.1).abs() < 0.5,
            "a tie went to the direction that was not drawn first"
        );
    }

    /// A page whose every line runs up it is read in the frame it was written
    /// in. Its bands lie across its lines, so without the turn the two lines
    /// share one band and come back as one (#546).
    #[test]
    fn a_turned_page_is_read_in_the_frame_it_was_written_in() {
        // A quarter-turned page reads up the page, and its next line is a
        // leading further along +x: text space moves down, and down is +x once
        // the matrix has turned a quarter turn.
        let spans: Vec<TextSpan> = ["the first line", "the second line"]
            .iter()
            .enumerate()
            .map(|(index, text)| turned_span(text, 90.0, 100.0 + 16.0 * index as f64, 100.0, 80.0))
            .collect();

        let lines = block_texts(spans);

        assert_eq!(
            lines,
            vec!["the first line", "the second line"],
            "the lines of a turned page were read in the bands of the frame it is drawn in"
        );
    }

    /// The turn into the page's own frame and the turn back move no coordinate
    /// by a single bit: a quarter turn's sine and cosine are 0 and ±1, so what
    /// a caller reads off a span of a turned page is the page's own number and
    /// not a rounding of it (#546).
    #[test]
    fn the_turn_into_the_frame_and_back_leaves_every_number_as_it_was() {
        // Courier at 12 pt, and a run of six glyphs up the page.
        const ADVANCE: f64 = 7.2;
        const X: f64 = 123.75;
        const Y: f64 = 456.5;
        // The width is what `draw_glyph` accumulates: the furthest a glyph
        // reaches in page x, which for a quarter turn is one advance however
        // long the run is. Written as that subtraction and not as the advance,
        // because `x + advance - x` is not `advance` in binary and the number
        // the caller gets back is the number the device measured.
        let mut original = turned_span("TURNED", 90.0, X, Y, (X + ADVANCE) - X);
        for index in 0..6 {
            let y = Y + ADVANCE * index as f64;
            original.char_bounds.push([X, y, X + ADVANCE, y + 12.0]);
        }

        for turn in [PageTurn::Quarter, PageTurn::Half, PageTurn::ThreeQuarter] {
            let spans = turn.into_frame(vec![original.clone()]);
            let blocks = turn.back(vec![TextBlock { spans }]);
            let span = &blocks[0].spans[0];

            assert_eq!(
                (span.x, span.y),
                (original.x, original.y),
                "{turn:?} moved the span's origin"
            );
            assert_eq!(
                span.transform, original.transform,
                "{turn:?} left the baseline turned"
            );
            assert_eq!(
                span.char_bounds, original.char_bounds,
                "{turn:?} moved a glyph bound"
            );
            assert_eq!(
                span.width, original.width,
                "{turn:?} left a frame width behind"
            );
        }
    }

    /// Only a page written in a quarter turn is turned: an upright one, a page
    /// drawn entirely at a free angle, and a page whose turned text is the
    /// minority all keep the bands they have (#546).
    #[test]
    fn a_page_is_turned_by_a_quarter_turn_or_by_nothing() {
        let cases = [
            (0.0, PageTurn::None),
            (90.0, PageTurn::Quarter),
            (180.0, PageTurn::Half),
            (270.0, PageTurn::ThreeQuarter),
            (45.0, PageTurn::None),
            (-52.0, PageTurn::None),
        ];
        for (degrees, expected) in cases {
            let spans = vec![turned_span("a line of it", degrees, 100.0, 100.0, 72.0)];
            assert_eq!(
                PageTurn::of(&spans),
                expected,
                "a page written at {degrees} degrees"
            );
        }

        // The watermark of #435: turned, and outnumbered by the page it is on.
        let page = vec![
            span(
                "the body of the page is written upright",
                72.0,
                700.0,
                230.0,
            ),
            turned_span("SANDBOX", 90.0, 300.0, 200.0, 42.0),
        ];
        assert_eq!(
            PageTurn::of(&page),
            PageTurn::None,
            "a turned watermark turned the page it is drawn on"
        );
    }

    /// A half-turned page keeps the ruling lines the page drew, because a half
    /// turn maps a horizontal line to a horizontal line; a quarter-turned page
    /// keeps none, because what the device recorded there runs the other way
    /// across the page (#546, review round 2).
    #[test]
    fn only_a_half_turn_keeps_the_pages_ruling_lines() {
        let rule = HorizontalRule {
            left: 72.0,
            right: 540.0,
            y: 400.0,
        };

        let drawn = [rule];
        let upright = PageTurn::None.rules_in_frame(&drawn);
        assert_eq!(
            (
                upright.len(),
                upright[0].left,
                upright[0].right,
                upright[0].y
            ),
            (1, rule.left, rule.right, rule.y),
            "an upright page's rules were touched at all"
        );

        let turned = PageTurn::Half.rules_in_frame(&drawn);
        let rotation = PageTurn::Half.rotation();
        let (left, y) = turn_point(rule.right, rule.y, rotation);
        let (right, _) = turn_point(rule.left, rule.y, rotation);
        assert_eq!(
            (turned.len(), turned[0].left, turned[0].right, turned[0].y),
            (1, left, right, y),
            "a half turn lost the page's rules, or left them where they were drawn"
        );
        assert!(
            turned[0].left < turned[0].right,
            "the ends of a mirrored rule did not swap, so it reads as empty"
        );

        for turn in [PageTurn::Quarter, PageTurn::ThreeQuarter] {
            assert!(
                turn.rules_in_frame(&drawn).is_empty(),
                "{turn:?} kept a rule that runs across its reading direction"
            );
        }
    }

    /// A page has to be WRITTEN in a direction before it is read in it: with
    /// its glyphs split four ways, as pdfbox `AcroFormsRotation` splits them
    /// over four blocks of form fields at the four rotations, the heaviest
    /// direction is a quarter of the page, and turning by it moves every block
    /// on a page that was never turned at all (#546).
    #[test]
    fn a_page_with_no_majority_direction_is_not_turned() {
        let quarter_each = vec![
            span("rotation zero", 72.0, 700.0, 78.0),
            turned_span("rotation ninety", 90.0, 200.0, 200.0, 90.0),
            turned_span("rotation oneeighty", 180.0, 400.0, 400.0, 108.0),
            turned_span("rotation twoseventy", 270.0, 500.0, 600.0, 114.0),
        ];
        assert_eq!(
            PageTurn::of(&quarter_each),
            PageTurn::None,
            "a plurality of a quarter of the glyphs turned the whole page"
        );

        // The same page with the turned block carrying most of the glyphs is
        // a page written in that direction, and is read in it.
        let mut majority = quarter_each;
        majority[1] = turned_span(
            "a line of ninety degree text that is most of this page by a street",
            90.0,
            200.0,
            200.0,
            400.0,
        );
        assert_eq!(
            PageTurn::of(&majority),
            PageTurn::Quarter,
            "a direction carrying most of the page did not turn it"
        );
    }

    /// A span drawn by a horizontal reflection, `[-1, 0, 0, 1, e, f]`. Its
    /// baseline runs in `(-1, 0)`, which is where a half turn puts one too --
    /// and its vertical axis is upright, which is where a half turn does not.
    fn mirrored_span(text: &str, x: f64, y: f64, width: f64) -> TextSpan {
        let scale = 12.0 / 1000.0;
        TextSpan {
            transform: Some([-scale, 0.0, 0.0, scale, x, y]),
            ..span(text, x, y, width)
        }
    }

    /// A page drawn mirrored is not a page drawn upside down, and the baseline
    /// vector cannot tell them apart: both run in `(-1, 0)`. Turning it half a
    /// turn negates the vertical axis as well, so a block whose lines descend
    /// the page is read bottom to top -- an order invented from a page that was
    /// never turned. The determinant separates the two. (codex, review round 2)
    #[test]
    fn a_mirrored_page_is_not_a_half_turned_page() {
        let mirrored = vec![
            mirrored_span("the first line of a mirrored page", 400.0, 700.0, 300.0),
            mirrored_span("and the second line below it", 400.0, 686.0, 260.0),
        ];
        assert_eq!(
            PageTurn::of(&mirrored),
            PageTurn::None,
            "a reflection was read as a half turn, and turning it reverses the page"
        );

        // The control, so the assertion above cannot pass by refusing every
        // page: the same two lines actually drawn upside down ARE a half turn.
        let half_turned: Vec<TextSpan> = vec![
            turned_span(
                "the first line of a turned page",
                180.0,
                400.0,
                700.0,
                300.0,
            ),
            turned_span("and the second line below it", 180.0, 400.0, 686.0, 260.0),
        ];
        assert_eq!(
            PageTurn::of(&half_turned),
            PageTurn::Half,
            "a page genuinely drawn at 180 degrees is no longer turned into its frame"
        );

        // And a page that is mostly mirrored with an upright minority stays
        // untouched rather than being read in the minority's direction: the
        // share is of the whole page, not of the rotations on it.
        let mut mostly_mirrored = mirrored;
        mostly_mirrored.push(span("a short upright caption", 72.0, 100.0, 40.0));
        assert_eq!(
            PageTurn::of(&mostly_mirrored),
            PageTurn::None,
            "an upright minority carried the vote on a mirrored page"
        );
    }

    /// The seam allowance of `second_run_carries_on_from_the_first` is one
    /// GLYPH of mean advance, and a glyph may decode to more than one
    /// character. Six characters drawn as five glyphs -- `office` with a `fi`
    /// ligature -- have a 6 pt allowance, where dividing the same advance by
    /// the six characters would leave 5 pt and reject a 5.5 pt seam that a
    /// re-drawn word arrives with (#432, review round 2).
    #[test]
    fn the_seam_allowance_counts_glyphs_and_not_characters() {
        let prev = span("first", 0.0, 700.0, 30.0);
        let mut curr = span("office", 24.5, 700.0, 30.0);
        curr.char_bounds = vec![[0.0; 4]; 5];

        assert!(
            second_run_carries_on_from_the_first(&prev, &curr),
            "a ligature shrank the seam allowance to the character count"
        );

        curr.char_bounds.clear();
        assert!(
            !second_run_carries_on_from_the_first(&prev, &curr),
            "the character count is the fallback, so it has to be the stricter one here"
        );
    }

    // ---- G1: read-only metadata field tests ----

    #[test]
    fn g1_default_text_span_has_empty_metadata() {
        let s = TextSpan::default();
        assert_eq!(s.font_name, None);
        assert!(!s.is_bold);
        assert!(!s.is_italic);
        assert_eq!(s.color, None);
    }

    #[test]
    fn g1_strip_subset_prefix_handles_six_char_prefix() {
        assert_eq!(strip_subset_prefix("AAAAAA+Helvetica"), "Helvetica");
        // Non-6-char prefix → keep verbatim.
        assert_eq!(strip_subset_prefix("ABC+Helvetica"), "ABC+Helvetica");
        // No `+` → unchanged.
        assert_eq!(strip_subset_prefix("Helvetica-Bold"), "Helvetica-Bold");
    }

    #[test]
    fn g1_name_style_hints_match_pdf_interpret_rules() {
        assert_eq!(name_style_hints("Helvetica-Bold"), (true, false));
        assert_eq!(name_style_hints("Times-Italic"), (false, true));
        assert_eq!(name_style_hints("MyFont-BoldOblique"), (true, true));
        assert_eq!(name_style_hints("Helvetica"), (false, false));
        // Semibold / Demi / Heavy / Black variants → bold.
        assert_eq!(name_style_hints("Roboto-DemiBold"), (true, false));
        assert_eq!(name_style_hints("Roboto-Black"), (true, false));
        // Oblique / slant variants → italic.
        assert_eq!(name_style_hints("Roboto-Oblique"), (false, true));
        assert_eq!(name_style_hints("MyFont-Slanted"), (false, true));
    }

    // ---- G2: widthSource + char_bounds on TextSpan ----

    #[test]
    fn g2_default_text_span_has_estimate_width_source() {
        let s = TextSpan::default();
        assert_eq!(s.width_source, WidthSource::Estimate);
        assert!(s.char_bounds.is_empty());
    }

    /// Verify that a single-glyph span has exactly one char_bound entry
    /// and that the bound matches the span's x / width.
    #[test]
    fn g2_single_glyph_span_has_one_char_bound() {
        let s = TextSpan {
            text: "A".into(),
            x: 10.0,
            y: 100.0,
            width: 7.22,
            height: 10.0,
            font_size: 10.0,
            width_source: WidthSource::Metric,
            char_bounds: vec![[10.0, 100.0, 17.22, 110.0]],
            ..Default::default()
        };

        assert_eq!(s.char_bounds.len(), 1);
        let [x0, y0, x1, y1] = s.char_bounds[0];
        assert!((x0 - 10.0).abs() < 0.001);
        assert!((x1 - 17.22).abs() < 0.001);
        assert!((y1 - y0 - s.font_size).abs() < 0.001);
    }

    /// When merging glyphs into a span the width_source degrades to Estimate
    /// if any glyph was estimated.
    #[test]
    fn g2_merged_span_degrades_width_source_on_estimate() {
        let mut s = TextSpan {
            width_source: WidthSource::Metric,
            char_bounds: vec![[0.0, 0.0, 7.0, 10.0]],
            ..Default::default()
        };

        // Simulate what draw_glyph does on merge: push bound + downgrade.
        s.char_bounds.push([7.0, 0.0, 12.0, 10.0]);
        s.width_source = WidthSource::Estimate; // second glyph had no advance

        assert_eq!(s.width_source, WidthSource::Estimate);
        assert_eq!(s.char_bounds.len(), 2);
    }

    /// Verify WidthSource enum serialises to the two expected string literals.
    #[test]
    fn g2_width_source_variants_are_correct() {
        assert_eq!(format!("{:?}", WidthSource::Metric), "Metric");
        assert_eq!(format!("{:?}", WidthSource::Estimate), "Estimate");
        assert_ne!(WidthSource::Metric, WidthSource::Estimate);
        assert_eq!(WidthSource::default(), WidthSource::Estimate);
    }

    // ---- M3: RichGeometry / tight glyph bounds tests ----

    #[test]
    fn m3_default_text_span_has_basic_mode() {
        let s = TextSpan::default();
        assert_eq!(s.geometry_mode, GeometryMode::Basic);
        assert_eq!(s.bounds_source, BoundsSource::Advance);
        assert!(s.tight_char_bounds.is_empty());
        assert!(s.glyph_advances.is_empty());
    }

    #[test]
    fn m3_geometry_mode_default_is_basic() {
        assert_eq!(GeometryMode::default(), GeometryMode::Basic);
    }

    #[test]
    fn m3_bounds_source_default_is_advance() {
        assert_eq!(BoundsSource::default(), BoundsSource::Advance);
    }

    #[test]
    fn m3_geometry_mode_variants_are_distinct() {
        assert_ne!(GeometryMode::Basic, GeometryMode::RichGeometry);
        assert_eq!(format!("{:?}", GeometryMode::Basic), "Basic");
        assert_eq!(format!("{:?}", GeometryMode::RichGeometry), "RichGeometry");
    }

    #[test]
    fn m3_bounds_source_variants_are_distinct() {
        assert_ne!(BoundsSource::Advance, BoundsSource::Tight);
        assert_ne!(BoundsSource::Tight, BoundsSource::Estimate);
        assert_eq!(format!("{:?}", BoundsSource::Advance), "Advance");
        assert_eq!(format!("{:?}", BoundsSource::Tight), "Tight");
        assert_eq!(format!("{:?}", BoundsSource::Estimate), "Estimate");
    }

    #[test]
    fn m3_text_span_rich_geometry_preserves_existing_fields() {
        let s = TextSpan {
            text: "Hello".into(),
            x: 10.0,
            y: 100.0,
            width: 30.0,
            height: 12.0,
            font_size: 12.0,
            font_name: Some("Helvetica".into()),
            is_bold: true,
            is_italic: false,
            color: Some([0, 0, 0, 255]),
            width_source: WidthSource::Metric,
            char_bounds: vec![[10.0, 100.0, 40.0, 112.0]],
            geometry_mode: GeometryMode::RichGeometry,
            bounds_source: BoundsSource::Tight,
            tight_char_bounds: vec![[8.5, 98.5, 41.5, 114.0]],
            glyph_advances: vec![30.0],
            glyph_bounds_sources: vec![BoundsSource::Tight],
            ..Default::default()
        };

        // Existing fields preserved.
        assert_eq!(s.text, "Hello");
        assert!((s.x - 10.0).abs() < 0.001);
        assert!((s.y - 100.0).abs() < 0.001);
        assert_eq!(s.width_source, WidthSource::Metric);
        assert_eq!(s.char_bounds.len(), 1);

        // M3 fields populated.
        assert_eq!(s.geometry_mode, GeometryMode::RichGeometry);
        assert_eq!(s.bounds_source, BoundsSource::Tight);
        assert_eq!(s.tight_char_bounds.len(), 1);
        assert_eq!(s.glyph_advances.len(), 1);
        assert!((s.glyph_advances[0] - 30.0).abs() < 0.001);
    }

    #[test]
    fn m3_text_span_basic_mode_does_not_populate_tight_fields() {
        let s = TextSpan {
            text: "A".into(),
            x: 0.0,
            y: 0.0,
            width: 7.0,
            height: 10.0,
            font_size: 10.0,
            geometry_mode: GeometryMode::Basic,
            bounds_source: BoundsSource::Advance,
            ..Default::default()
        };

        assert!(s.tight_char_bounds.is_empty());
        assert!(s.glyph_advances.is_empty());
    }

    #[test]
    fn m3_tight_char_bounds_are_optional_in_basic_mode() {
        // A span from Basic mode should have empty tight fields.
        let s = TextSpan {
            text: "test".into(),
            x: 0.0,
            y: 0.0,
            width: 40.0,
            height: 12.0,
            font_size: 12.0,
            geometry_mode: GeometryMode::Basic,
            ..Default::default()
        };
        assert!(s.tight_char_bounds.is_empty());
        assert!(s.glyph_advances.is_empty());
    }

    #[test]
    fn m3_test_span_constructor_preserves_all_fields() {
        // Verify the span constructor used in existing tests still works.
        let s = span("hello", 10.0, 100.0, 30.0);
        assert_eq!(s.geometry_mode, GeometryMode::Basic);
        assert_eq!(s.bounds_source, BoundsSource::Advance);
        assert!(s.tight_char_bounds.is_empty());
    }

    #[test]
    fn m3_width_source_unchanged_by_m3() {
        // WidthSource should not be affected by RichGeometry.
        assert_eq!(WidthSource::Metric, WidthSource::Metric);
        assert_eq!(WidthSource::Estimate, WidthSource::Estimate);
        assert_eq!(WidthSource::default(), WidthSource::Estimate);
    }

    #[test]
    fn m3_transform_bbox_corners_identity() {
        let bbox = [0.0, 0.0, 10.0, 12.0];
        let identity = kurbo::Affine::IDENTITY;
        let result = transform_bbox_corners(&bbox, &identity);
        assert!((result[0] - 0.0).abs() < 0.001);
        assert!((result[1] - 0.0).abs() < 0.001);
        assert!((result[2] - 10.0).abs() < 0.001);
        assert!((result[3] - 12.0).abs() < 0.001);
    }

    #[test]
    fn m3_transform_bbox_corners_translation() {
        let bbox = [0.0, 0.0, 10.0, 12.0];
        let t = kurbo::Affine::translate((50.0, 100.0));
        let result = transform_bbox_corners(&bbox, &t);
        assert!((result[0] - 50.0).abs() < 0.001);
        assert!((result[1] - 100.0).abs() < 0.001);
        assert!((result[2] - 60.0).abs() < 0.001);
        assert!((result[3] - 112.0).abs() < 0.001);
    }

    #[test]
    fn m3_transform_bbox_corners_scale() {
        let bbox = [0.0, 0.0, 10.0, 12.0];
        let s = kurbo::Affine::scale(2.0);
        let result = transform_bbox_corners(&bbox, &s);
        assert!((result[0] - 0.0).abs() < 0.001);
        assert!((result[1] - 0.0).abs() < 0.001);
        assert!((result[2] - 20.0).abs() < 0.001);
        assert!((result[3] - 24.0).abs() < 0.001);
    }

    #[test]
    fn m3_transform_bbox_corners_with_negative_bbox() {
        // Glyphs with descenders have negative y0 in font space.
        let bbox = [-5.0, -200.0, 15.0, 800.0];
        let s = kurbo::Affine::scale(0.012); // 12pt font at 1000-upem
        let result = transform_bbox_corners(&bbox, &s);
        assert!((result[0] - (-0.06)).abs() < 0.01);
        assert!((result[1] - (-2.4)).abs() < 0.01);
        assert!((result[2] - 0.18).abs() < 0.01);
        assert!((result[3] - 9.6).abs() < 0.01);
    }

    #[test]
    fn m3_tight_char_bounds_descender_detection() {
        // A glyph with a descender should have tight_char_bounds.y0 < origin.y0.
        let s = TextSpan {
            text: "g".into(),
            x: 100.0,
            y: 200.0, // baseline
            width: 8.0,
            height: 12.0,
            font_size: 12.0,
            geometry_mode: GeometryMode::RichGeometry,
            bounds_source: BoundsSource::Tight,
            tight_char_bounds: vec![[99.0, 197.5, 109.0, 210.0]],
            char_bounds: vec![[100.0, 200.0, 108.0, 212.0]],
            glyph_advances: vec![8.0],
            ..Default::default()
        };

        // Tight y0 (197.5) < span y (200.0) — descender extends below baseline.
        assert!(
            s.tight_char_bounds[0][1] < s.y,
            "descender should extend below baseline"
        );
    }

    #[test]
    fn m3_tight_char_bounds_ascender_detection() {
        // A glyph with an ascender should have tight_char_bounds.y1 > advance y1.
        let s = TextSpan {
            text: "f".into(),
            x: 100.0,
            y: 200.0,
            width: 7.0,
            height: 12.0,
            font_size: 12.0,
            geometry_mode: GeometryMode::RichGeometry,
            bounds_source: BoundsSource::Tight,
            tight_char_bounds: vec![[95.0, 200.0, 108.0, 214.0]],
            char_bounds: vec![[100.0, 200.0, 107.0, 212.0]],
            glyph_advances: vec![7.0],
            ..Default::default()
        };

        // Tight y1 (214.0) > advance y1 (200.0 + 12.0 = 212.0).
        let advance_y1 = s.y + s.height;
        assert!(
            s.tight_char_bounds[0][3] > advance_y1,
            "ascender should extend above advance bounds"
        );
    }

    #[test]
    fn m3_tight_char_bounds_differ_from_advance() {
        // Verify tight bounds produce a different bbox than advance bounds.
        let s = TextSpan {
            text: "A".into(),
            x: 10.0,
            y: 100.0,
            width: 7.22,
            height: 10.0,
            font_size: 10.0,
            geometry_mode: GeometryMode::RichGeometry,
            bounds_source: BoundsSource::Tight,
            char_bounds: vec![[10.0, 100.0, 17.22, 110.0]], // advance
            tight_char_bounds: vec![[9.5, 100.2, 17.5, 109.5]], // tight (different)
            glyph_advances: vec![7.22],
            ..Default::default()
        };

        let ac = s.char_bounds[0];
        let tc = s.tight_char_bounds[0];
        let differs = (ac[0] - tc[0]).abs() > 0.01
            || (ac[1] - tc[1]).abs() > 0.01
            || (ac[2] - tc[2]).abs() > 0.01
            || (ac[3] - tc[3]).abs() > 0.01;
        assert!(differs, "tight bounds should differ from advance bounds");
    }

    #[test]
    fn m3_device_new_uses_basic_mode() {
        let dev = TextExtractionDevice::new();
        assert_eq!(dev.geometry_mode, GeometryMode::Basic);
        assert!(dev.deferred_rich_glyphs.is_empty());
    }

    #[test]
    fn m3_device_with_mode_rich_geometry() {
        let dev = TextExtractionDevice::with_mode(GeometryMode::RichGeometry);
        assert_eq!(dev.geometry_mode, GeometryMode::RichGeometry);
        assert!(dev.deferred_rich_glyphs.is_empty());
    }

    /// A synthetic rectangular glyph outline in raw design space, plus its
    /// bbox. The renderer (`renderer.rs::fill_glyph`) fills this raw outline
    /// with `composed = transform * glyph_transform` and NO upem pre-scaling,
    /// so the page-space bbox of a tight glyph MUST equal
    /// `(composed * outline).bounding_box()`. These tests use that as the
    /// ground-truth oracle, which is what guards against scaling regressions.
    #[cfg(test)]
    fn synthetic_glyph_rect() -> (BezPath, kurbo::Rect) {
        let mut path = BezPath::new();
        path.move_to((100.0, 0.0));
        path.line_to((600.0, 0.0));
        path.line_to((600.0, 700.0));
        path.line_to((100.0, 700.0));
        path.close_path();
        let bbox = path.bounding_box();
        (path, bbox)
    }

    #[test]
    fn m3_basic_mode_skips_tight_bounds_computation() {
        // Basic mode must NOT compute tight bounds, even when a span is present.
        let mut dev = TextExtractionDevice::new();
        dev.spans.push(TextSpan {
            text: "A".into(),
            char_bounds: vec![[0.0, 0.0, 7.0, 10.0]],
            ..Default::default()
        });
        let spans = dev.into_spans();
        assert_eq!(spans.len(), 1);
        assert!(spans[0].tight_char_bounds.is_empty());
        assert!(spans[0].glyph_bounds_sources.is_empty());
        assert_eq!(spans[0].bounds_source, BoundsSource::Advance);
    }

    #[test]
    fn m3_rich_geometry_tight_bounds_match_rendered_outline() {
        // Axis-aligned scale 0.01: the page-space tight bbox must equal the
        // bbox of the transformed outline — i.e. design [100,600]x[0,700]
        // scaled by 0.01 → [1.0, 0.0, 6.0, 7.0]. A double-scale regression
        // (e.g. an extra font_size/1000) would yield ~[0.01, 0, 0.06, 0.07].
        let (path, bbox) = synthetic_glyph_rect();
        let composed = Affine::scale(0.01);
        let oracle = (composed * path.clone()).bounding_box();

        let mut dev = TextExtractionDevice::with_mode(GeometryMode::RichGeometry);
        dev.spans.push(TextSpan {
            text: "A".into(),
            char_bounds: vec![[0.0, 0.0, 7.0, 10.0]],
            geometry_mode: GeometryMode::RichGeometry,
            ..Default::default()
        });
        dev.deferred_rich_glyphs.push(DeferredGlyph {
            coeffs: composed.as_coeffs(),
            font_size: 10.0,
            glyph_width: 7.0,
            needs_exact: false,
            outline: Some(path),
            font_bbox: Some(bbox),
        });

        let spans = dev.into_spans();
        assert_eq!(spans[0].glyph_bounds_sources, vec![BoundsSource::Tight]);
        assert_eq!(spans[0].bounds_source, BoundsSource::Tight);
        let tb = spans[0].tight_char_bounds[0];
        assert!(
            (tb[0] - oracle.x0).abs() < 1e-6,
            "x0: got {} want {}",
            tb[0],
            oracle.x0
        );
        assert!(
            (tb[1] - oracle.y0).abs() < 1e-6,
            "y0: got {} want {}",
            tb[1],
            oracle.y0
        );
        assert!(
            (tb[2] - oracle.x1).abs() < 1e-6,
            "x1: got {} want {}",
            tb[2],
            oracle.x1
        );
        assert!(
            (tb[3] - oracle.y1).abs() < 1e-6,
            "y1: got {} want {}",
            tb[3],
            oracle.y1
        );
        // Sanity: tight height (~7) is commensurate with the advance font_size
        // (10), not ~100x smaller — the regression this test exists to catch.
        assert!(
            tb[3] - tb[1] > 1.0,
            "tight height must be commensurate with font size"
        );
    }

    #[test]
    fn m3_rich_geometry_tight_bounds_rotation_is_exact() {
        // 90° rotation routes through the needs_exact (transform-then-bound)
        // path. Oracle = bbox of the rotated outline.
        let (path, bbox) = synthetic_glyph_rect();
        let composed = Affine::scale(0.01) * Affine::rotate(std::f64::consts::FRAC_PI_2);
        let oracle = (composed * path.clone()).bounding_box();

        let mut dev = TextExtractionDevice::with_mode(GeometryMode::RichGeometry);
        dev.spans.push(TextSpan {
            text: "A".into(),
            char_bounds: vec![[0.0, 0.0, 7.0, 10.0]],
            geometry_mode: GeometryMode::RichGeometry,
            ..Default::default()
        });
        dev.deferred_rich_glyphs.push(DeferredGlyph {
            coeffs: composed.as_coeffs(),
            font_size: 10.0,
            glyph_width: 7.0,
            needs_exact: true,
            outline: Some(path),
            font_bbox: Some(bbox),
        });

        let spans = dev.into_spans();
        assert_eq!(spans[0].glyph_bounds_sources, vec![BoundsSource::Tight]);
        let tb = spans[0].tight_char_bounds[0];
        assert!(
            (tb[0] - oracle.x0).abs() < 1e-6,
            "x0: got {} want {}",
            tb[0],
            oracle.x0
        );
        assert!(
            (tb[1] - oracle.y0).abs() < 1e-6,
            "y0: got {} want {}",
            tb[1],
            oracle.y0
        );
        assert!(
            (tb[2] - oracle.x1).abs() < 1e-6,
            "x1: got {} want {}",
            tb[2],
            oracle.x1
        );
        assert!(
            (tb[3] - oracle.y1).abs() < 1e-6,
            "y1: got {} want {}",
            tb[3],
            oracle.y1
        );
    }

    #[test]
    fn m3_empty_device_rich_geometry_no_panic() {
        let dev = TextExtractionDevice::with_mode(GeometryMode::RichGeometry);
        let text = dev.into_text();
        assert!(text.is_empty());
    }

    #[test]
    fn m3_bounds_source_estimate_fallback() {
        // Verify that BoundsSource::Estimate can be set on a span.
        let s = TextSpan {
            geometry_mode: GeometryMode::RichGeometry,
            bounds_source: BoundsSource::Estimate,
            ..Default::default()
        };
        assert_eq!(s.bounds_source, BoundsSource::Estimate);
        assert_eq!(s.geometry_mode, GeometryMode::RichGeometry);
        // Fallback still has empty tight fields (no glyphs).
        assert!(s.tight_char_bounds.is_empty());
    }

    #[test]
    fn m3_multiple_glyphs_tight_bounds_consistent_count() {
        // Simulate a span with 3 glyphs — tight_char_bounds and glyph_advances
        // should have the same length.
        let s = TextSpan {
            text: "abc".into(),
            x: 0.0,
            y: 0.0,
            width: 25.0,
            height: 12.0,
            font_size: 12.0,
            geometry_mode: GeometryMode::RichGeometry,
            bounds_source: BoundsSource::Tight,
            char_bounds: vec![[0., 0., 8., 12.], [8., 0., 16., 12.], [16., 0., 25., 12.]],
            tight_char_bounds: vec![
                [-1., -2., 9., 14.],
                [7., -2., 17., 14.],
                [15., -2., 26., 14.],
            ],
            glyph_advances: vec![8.0, 8.0, 9.0],
            ..Default::default()
        };

        assert_eq!(s.tight_char_bounds.len(), 3);
        assert_eq!(s.glyph_advances.len(), 3);
        assert_eq!(s.char_bounds.len(), 3);
        // Every glyph has advance >= 0.
        for &adv in &s.glyph_advances {
            assert!(adv >= 0.0, "glyph advance must be non-negative");
        }
    }
}