pdf: read interleaved font runs in visual order ("C.6." kept whole) (#157)

PDF generators that paint a line's bold runs *after* the surrounding regular
text (the XXXLutz terms document does this for every bold token) hand the
sanitizer cells in stream order, not reading order. docling's cluster join
follows the docling-parse cell index — that same stream order — so the bold
label number drifted to the line's end: "C.6. Zur Wahrung der Widerrufsfrist
…" read "C. Zur Wahrung … Mitteilung 6.", "binnen 14 Tagen ohne Angabe"
read "binnen ohne 2. 14 Tagen Angabe", and searching the output for "C.6"
found nothing.

Two changes, both in the shared text path (native + browser, flat + ML):

- region_text: restore reading order geometrically before joining — group a
  region's cells into lines by vertical *overlap* (not a quantized band:
  2206's inline `>` sits ~2 pt above its line's band, and a plain band-sort
  drifted it into the next line, which is why the join trusted index order
  until now), sort lines top to bottom and cells left to right (right to
  left for Arabic-majority regions), stably — index order still breaks ties.
- dp_lines contraction: never merge two cells across a horizontal gap that
  another active cell occupies — an occupied gap is not a gap, and bridging
  it with a space would stitch the line wrong before any ordering could
  help. Space-only cells never block; glyph-adjacent merges skip the scan.

The full corpus battery is the arbiter that this deviation from raw index
order is safe: docling-core, docling (regression suite included),
docling-asr, docling-serve and docling-pdf suites all green, plus a unit
test locking the interleaved-runs order and the off-baseline `>` grouping.
fmt/clippy clean; the no-default-features and wasm targets compile.

Refs #157

Signed-off-by: artiz <artem.kustikov@gmail.com>
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EY5KAiquN4YpVf2PXEQkVT

Author: artiz

crates/docling-pdf/src/assemble.rs

@@ -729,10 +729,43 @@ fn region_text(region: &Region, cells: &[TextCell]) -> String {
     if dp {
         // docling orders a cluster's cells by their docling-parse cell index
         // (`LayoutPostprocessor._sort_cells`: `sorted(cells, key=c.index)`) —
-        // the sanitizer's output order, which our `cells` slice already is. A
-        // geometric band-sort loses that on off-baseline glyphs: 2206's inline
-        // math `>` sits ~2 pt above its line's band and drifted into the next
-        // one, `( > 10 pages)` → `( 10 pages) … complex > tables`.
+        // the sanitizer's output order, which our `cells` slice already is.
+        // That is *stream* order, and a generator that paints a line's bold
+        // runs after the surrounding regular text strands them out of place
+        // ("C.6. Zur Wahrung …" read "C. Zur Wahrung … 6."). Restore reading
+        // order geometrically — but group lines by vertical *overlap*, not a
+        // quantized band: 2206's inline math `>` sits ~2 pt above its line's
+        // band and a plain band-sort drifted it into the next line
+        // (`( > 10 pages)` → `( 10 pages) … complex > tables`); overlap
+        // grouping keeps it home. Sorts are stable, so cells sharing a line
+        // and an x-position keep their index order.
+        let mut lines: Vec<(f32, f32, Vec<&TextCell>)> = Vec::new();
+        for c in inside.drain(..) {
+            let (ct, cb) = (c.t.min(c.b), c.t.max(c.b));
+            let line = lines.iter_mut().find(|(lt, lb, _)| {
+                let ov = cb.min(*lb) - ct.max(*lt);
+                ov > 0.5 * (cb - ct).min(*lb - *lt).max(1.0)
+            });
+            match line {
+                Some((lt, lb, cs)) => {
+                    *lt = lt.min(ct);
+                    *lb = lb.max(cb);
+                    cs.push(c);
+                }
+                None => lines.push((ct, cb, vec![c])),
+            }
+        }
+        lines.sort_by(|a, b| a.0.total_cmp(&b.0));
+        for (_, _, mut cs) in lines {
+            cs.sort_by(|a, b| {
+                if rtl {
+                    b.l.total_cmp(&a.l)
+                } else {
+                    a.l.total_cmp(&b.l)
+                }
+            });
+            inside.extend(cs);
+        }
     } else {
         inside.sort_by_key(|c| {
             let x = (c.l * 10.0) as i64;
@@ -1710,6 +1743,50 @@ mod tests {
     use crate::pdfium_backend::{LinkAnnot, PdfPage, TextCell};
     use docling_core::Node;
 
+    /// A generator that paints a line's bold runs *after* its regular text
+    /// hands the sanitizer the cells out of visual order ("C." | "Zur Wahrung
+    /// …" | "6." — the bold label number drawn last). docling's index order
+    /// would strand the bold token at the line's end ("… Mitteilung 6."); the
+    /// overlap-grouped line sort restores reading order, and an off-baseline
+    /// glyph (2206's inline `>` sits ~2 pt above its line) still belongs to
+    /// its own line rather than drifting into the next band.
+    #[test]
+    fn interleaved_font_runs_read_in_visual_order() {
+        let cell = |text: &str, l: f32, t: f32, r: f32, b: f32| TextCell {
+            text: text.to_string(),
+            l,
+            t,
+            r,
+            b,
+        };
+        let cells = vec![
+            cell("C.", 10.0, 100.0, 18.0, 110.0),
+            cell("Zur Wahrung der Widerrufsfrist", 30.0, 100.0, 150.0, 110.0),
+            cell("über die Ausübung", 10.0, 112.0, 90.0, 122.0),
+            cell("6.", 19.0, 100.0, 27.0, 110.0), // bold run, drawn last
+        ];
+        let region = Region {
+            label: "text",
+            score: 1.0,
+            l: 0.0,
+            t: 95.0,
+            r: 200.0,
+            b: 130.0,
+        };
+        assert_eq!(
+            super::region_text(&region, &cells),
+            "C. 6. Zur Wahrung der Widerrufsfrist über die Ausübung"
+        );
+        // Off-baseline glyph: raised but overlapping its line by more than half
+        // its height — stays on that line, ordered by x.
+        let raised = vec![
+            cell("(", 10.0, 100.0, 14.0, 110.0),
+            cell(">", 15.0, 97.0, 20.0, 104.0),
+            cell("10 pages)", 21.0, 100.0, 60.0, 110.0),
+        ];
+        assert_eq!(super::region_text(&region, &raised), "( > 10 pages)");
+    }
+
     /// The geometric-reliability gate, on the two shapes it has to tell apart.
     #[test]
     fn geometric_reliability_rejects_split_column_grids() {

crates/docling-pdf/src/dp_lines.rs

@@ -170,6 +170,48 @@ impl Cell {
     }
 }
 
+/// Axis-aligned bounds of a cell's quad, `(l, r, b, t)` in PDF points (y-up).
+fn bounds(c: &Cell) -> (f64, f64, f64, f64) {
+    let xs = [c.rx0, c.rx1, c.rx2, c.rx3];
+    let ys = [c.ry0, c.ry1, c.ry2, c.ry3];
+    let fold = |it: &[f64], f: fn(f64, f64) -> f64| it.iter().copied().reduce(f).unwrap();
+    (
+        fold(&xs, f64::min),
+        fold(&xs, f64::max),
+        fold(&ys, f64::min),
+        fold(&ys, f64::max),
+    )
+}
+
+/// Is another active cell painted inside the horizontal gap between `i` and
+/// `j`? The contraction walks cells in **stream** order, and a generator that
+/// draws a line's bold runs after its regular text leaves them as later cells
+/// — the space tolerance would then stitch `C.[ ]Zur Wahrung …` straight
+/// across the hole where the bold `6.` sits, and the stranded token ends up at
+/// the line's end ("… wenn Sie die Mitteilung 6."). An occupied gap is not a
+/// gap. Space-only cells never block (they *are* the gap), and the scan is
+/// skipped entirely for glyph-adjacent merges (no room for anything).
+fn gap_occupied(cells: &[Cell], i: usize, j: usize) -> bool {
+    let (al, ar, ab, at) = bounds(&cells[i]);
+    let (bl, br, bb, bt) = bounds(&cells[j]);
+    let (gl, gr) = if ar <= bl { (ar, bl) } else { (br, al) };
+    if gr - gl < 0.5 {
+        return false; // touching or overlapping — nothing fits in between
+    }
+    let (band_b, band_t) = (ab.min(bb), at.max(bt));
+    cells.iter().enumerate().any(|(k, c)| {
+        if k == i || k == j || !c.active || c.text.trim().is_empty() {
+            return false;
+        }
+        let (cl, cr, cb, ct) = bounds(c);
+        // Vertically on this line: most of the candidate inside the pair's band.
+        let overlap = (ct.min(band_t) - cb.max(band_b)).max(0.0);
+        overlap > 0.5 * (ct - cb).max(f64::EPSILON)
+            // Horizontally: real ink inside the gap interval.
+            && cr.min(gr) - cl.max(gl) > 0.1
+    })
+}
+
 /// `applicable_for_merge`: both active and same reading orientation. A different
 /// font normally blocks the merge (keeps a bold label and its value as separate
 /// line cells). On the clean-box parser path, **punctuation/space cells bridge
@@ -214,13 +256,16 @@ fn pass_ltr(cells: &mut [Cell], allow_reverse: bool, euclidean: bool) {
             let d0 = cells[i].avg_char_width() * MERGE;
             let d1 = cells[i].avg_char_width() * MERGE_WITH_SPACE;
             let adj_d1 = d0 + if i_lig || j_lig { H_TOL } else { 0.0 };
-            if cells[i].adjacent(&cells[j], d0, adj_d1) {
+            if cells[i].adjacent(&cells[j], d0, adj_d1) && !gap_occupied(cells, i, j) {
                 let other = cells[j].clone();
                 cells[i].merge_with(&other, d1, euclidean);
                 cells[i].lig_carry = is_ligature(&other.text);
                 cells[j].active = false;
                 j += 1; // i keeps absorbing the next cell to its right
-            } else if allow_reverse && cells[j].adjacent(&cells[i], d0, adj_d1) {
+            } else if allow_reverse
+                && cells[j].adjacent(&cells[i], d0, adj_d1)
+                && !gap_occupied(cells, j, i)
+            {
                 let other = cells[i].clone();
                 cells[j].merge_with(&other, d1, euclidean);
                 cells[j].lig_carry = is_ligature(&other.text);
@@ -251,7 +296,7 @@ fn pass_rtl(cells: &mut [Cell], euclidean: bool) {
         let d0 = cells[i].avg_char_width() * MERGE;
         let d1 = cells[i].avg_char_width() * MERGE_WITH_SPACE;
         let adj_d1 = d0 + if i_lig || j_lig { H_TOL } else { 0.0 };
-        if cells[j].adjacent(&cells[i], d0, adj_d1) {
+        if cells[j].adjacent(&cells[i], d0, adj_d1) && !gap_occupied(cells, j, i) {
             let other = cells[i].clone();
             cells[j].merge_with(&other, d1, euclidean);
             cells[j].lig_carry = is_ligature(&other.text);