feat(pdf): docling-parse migration phase 1 — char-extraction parity + tooling

Groundwork for porting docling-parse's text reconstruction (the path to higher
PDF conformance). Two pieces:

- Lam-alef ligature order: pdfium splits the Arabic lam-alef ligature into two
  chars at the *same* x in visual order (`alef-variant, lam`); docling-parse and
  logical order are `lam, alef-variant`. Reorder same-x ligature pairs at the
  glyph level. The shared-x test reliably distinguishes a real ligature from a
  genuine `alef + lam` sequence (article `ال`, `فعالة`) whose glyphs sit at
  different x — unlike the earlier ambiguous mid-word heuristic.
- Debug tooling: `pdfium_backend::debug_glyphs` + `examples/dump_chars` dump the
  raw pdfium char stream (codepoint + x) to diff against docling-parse's char
  cells; `pdfium_backend` is now `pub` for inspection.

Verified char-extraction parity against docling-parse: both emit chars in
content-stream order (visual for RTL), and with the ligature fix the lam-alef
order matches. The EXACT 3 stay exact; Arabic-only, no other regressions.

Next (phase 2): port `cells.h`'s 3-pass line contraction (corner-distance
adjacency + merge_with space insertion, LTR/RTL/LTR-reverse) to replace the
ad-hoc reconstruction — targets multi_page (run-boundary colons) and the RTL PDFs.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: artiz

crates/fleischwolf-pdf/examples/dump_chars.rs

@@ -0,0 +1,11 @@
+//! Dump pdfium's raw char stream (codepoint + x) for a page, to compare char
+//! extraction against docling-parse. Usage: `... --example dump_chars -- file.pdf`
+fn main() {
+    let path = std::env::args().nth(1).expect("usage: dump_chars <pdf>");
+    let bytes = std::fs::read(&path).expect("read");
+    let glyphs = fleischwolf_pdf::pdfium_backend::debug_glyphs(&bytes, 0);
+    println!("pdfium CHAR order (first 16):");
+    for (ch, l, _b, _r, _t) in glyphs.iter().take(16) {
+        println!("  {:?} U+{:04X}  xl={:.1}", ch, *ch as u32, l);
+    }
+}

crates/fleischwolf-pdf/src/lib.rs

@@ -13,7 +13,7 @@ mod assemble;
 pub mod layout;
 mod mets;
 mod ocr;
-mod pdfium_backend;
+pub mod pdfium_backend;
 pub mod resample;
 pub mod tableformer;
 

crates/fleischwolf-pdf/src/pdfium_backend.rs

@@ -237,6 +237,34 @@ impl Drop for FfiText<'_> {
 /// pdfium emits these on most lines and they pin word splits exactly. Hard line
 /// breaks are dropped (line structure comes from geometry); the gap heuristic in
 /// [`lines_from_glyphs`] is the fallback for the lines pdfium leaves space-less.
+/// Debug helper: the raw pdfium glyph stream (codepoint + native bottom-left
+/// box) for a page, in pdfium's character order. For comparing against
+/// docling-parse's char cells.
+pub fn debug_glyphs(bytes: &[u8], index: i32) -> Vec<(char, f32, f32, f32, f32)> {
+    let Ok(pdfium) = bind() else {
+        return Vec::new();
+    };
+    let ffi = FfiText::load(pdfium.bindings(), bytes, None);
+    if ffi.doc.is_null() {
+        return Vec::new();
+    }
+    let b = ffi.bindings;
+    let page = b.FPDF_LoadPage(ffi.doc, index);
+    if page.is_null() {
+        return Vec::new();
+    }
+    let tp = b.FPDFText_LoadPage(page);
+    let mut out = Vec::new();
+    if !tp.is_null() {
+        for g in glyphs(b, tp) {
+            out.push((g.ch, g.l, g.b, g.r, g.t));
+        }
+        b.FPDFText_ClosePage(tp);
+    }
+    b.FPDF_ClosePage(page);
+    out
+}
+
 fn glyphs(b: &dyn PdfiumLibraryBindings, tp: FPDF_TEXTPAGE) -> Vec<Glyph> {
     let n = b.FPDFText_CountChars(tp);
     let mut out = Vec::with_capacity(n.max(0) as usize);
@@ -270,6 +298,23 @@ fn glyphs(b: &dyn PdfiumLibraryBindings, tp: FPDF_TEXTPAGE) -> Vec<Glyph> {
             t: top as f32,
         });
     }
+    // pdfium splits the Arabic lam-alef ligature into two chars at the *same* x
+    // (it's one glyph) in visual order — `alef-variant, lam`. docling-parse and
+    // logical order are `lam, alef-variant`. Detect the ligature by the shared x
+    // and swap. The shared-x test reliably distinguishes a true ligature from a
+    // genuine `alef + lam` sequence (the article `ال`, or `فعالة`), whose two
+    // glyphs sit at different x and must NOT be reordered.
+    for i in 0..out.len().saturating_sub(1) {
+        let same_x = out[i].l.is_finite()
+            && out[i + 1].l.is_finite()
+            && (out[i].l - out[i + 1].l).abs() < 1.0;
+        if same_x
+            && matches!(out[i].ch, '\u{0622}' | '\u{0623}' | '\u{0625}' | '\u{0627}')
+            && out[i + 1].ch == '\u{0644}'
+        {
+            out.swap(i, i + 1);
+        }
+    }
     out
 }