Merge pull request yfedoseev#238 from yfedoseev/release/v0.3.17

feat: v0.3.17 - resolve RefCell panic and refine table detection

Author: yfedoseev

CHANGELOG.md

@@ -2,6 +2,22 @@
 
 All notable changes to PDFOxide are documented here.
 
+## [0.3.17] - 2026-03-08
+> Stable Recursion and Refined Table Heuristics
+
+### Features
+
+- **Refined Table Detection** — The spatial table detector now requires at least **2 columns** to identify a region as a table. This significantly reduces false positives where single-column lists or bullet points were incorrectly wrapped in ASCII boxes.
+- **Optimized Text Extraction** — Refactored the internal extraction pipeline to eliminate redundant work when processing Tagged PDFs. The structure tree and page spans are now extracted once and shared across the detection and rendering phases.
+
+### Bug Fixes
+
+- **Resolved `RefCell` already borrowed panic** (#237) — Fixed a critical reentrancy issue where recursive Form XObject processing (e.g., extracting images from nested forms) could trigger a runtime panic. Replaced long-lived borrows with scoped, tiered cache access using Rust best practices. (Reported by **@marph91**)
+
+### 🏆 Community Contributors
+
+🥇 **@marph91** — Thank you for identifying the complex `RefCell` borrow conflict in nested image extraction (#237). This report led to a comprehensive safety audit of our interior mutability patterns and a more robust, recursion-safe caching architecture! 🚀
+
 ## [0.3.16] - 2026-03-08
 > Advanced Visual Table Detection and Automated Python Stubs
 

Cargo.lock

@@ -3,7 +3,7 @@ members = [".", "pdf_oxide_mcp", "pdf_oxide_cli"]
 
 [package]
 name = "pdf_oxide"
-version = "0.3.16"
+version = "0.3.17"
 edition = "2021"
 authors = ["Yury Fedoseev <yfedoseev@gmail.com>"]
 license = "MIT OR Apache-2.0"

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "pdf_oxide_cli"
-version = "0.3.16"
+version = "0.3.17"
 edition = "2021"
 description = "CLI for pdf-oxide — the fastest PDF toolkit. 22 commands: text extraction, PDF to markdown, search, merge, split, images, compress, encrypt, watermark, forms, and more."
 license = "MIT OR Apache-2.0"
@@ -16,7 +16,7 @@ name = "pdf-oxide"
 path = "src/main.rs"
 
 [dependencies]
-pdf_oxide = { version = "0.3.16", path = "..", features = ["rendering", "logging"] }
+pdf_oxide = { version = "0.3.17", path = "..", features = ["rendering", "logging"] }
 clap = { version = "4", features = ["derive"] }
 is-terminal = "0.4"
 serde_json = "1.0"

pdf_oxide_cli/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "pdf_oxide_mcp"
-version = "0.3.16"
+version = "0.3.17"
 edition = "2021"
 description = "MCP server for PDF extraction — gives Claude, Cursor, and AI assistants the ability to read PDFs locally. Text, markdown, and HTML output. Powered by pdf_oxide."
 license = "MIT OR Apache-2.0"
@@ -16,7 +16,7 @@ name = "pdf-oxide-mcp"
 path = "src/main.rs"
 
 [dependencies]
-pdf_oxide = { version = "0.3.16", path = ".." }
+pdf_oxide = { version = "0.3.17", path = ".." }
 serde = { version = "1.0", features = ["derive"] }
 serde_json = "1.0"
 

pdf_oxide_mcp/Cargo.toml

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "pdf_oxide"
-version = "0.3.16"
+version = "0.3.17"
 description = "The fastest Python PDF library: 0.8ms mean, 5× faster than PyMuPDF. Text extraction, markdown conversion, PDF creation. 100% pass rate on 3,830 PDFs."
 readme = "README.md"
 requires-python = ">=3.8"

pyproject.toml

@@ -188,7 +188,8 @@ pub struct PdfDocument {
         RefCell<HashMap<ObjectRef, Option<Vec<crate::layout::TextSpan>>>>,
     /// Cache of extracted images from Form XObjects (keyed by ObjectRef).
     /// Images are stored without CTM applied — caller applies its own CTM.
-    pub(crate) form_xobject_images_cache: HashMap<ObjectRef, Vec<crate::extractors::PdfImage>>,
+    pub(crate) form_xobject_images_cache:
+        RefCell<HashMap<ObjectRef, Vec<crate::extractors::PdfImage>>>,
     /// Regions marked for erasure per page
     pub(crate) erase_regions: HashMap<usize, Vec<crate::geometry::Rect>>,
 }
@@ -436,7 +437,7 @@ impl PdfDocument {
             xobject_stream_cache: RefCell::new(HashMap::new()),
             xobject_stream_cache_bytes: Cell::new(0),
             xobject_spans_cache: RefCell::new(HashMap::new()),
-            form_xobject_images_cache: HashMap::new(),
+            form_xobject_images_cache: RefCell::new(HashMap::new()),
             erase_regions: HashMap::new(),
         };
 
@@ -867,7 +868,8 @@ impl PdfDocument {
         }
 
         // Check cache first
-        if let Some(cached) = self.object_cache.borrow().get(&obj_ref).cloned() {
+        let cached_opt = self.object_cache.borrow().get(&obj_ref).cloned();
+        if let Some(cached) = cached_opt {
             return Ok(cached);
         }
 
@@ -1098,12 +1100,15 @@ impl PdfDocument {
     /// For compressed objects or on any error, returns true (conservative — will load fully).
     pub fn is_form_xobject(&self, obj_ref: ObjectRef) -> bool {
         // Check negative cache first (known non-Form XObjects)
-        if self.image_xobject_cache.borrow().contains(&obj_ref) {
-            return false;
+        {
+            if self.image_xobject_cache.borrow().contains(&obj_ref) {
+                return false;
+            }
         }
 
         // If already in object cache, check directly
-        if let Some(cached) = self.object_cache.borrow().get(&obj_ref).cloned() {
+        let cached_opt = self.object_cache.borrow().get(&obj_ref).cloned();
+        if let Some(cached) = cached_opt {
             let is_form = cached
                 .as_dict()
                 .and_then(|d| d.get("Subtype"))
@@ -6711,8 +6716,8 @@ impl PdfDocument {
             // Layer 2: Check font set cache for the /Font dictionary.
             // Pages sharing the same /Font dict skip the entire per-font loop.
             if let Some(font_dict_ref) = font_dict_ref {
-                if let Some(cached_set) = self.font_set_cache.borrow().get(&font_dict_ref).cloned()
-                {
+                let cached_set_opt = self.font_set_cache.borrow().get(&font_dict_ref).cloned();
+                if let Some(cached_set) = cached_set_opt {
                     for (name, font_arc) in &cached_set {
                         extractor.add_font_shared(name.clone(), Arc::clone(font_arc));
                     }
@@ -6745,12 +6750,12 @@ impl PdfDocument {
                     hasher.finish()
                 };
 
-                if let Some(cached_set) = self
+                let cached_fingerprint_opt = self
                     .font_fingerprint_cache
                     .borrow()
                     .get(&fingerprint)
-                    .cloned()
-                {
+                    .cloned();
+                if let Some(cached_set) = cached_fingerprint_opt {
                     for (name, font_arc) in &cached_set {
                         extractor.add_font_shared(name.clone(), Arc::clone(font_arc));
                     }
@@ -6772,9 +6777,8 @@ impl PdfDocument {
                     hasher.finish()
                 };
 
-                if let Some((cached_set, _check_name, _check_hash)) =
-                    self.font_name_set_cache.borrow().get(&name_hash).cloned()
-                {
+                let cached_name_set = self.font_name_set_cache.borrow().get(&name_hash).cloned();
+                if let Some((cached_set, _check_name, _check_hash)) = cached_name_set {
                     // Layer 4: Same font names within a document virtually always map
                     // to the same underlying fonts. Trust the name-based cache to avoid
                     // expensive load_object calls for spot-check verification.
@@ -6798,7 +6802,8 @@ impl PdfDocument {
                 for (name, font_obj) in sorted_font_entries {
                     // If font is a reference, check per-font cache first
                     if let Some(font_ref) = font_obj.as_reference() {
-                        if let Some(cached) = self.font_cache.borrow().get(&font_ref).cloned() {
+                        let cached_font_opt = self.font_cache.borrow().get(&font_ref).cloned();
+                        if let Some(cached) = cached_font_opt {
                             extractor.add_font_shared(name.clone(), cached);
                             continue;
                         }
@@ -6815,9 +6820,9 @@ impl PdfDocument {
 
                         // Layer 5: Per-font identity cache — skip from_dict when a
                         // structurally identical font was already parsed elsewhere.
-                        if let Some(cached) =
-                            self.font_identity_cache.borrow().get(&id_hash).cloned()
-                        {
+                        let cached_identity_opt =
+                            self.font_identity_cache.borrow().get(&id_hash).cloned();
+                        if let Some(cached) = cached_identity_opt {
                             self.font_cache
                                 .borrow_mut()
                                 .insert(font_ref, Arc::clone(&cached));
@@ -8162,19 +8167,22 @@ impl PdfDocument {
             return Ok(Vec::new());
         }
 
-        // Check image result cache — images stored with Form's own Matrix only
-        if let Some(cached_images) = self.form_xobject_images_cache.get(&xobject_ref) {
-            let images = cached_images
-                .iter()
-                .map(|img| {
-                    let mut cloned = img.clone();
-                    if let Some(rect) = cloned.bbox() {
-                        cloned.set_bbox(self.transform_bbox_with_ctm(rect, parent_ctm));
-                    }
-                    cloned
-                })
-                .collect();
-            return Ok(images);
+        // Check image result cache — images stored with Form's own Matrix only.
+        // Scope the borrow to ensure it's dropped before potential recursion.
+        {
+            if let Some(cached_images) = self.form_xobject_images_cache.borrow().get(&xobject_ref) {
+                let images = cached_images
+                    .iter()
+                    .map(|img| {
+                        let mut cloned = img.clone();
+                        if let Some(rect) = cloned.bbox() {
+                            cloned.set_bbox(self.transform_bbox_with_ctm(rect, parent_ctm));
+                        }
+                        cloned
+                    })
+                    .collect();
+                return Ok(images);
+            }
         }
 
         xobject_stack.push(xobject_ref);
@@ -8220,12 +8228,12 @@ impl PdfDocument {
         };
 
         // Decode form stream — check cache first to avoid repeated decompression
-        let stream_data = if let Some(cached) = self
+        let cached_stream = self
             .xobject_stream_cache
             .borrow()
             .get(&xobject_ref)
-            .cloned()
-        {
+            .cloned();
+        let stream_data = if let Some(cached) = cached_stream {
             cached.as_ref().clone()
         } else {
             match self.decode_stream_with_encryption(xobject, xobject_ref) {
@@ -8322,6 +8330,7 @@ impl PdfDocument {
 
         // Cache the raw images (with Form's own Matrix applied, but no parent CTM)
         self.form_xobject_images_cache
+            .borrow_mut()
             .insert(xobject_ref, raw_images.clone());
 
         // Apply parent_ctm to produce final images for this call

src/document.rs

@@ -4419,7 +4419,7 @@ impl TextExtractor {
         // Span result cache: reuse extracted spans from self-contained Form XObjects.
         // Only works for XObjects with own /Resources (font context is self-contained).
         if self.extract_spans {
-            let cached_spans = doc.xobject_spans_cache.borrow().get(&xobject_ref).cloned();
+            let cached_spans = { doc.xobject_spans_cache.borrow().get(&xobject_ref).cloned() };
             if let Some(cached_spans) = cached_spans {
                 if let Some(spans) = cached_spans {
                     self.spans.extend(spans.iter().cloned());
@@ -4482,7 +4482,8 @@ impl TextExtractor {
 
                 // Decode the stream — check cache first to avoid repeated FlateDecode.
                 self.xobject_decode_count += 1;
-                let cached_stream = doc.xobject_stream_cache.borrow().get(&xobject_ref).cloned();
+                let cached_stream =
+                    { doc.xobject_stream_cache.borrow().get(&xobject_ref).cloned() };
                 let stream_data = if let Some(cached) = cached_stream {
                     cached.as_ref().clone()
                 } else {

src/extractors/text.rs

@@ -0,0 +1,79 @@
+use pdf_oxide::converters::ConversionOptions;
+use pdf_oxide::document::PdfDocument;
+
+#[test]
+fn test_recursive_xobject_image_extraction_safety() {
+    // Regression test for ensuring recursive image extraction from Form XObjects
+    // does not trigger RefCell borrow conflicts.
+
+    let mut pdf = Vec::new();
+    let mut offsets: Vec<usize> = Vec::new();
+
+    pdf.extend_from_slice(b"%PDF-1.4\n");
+
+    // 1 0 obj: Catalog
+    offsets.push(pdf.len());
+    pdf.extend_from_slice(b"1 0 obj\n<< /Type /Catalog /Pages 2 0 R >>\nendobj\n");
+
+    // 2 0 obj: Pages
+    offsets.push(pdf.len());
+    pdf.extend_from_slice(b"2 0 obj\n<< /Type /Pages /Kids [3 0 R] /Count 1 >>\nendobj\n");
+
+    // 3 0 obj: Page
+    offsets.push(pdf.len());
+    pdf.extend_from_slice(b"3 0 obj\n<< /Type /Page /Parent 2 0 R /MediaBox [0 0 612 792] /Contents 4 0 R /Resources << /XObject << /Form1 5 0 R >> >> >>\nendobj\n");
+
+    // 4 0 obj: Page content (invokes Form1)
+    let content = b"/Form1 Do";
+    offsets.push(pdf.len());
+    pdf.extend_from_slice(format!("4 0 obj\n<< /Length {} >>\nstream\n", content.len()).as_bytes());
+    pdf.extend_from_slice(content);
+    pdf.extend_from_slice(b"\nendstream\nendobj\n");
+
+    // 5 0 obj: Form XObject (invokes Im1)
+    let form_content = b"q 100 0 0 100 100 100 cm /Im1 Do Q";
+    let form_res = b"<< /XObject << /Im1 6 0 R >> >>";
+    offsets.push(pdf.len());
+    pdf.extend_from_slice(format!("5 0 obj\n<< /Type /XObject /Subtype /Form /BBox [0 0 612 792] /Resources {} /Length {} >>\nstream\n", String::from_utf8_lossy(form_res), form_content.len()).as_bytes());
+    pdf.extend_from_slice(form_content);
+    pdf.extend_from_slice(b"\nendstream\nendobj\n");
+
+    // 6 0 obj: Image XObject
+    let img_data = vec![0u8; 100 * 100 * 3];
+    offsets.push(pdf.len());
+    pdf.extend_from_slice(format!("6 0 obj\n<< /Type /XObject /Subtype /Image /Width 100 /Height 100 /ColorSpace /DeviceRGB /BitsPerComponent 8 /Length {} >>\nstream\n", img_data.len()).as_bytes());
+    pdf.extend_from_slice(&img_data);
+    pdf.extend_from_slice(b"\nendstream\nendobj\n");
+
+    let xref_offset = pdf.len();
+    pdf.extend_from_slice(b"xref\n");
+    pdf.extend_from_slice(format!("0 {}\n", offsets.len() + 1).as_bytes());
+    pdf.extend_from_slice(b"0000000000 65535 f \n");
+    for offset in &offsets {
+        pdf.extend_from_slice(format!("{:010} 00000 n \n", offset).as_bytes());
+    }
+
+    pdf.extend_from_slice(
+        format!(
+            "trailer\n<< /Size {} /Root 1 0 R >>\nstartxref\n{}\n%%EOF\n",
+            offsets.len() + 1,
+            xref_offset
+        )
+        .as_bytes(),
+    );
+
+    let mut doc = PdfDocument::from_bytes(pdf).expect("Failed to parse PDF");
+
+    let options = ConversionOptions {
+        include_images: true,
+        ..Default::default()
+    };
+
+    // Multiple iterations to ensure caching logic is also exercised safely
+    for _ in 0..10 {
+        let result = doc.to_markdown(0, &options);
+        assert!(result.is_ok(), "Image extraction failed in recursive XObject");
+        let markdown = result.unwrap();
+        assert!(markdown.contains("![Image"), "Markdown should contain image reference");
+    }
+}