fix(vision): preserve adaptive OCR fallbacks

Cargo.toml

@@ -86,6 +86,9 @@ model-cache = ["vision", "dep:dirs", "dep:fs2", "dep:sha2", "dep:windows-sys"]
 model-download = ["model-cache", "dep:ureq"]
 ocr-oar = ["model-cache", "dep:image", "dep:oar-ocr", "dep:ort"]
 render-pdfium = ["vision", "dep:firecrawl-pdfium"]
+# Complete native OCR path. This remains opt-in so default library,
+# renderer-only, and browser consumers do not inherit inference or HTTP/TLS.
+ocr = ["render-pdfium", "ocr-oar", "model-download"]
 
 [[bin]]
 name = "pdf2md"

docs/rust-api.md

@@ -308,6 +308,123 @@ SHA-256 verification to `ModelStore`. The store serializes installation across
 processes and publishes completed artifacts atomically. Warm caches make no
 network calls; offline mode and explicit model directories never download.
 
+### OCR Markdown assembly and native fusion
+
+`fuse_ocr_pages` maps OCR polygons back into PDF coordinates and sends the
+result through pdf-inspector's existing deterministic reading-order, table,
+and Markdown pipeline. Pages whose native extraction was rejected use OCR
+output. When `Force` runs on a clean native page, normalized duplicate OCR
+blocks are removed and only additional image-backed text is retained.
+
+```rust
+use pdf_inspector::vision::{fuse_ocr_pages, OcrFusionOptions};
+
+let fused = fuse_ocr_pages(
+    &extraction.pages,
+    &run,
+    extraction.pages.len() as u32,
+    &OcrFusionOptions::new().render_dpi(150.0),
+)?;
+
+for page in &fused.pages {
+    println!("{}", page.markdown);
+    if page.provenance.hosted_recommended {
+        eprintln!("page {} needs the hosted document pipeline", page.page + 1);
+    }
+}
+```
+
+Each page carries `Native`, `Ocr`, or `Fused` provenance, the exact OCR model
+revision, accepted-page confidence, local stage timings, and non-fatal
+warnings. A page that required OCR recommends the hosted pipeline when local
+OCR is missing, empty, or below the configurable page-confidence threshold.
+This keeps the lightweight path explicit about cases it cannot finish well.
+
+### Complete OCR API
+
+The `ocr` convenience feature enables the renderer, OCR engine, verified
+model acquisition, routing, and fusion layers together. It is the intended
+downstream application integration boundary; lower-level features remain
+available for consumers that bring their own renderer, model package manager,
+or engine.
+
+```toml
+[dependencies]
+pdf-inspector = { version = "1", features = ["ocr"] }
+```
+
+```rust
+use pdf_inspector::vision::{
+    process_pdf_with_ocr, OcrMode, OcrPdfOptions,
+};
+
+let result = process_pdf_with_ocr(
+    "document.pdf",
+    OcrPdfOptions::new()
+        .mode(OcrMode::Auto)
+        .pages([1, 2, 3]),
+)?;
+
+println!("{}", result.markdown);
+println!("OCR pages: {:?}", result.pages_routed_to_ocr);
+println!(
+    "Hosted fallback pages: {:?}",
+    result.pages_recommending_hosted,
+);
+```
+
+Native extraction always runs first. In `Auto`, a clean PDF returns before
+PDFium loading, model-cache access, HTTP, or OAR initialization. Model files
+remain external and the default crate feature set remains unchanged. `Off`
+provides the same native-only behavior through the OCR result/provenance
+shape; `Force` renders every selected page. Learned layout intentionally
+returns an explicit unsupported error in this lightweight pipeline.
+
+For ambiguous mixed pages, `Auto` privately retains clean native fragments
+instead of discarding them when OCR is selected. After recognition it compares
+script-agnostic text quality, OCR confidence, character overlap, and material
+new coverage. Exact native text wins over a duplicate or weak OCR hypothesis;
+complementary image-backed text is fused; and pages where both candidates are
+weak recommend the hosted document pipeline. Public native-only extraction
+continues to suppress pages marked unreliable, and clean text documents pay no
+renderer or model-initialization cost.
+
+In `Auto`, pages routed only for suspicious font encoding or vectorized text
+first get a bounded positioned-text probe through PDFium. A credible recovered
+text layer with sufficient geometric page coverage skips rasterization and
+model loading for that page; garbled, partial, or insubstantial recovery
+continues through OCR. Recovered tables are reflected in the same document
+metadata as tables found by the primary extractor.
+
+The one-call API keeps the most recently used verified OCR engine in process.
+Long-lived workers therefore verify the pinned artifacts and build the ONNX
+sessions once, then reuse those loaded sessions across documents. The cache is
+bounded to one model configuration and keyed by normalized model/runtime paths
+plus the pinned manifest revision and artifact digests; switching the model
+directory, runtime library, or compiled manifest replaces it. An active engine
+owns the model data it already verified, so mutating artifacts in place does
+not hot-reload a running process; restart the process when intentionally
+replacing files at the same paths. CPU inference uses at most four intra-op
+threads per ONNX session so a single small page does not oversubscribe larger
+hosts, and recognizes variable-width line crops individually to avoid
+padding-heavy CPU batches.
+
+Build the CLI with the same opt-in feature:
+
+```bash
+cargo build --release --features ocr --bin pdf2md
+pdf2md document.pdf --ocr auto --raw
+pdf2md document.pdf --ocr auto --json
+pdf2md document.pdf --ocr auto --ocr-offline --ocr-model-dir /opt/models/pp-ocrv6-small
+```
+
+CLI controls include `--ocr-dpi`, `--ocr-min-confidence`,
+`--ocr-hosted-threshold`, `--select-pages`, and the existing encrypted-PDF
+`--password` option. JSON output includes per-page Markdown, source/model
+provenance, confidence, timings, warnings, routed pages, and hosted-fallback
+recommendations. Page numbers in `OcrPdfResult` and its per-page provenance
+are 1-indexed, matching the PDF page numbers accepted by `OcrPdfOptions::pages`.
+
 Extract per-page Markdown (one string per page, plus document-wide layout
 metadata):
 

src/bin/pdf2md.rs

@@ -1,6 +1,11 @@
 //! CLI tool for PDF to Markdown conversion
 
 use pdf_inspector::extractor::ItemType;
+#[cfg(all(feature = "ocr", not(target_arch = "wasm32")))]
+use pdf_inspector::vision::{
+    process_pdf_with_ocr, ModelDownloadPolicy, OcrMode, OcrOptions, OcrPdfOptions, OcrPdfResult,
+    PageContentSource, RenderOptions,
+};
 use pdf_inspector::{
     extract_text_with_positions_pages_with_password, process_pdf_with_options, LayoutComplexity,
     PdfOptions, PdfType, ProcessMode, TextItem,
@@ -103,6 +108,134 @@ fn format_items_json(items: &[TextItem]) -> String {
     )
 }
 
+#[cfg(all(feature = "ocr", not(target_arch = "wasm32")))]
+fn optional_json_number(value: Option<f32>) -> String {
+    value
+        .filter(|value| value.is_finite())
+        .map(|value| format!("{value:.4}"))
+        .unwrap_or_else(|| "null".to_string())
+}
+
+#[cfg(all(feature = "ocr", not(target_arch = "wasm32")))]
+fn format_ocr_json(result: &OcrPdfResult) -> String {
+    let routed = result
+        .pages_routed_to_ocr
+        .iter()
+        .map(u32::to_string)
+        .collect::<Vec<_>>()
+        .join(",");
+    let recommended = result
+        .pages_recommended_for_ocr
+        .iter()
+        .map(u32::to_string)
+        .collect::<Vec<_>>()
+        .join(",");
+    let hosted = result
+        .pages_recommending_hosted
+        .iter()
+        .map(u32::to_string)
+        .collect::<Vec<_>>()
+        .join(",");
+    let pages = result
+        .pages
+        .iter()
+        .map(|page| {
+            let provenance = &page.provenance;
+            let source = match provenance.source {
+                PageContentSource::Native => "native",
+                PageContentSource::Ocr => "ocr",
+                PageContentSource::Fused => "fused",
+                _ => "unknown",
+            };
+            let model = provenance
+                .ocr_model
+                .as_ref()
+                .map(|model| {
+                    format!(
+                        r#"{{"name":"{}","revision":"{}"}}"#,
+                        json_escape(&model.name),
+                        json_escape(&model.revision)
+                    )
+                })
+                .unwrap_or_else(|| "null".to_string());
+            let warnings = provenance
+                .warnings
+                .iter()
+                .map(|warning| format!(r#""{}""#, json_escape(warning)))
+                .collect::<Vec<_>>()
+                .join(",");
+            format!(
+                r#"{{"page":{},"source":"{}","markdown":"{}","ocr_model":{},"render_dpi":{},"ocr_confidence":{},"hosted_recommended":{},"timings":{{"render_ms":{},"ocr_ms":{},"layout_ms":{},"assembly_ms":{}}},"warnings":[{}]}}"#,
+                provenance.page,
+                source,
+                json_escape(&page.markdown),
+                model,
+                optional_json_number(provenance.render_dpi),
+                optional_json_number(provenance.ocr_confidence),
+                provenance.hosted_recommended,
+                provenance.timings.render_ms,
+                provenance.timings.ocr_ms,
+                provenance.timings.layout_ms,
+                provenance.timings.assembly_ms,
+                warnings,
+            )
+        })
+        .collect::<Vec<_>>()
+        .join(",");
+    let table_pages = result
+        .pages_with_tables
+        .iter()
+        .map(u32::to_string)
+        .collect::<Vec<_>>()
+        .join(",");
+    let column_pages = result
+        .pages_with_columns
+        .iter()
+        .map(u32::to_string)
+        .collect::<Vec<_>>()
+        .join(",");
+    let ocr_reasons = format_ocr_reasons_by_page(&result.ocr_reasons_by_page);
+    format!(
+        r#"{{"page_count":{},"processing_time_ms":{},"render_time_ms":{},"ocr_time_ms":{},"pages_recommended_for_ocr":[{}],"pages_routed_to_ocr":[{}],"pages_recommending_hosted":[{}],"ocr_reasons_by_page":[{}],"is_complex":{},"pages_with_tables":[{}],"pages_with_columns":[{}],"pages":[{}],"markdown":"{}"}}"#,
+        result.page_count,
+        result.processing_time_ms,
+        result.render_time_ms,
+        result.ocr_time_ms,
+        recommended,
+        routed,
+        hosted,
+        ocr_reasons,
+        result.is_complex,
+        table_pages,
+        column_pages,
+        pages,
+        json_escape(&result.markdown),
+    )
+}
+
+fn argument_value<'a>(args: &'a [String], name: &str) -> Result<Option<&'a str>, String> {
+    args.iter()
+        .position(|argument| argument == name)
+        .map(|index| {
+            args.get(index + 1)
+                .map(String::as_str)
+                .ok_or_else(|| format!("{name} requires a value"))
+        })
+        .transpose()
+}
+
+#[cfg(all(feature = "ocr", not(target_arch = "wasm32")))]
+fn float_argument(args: &[String], name: &str, default: f32) -> Result<f32, String> {
+    argument_value(args, name)?
+        .map(|value| {
+            value
+                .parse::<f32>()
+                .map_err(|_| format!("{name} requires a number, got {value:?}"))
+        })
+        .transpose()
+        .map(|value| value.unwrap_or(default))
+}
+
 fn extract_items_json(
     pdf_path: &str,
     page_filter: Option<&HashSet<u32>>,
@@ -242,6 +375,12 @@ fn main() {
         eprintln!("  --password PW       Password for an encrypted PDF");
         eprintln!("  --detect-only       Only detect PDF type (no extraction)");
         eprintln!("  --analyze           Detect + extract + layout analysis (no markdown)");
+        eprintln!("  --ocr MODE          OCR mode: off, auto, or force (requires feature `ocr`)");
+        eprintln!("  --ocr-dpi N         OCR render resolution (default: 150)");
+        eprintln!("  --ocr-min-confidence N  Drop OCR spans below N (default: 0)");
+        eprintln!("  --ocr-hosted-threshold N  Recommend hosted parsing below N (default: 0.5)");
+        eprintln!("  --ocr-model-dir DIR Use a package-managed local model directory");
+        eprintln!("  --ocr-offline       Never download missing OCR models");
         process::exit(1);
     }
 
@@ -253,6 +392,10 @@ fn main() {
     let page_numbers = args.iter().any(|a| a == "--pages");
     let detect_only = args.iter().any(|a| a == "--detect-only");
     let analyze = args.iter().any(|a| a == "--analyze");
+    let ocr_mode_argument = argument_value(&args, "--ocr").unwrap_or_else(|error| {
+        eprintln!("Error: {error}");
+        process::exit(1);
+    });
 
     // Parse --password value
     let password = args.iter().position(|a| a == "--password").map(|i| {
@@ -283,6 +426,141 @@ fn main() {
             })
         });
 
+    let output_file = args
+        .get(2)
+        .filter(|a| !a.starts_with("--"))
+        .map(|s| s.as_str());
+
+    let has_ocr_only_option = [
+        "--ocr-dpi",
+        "--ocr-min-confidence",
+        "--ocr-hosted-threshold",
+        "--ocr-model-dir",
+        "--ocr-offline",
+    ]
+    .iter()
+    .any(|option| args.iter().any(|argument| argument == option));
+    if ocr_mode_argument.is_none() && has_ocr_only_option {
+        eprintln!("Error: OCR options require --ocr off, --ocr auto, or --ocr force");
+        process::exit(1);
+    }
+
+    if let Some(mode) = ocr_mode_argument {
+        if items_json_output || detect_only || analyze {
+            eprintln!(
+                "Error: --ocr cannot be combined with --items-json, --detect-only, or --analyze"
+            );
+            process::exit(1);
+        }
+
+        #[cfg(not(all(feature = "ocr", not(target_arch = "wasm32"))))]
+        {
+            let _ = mode;
+            eprintln!("Error: this pdf2md build does not include OCR; rebuild with --features ocr");
+            process::exit(1);
+        }
+
+        #[cfg(all(feature = "ocr", not(target_arch = "wasm32")))]
+        {
+            let mode = match mode {
+                "off" => OcrMode::Off,
+                "auto" => OcrMode::Auto,
+                "force" => OcrMode::Force,
+                value => {
+                    eprintln!("Error: invalid --ocr mode {value:?}; expected off, auto, or force");
+                    process::exit(1);
+                }
+            };
+            let dpi = float_argument(&args, "--ocr-dpi", 150.0).unwrap_or_else(|error| {
+                eprintln!("Error: {error}");
+                process::exit(1);
+            });
+            let minimum_confidence = float_argument(&args, "--ocr-min-confidence", 0.0)
+                .unwrap_or_else(|error| {
+                    eprintln!("Error: {error}");
+                    process::exit(1);
+                });
+            let hosted_threshold = float_argument(&args, "--ocr-hosted-threshold", 0.5)
+                .unwrap_or_else(|error| {
+                    eprintln!("Error: {error}");
+                    process::exit(1);
+                });
+            let model_directory =
+                argument_value(&args, "--ocr-model-dir").unwrap_or_else(|error| {
+                    eprintln!("Error: {error}");
+                    process::exit(1);
+                });
+
+            let mut ocr = OcrOptions::new()
+                .mode(mode)
+                .minimum_confidence(minimum_confidence);
+            if let Some(directory) = model_directory {
+                ocr = ocr.model_directory(directory);
+            }
+            if args.iter().any(|argument| argument == "--ocr-offline") {
+                ocr = ocr.model_downloads(ModelDownloadPolicy::Offline);
+            }
+            let mut markdown = pdf_inspector::MarkdownOptions::default();
+            if compact_output {
+                markdown.profile = pdf_inspector::MarkdownProfile::Compact;
+            }
+            markdown.include_page_numbers = page_numbers;
+            let mut pdf_options = OcrPdfOptions::new()
+                .render(RenderOptions::new().dpi(dpi))
+                .ocr(ocr)
+                .markdown(markdown)
+                .hosted_recommendation_confidence(hosted_threshold);
+            if let Some(pages) = page_filter.clone() {
+                pdf_options = pdf_options.pages(pages);
+            }
+            if let Some(password) = password.clone() {
+                pdf_options = pdf_options.password(password);
+            }
+
+            match process_pdf_with_ocr(pdf_path, pdf_options) {
+                Ok(result) => {
+                    if json_output {
+                        println!("{}", format_ocr_json(&result));
+                    } else if raw_output {
+                        print!("{}", result.markdown);
+                    } else {
+                        eprintln!("PDF to Markdown Conversion (OCR)");
+                        eprintln!("======================================");
+                        eprintln!("File: {pdf_path}");
+                        eprintln!("Pages: {}", result.page_count);
+                        eprintln!("Pages routed to OCR: {:?}", result.pages_routed_to_ocr);
+                        if !result.pages_recommending_hosted.is_empty() {
+                            eprintln!(
+                                "Hosted parsing recommended for pages: {:?}",
+                                result.pages_recommending_hosted
+                            );
+                        }
+                        eprintln!("Processing time: {}ms", result.processing_time_ms);
+                        if let Some(output) = output_file {
+                            fs::write(output, &result.markdown)
+                                .expect("Failed to write output file");
+                            eprintln!("Markdown written to: {output}");
+                        } else {
+                            eprintln!();
+                            eprintln!("--- Markdown Output ---");
+                            eprintln!();
+                            print!("{}", result.markdown);
+                        }
+                    }
+                }
+                Err(error) => {
+                    if json_output {
+                        println!(r#"{{"error":"{}"}}"#, json_escape(&error.to_string()));
+                    } else {
+                        eprintln!("Error: {error}");
+                    }
+                    process::exit(1);
+                }
+            }
+            return;
+        }
+    }
+
     if items_json_output {
         match extract_items_json(pdf_path, page_filter.as_ref(), password.as_deref()) {
             Ok(json) => println!("{}", json),
@@ -294,11 +572,6 @@ fn main() {
         return;
     }
 
-    let output_file = args
-        .get(2)
-        .filter(|a| !a.starts_with("--"))
-        .map(|s| s.as_str());
-
     let process_mode = if detect_only {
         ProcessMode::DetectOnly
     } else if analyze {

src/lib.rs

@@ -459,8 +459,44 @@ pub fn extract_pages_markdown_mem(
     buffer: &[u8],
     pages: Option<&[u32]>,
 ) -> Result<PagesExtractionResult, PdfError> {
+    extract_pages_markdown_mem_impl(
+        buffer,
+        pages,
+        None,
+        &MarkdownOptions::default(),
+        false,
+        false,
+    )
+    .map(|(result, _)| result)
+}
+
+#[cfg(all(feature = "ocr", not(target_arch = "wasm32")))]
+pub(crate) fn extract_pages_markdown_mem_for_ocr(
+    buffer: &[u8],
+    pages: Option<&[u32]>,
+    password: Option<&str>,
+    markdown_options: &MarkdownOptions,
+) -> Result<(PagesExtractionResult, u32), PdfError> {
+    extract_pages_markdown_mem_impl(
+        buffer,
+        pages,
+        password,
+        markdown_options,
+        markdown_options.strip_headers_footers,
+        true,
+    )
+}
+
+fn extract_pages_markdown_mem_impl(
+    buffer: &[u8],
+    pages: Option<&[u32]>,
+    password: Option<&str>,
+    markdown_options: &MarkdownOptions,
+    strip_repeated_headers_footers: bool,
+    preserve_ocr_candidates: bool,
+) -> Result<(PagesExtractionResult, u32), PdfError> {
     validate_pdf_bytes(buffer)?;
-    let (doc, page_count) = load_document_from_mem(buffer)?;
+    let (doc, page_count) = load_document_from_mem_with_password(buffer, password)?;
     let font_cmaps = FontCMaps::from_doc(&doc);
 
     // Extract ALL pages to get accurate, document-wide font stats. A malformed
@@ -503,6 +539,11 @@ pub fn extract_pages_markdown_mem(
 
     // Compute font stats from full document (cross-page consistency).
     let font_stats = markdown::analysis::calculate_font_stats_from_items(&filtered_items);
+    let repeated_header_footer_items = if strip_repeated_headers_footers {
+        repeated_header_footer_item_keys(&all_items, &page_thresholds, &chart_regions, page_count)
+    } else {
+        HashSet::new()
+    };
 
     // When caller doesn't specify pages, return every page in document order.
     let all_pages: Vec<u32>;
@@ -538,7 +579,10 @@ pub fn extract_pages_markdown_mem(
         let (page_items, page_number_removal_mask): (Vec<TextItem>, Vec<bool>) = all_items
             .iter()
             .zip(&page_number_removal_mask)
-            .filter(|(item, _)| item.page == page_1idx)
+            .filter(|(item, _)| {
+                item.page == page_1idx
+                    && !repeated_header_footer_items.contains(&HeaderFooterItemKey::from(*item))
+            })
             .map(|(item, remove)| (item.clone(), *remove))
             .unzip();
 
@@ -575,7 +619,7 @@ pub fn extract_pages_markdown_mem(
             base_font_size: Some(font_stats.most_common_size),
             include_page_numbers: false,
             strip_headers_footers: false,
-            ..MarkdownOptions::default()
+            ..markdown_options.clone()
         };
 
         let md = if has_text_quality_issue {
@@ -628,20 +672,143 @@ pub fn extract_pages_markdown_mem(
 
         results.push(PageMarkdown {
             page: page_0idx,
-            markdown: if needs_ocr { String::new() } else { md },
+            // The public native extractor continues to suppress unreliable
+            // text. The OCR orchestrator retains clean partial text
+            // internally so it can compare/fuse it with OCR before deciding
+            // what is safe to return.
+            markdown: if needs_ocr && !preserve_ocr_candidates {
+                String::new()
+            } else {
+                md
+            },
             needs_ocr,
             ocr_reason,
         });
     }
 
-    Ok(PagesExtractionResult {
-        pages: results,
-        pages_with_tables: complexity.pages_with_tables,
-        pages_with_columns: complexity.pages_with_columns,
-        pages_needing_ocr,
-        ocr_reasons_by_page: page_ocr_reasons_vec(ocr_reasons_by_page),
-        is_complex: complexity.is_complex,
-    })
+    Ok((
+        PagesExtractionResult {
+            pages: results,
+            pages_with_tables: complexity.pages_with_tables,
+            pages_with_columns: complexity.pages_with_columns,
+            pages_needing_ocr,
+            ocr_reasons_by_page: page_ocr_reasons_vec(ocr_reasons_by_page),
+            is_complex: complexity.is_complex,
+        },
+        page_count,
+    ))
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Hash)]
+struct HeaderFooterItemKey {
+    page: u32,
+    x: u32,
+    y: u32,
+    text: String,
+}
+
+impl From<&TextItem> for HeaderFooterItemKey {
+    fn from(item: &TextItem) -> Self {
+        Self {
+            page: item.page,
+            x: item.x.to_bits(),
+            y: item.y.to_bits(),
+            text: item.text.clone(),
+        }
+    }
+}
+
+fn repeated_header_footer_item_keys(
+    items: &[TextItem],
+    page_thresholds: &HashMap<u32, f32>,
+    chart_regions: &HashMap<u32, Vec<(f32, f32, f32, f32)>>,
+    page_count: u32,
+) -> HashSet<HeaderFooterItemKey> {
+    let candidates = items
+        .iter()
+        .filter(|item| {
+            matches!(
+                item.item_type,
+                types::ItemType::Text | types::ItemType::FormField
+            )
+        })
+        .cloned()
+        .collect();
+    let lines = extractor::group_prefiltered_items_into_lines_with_thresholds_and_charts(
+        candidates,
+        page_thresholds,
+        &HashSet::new(),
+        chart_regions,
+    );
+    let all_items: HashSet<_> = lines
+        .iter()
+        .flat_map(|line| line.items.iter().map(HeaderFooterItemKey::from))
+        .collect();
+    let kept = markdown::strip_repeated_header_footer_lines(lines, page_count);
+    let kept_items: HashSet<_> = kept
+        .iter()
+        .flat_map(|line| line.items.iter().map(HeaderFooterItemKey::from))
+        .collect();
+    all_items.difference(&kept_items).cloned().collect()
+}
+
+#[cfg(all(test, feature = "ocr", not(target_arch = "wasm32")))]
+mod ocr_header_footer_tests {
+    use super::*;
+
+    fn item(page: u32, text: &str, y: f32) -> TextItem {
+        TextItem {
+            text: text.to_string(),
+            x: 10.0,
+            y,
+            width: 120.0,
+            height: 10.0,
+            font: "Test".to_string(),
+            font_size: 10.0,
+            page,
+            is_bold: false,
+            is_italic: false,
+            is_underline: false,
+            is_strikeout: false,
+            item_type: types::ItemType::Text,
+            mcid: None,
+        }
+    }
+
+    #[test]
+    fn local_pipeline_prefilters_document_wide_repeated_headers() {
+        let mut items = Vec::new();
+        let mut thresholds = HashMap::new();
+        for page in 1..=3 {
+            items.push(item(page, "Repeated report header", 800.0));
+            for line in 0..12 {
+                items.push(item(
+                    page,
+                    &format!("Page {page} paragraph {line} unique content"),
+                    700.0 - line as f32 * 40.0,
+                ));
+            }
+            thresholds.insert(page, 0.1);
+        }
+
+        let removed = repeated_header_footer_item_keys(&items, &thresholds, &HashMap::new(), 3);
+        assert_eq!(removed.len(), 2);
+        for page in 1..=3 {
+            assert_eq!(
+                removed.contains(&HeaderFooterItemKey::from(&item(
+                    page,
+                    "Repeated report header",
+                    800.0,
+                ))),
+                page > 1,
+            );
+            assert!(!removed.contains(&HeaderFooterItemKey::from(&item(
+                page,
+                &format!("Page {page} paragraph 5 unique content"),
+                500.0,
+            ))));
+        }
+    }
 }
 
 /// Path-based wrapper for [`extract_pages_markdown_mem`].

src/markdown/mod.rs

@@ -1144,6 +1144,14 @@ pub fn to_markdown(text: &str, options: MarkdownOptions) -> String {
     output
 }
 
+/// Applies the document-wide repeated header/footer classifier to grouped lines.
+pub(crate) fn strip_repeated_header_footer_lines(
+    lines: Vec<crate::types::TextLine>,
+    page_count: u32,
+) -> Vec<crate::types::TextLine> {
+    preprocess::strip_repeated_lines(lines, page_count)
+}
+
 /// Convert positioned text items to markdown with structure detection
 pub fn to_markdown_from_items(items: Vec<TextItem>, options: MarkdownOptions) -> String {
     to_markdown_from_items_with_rects(items, options, &[])

src/tables/format.rs

@@ -442,6 +442,16 @@ fn clean_table_cells(cells: &[Vec<String>]) -> (Vec<Vec<String>>, Vec<String>) {
 fn is_footnote_row(text: &str) -> bool {
     let trimmed = text.trim();
 
+    // Japanese documents commonly use the reference mark followed by an
+    // ASCII or full-width number (for example `※1` / `※１`). These rows often
+    // sit immediately below a wide table and must not be merged into its last
+    // data row as wrapped first-column content.
+    if let Some(rest) = trimmed.strip_prefix('※') {
+        return rest.chars().next().is_some_and(|character| {
+            character.is_ascii_digit() || ('０'..='９').contains(&character)
+        });
+    }
+
     // Check for common footnote patterns
     // (1), (2), etc.
     if trimmed.starts_with('(') && trimmed.len() >= 2 {
@@ -503,6 +513,13 @@ mod tests {
         assert!(is_footnote_row("NOTES: uppercase"));
     }
 
+    #[test]
+    fn test_is_footnote_row_reference_mark_number() {
+        assert!(is_footnote_row("※1 explanation"));
+        assert!(is_footnote_row("※１ 説明"));
+        assert!(!is_footnote_row("※ general marker"));
+    }
+
     #[test]
     fn test_is_footnote_row_plain_text_false() {
         assert!(!is_footnote_row("Regular cell text"));

src/vision/mod.rs

@@ -12,10 +12,14 @@
 mod contracts;
 #[cfg(all(feature = "model-download", not(target_arch = "wasm32")))]
 mod download;
+#[cfg(all(feature = "vision", not(target_arch = "wasm32")))]
+mod fusion;
 #[cfg(all(feature = "model-cache", not(target_arch = "wasm32")))]
 mod models;
 #[cfg(all(feature = "ocr-oar", not(target_arch = "wasm32")))]
 mod oar;
+#[cfg(all(feature = "ocr", not(target_arch = "wasm32")))]
+mod pipeline;
 #[cfg(all(feature = "vision", not(target_arch = "wasm32")))]
 mod render;
 #[cfg(all(feature = "vision", not(target_arch = "wasm32")))]
@@ -32,6 +36,11 @@ pub use contracts::{
 };
 #[cfg(all(feature = "model-download", not(target_arch = "wasm32")))]
 pub use download::{HttpModelDownloadError, HttpModelDownloader, DEFAULT_MODEL_DOWNLOAD_TIMEOUT};
+#[cfg(all(feature = "vision", not(target_arch = "wasm32")))]
+pub use fusion::{
+    fuse_ocr_pages, ocr_page_to_markdown, FusedPageMarkdown, FusedPages, OcrFusionError,
+    OcrFusionOptions,
+};
 #[cfg(all(feature = "model-cache", not(target_arch = "wasm32")))]
 pub use models::{
     ModelAcquireError, ModelArtifact, ModelArtifactKind, ModelDownloader, ModelManifest,
@@ -39,9 +48,14 @@ pub use models::{
 };
 #[cfg(all(feature = "ocr-oar", not(target_arch = "wasm32")))]
 pub use oar::{OarOcrEngine, OarOcrError, ONNX_RUNTIME_LIBRARY_ENV};
+#[cfg(all(feature = "ocr", not(target_arch = "wasm32")))]
+pub use pipeline::{
+    process_pdf_with_ocr, process_pdf_with_ocr_mem, OcrPdfOptions, OcrPdfResult, OcrPipelineError,
+};
 #[cfg(all(feature = "vision", not(target_arch = "wasm32")))]
 pub use render::{
     PagePoint, PageTransform, RenderBufferError, RenderOptions, RenderPixelFormat, RenderedPage,
+    DEFAULT_RENDER_DPI,
 };
 #[cfg(all(feature = "vision", not(target_arch = "wasm32")))]
 pub use routing::{

src/vision/models.rs

@@ -190,16 +190,17 @@ impl ModelStore {
         &self.cache_root
     }
 
+    /// Effective directory containing one manifest's artifacts.
+    pub(crate) fn model_root(&self, manifest: &ModelManifest) -> PathBuf {
+        self.override_root
+            .clone()
+            .unwrap_or_else(|| self.manifest_cache_root(manifest))
+    }
+
     /// Validates and resolves every required artifact.
     pub fn resolve(&self, manifest: &ModelManifest) -> Result<ModelPaths, ModelStoreError> {
         validate_manifest(manifest)?;
-        let managed_root;
-        let root = if let Some(root) = self.override_root.as_deref() {
-            root
-        } else {
-            managed_root = self.manifest_cache_root(manifest);
-            managed_root.as_path()
-        };
+        let root = self.model_root(manifest);
 
         let mut artifacts = BTreeMap::new();
         for artifact in manifest.artifacts {

src/vision/oar.rs

@@ -4,6 +4,7 @@ use std::path::PathBuf;
 use std::time::Instant;
 
 use image::RgbImage;
+use oar_ocr::core::config::onnx::OrtSessionConfig;
 use oar_ocr::oarocr::{OAROCRBuilder, OAROCR};
 use oar_ocr::processors::BoundingBox;
 use thiserror::Error;
@@ -86,7 +87,13 @@ impl OarOcrEngine {
         let recognition = required_model(models, ModelArtifactKind::TextRecognition)?;
         let dictionary = required_model(models, ModelArtifactKind::CharacterDictionary)?;
 
-        let pipeline = OAROCRBuilder::new(detection, recognition, dictionary).build()?;
+        let pipeline = OAROCRBuilder::new(detection, recognition, dictionary)
+            .ort_session(ocr_session_config())
+            // Document line crops often have very different widths. Keeping
+            // CPU recognition batches at one avoids padding every crop to the
+            // widest line, reducing both inference work and peak memory.
+            .region_batch_size(1)
+            .build()?;
         let model = ModelIdentity::new(models.manifest_id(), models.revision());
         Ok(Self { pipeline, model })
     }
@@ -169,11 +176,18 @@ impl OarOcrEngine {
     }
 }
 
+fn ocr_session_config() -> OrtSessionConfig {
+    let available = std::thread::available_parallelism()
+        .map(std::num::NonZeroUsize::get)
+        .unwrap_or(1);
+    OrtSessionConfig::new()
+        .with_intra_threads(available.min(4))
+        .with_inter_threads(1)
+        .with_parallel_execution(false)
+}
+
 fn load_onnx_runtime() -> Result<(), OarOcrError> {
-    let path = std::env::var_os(ONNX_RUNTIME_LIBRARY_ENV)
-        .filter(|path| !path.is_empty())
-        .map(PathBuf::from)
-        .unwrap_or_else(default_onnx_runtime_library);
+    let path = onnx_runtime_library_path();
     drop(
         ort::init_from(&path).map_err(|source| OarOcrError::OnnxRuntimeLoad {
             path: path.clone(),
@@ -183,6 +197,13 @@ fn load_onnx_runtime() -> Result<(), OarOcrError> {
     Ok(())
 }
 
+pub(crate) fn onnx_runtime_library_path() -> PathBuf {
+    std::env::var_os(ONNX_RUNTIME_LIBRARY_ENV)
+        .filter(|path| !path.is_empty())
+        .map(PathBuf::from)
+        .unwrap_or_else(default_onnx_runtime_library)
+}
+
 fn default_onnx_runtime_library() -> PathBuf {
     #[cfg(target_os = "windows")]
     const NAME: &str = "onnxruntime.dll";
@@ -355,6 +376,14 @@ mod tests {
     use super::*;
     use crate::vision::PageTransform;
 
+    #[test]
+    fn cpu_session_budget_is_bounded_for_small_ocr_models() {
+        let config = ocr_session_config();
+        assert!((1..=4).contains(&config.intra_threads.unwrap()));
+        assert_eq!(config.inter_threads, Some(1));
+        assert_eq!(config.parallel_execution, Some(false));
+    }
+
     fn page(format: RenderPixelFormat, stride: usize, pixels: Vec<u8>) -> RenderedPage {
         let transform =
             PageTransform::from_corners(2, 2, (0.0, 2.0), (2.0, 2.0), (0.0, 0.0)).unwrap();

src/vision/pdfium.rs

@@ -2,9 +2,11 @@
 
 use std::path::Path;
 
-use firecrawl_pdfium::{Pdfium, PixelFormat, PixelPoint, RenderConfig};
+use firecrawl_pdfium::{PageChar, Pdfium, PixelFormat, PixelPoint, RenderConfig};
 use thiserror::Error;
 
+use crate::types::{ItemType, TextItem};
+
 use super::{
     PageRenderer, PageTransform, RenderBufferError, RenderOptions, RenderPixelFormat, RenderedPage,
 };
@@ -65,6 +67,15 @@ pub struct PdfiumRenderer {
     pdfium: Pdfium,
 }
 
+/// Positioned native text recovered from one selected PDF page.
+#[derive(Debug)]
+pub(crate) struct PdfiumTextPage {
+    pub(crate) page: u32,
+    pub(crate) page_width: f32,
+    pub(crate) page_height: f32,
+    pub(crate) items: Vec<TextItem>,
+}
+
 impl PdfiumRenderer {
     /// Loads PDFium using `firecrawl-pdfium`'s documented discovery chain.
     pub fn load() -> Result<Self, RenderError> {
@@ -100,6 +111,56 @@ impl PdfiumRenderer {
         self.render_pages_impl(pdf_bytes, pages, password, options)
     }
 
+    /// Extracts positioned native text from selected 1-indexed pages.
+    ///
+    /// This is deliberately separate from rendering: callers can probe a
+    /// suspicious embedded text layer before paying for rasterization and
+    /// OCR. A page-level text failure is treated as an unavailable recovery
+    /// candidate so the caller can continue to its normal OCR fallback.
+    pub(crate) fn extract_text_pages(
+        &self,
+        pdf_bytes: &[u8],
+        pages: &[u32],
+        password: Option<&str>,
+    ) -> Result<Vec<PdfiumTextPage>, RenderError> {
+        const MAX_TEXT_CHARS_PER_PAGE: usize = 250_000;
+
+        if pages.is_empty() {
+            return Ok(Vec::new());
+        }
+        if pages.contains(&0) {
+            return Err(RenderError::InvalidPageNumber);
+        }
+
+        let document = self.pdfium.load_document(pdf_bytes.to_vec(), password)?;
+        let page_count = document.page_count();
+        if let Some(&page) = pages.iter().find(|&&page| page as usize > page_count) {
+            return Err(RenderError::PageOutOfBounds { page, page_count });
+        }
+
+        let mut recovered = Vec::with_capacity(pages.len());
+        for &page_number in pages {
+            let page = document.page(page_number as usize - 1)?;
+            let page_size = page.size();
+            let text = match page.text_with_limit(MAX_TEXT_CHARS_PER_PAGE) {
+                Ok(text) => text,
+                Err(error) => {
+                    log::debug!(
+                        "page {page_number}: positioned native text recovery unavailable: {error}"
+                    );
+                    continue;
+                }
+            };
+            recovered.push(PdfiumTextPage {
+                page: page_number,
+                page_width: page_size.width,
+                page_height: page_size.height,
+                items: text_chars_to_items(text.chars(), page_number),
+            });
+        }
+        Ok(recovered)
+    }
+
     fn render_pages_impl(
         &self,
         pdf_bytes: &[u8],
@@ -145,6 +206,106 @@ impl PdfiumRenderer {
     }
 }
 
+fn text_chars_to_items(chars: &[PageChar], page: u32) -> Vec<TextItem> {
+    #[derive(Debug, Clone, Copy)]
+    struct Bounds {
+        left: f64,
+        bottom: f64,
+        right: f64,
+        top: f64,
+    }
+
+    fn flush(items: &mut Vec<TextItem>, text: &mut String, bounds: &mut Option<Bounds>, page: u32) {
+        let Some(bounds) = bounds.take() else {
+            text.clear();
+            return;
+        };
+        if text.is_empty() {
+            return;
+        }
+        let width = (bounds.right - bounds.left) as f32;
+        let height = (bounds.top - bounds.bottom) as f32;
+        let x = bounds.left as f32;
+        let y = bounds.bottom as f32;
+        if !x.is_finite()
+            || !y.is_finite()
+            || !width.is_finite()
+            || !height.is_finite()
+            || width <= 0.0
+            || height <= 0.0
+        {
+            text.clear();
+            return;
+        }
+        items.push(TextItem {
+            text: std::mem::take(text),
+            x,
+            y,
+            width,
+            height,
+            font: "PDFium native text".to_string(),
+            font_size: height.max(1.0),
+            page,
+            is_bold: false,
+            is_italic: false,
+            is_underline: false,
+            is_strikeout: false,
+            item_type: ItemType::Text,
+            mcid: None,
+        });
+    }
+
+    let mut items = Vec::new();
+    let mut text = String::new();
+    let mut bounds: Option<Bounds> = None;
+    for character in chars {
+        let Some(value) = character.unicode else {
+            flush(&mut items, &mut text, &mut bounds, page);
+            continue;
+        };
+        if value.is_whitespace() {
+            flush(&mut items, &mut text, &mut bounds, page);
+            continue;
+        }
+
+        let rect = character.loose_bounds.normalized();
+        if !rect.left.is_finite()
+            || !rect.bottom.is_finite()
+            || !rect.right.is_finite()
+            || !rect.top.is_finite()
+            || rect.width() <= 0.0
+            || rect.height() <= 0.0
+        {
+            flush(&mut items, &mut text, &mut bounds, page);
+            continue;
+        }
+        text.push(value);
+        bounds = Some(match bounds {
+            Some(bounds) => Bounds {
+                left: bounds.left.min(rect.left),
+                bottom: bounds.bottom.min(rect.bottom),
+                right: bounds.right.max(rect.right),
+                top: bounds.top.max(rect.top),
+            },
+            None => Bounds {
+                left: rect.left,
+                bottom: rect.bottom,
+                right: rect.right,
+                top: rect.top,
+            },
+        });
+    }
+    flush(&mut items, &mut text, &mut bounds, page);
+    items.sort_by(|first, second| {
+        first
+            .page
+            .cmp(&second.page)
+            .then(second.y.total_cmp(&first.y))
+            .then(first.x.total_cmp(&second.x))
+    });
+    items
+}
+
 impl PageRenderer for PdfiumRenderer {
     type Error = RenderError;
 
@@ -237,6 +398,17 @@ fn bgr_to_rgb_in_place(
 #[cfg(test)]
 mod tests {
     use super::*;
+    use firecrawl_pdfium::{PagePoint, PageRect};
+
+    fn page_char(value: char, bounds: PageRect) -> PageChar {
+        PageChar {
+            unicode: Some(value),
+            code: value as u32,
+            bounds,
+            loose_bounds: bounds,
+            origin: PagePoint::new(bounds.left, bounds.bottom),
+        }
+    }
 
     #[test]
     fn bgr_pixels_are_converted_to_rgb_in_place() {
@@ -263,4 +435,34 @@ mod tests {
             Err(RenderBufferError::InvalidBufferLength { .. })
         ));
     }
+
+    #[test]
+    fn invalid_character_geometry_splits_text_runs() {
+        let chars = [
+            page_char('A', PageRect::new(0.0, 0.0, 8.0, 10.0)),
+            page_char('X', PageRect::new(10.0, 0.0, 10.0, 10.0)),
+            page_char('B', PageRect::new(20.0, 0.0, 28.0, 10.0)),
+        ];
+
+        let items = text_chars_to_items(&chars, 1);
+
+        assert_eq!(
+            items
+                .iter()
+                .map(|item| item.text.as_str())
+                .collect::<Vec<_>>(),
+            ["A", "B"]
+        );
+    }
+
+    #[test]
+    fn coordinates_that_overflow_f32_are_discarded() {
+        let left = f64::from(f32::MAX) * 2.0;
+        let chars = [page_char(
+            'A',
+            PageRect::new(left, 0.0, left + 1.0e30, 10.0),
+        )];
+
+        assert!(text_chars_to_items(&chars, 1).is_empty());
+    }
 }

tests/ocr_tests.rs

@@ -1,5 +1,10 @@
 #![cfg(all(feature = "ocr-oar", not(target_arch = "wasm32")))]
 
+#[cfg(feature = "ocr")]
+use pdf_inspector::vision::{
+    process_pdf_with_ocr_mem, ModelDownloadPolicy, OcrPdfOptions, OcrPipelineError,
+    PageContentSource,
+};
 use pdf_inspector::vision::{
     ModelStore, OarOcrEngine, OcrEngine, OcrMode, OcrOptions, PageTransform, RenderPixelFormat,
     RenderedPage, PP_OCR_V6_SMALL,
@@ -100,6 +105,90 @@ fn recognizes_a_pdfium_rendered_fixture_with_verified_models() {
     assert_usable_result(&results);
 }
 
+#[cfg(all(feature = "ocr", feature = "render-pdfium"))]
+#[test]
+fn complete_ocr_pipeline_routes_and_assembles_a_scanned_fixture() {
+    let Some(model_directory) = std::env::var_os(MODEL_DIRECTORY_ENV) else {
+        eprintln!("skipping OCR runtime test because {MODEL_DIRECTORY_ENV} is not set");
+        return;
+    };
+    let Some(_renderer) = load_renderer() else {
+        return;
+    };
+
+    let bytes = std::fs::read("tests/fixtures/scan_with_native_header_text.pdf").unwrap();
+    let ocr = OcrOptions::new()
+        .mode(OcrMode::Auto)
+        .minimum_confidence(0.3)
+        .model_directory(model_directory)
+        .model_downloads(ModelDownloadPolicy::Offline);
+    let options = OcrPdfOptions::new().ocr(ocr);
+    let result = process_pdf_with_ocr_mem(&bytes, options.clone()).unwrap();
+    let repeated = process_pdf_with_ocr_mem(&bytes, options).unwrap();
+
+    assert_eq!(result.pages_routed_to_ocr, vec![1]);
+    assert!(!result.markdown.trim().is_empty());
+    assert!(result
+        .markdown
+        .contains("Order Date Item Code Description Status Unit Cost\n\n03/14/2024"));
+    assert!(result.markdown.contains("$482,110.40\n\n05/02/2024"));
+    assert_eq!(result.pages[0].provenance.source, PageContentSource::Fused);
+    assert!(result.pages[0]
+        .provenance
+        .warnings
+        .iter()
+        .any(|warning| warning.contains("complementary OCR")));
+    assert_eq!(
+        result.pages[0].provenance.ocr_model.as_ref().unwrap().name,
+        PP_OCR_V6_SMALL.id
+    );
+    assert_eq!(repeated.markdown, result.markdown);
+}
+
+#[cfg(all(feature = "ocr", feature = "render-pdfium"))]
+#[test]
+fn auto_recovers_credible_native_text_before_loading_ocr_models() {
+    let Some(_renderer) = load_renderer() else {
+        return;
+    };
+
+    let bytes = std::fs::read("tests/fixtures/shinagawa_identity_h.pdf").unwrap();
+    let ocr = OcrOptions::new()
+        .mode(OcrMode::Auto)
+        .model_directory("/models/must-not-be-read")
+        .model_downloads(ModelDownloadPolicy::Offline);
+    let result = process_pdf_with_ocr_mem(&bytes, OcrPdfOptions::new().ocr(ocr)).unwrap();
+
+    assert_eq!(result.pages_recommended_for_ocr, vec![1]);
+    assert!(result.pages_routed_to_ocr.is_empty());
+    assert!(result.markdown.contains("羽田空港新飛行経路"));
+    assert!(result.markdown.contains("|4月30日|有|81.0|"));
+    assert!(result.markdown.contains("※１ 最大騒音レベル"));
+    assert!(result.pages_with_tables.contains(&1));
+    assert_eq!(result.pages[0].provenance.source, PageContentSource::Native);
+    assert!(result.pages[0].provenance.ocr_model.is_none());
+}
+
+#[cfg(all(feature = "ocr", feature = "render-pdfium"))]
+#[test]
+fn auto_rejects_garbled_native_recovery_and_continues_to_ocr() {
+    let Some(_renderer) = load_renderer() else {
+        return;
+    };
+
+    let bytes = std::fs::read("tests/fixtures/shifted_cipher_tounicode.pdf").unwrap();
+    let ocr = OcrOptions::new()
+        .mode(OcrMode::Auto)
+        .model_directory("/models/must-not-be-read")
+        .model_downloads(ModelDownloadPolicy::Offline);
+    let error = process_pdf_with_ocr_mem(&bytes, OcrPdfOptions::new().ocr(ocr)).unwrap_err();
+
+    assert!(matches!(
+        error,
+        OcrPipelineError::ModelAcquire(_) | OcrPipelineError::ModelStore(_)
+    ));
+}
+
 fn recognize(
     model_directory: &std::ffi::OsStr,
     pages: &[RenderedPage],