chore(pdf): add hidden-text-layer diagnostic (debug_text_objects)

Investigating the reported code-block duplication (e.g. dotnet-csharp-language-
reference.pdf), the most likely cause is a hidden/invisible duplicate text layer
that the char-level text extraction pulls in — common in web-generated PDFs whose
syntax-highlighted code carries a plain-text copy for copy-paste.

The clean fix (skip text render mode 3) is blocked for now: pdfium-render 0.8's
default `pdfium_latest` binding does not expose the per-character
FPDFText_GetTextRenderMode (it is feature-gated to pdfium <= 6569). The
object-level FPDFTextObj_GetTextRenderMode *is* available, so add:

- `debug_text_objects(bytes, page)` — every text object with its visibility
  (render mode 3), bounding box, and text; and
- the `dump_render_modes` example — find the page containing a needle and list
  its text objects, so we can confirm on the actual PDF whether the duplicate is
  an invisible layer (and at what geometry) before implementing the filter.

No pipeline behavior changes; this only adds a diagnostic accessor + example.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01H3AUFjF71HP2YY9cD32wx8

Author: claude

crates/fleischwolf-pdf/examples/dump_render_modes.rs

@@ -0,0 +1,48 @@
+//! Diagnose a duplicated / hidden PDF text layer.
+//!
+//! Finds the first page whose text objects contain `needle` and lists that page's
+//! text objects, each tagged visible or INVISIBLE (text render mode 3), with their
+//! bounding box and text. A hidden duplicate layer — e.g. the plain-text copy
+//! web exporters stash behind a syntax-highlighted code block — shows up as
+//! INVISIBLE objects repeating the visible text, usually at a different position.
+//!
+//! Usage:
+//!   cargo run -p fleischwolf-pdf --example dump_render_modes -- file.pdf "LangVersion"
+
+use fleischwolf_pdf::pdfium_backend::{debug_text_objects, page_count};
+
+fn main() {
+    let path = std::env::args()
+        .nth(1)
+        .expect("usage: dump_render_modes <pdf> <needle>");
+    let needle = std::env::args().nth(2).expect("needle substring required");
+    let bytes = std::fs::read(&path).expect("read pdf");
+    let pages = page_count(&bytes, None).expect("page count");
+
+    for p in 0..pages as i32 {
+        let objs = debug_text_objects(&bytes, p);
+        if !objs.iter().any(|o| o.text.contains(&needle)) {
+            continue;
+        }
+        let visible = objs.iter().filter(|o| !o.invisible).count();
+        let invisible = objs.iter().filter(|o| o.invisible).count();
+        println!(
+            "page {p}: {} text object(s) — {visible} visible, {invisible} INVISIBLE\n",
+            objs.len()
+        );
+        for o in &objs {
+            let tag = if o.invisible {
+                "INVISIBLE"
+            } else {
+                "visible  "
+            };
+            let text: String = o.text.chars().take(70).collect();
+            println!(
+                "  [{tag}] l={:8.2} b={:8.2} r={:8.2} t={:8.2}  {text:?}",
+                o.l, o.b, o.r, o.t
+            );
+        }
+        return;
+    }
+    println!("needle {needle:?} not found in any text object across {pages} page(s)");
+}

crates/fleischwolf-pdf/src/pdfium_backend.rs

@@ -411,6 +411,87 @@ pub fn debug_glyphs(bytes: &[u8], index: i32) -> Vec<(char, f32, f32)> {
     out
 }
 
+/// One text object on a page, for the hidden-layer diagnostic.
+#[derive(Debug, Clone)]
+pub struct DebugTextObject {
+    /// True when the object is drawn invisibly (text render mode 3) — the marker of
+    /// a hidden duplicate text layer.
+    pub invisible: bool,
+    /// Bounding box in native PDF points (bottom-left origin).
+    pub l: f32,
+    pub b: f32,
+    pub r: f32,
+    pub t: f32,
+    /// The object's text (best-effort; empty if it could not be read).
+    pub text: String,
+}
+
+/// Diagnostic: every text object on page `index`, each tagged visible/invisible
+/// (via the object-level [`FPDFTextObj_GetTextRenderMode`], which — unlike the
+/// per-character render-mode API — is available on the default pdfium binding).
+/// A hidden duplicate text layer shows up as invisible objects repeating the
+/// visible text. Used by the `dump_render_modes` example.
+///
+/// [`FPDFTextObj_GetTextRenderMode`]: pdfium_render::prelude::PdfiumLibraryBindings::FPDFTextObj_GetTextRenderMode
+pub fn debug_text_objects(bytes: &[u8], index: i32) -> Vec<DebugTextObject> {
+    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();
+    let n = b.FPDFPage_CountObjects(page);
+    for i in 0..n {
+        let obj = b.FPDFPage_GetObject(page, i);
+        if obj.is_null() || b.FPDFPageObj_GetType(obj) != FPDF_PAGEOBJ_TEXT as i32 {
+            continue;
+        }
+        let (mut l, mut bot, mut r, mut top) = (0f32, 0f32, 0f32, 0f32);
+        if b.FPDFPageObj_GetBounds(obj, &mut l, &mut bot, &mut r, &mut top) == 0 {
+            continue;
+        }
+        let invisible = b.FPDFTextObj_GetTextRenderMode(obj) == INVISIBLE_RENDER_MODE;
+        let text = if tp.is_null() {
+            String::new()
+        } else {
+            // FPDFTextObj_GetText returns the count of UTF-16 code units, including
+            // the trailing NUL; call once for the size, once to fill.
+            let need = b.FPDFTextObj_GetText(obj, tp, std::ptr::null_mut(), 0);
+            if need <= 1 {
+                String::new()
+            } else {
+                let mut buf = vec![0u16; need as usize];
+                b.FPDFTextObj_GetText(obj, tp, buf.as_mut_ptr(), need);
+                if let Some(&0) = buf.last() {
+                    buf.pop();
+                }
+                String::from_utf16_lossy(&buf)
+            }
+        };
+        out.push(DebugTextObject {
+            invisible,
+            l,
+            b: bot,
+            r,
+            t: top,
+            text,
+        });
+    }
+    if !tp.is_null() {
+        b.FPDFText_ClosePage(tp);
+    }
+    b.FPDF_ClosePage(page);
+    out
+}
+
 /// Hash a glyph's PDF font name + flags, for `enforce_same_font`. 0 if unavailable.
 fn font_hash(b: &dyn PdfiumLibraryBindings, tp: FPDF_TEXTPAGE, i: i32) -> u64 {
     use std::hash::{Hash, Hasher};
@@ -433,6 +514,12 @@ fn font_hash(b: &dyn PdfiumLibraryBindings, tp: FPDF_TEXTPAGE, i: i32) -> u64 {
     h.finish()
 }
 
+/// pdfium text render mode 3: the glyph is drawn with neither fill nor stroke —
+/// an invisible glyph. Web-to-PDF exporters put a hidden plain-text copy of
+/// syntax-highlighted code (and other "copy"/accessibility layers) in this mode,
+/// which the char-level text API then extracts as a duplicate of the visible text.
+const INVISIBLE_RENDER_MODE: i32 = 3;
+
 fn glyphs(b: &dyn PdfiumLibraryBindings, tp: FPDF_TEXTPAGE, fetch_font: bool) -> Vec<Glyph> {
     let n = b.FPDFText_CountChars(tp);
     let mut out = Vec::with_capacity(n.max(0) as usize);