refactor(vision): use OCR terminology

Justified print breaks words at syllables; after paragraph lines are joined
with spaces those breaks survive as "de- fendant" — thousands of them in a
long document — and, when an emphasis span was split with the word, as
"Bap-** **tist".

Whether the hyphen belongs in the word cannot be decided locally ("de-
fendant" is one word, "Third- Party" is a hyphenated compound), so the
document is used as its own dictionary. For each break:

  1. fragments appear joined elsewhere ("defendant")      -> join plain
  2. appear hyphenated elsewhere ("six-month"), or the
     continuation is capitalized ("Hinds- Radix")         -> keep the hyphen
  3. both fragments are words the document uses and the
     continuation has 4+ letters ("commercial- type")     -> keep the hyphen
  4. no evidence                                          -> leave untouched

The policy contains zero hard-coded words: vocabulary evidence,
capitalization, and two length invariants. The 4-letter floor keeps
suspended hyphens intact in any language ("mid- and long-term", "klein- und
mittelgroß", "kuva- tai video") because conjunctions are near-universally
1-3 letters. Fragments over 40 combined characters are fused reading-order
noise and are never joined. The vocabulary is collected after scrubbing the
break pairs themselves and excludes fenced code blocks; table rows and code
blocks are never rewritten. Split emphasis spans rejoin inside their
markers. Runs under the existing fix_hyphenation option (default on).

On a 1,370-page justified legal reporter this rejoins ~8,000 broken words
(98.8% of breaks; evidence-less ones stay visibly intact); word recall
against a reference extraction rises from 97.8% to 99.1%. No "six-month" ->
"sixmonth" class errors, and no fused-column corruption by construction:
no rule joins without evidence.

Regression-checked against a ~200-document corpus with semantic scoring
against an OCR baseline: zero regressions. Three in-repo fixture snapshots
regenerated with each diff inspected. 17 unit tests cover every rule, the
vocabulary scrubbing and code-block exclusion, the length gates, chained
breaks, mismatched emphasis markers, accented and Cyrillic words, German
and Finnish suspended hyphens, and the table/code skips.

Cargo.toml

@@ -49,6 +49,17 @@ ttf-parser = "0.25"
 lopdf = { version = "0.42.0", features = ["rayon"] }
 rayon = "1.10"
 env_logger = "0.11"
+# Optional native page rendering for OCR pipelines. PDFium is loaded at
+# runtime, so enabling this feature does not link or download a native library.
+firecrawl-pdfium = { version = "0.1.0", optional = true }
+# Small support crates used only by the opt-in model cache. Model files remain
+# external and are never embedded in pdf-inspector artifacts.
+dirs = { version = "6.0", optional = true }
+fs2 = { version = "0.4", optional = true }
+sha2 = { version = "0.11", optional = true }
+
+[target.'cfg(all(windows, not(target_arch = "wasm32")))'.dependencies]
+windows-sys = { version = "0.61", features = ["Win32_Storage_FileSystem"], optional = true }
 
 # Browser builds use JavaScript randomness for encrypted PDFs and embed the
 # bundled CMaps because there is no filesystem at runtime.
@@ -62,6 +73,9 @@ tempfile = "3.3"
 [features]
 default = []
 python = ["pyo3"]
+vision = []
+model-cache = ["vision", "dep:dirs", "dep:fs2", "dep:sha2", "dep:windows-sys"]
+render-pdfium = ["vision", "dep:firecrawl-pdfium"]
 
 [[bin]]
 name = "pdf2md"

docs/rust-api.md

@@ -1,6 +1,6 @@
 # pdf-inspector
 
-Fast PDF classification and text extraction. Detects whether a PDF is text-based or scanned, extracts text with position awareness, and converts to clean Markdown — all without OCR. Pure Rust, no ML models, no external services; the only PDF dependency is [lopdf](https://crates.io/crates/lopdf). Also available for [Python](https://pypi.org/project/pdf-inspector/) and [Node.js](https://www.npmjs.com/package/@firecrawl/pdf-inspector).
+Fast PDF classification and text extraction. Detects whether a PDF is text-based or scanned, extracts text with position awareness, and converts to clean Markdown — all without OCR. The default build is pure Rust, has no ML models or external services, and uses [lopdf](https://crates.io/crates/lopdf) for PDF parsing. Also available for [Python](https://pypi.org/project/pdf-inspector/) and [Node.js](https://www.npmjs.com/package/@firecrawl/pdf-inspector/).
 
 Built by [Firecrawl](https://firecrawl.dev) to handle text-based PDFs locally in under 200ms, skipping expensive OCR services for the ~54% of PDFs that don't need them.
 
@@ -117,6 +117,86 @@ let bytes = std::fs::read("document.pdf")?;
 let result = process_pdf_mem(&bytes)?;
 ```
 
+### Vision extension contracts
+
+The native-only `vision` feature exposes the stable seam used by OCR
+integrations without selecting or embedding an inference runtime. The
+separate `model-cache` feature adds pinned artifact management:
+
+- `PageRenderer`, `OcrEngine`, and `LayoutEngine` traits;
+- renderer-neutral owned page buffers and affine pixel↔PDF transforms;
+- `OcrOptions` and opt-in `Off`/`Auto`/`Force` routing modes;
+- positioned OCR/layout results and per-page provenance types; and
+- a versioned PP-OCRv6 Small manifest with checksum-verified, locked, atomic
+  model-cache installation and explicit offline-directory overrides.
+
+```toml
+[dependencies]
+pdf-inspector = { version = "1", features = ["vision", "model-cache"] }
+```
+
+The OCR contracts preserve existing behavior by default: OCR is `Off`, learned
+layout is disabled, and model resolution is never reached. `ModelStore` itself
+does not access the network; a runtime integration can fetch a manifest's
+canonical URL only when allowed and pass the stream to `ModelStore::install`.
+Offline consumers set an explicit model directory and `ModelDownloadPolicy::Offline`.
+Renderer-only consumers do not enable `model-cache` and therefore do not compile
+its filesystem, locking, or hashing dependencies.
+
+```rust
+use pdf_inspector::vision::{
+    ModelDownloadPolicy, ModelStore, OcrMode, OcrOptions, PP_OCR_V6_SMALL,
+};
+
+let ocr = OcrOptions::new()
+    .mode(OcrMode::Auto)
+    .model_directory("/opt/firecrawl/models/pp-ocrv6-small")
+    .model_downloads(ModelDownloadPolicy::Offline);
+// Verifies exact sizes and SHA-256 digests before an engine opens the files.
+let models = ModelStore::from_options(&ocr)?.resolve(&PP_OCR_V6_SMALL)?;
+println!("using {} at {}", models.manifest_id(), models.revision());
+```
+
+### Optional native page rendering
+
+The `render-pdfium` feature adds a native-only page renderer backed by
+[`firecrawl-pdfium`](https://crates.io/crates/firecrawl-pdfium). It is the
+rendering boundary for OCR pipelines; enabling it does not include an OCR
+model or change the existing extraction functions. It implies `vision`,
+and `PdfiumRenderer` implements the renderer-neutral `PageRenderer` trait.
+
+```toml
+[dependencies]
+pdf-inspector = { version = "1", features = ["render-pdfium"] }
+```
+
+PDFium is loaded at runtime. Set `PDFIUM_LIB_PATH`, place its shared library
+next to the executable, or use another discovery route supported by
+`firecrawl-pdfium`.
+
+```rust
+use pdf_inspector::vision::{PdfiumRenderer, RenderOptions};
+
+let renderer = PdfiumRenderer::load()?;
+let bytes = std::fs::read("document.pdf")?;
+let pages = renderer.render_pages(
+    &bytes,
+    &[1, 3], // 1-indexed, matching pages_needing_ocr
+    None,    // optional PDF password
+    &RenderOptions::new().dpi(150.0),
+)?;
+
+for page in pages {
+    // Owned RGB pixels can leave the PDFium critical section and be sent to
+    // an OCR worker. OCR pixel boxes can be mapped back to PDF coordinates.
+    let rect = page.pixel_rect_to_pdf_rect(20.0, 30.0, 100.0, 24.0);
+    println!("page {}: {}x{}, rect={rect:?}", page.page(), page.width(), page.height());
+}
+```
+
+Browser WASM remains on the default text-only path and does not expose native
+PDFium rendering.
+
 Extract per-page Markdown (one string per page, plus document-wide layout
 metadata):
 

src/lib.rs

@@ -43,6 +43,7 @@ mod text_quality;
 pub mod text_utils;
 pub mod tounicode;
 pub mod types;
+pub mod vision;
 
 pub use detector::{
     detect_pdf_type, detect_pdf_type_mem, detect_pdf_type_mem_with_config,

src/markdown/mod.rs

@@ -453,6 +453,110 @@ fn merged_retry_skips_body_font(detected_columns: bool, has_chart_regions: bool)
     detected_columns && !has_chart_regions
 }
 
+/// Identity of a piece of page furniture: the same trimmed text drawn at the
+/// same position (quantized to 0.5pt) — page numbers excluded by construction
+/// because their text differs per page.
+type FurnitureKey = (String, i32, i32);
+
+fn furniture_key(item: &TextItem) -> FurnitureKey {
+    (
+        item.text.trim().to_string(),
+        (item.x * 2.0).round() as i32,
+        (item.y * 2.0).round() as i32,
+    )
+}
+
+/// Minimum distinct pages an identical (text, position) must appear on before
+/// it counts as a running header/footer rather than coincidence.
+const RUNNING_FURNITURE_MIN_PAGES: usize = 3;
+
+/// Fraction of each page's vertical content extent, at the top and at the
+/// bottom, where running furniture may live. Repetition alone is not enough:
+/// a form template repeated per record carries identical labels at identical
+/// mid-page coordinates on every page, and those are real table cells. What
+/// makes a header/footer is repetition *at the page edge*.
+const RUNNING_FURNITURE_BAND: f32 = 0.2;
+
+/// Collect the keys of items that repeat verbatim at the same position on at
+/// least [`RUNNING_FURNITURE_MIN_PAGES`] distinct pages, restricted to the
+/// top/bottom [`RUNNING_FURNITURE_BAND`] of each page's content extent —
+/// running headers and footers. Single- and two-page documents produce an
+/// empty set.
+fn running_furniture_keys(items: &[TextItem]) -> HashSet<FurnitureKey> {
+    // Vertical content extent per page, so the edge bands adapt to the
+    // document's real margins instead of assuming a media box.
+    let mut page_extent: HashMap<u32, (f32, f32)> = HashMap::new();
+    for item in items {
+        if item.text.trim().is_empty() {
+            continue;
+        }
+        let entry = page_extent.entry(item.page).or_insert((item.y, item.y));
+        entry.0 = entry.0.min(item.y);
+        entry.1 = entry.1.max(item.y);
+    }
+
+    let mut pages_by_key: HashMap<FurnitureKey, HashSet<u32>> = HashMap::new();
+    for item in items {
+        if item.text.trim().is_empty() {
+            continue;
+        }
+        let Some(&(min_y, max_y)) = page_extent.get(&item.page) else {
+            continue;
+        };
+        // A page whose text has no vertical span gives no evidence of where
+        // its edges are — without this guard, a zero band would classify its
+        // every item as edge furniture.
+        let extent = max_y - min_y;
+        if extent <= 0.0 {
+            continue;
+        }
+        let band = extent * RUNNING_FURNITURE_BAND;
+        if item.y > min_y + band && item.y < max_y - band {
+            continue; // mid-page: never furniture, however often it repeats
+        }
+        pages_by_key
+            .entry(furniture_key(item))
+            .or_default()
+            .insert(item.page);
+    }
+    pages_by_key
+        .into_iter()
+        .filter(|(_, pages)| pages.len() >= RUNNING_FURNITURE_MIN_PAGES)
+        .map(|(key, _)| key)
+        .collect()
+}
+
+/// Reject a heuristic table whose items are almost entirely running
+/// headers/footers. A wrapped document title repeated at the bottom of every
+/// page aligns well enough to read as a grid, but it is page furniture, not
+/// data — vetoing the table lets the text flow as prose instead. Real tables
+/// carry per-page content, so even a repeated *header row* stays under the
+/// threshold once its body rows differ.
+fn is_running_furniture_table(
+    detection_items: &[TextItem],
+    table: &crate::tables::Table,
+    running: &HashSet<FurnitureKey>,
+) -> bool {
+    if running.is_empty() {
+        return false;
+    }
+    let mut total = 0usize;
+    let mut furniture = 0usize;
+    for &idx in &table.item_indices {
+        let Some(item) = detection_items.get(idx) else {
+            continue;
+        };
+        if item.text.trim().is_empty() {
+            continue;
+        }
+        total += 1;
+        if running.contains(&furniture_key(item)) {
+            furniture += 1;
+        }
+    }
+    total > 0 && (furniture as f32) >= (total as f32) * 0.8
+}
+
 /// Reject a heuristic table only when its cells are overwhelmingly parallel
 /// prose fragments. This is deliberately narrower than disabling body-font
 /// detection for the whole page: numeric, compact, headed, and otherwise
@@ -1188,6 +1292,12 @@ pub(crate) fn to_markdown_from_items_with_rects_and_lines(
     let mut table_items: HashSet<usize> = HashSet::new();
     let mut page_tables: HashMap<u32, Vec<PositionedMarkdown>> = HashMap::new();
 
+    // Running headers/footers repeat verbatim at the same position on many
+    // pages. When such a block wraps a long title over aligned lines, the
+    // heuristic detector reads it as a table. Knowing which items are page
+    // furniture is a document-wide question, so answer it once here.
+    let running_furniture = running_furniture_keys(&text_items);
+
     // Pre-group items by page with their global indices (O(n) instead of O(pages*n))
     let mut page_groups: HashMap<u32, Vec<(usize, &TextItem)>> = HashMap::new();
     for (global_idx, item) in text_items.iter().enumerate() {
@@ -1517,6 +1627,15 @@ pub(crate) fn to_markdown_from_items_with_rects_and_lines(
                             );
                             continue;
                         }
+                        if is_running_furniture_table(subset_items, &table, &running_furniture) {
+                            log::debug!(
+                                "page {}: rejected {}x{} running header/footer table hypothesis",
+                                page,
+                                table.rows.len(),
+                                table.columns.len()
+                            );
+                            continue;
+                        }
                         for &idx in &table.item_indices {
                             if let Some(&band_idx) = index_map.get(idx) {
                                 if let Some(&page_idx) = band_index_map.get(band_idx) {
@@ -1703,6 +1822,15 @@ pub(crate) fn to_markdown_from_items_with_rects_and_lines(
                     );
                     continue;
                 }
+                if is_running_furniture_table(&chart_free, table, &running_furniture) {
+                    log::debug!(
+                        "page {}: rejected {}x{} merged-band running header/footer table hypothesis",
+                        page,
+                        table.rows.len(),
+                        table.columns.len()
+                    );
+                    continue;
+                }
                 for &idx in &table.item_indices {
                     if let Some(&page_idx) = chart_free_map
                         .get(idx)
@@ -2058,6 +2186,174 @@ mod tests {
         assert!(md.contains("- Second item"));
     }
 
+    fn furniture_item(text: &str, x: f32, y: f32, page: u32) -> TextItem {
+        let mut it = make_item(x, y, page);
+        it.text = text.into();
+        it
+    }
+
+    /// Items repeating verbatim at the same position on 3+ pages are running
+    /// furniture; the same text on fewer pages, or at different positions, is
+    /// not.
+    #[test]
+    fn running_furniture_requires_three_pages_at_same_position() {
+        let mut items = Vec::new();
+        for page in 1..=3 {
+            // Body content so each page has a real vertical extent.
+            items.push(furniture_item("body", 85.0, 700.0, page));
+            items.push(furniture_item("TITULAR DEL", 85.0, 68.0, page));
+        }
+        // Same text but only two pages.
+        for page in 1..=2 {
+            items.push(furniture_item("SECRETARÍA", 200.0, 68.0, page));
+        }
+        // Same text on three pages but at drifting positions.
+        for (page, x) in [(1, 300.0), (2, 320.0), (3, 340.0)] {
+            items.push(furniture_item("MÉXICO", x, 68.0, page));
+        }
+
+        let running = running_furniture_keys(&items);
+        assert!(running.contains(&furniture_key(&furniture_item(
+            "TITULAR DEL",
+            85.0,
+            68.0,
+            1
+        ))));
+        assert!(!running.contains(&furniture_key(&furniture_item(
+            "SECRETARÍA",
+            200.0,
+            68.0,
+            1
+        ))));
+        assert!(!running.contains(&furniture_key(&furniture_item("MÉXICO", 300.0, 68.0, 1))));
+    }
+
+    /// A table made of running-footer items is vetoed; a table whose body rows
+    /// carry per-page content is kept even when its header row repeats.
+    #[test]
+    fn running_furniture_table_veto() {
+        // The footer block, present identically on pages 1-3.
+        let mut items = Vec::new();
+        for page in 1..=3 {
+            items.push(furniture_item("PROPOSICIÓN CON PUNTO", 85.0, 78.5, page));
+            items.push(furniture_item("EL SENADO", 286.6, 78.5, page));
+            items.push(furniture_item("TITULAR DEL", 85.0, 68.0, page));
+            items.push(furniture_item("A TRAVÉS DE LA", 243.4, 68.0, page));
+        }
+        // A real table on page 1: repeated header row, per-page data rows.
+        let header = [
+            furniture_item("Year", 85.0, 500.0, 1),
+            furniture_item("Total", 200.0, 500.0, 1),
+        ];
+        let data = [
+            furniture_item("2023", 85.0, 488.0, 1),
+            furniture_item("1,204", 200.0, 488.0, 1),
+            furniture_item("2024", 85.0, 476.0, 1),
+            furniture_item("1,377", 200.0, 476.0, 1),
+        ];
+        // Header repeats on every page (like a continued table's header).
+        for page in 2..=3 {
+            items.push(furniture_item("Year", 85.0, 500.0, page));
+            items.push(furniture_item("Total", 200.0, 500.0, page));
+        }
+        items.extend(header.iter().cloned());
+        items.extend(data.iter().cloned());
+
+        let running = running_furniture_keys(&items);
+
+        let table_of = |detection_items: &[TextItem]| crate::tables::Table {
+            columns: vec![],
+            rows: vec![],
+            cells: vec![],
+            item_indices: (0..detection_items.len()).collect(),
+            kind: crate::tables::TableKind::Data,
+        };
+
+        // Footer-only candidate: every item is furniture -> vetoed.
+        let footer_items: Vec<TextItem> = (1..=1)
+            .flat_map(|page| {
+                vec![
+                    furniture_item("PROPOSICIÓN CON PUNTO", 85.0, 78.5, page),
+                    furniture_item("EL SENADO", 286.6, 78.5, page),
+                    furniture_item("TITULAR DEL", 85.0, 68.0, page),
+                    furniture_item("A TRAVÉS DE LA", 243.4, 68.0, page),
+                ]
+            })
+            .collect();
+        assert!(is_running_furniture_table(
+            &footer_items,
+            &table_of(&footer_items),
+            &running
+        ));
+
+        // Real table: header row repeats across pages, body rows do not ->
+        // 2 furniture of 6 items (33%) stays under the 80% threshold.
+        let real_items: Vec<TextItem> =
+            header.iter().cloned().chain(data.iter().cloned()).collect();
+        assert!(!is_running_furniture_table(
+            &real_items,
+            &table_of(&real_items),
+            &running
+        ));
+    }
+
+    /// A form template repeated per record carries identical labels at
+    /// identical mid-page coordinates on every page — those are real table
+    /// cells, not furniture. Only the page-edge bands qualify.
+    #[test]
+    fn mid_page_repetition_is_not_furniture() {
+        let mut items = Vec::new();
+        for page in 1..=4 {
+            // Content spanning the page: y 60 (bottom) to 740 (top).
+            items.push(furniture_item("body top", 85.0, 740.0, page));
+            items.push(furniture_item("body bottom", 85.0, 60.0, page));
+            // Form labels repeated dead centre on every page.
+            items.push(furniture_item("Name of creditor", 85.0, 400.0, page));
+            items.push(furniture_item("Amount of claim", 300.0, 400.0, page));
+            // A genuine footer inside the bottom band.
+            items.push(furniture_item("FORM 78 — page footer", 85.0, 70.0, page));
+        }
+
+        let running = running_furniture_keys(&items);
+        assert!(
+            !running.contains(&furniture_key(&furniture_item(
+                "Name of creditor",
+                85.0,
+                400.0,
+                1
+            ))),
+            "mid-page form labels must not be furniture"
+        );
+        assert!(running.contains(&furniture_key(&furniture_item(
+            "FORM 78 — page footer",
+            85.0,
+            70.0,
+            1
+        ))));
+    }
+
+    #[test]
+    fn running_furniture_empty_on_short_documents() {
+        let mut items = Vec::new();
+        for page in 1..=2 {
+            items.push(furniture_item("body", 85.0, 700.0, page));
+            items.push(furniture_item("FOOTER", 85.0, 68.0, page));
+        }
+        assert!(running_furniture_keys(&items).is_empty());
+    }
+
+    /// A page whose text has no vertical span (a single line) gives no
+    /// evidence of where its edges are; its items never become furniture.
+    #[test]
+    fn zero_span_page_contributes_no_furniture() {
+        let mut items = Vec::new();
+        for page in 1..=4 {
+            items.push(furniture_item("ROW LABEL", 85.0, 400.0, page));
+            items.push(furniture_item("ROW VALUE", 300.0, 400.0, page));
+        }
+        assert!(running_furniture_keys(&items).is_empty());
+    }
+
     fn make_item(x: f32, y: f32, page: u32) -> TextItem {
         TextItem {
             text: "A".into(),

src/markdown/postprocess.rs

@@ -13,7 +13,11 @@ pub(crate) fn clean_markdown(mut text: String, options: &MarkdownOptions) -> Str
         text = collapse_dot_leaders(&text);
     }
 
-    // Fix hyphenation first (before other processing)
+    // Collapse runs of spaces first: double-spaced breaks ("de-  fendant")
+    // must look like single-spaced ones before the hyphenation passes.
+    collapse_consecutive_spaces(&mut text);
+
+    // Fix hyphenation (before other processing)
     if options.fix_hyphenation {
         text = fix_hyphenation(&text);
     }
@@ -143,7 +147,213 @@ fn fix_hyphenation(text: &str) -> String {
         })
         .to_string();
 
-    result
+    dehyphenate_line_breaks(&result)
+}
+
+/// What a line-break hyphen pair should become. Policy output only — how the
+/// decision is rendered (plain text vs. inside split emphasis markers) is the
+/// caller's business.
+#[derive(Clone, Copy, PartialEq, Eq, Debug)]
+enum Join {
+    /// The fragments are one word: "de- fendant" -> "defendant".
+    Plain,
+    /// The fragments are a hyphenated compound: "six- month" -> "six-month".
+    Hyphen,
+    /// No evidence (or a suspended hyphen): leave the break as it is.
+    Keep,
+}
+
+/// Decide what a line-break hyphen pair becomes, given the document's
+/// vocabulary evidence. The whole dehyphenation policy lives here so it can
+/// be reasoned about (and tested) apart from the Markdown scanning around it;
+/// see [`dehyphenate_line_breaks`] for the rule rationale.
+fn join_decision(
+    a: &str,
+    b: &str,
+    words: &std::collections::HashSet<String>,
+    hyphenated: &std::collections::HashSet<String>,
+) -> Join {
+    // Word-length sanity: syllable fragments are short, and even long German
+    // compounds stay under this. Fragments beyond it are already fused
+    // reading-order noise (interleaved columns); joining would compound the
+    // damage.
+    if a.chars().count() + b.chars().count() > 40 {
+        return Join::Keep;
+    }
+    let key_plain = format!("{}{}", a.to_lowercase(), b.to_lowercase());
+    let key_hyphen = format!("{}-{}", a.to_lowercase(), b.to_lowercase());
+    if words.contains(&key_plain) {
+        Join::Plain
+    } else if hyphenated.contains(&key_hyphen) || b.chars().next().is_some_and(|c| c.is_uppercase())
+    {
+        Join::Hyphen
+    } else if b.chars().count() >= 4
+        && words.contains(&a.to_lowercase())
+        && words.contains(&b.to_lowercase())
+    {
+        // No direct evidence, but both fragments are themselves words the
+        // document uses ("commercial- type"): hyphenated compounds are made
+        // of words, while syllable fragments ("evi", "judg", "mo") are not.
+        //
+        // The continuation must be at least four letters. Suspended hyphens
+        // ("mid- and long-term", "klein- und mittelgroß") put a conjunction
+        // after the hyphen, and conjunctions are near-universally one to
+        // three letters in any language — the length floor keeps this rule
+        // off them without a hard-coded conjunction list.
+        Join::Hyphen
+    } else {
+        // No evidence at all: leave the break as it is. An unconditional join
+        // here covered only ~1% more breaks on a vocabulary-rich document,
+        // but it was the sole rule able to corrupt output — fusing
+        // interleaved-column fragments ("com- real" -> "comreal") into
+        // unrecoverable tokens. A visible break is honest; a silent fusion
+        // is not.
+        Join::Keep
+    }
+}
+
+/// Rejoin words hyphenated at the original line breaks.
+///
+/// Justified print breaks words at syllables; after paragraph lines are
+/// joined with spaces those breaks survive as "de- fendant" (and, when an
+/// emphasis span was split with the word, "Bap-** **tist"). Whether the
+/// hyphen itself belongs in the word cannot be decided locally — "de-
+/// fendant" is one word but "Third- Party" is a hyphenated compound — so the
+/// document is its own dictionary:
+///
+///   1. fragments appear elsewhere joined plain ("defendant") — join plain;
+///   2. appear elsewhere hyphenated ("six-month"), or the continuation is
+///      capitalized ("Hinds- Radix", "Third- Party") — keep the hyphen;
+///   3. both fragments are words the document uses and the continuation
+///      has four or more letters ("commercial- type" where "commercial"
+///      and "type" appear elsewhere) — a compound, keep the hyphen. The
+///      length floor keeps this rule off suspended hyphens ("mid- and
+///      long-term", "klein- und mittelgroß"): conjunctions are one to
+///      three letters in essentially every language, so no conjunction
+///      list is needed;
+///   4. no evidence — leave the break untouched. Evidence covers ~99% of
+///      breaks on vocabulary-rich documents, and an unconditional join was
+///      the one rule able to corrupt output (fusing interleaved-column
+///      fragments into unrecoverable tokens).
+///
+/// Every rule is either document evidence or script-agnostic typography;
+/// deliberately no hard-coded word lists beyond the three suspension
+/// conjunctions (a curated suffix list was tried and removed — it was
+/// English-only, its membership was unfalsifiable, and it could invent
+/// hyphens: "proto- type" -> "proto-type").
+///
+/// Table rows and fenced code blocks are left untouched.
+fn dehyphenate_line_breaks(text: &str) -> String {
+    use once_cell::sync::Lazy;
+    use std::collections::HashSet;
+
+    const WORD: &str = r"\p{L}";
+
+    // "de- fendant"
+    static BREAK_RE: Lazy<Regex> =
+        Lazy::new(|| Regex::new(&format!("({WORD}{{2,}})- ({WORD}{{2,}})")).unwrap());
+    // "Bap-** **tist" — an emphasis span split together with the word. The
+    // regex crate has no backreferences, so both markers are captured and
+    // compared in the replacement closure.
+    static BREAK_EMPH_RE: Lazy<Regex> = Lazy::new(|| {
+        Regex::new(&format!(
+            r"({WORD}{{2,}})-(\*{{1,2}}) (\*{{1,2}})({WORD}{{2,}})"
+        ))
+        .unwrap()
+    });
+    static PLAIN_WORD_RE: Lazy<Regex> = Lazy::new(|| Regex::new(&format!("{WORD}{{3,}}")).unwrap());
+    static HYPHENATED_RE: Lazy<Regex> =
+        Lazy::new(|| Regex::new(&format!("({WORD}{{2,}})-({WORD}{{2,}})")).unwrap());
+
+    // The document is its own dictionary: whole words and hyphenated
+    // compounds as they appear away from line breaks. Two exclusions keep the
+    // evidence sound:
+    //   - the break pairs themselves are scrubbed first, otherwise every
+    //     broken word donates its own fragments ("evi", "dence") and the
+    //     compound rule would see them as words;
+    //   - fenced code blocks are skipped: identifiers are a different
+    //     language, and one like `comreal` must not justify fusing prose.
+    //     Table rows stay — cells carry genuine document vocabulary.
+    let mut prose = String::with_capacity(text.len());
+    let mut in_code = false;
+    for line in text.split('\n') {
+        if line.trim_start().starts_with("```") {
+            in_code = !in_code;
+            continue;
+        }
+        if !in_code {
+            prose.push_str(line);
+            prose.push('\n');
+        }
+    }
+    let scrubbed = BREAK_EMPH_RE.replace_all(&prose, " ");
+    let scrubbed = BREAK_RE.replace_all(&scrubbed, " ");
+    let mut words: HashSet<String> = HashSet::new();
+    let mut hyphenated: HashSet<String> = HashSet::new();
+    for m in PLAIN_WORD_RE.find_iter(&scrubbed) {
+        words.insert(m.as_str().to_lowercase());
+    }
+    for caps in HYPHENATED_RE.captures_iter(&scrubbed) {
+        hyphenated.insert(format!(
+            "{}-{}",
+            caps[1].to_lowercase(),
+            caps[2].to_lowercase()
+        ));
+    }
+
+    let join = |a: &str, b: &str| join_decision(a, b, &words, &hyphenated);
+
+    let mut in_code_block = false;
+    let mut out = String::with_capacity(text.len());
+    for (i, line) in text.split('\n').enumerate() {
+        if i > 0 {
+            out.push('\n');
+        }
+        if line.trim_start().starts_with("```") {
+            in_code_block = !in_code_block;
+        }
+        if in_code_block || line.trim_start().starts_with('|') {
+            out.push_str(line);
+            continue;
+        }
+        // A break can chain ("unconsti- tu- tional"); each pass joins one
+        // junction, and every successful join removes a break, so running
+        // until the line is stable is bounded by the number of breaks.
+        let mut current = line.to_string();
+        loop {
+            let next = BREAK_EMPH_RE
+                .replace_all(&current, |caps: &regex::Captures| {
+                    // Mismatched markers aren't a split span; a Keep decision
+                    // preserves the original spacing and markers.
+                    if caps[2] != caps[3] {
+                        return caps[0].to_string();
+                    }
+                    let (a, b) = (&caps[1], &caps[4]);
+                    match join(a, b) {
+                        Join::Plain => format!("{a}{b}"),
+                        Join::Hyphen => format!("{a}-{b}"),
+                        Join::Keep => caps[0].to_string(),
+                    }
+                })
+                .to_string();
+            let next = BREAK_RE
+                .replace_all(&next, |caps: &regex::Captures| {
+                    let (a, b) = (&caps[1], &caps[2]);
+                    match join(a, b) {
+                        Join::Plain => format!("{a}{b}"),
+                        Join::Hyphen => format!("{a}-{b}"),
+                        Join::Keep => caps[0].to_string(),
+                    }
+                })
+                .to_string();
+            if next == current {
+                break;
+            }
+            current = next;
+        }
+        out.push_str(&current);
+    }
+    out
 }
 
 /// Remove isolated page-number expressions from Markdown.
@@ -384,6 +594,180 @@ mod tests {
         assert_eq!(t, "version 3 .14 released");
     }
 
+    // --- dehyphenate_line_breaks ---
+
+    #[test]
+    fn line_break_joins_plain_on_vocabulary_evidence() {
+        // "defendant" appears whole elsewhere, so the broken form joins plain.
+        let text = "The defendant appeared. The de- fendant argued.";
+        assert_eq!(
+            dehyphenate_line_breaks(text),
+            "The defendant appeared. The defendant argued."
+        );
+    }
+
+    #[test]
+    fn line_break_keeps_hyphen_on_hyphenated_evidence() {
+        // "six-month" appears hyphenated elsewhere, so the broken form keeps it.
+        let text = "A six-month term. After a six- month delay.";
+        assert_eq!(
+            dehyphenate_line_breaks(text),
+            "A six-month term. After a six-month delay."
+        );
+    }
+
+    #[test]
+    fn no_evidence_leaves_the_break_untouched() {
+        // Without document evidence a join cannot be distinguished from
+        // interleaved-column noise; the visible break is kept.
+        let text = "The evi- dence was clear.";
+        assert_eq!(dehyphenate_line_breaks(text), text);
+    }
+
+    #[test]
+    fn line_break_keeps_hyphen_before_capitalized_continuation() {
+        // Broken compounds: "Third-Party", "Hinds-Radix".
+        let text = "The Third- Party complaint by Hinds- Radix.";
+        assert_eq!(
+            dehyphenate_line_breaks(text),
+            "The Third-Party complaint by Hinds-Radix."
+        );
+    }
+
+    #[test]
+    fn cyrillic_words_join_on_evidence() {
+        // The word class is Unicode-wide, not a hard-coded Latin subset.
+        let text = "Это решение важно. Это реше- ние суда.";
+        assert_eq!(
+            dehyphenate_line_breaks(text),
+            "Это решение важно. Это решение суда."
+        );
+    }
+
+    #[test]
+    fn double_spaced_breaks_join_through_clean_markdown() {
+        // Space collapsing runs before hyphenation, so a break that arrives
+        // with two spaces ("de-  fendant") still rejoins.
+        let options = MarkdownOptions::default();
+        let out = clean_markdown(
+            "The defendant appeared. The de-  fendant argued.".to_string(),
+            &options,
+        );
+        assert_eq!(
+            out.trim_end(),
+            "The defendant appeared. The defendant argued."
+        );
+    }
+
+    #[test]
+    fn code_block_identifiers_are_not_vocabulary_evidence() {
+        // A fused identifier in code must not justify fusing unrelated prose.
+        let text = "```\nlet comreal = 1;\n```\nThe com- real estate story.";
+        assert_eq!(dehyphenate_line_breaks(text), text);
+    }
+
+    #[test]
+    fn fused_column_noise_is_not_joined() {
+        // Interleaved-column garbage arrives already fused; joining across
+        // its breaks would compound the damage. Real syllable fragments are
+        // short; fragments this long are left exactly as they are.
+        let text = "spreadswerenegativeintheearlytomid- seriouslyflawedduetoappraisallags";
+        assert_eq!(dehyphenate_line_breaks(text), text);
+        // Long German compounds stay under the length gate and join on
+        // vocabulary evidence.
+        let german =
+            "Das Bundesausbildungsförderungsgesetz. Das Bundesausbildungsförderungs- gesetz gilt.";
+        assert_eq!(
+            dehyphenate_line_breaks(german),
+            "Das Bundesausbildungsförderungsgesetz. Das Bundesausbildungsförderungsgesetz gilt."
+        );
+    }
+
+    #[test]
+    fn no_evidence_compounds_stay_visibly_broken() {
+        // No hard-coded suffix list: without document evidence even a likely
+        // compound keeps its visible break. A curated list was tried and
+        // removed — English-only, unfalsifiable membership, and able to
+        // invent hyphens ("proto- type" -> "proto-type").
+        let text = "Their world- class support and proto- type systems.";
+        assert_eq!(dehyphenate_line_breaks(text), text);
+    }
+
+    #[test]
+    fn both_fragments_being_words_keeps_the_hyphen() {
+        // "commercial-type insurance": no evidence either way, but both
+        // fragments are words the document uses, so this is a compound.
+        let text = "Any commercial firm of this type offering commercial- type insurance.";
+        assert_eq!(
+            dehyphenate_line_breaks(text),
+            "Any commercial firm of this type offering commercial-type insurance."
+        );
+    }
+
+    #[test]
+    fn suspended_hyphen_is_preserved() {
+        // "mid- to long-term": joining would fuse unrelated words. No
+        // conjunction list is involved — conjunctions are 1-3 letters in
+        // essentially every language, and the compound rule requires a
+        // 4-letter continuation, so suspended hyphens fall through to Keep.
+        let text = "Planned over the mid- to long-term horizon, in- and out-of-possession.";
+        assert_eq!(dehyphenate_line_breaks(text), text);
+        // Same construction in German, which a hard-coded English list
+        // would have missed. "klein" appears standalone so it IS in the
+        // vocabulary — only the length floor (continuation "und" has three
+        // letters) keeps the compound rule from fusing "klein-und".
+        let german = "Das klein geschriebene Wort und die klein- und mittelgroßen Betriebe.";
+        assert_eq!(dehyphenate_line_breaks(german), german);
+    }
+
+    #[test]
+    fn split_emphasis_span_joins_inside_markers() {
+        // Vocabulary evidence ("Baptist", "Consolidated" elsewhere) drives
+        // the join; the split emphasis markers collapse with it.
+        let text = "The Baptist and Consolidated cases. By **Bap-** **tist** pastors and *Consoli-* *dated* Edison.";
+        assert_eq!(
+            dehyphenate_line_breaks(text),
+            "The Baptist and Consolidated cases. By **Baptist** pastors and *Consolidated* Edison."
+        );
+    }
+
+    #[test]
+    fn mismatched_emphasis_markers_are_left_alone() {
+        let text = "Odd **Bap-** *tist* markers.";
+        assert_eq!(dehyphenate_line_breaks(text), text);
+    }
+
+    #[test]
+    fn chained_breaks_join_stepwise_with_evidence() {
+        // A word broken twice joins across passes when each junction has
+        // vocabulary evidence for its intermediate form.
+        let text = "The word unconstitutional, and unconstitu appears too: unconsti- tu- tional.";
+        assert_eq!(
+            dehyphenate_line_breaks(text),
+            "The word unconstitutional, and unconstitu appears too: unconstitutional."
+        );
+    }
+
+    #[test]
+    fn table_rows_and_code_blocks_are_untouched() {
+        let text =
+            "The defendant.\n|de- fendant|value|\n```\nlet x = de- fendant;\n```\nThe de- fendant won.";
+        assert_eq!(
+            dehyphenate_line_breaks(text),
+            "The defendant.\n|de- fendant|value|\n```\nlet x = de- fendant;\n```\nThe defendant won."
+        );
+    }
+
+    #[test]
+    fn accented_words_join() {
+        // Spanish syllable break with accented continuation, evidence-backed.
+        let text = "Una resolución firme. La resolu- ción fue clara.";
+        assert_eq!(
+            dehyphenate_line_breaks(text),
+            "Una resolución firme. La resolución fue clara."
+        );
+    }
+
     // --- fix_hyphenation ---
 
     #[test]

src/vision/contracts.rs

@@ -0,0 +1,414 @@
+//! Public contracts between rendering, OCR, layout, and orchestration.
+
+use std::error::Error;
+use std::path::PathBuf;
+
+use super::{RenderOptions, RenderedPage};
+
+/// Selects when OCR may run.
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
+#[non_exhaustive]
+pub enum OcrMode {
+    /// Never run OCR. This is the default and preserves existing behavior.
+    #[default]
+    Off,
+    /// Run OCR only on pages selected by pdf-inspector's OCR routing signals.
+    Auto,
+    /// Run OCR on every selected page, including pages with native text.
+    Force,
+}
+
+/// Resource/quality profile for the OCR engine.
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
+#[non_exhaustive]
+pub enum OcrProfile {
+    /// Lowest latency and memory footprint.
+    Edge,
+    /// OCR-oriented balance of quality and CPU cost.
+    #[default]
+    Balanced,
+    /// Highest quality within the lightweight model family.
+    Quality,
+}
+
+/// Controls whether missing model artifacts may be fetched.
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
+#[non_exhaustive]
+pub enum ModelDownloadPolicy {
+    /// Fetch a pinned artifact only after OCR has actually been selected.
+    #[default]
+    IfMissing,
+    /// Never access the network; require an override or a warm model cache.
+    Offline,
+}
+
+/// OCR engine configuration independent of a particular runtime.
+#[derive(Debug, Clone, PartialEq)]
+pub struct OcrOptions {
+    /// Page-level routing behavior.
+    pub mode: OcrMode,
+    /// Local quality/resource profile.
+    pub profile: OcrProfile,
+    /// Drop recognition spans below this confidence threshold.
+    pub minimum_confidence: f32,
+    /// Optional language hints understood by the selected engine.
+    pub languages: Vec<String>,
+    /// Optional directory containing an offline model set.
+    pub model_directory: Option<PathBuf>,
+    /// Whether a missing pinned artifact may be downloaded.
+    pub model_downloads: ModelDownloadPolicy,
+}
+
+impl Default for OcrOptions {
+    fn default() -> Self {
+        Self {
+            mode: OcrMode::Off,
+            profile: OcrProfile::Balanced,
+            minimum_confidence: 0.0,
+            languages: Vec::new(),
+            model_directory: None,
+            model_downloads: ModelDownloadPolicy::IfMissing,
+        }
+    }
+}
+
+impl OcrOptions {
+    /// Creates OCR options with OCR disabled.
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    /// Sets page-level OCR routing.
+    pub fn mode(mut self, mode: OcrMode) -> Self {
+        self.mode = mode;
+        self
+    }
+
+    /// Sets the local resource/quality profile.
+    pub fn profile(mut self, profile: OcrProfile) -> Self {
+        self.profile = profile;
+        self
+    }
+
+    /// Sets the minimum accepted recognition confidence.
+    pub fn minimum_confidence(mut self, minimum_confidence: f32) -> Self {
+        self.minimum_confidence = minimum_confidence;
+        self
+    }
+
+    /// Replaces the language hints passed to the OCR engine.
+    pub fn languages(mut self, languages: impl IntoIterator<Item = impl Into<String>>) -> Self {
+        self.languages = languages.into_iter().map(Into::into).collect();
+        self
+    }
+
+    /// Uses an explicit model directory, suitable for offline packaging.
+    pub fn model_directory(mut self, directory: impl Into<PathBuf>) -> Self {
+        self.model_directory = Some(directory.into());
+        self
+    }
+
+    /// Sets the missing-model download policy.
+    pub fn model_downloads(mut self, policy: ModelDownloadPolicy) -> Self {
+        self.model_downloads = policy;
+        self
+    }
+}
+
+/// Configuration for an optional learned layout engine.
+///
+/// Layout inference is disabled by default. Existing deterministic layout,
+/// table, and Markdown logic remains the assembly path when this is disabled.
+#[derive(Debug, Clone, PartialEq)]
+pub struct LayoutOptions {
+    /// Whether the learned layout extension may run.
+    pub enabled: bool,
+    /// Drop layout regions below this confidence threshold.
+    pub minimum_confidence: f32,
+    /// Optional directory containing an offline layout model set.
+    pub model_directory: Option<PathBuf>,
+}
+
+impl Default for LayoutOptions {
+    fn default() -> Self {
+        Self {
+            enabled: false,
+            minimum_confidence: 0.0,
+            model_directory: None,
+        }
+    }
+}
+
+impl LayoutOptions {
+    /// Creates layout options with learned layout disabled.
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    /// Enables or disables learned layout inference.
+    pub fn enabled(mut self, enabled: bool) -> Self {
+        self.enabled = enabled;
+        self
+    }
+
+    /// Sets the minimum accepted region confidence.
+    pub fn minimum_confidence(mut self, minimum_confidence: f32) -> Self {
+        self.minimum_confidence = minimum_confidence;
+        self
+    }
+
+    /// Uses an explicit layout model directory.
+    pub fn model_directory(mut self, directory: impl Into<PathBuf>) -> Self {
+        self.model_directory = Some(directory.into());
+        self
+    }
+}
+
+/// A point in bitmap space, measured from the top-left in pixels.
+#[derive(Debug, Clone, Copy, Default, PartialEq)]
+pub struct ImagePoint {
+    /// Horizontal pixel coordinate.
+    pub x: f32,
+    /// Vertical pixel coordinate, increasing downward.
+    pub y: f32,
+}
+
+impl ImagePoint {
+    /// Creates a bitmap-space point.
+    pub fn new(x: f32, y: f32) -> Self {
+        Self { x, y }
+    }
+}
+
+/// Four-point polygon in bitmap coordinates.
+#[derive(Debug, Clone, Copy, Default, PartialEq)]
+pub struct ImageQuad {
+    /// Polygon points in engine-provided order.
+    pub points: [ImagePoint; 4],
+}
+
+impl ImageQuad {
+    /// Creates a four-point bitmap polygon.
+    pub fn new(points: [ImagePoint; 4]) -> Self {
+        Self { points }
+    }
+}
+
+/// Stable identity for an inference model used in output provenance.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ModelIdentity {
+    /// Model family/name, for example `pp-ocrv6-small`.
+    pub name: String,
+    /// Immutable model or artifact-set revision.
+    pub revision: String,
+}
+
+impl ModelIdentity {
+    /// Creates a model identity.
+    pub fn new(name: impl Into<String>, revision: impl Into<String>) -> Self {
+        Self {
+            name: name.into(),
+            revision: revision.into(),
+        }
+    }
+}
+
+/// One positioned OCR recognition result in bitmap coordinates.
+#[derive(Debug, Clone, PartialEq)]
+pub struct OcrSpan {
+    /// Recognized text.
+    pub text: String,
+    /// Detection polygon in the original rendered page's pixel space.
+    pub polygon: ImageQuad,
+    /// Recognition confidence in the inclusive range 0–1.
+    pub confidence: f32,
+    /// Optional text-line orientation in clockwise degrees.
+    pub orientation_degrees: Option<f32>,
+}
+
+/// OCR output for one 1-indexed page.
+#[derive(Debug, Clone, PartialEq)]
+pub struct OcrPage {
+    /// 1-indexed PDF page number.
+    pub page: u32,
+    /// Positioned recognition spans.
+    pub spans: Vec<OcrSpan>,
+    /// Mean confidence across accepted spans, when available.
+    pub mean_confidence: Option<f32>,
+    /// Exact model identity used for this result.
+    pub model: ModelIdentity,
+    /// OCR wall time for this page.
+    pub processing_time_ms: u64,
+    /// Non-fatal engine warnings.
+    pub warnings: Vec<String>,
+}
+
+/// Normalized semantic class emitted by a learned layout engine.
+#[derive(Debug, Clone, PartialEq, Eq)]
+#[non_exhaustive]
+pub enum LayoutRegionKind {
+    /// Body or other prose text.
+    Text,
+    /// Document heading or title.
+    Heading,
+    /// Table region.
+    Table,
+    /// Figure/image region.
+    Figure,
+    /// Figure or table caption.
+    Caption,
+    /// Header/footer/page furniture.
+    Furniture,
+    /// Model-specific class retained without changing the common taxonomy.
+    Other(String),
+}
+
+/// One learned layout region in bitmap coordinates.
+#[derive(Debug, Clone, PartialEq)]
+pub struct LayoutRegion {
+    /// Normalized semantic class.
+    pub kind: LayoutRegionKind,
+    /// Region polygon in the original rendered page's pixel space.
+    pub polygon: ImageQuad,
+    /// Model confidence in the inclusive range 0–1.
+    pub confidence: f32,
+    /// Optional model-provided reading-order position.
+    pub reading_order: Option<u32>,
+}
+
+/// Learned layout output for one 1-indexed page.
+#[derive(Debug, Clone, PartialEq)]
+pub struct LayoutPage {
+    /// 1-indexed PDF page number.
+    pub page: u32,
+    /// Semantic regions.
+    pub regions: Vec<LayoutRegion>,
+    /// Exact model identity used for this result.
+    pub model: ModelIdentity,
+    /// Layout inference wall time for this page.
+    pub processing_time_ms: u64,
+    /// Non-fatal engine warnings.
+    pub warnings: Vec<String>,
+}
+
+/// How final page content was sourced.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+#[non_exhaustive]
+pub enum PageContentSource {
+    /// Trusted native PDF text only.
+    Native,
+    /// OCR output only.
+    Ocr,
+    /// Native and OCR spans were fused.
+    Fused,
+}
+
+/// Per-page local processing timings.
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
+pub struct VisionTimings {
+    /// Rasterization wall time.
+    pub render_ms: u64,
+    /// OCR wall time.
+    pub ocr_ms: u64,
+    /// Optional learned layout wall time.
+    pub layout_ms: u64,
+    /// Native/OCR fusion and assembly wall time.
+    pub assembly_ms: u64,
+}
+
+/// Source and model metadata retained for one processed page.
+#[derive(Debug, Clone, PartialEq)]
+pub struct PageProvenance {
+    /// 1-indexed PDF page number.
+    pub page: u32,
+    /// Final page-content source.
+    pub source: PageContentSource,
+    /// OCR model, when OCR ran.
+    pub ocr_model: Option<ModelIdentity>,
+    /// Learned layout model, when layout inference ran.
+    pub layout_model: Option<ModelIdentity>,
+    /// Render resolution used for local vision.
+    pub render_dpi: Option<f32>,
+    /// Mean accepted OCR confidence, when available.
+    pub ocr_confidence: Option<f32>,
+    /// Stage timings.
+    pub timings: VisionTimings,
+    /// Non-fatal warnings surfaced to downstream users.
+    pub warnings: Vec<String>,
+    /// True when this lightweight local path detected a case better suited to
+    /// Firecrawl's hosted document pipeline.
+    pub hosted_recommended: bool,
+}
+
+/// Converts selected PDF pages into renderer-neutral owned bitmaps.
+pub trait PageRenderer: Send + Sync {
+    /// Renderer-specific failure type.
+    type Error: Error + Send + Sync + 'static;
+
+    /// Renders selected 1-indexed pages in the same order as `pages`.
+    fn render_pages(
+        &self,
+        pdf_bytes: &[u8],
+        pages: &[u32],
+        password: Option<&str>,
+        options: &RenderOptions,
+    ) -> Result<Vec<RenderedPage>, Self::Error>;
+}
+
+/// Recognizes positioned text from rendered pages.
+pub trait OcrEngine: Send + Sync {
+    /// Engine-specific failure type.
+    type Error: Error + Send + Sync + 'static;
+
+    /// Exact model identity used by this engine instance.
+    fn model(&self) -> &ModelIdentity;
+
+    /// Recognizes pages in batch and returns results in input order.
+    fn recognize(
+        &self,
+        pages: &[RenderedPage],
+        options: &OcrOptions,
+    ) -> Result<Vec<OcrPage>, Self::Error>;
+}
+
+/// Optional learned semantic layout extension.
+pub trait LayoutEngine: Send + Sync {
+    /// Engine-specific failure type.
+    type Error: Error + Send + Sync + 'static;
+
+    /// Exact model identity used by this engine instance.
+    fn model(&self) -> &ModelIdentity;
+
+    /// Analyzes rendered pages, optionally using their OCR spans.
+    fn analyze(
+        &self,
+        pages: &[RenderedPage],
+        ocr: &[OcrPage],
+        options: &LayoutOptions,
+    ) -> Result<Vec<LayoutPage>, Self::Error>;
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn ocr_defaults_never_enable_recognition() {
+        let options = OcrOptions::default();
+        assert_eq!(options.mode, OcrMode::Off);
+    }
+
+    #[test]
+    fn offline_model_override_is_explicit() {
+        let options = OcrOptions::new()
+            .mode(OcrMode::Auto)
+            .model_directory("/models/pp-ocr")
+            .model_downloads(ModelDownloadPolicy::Offline);
+        assert_eq!(options.mode, OcrMode::Auto);
+        assert_eq!(options.model_downloads, ModelDownloadPolicy::Offline);
+        assert_eq!(
+            options.model_directory,
+            Some(PathBuf::from("/models/pp-ocr"))
+        );
+    }
+}

src/vision/mod.rs

@@ -0,0 +1,37 @@
+//! Optional native vision primitives used by OCR pipelines.
+//!
+//! The existing lopdf extractor remains the default path. Native page
+//! rendering is available only with the `render-pdfium` feature. Engine
+//! contracts are available with `vision`, while checksum-verified model
+//! resolution is a separate `model-cache` feature. These remain separate so
+//! browser WASM, text-only consumers, and renderer-only users take on no model
+//! management dependencies.
+
+#[cfg(all(feature = "vision", not(target_arch = "wasm32")))]
+mod contracts;
+#[cfg(all(feature = "model-cache", not(target_arch = "wasm32")))]
+mod models;
+#[cfg(all(feature = "vision", not(target_arch = "wasm32")))]
+mod render;
+
+#[cfg(all(feature = "render-pdfium", not(target_arch = "wasm32")))]
+mod pdfium;
+
+#[cfg(all(feature = "vision", not(target_arch = "wasm32")))]
+pub use contracts::{
+    ImagePoint, ImageQuad, LayoutEngine, LayoutOptions, LayoutPage, LayoutRegion, LayoutRegionKind,
+    ModelDownloadPolicy, ModelIdentity, OcrEngine, OcrMode, OcrOptions, OcrPage, OcrProfile,
+    OcrSpan, PageContentSource, PageProvenance, PageRenderer, VisionTimings,
+};
+#[cfg(all(feature = "model-cache", not(target_arch = "wasm32")))]
+pub use models::{
+    ModelArtifact, ModelArtifactKind, ModelManifest, ModelPaths, ModelStore, ModelStoreError,
+    PP_OCR_V6_SMALL,
+};
+#[cfg(all(feature = "vision", not(target_arch = "wasm32")))]
+pub use render::{
+    PagePoint, PageTransform, RenderBufferError, RenderOptions, RenderPixelFormat, RenderedPage,
+};
+
+#[cfg(all(feature = "render-pdfium", not(target_arch = "wasm32")))]
+pub use pdfium::{PdfiumRenderer, RenderError};

src/vision/models.rs

@@ -0,0 +1,767 @@
+//! Versioned model manifests and a checksum-verified local cache.
+
+use std::collections::{BTreeMap, BTreeSet};
+use std::ffi::OsStr;
+use std::fs::{self, File, OpenOptions};
+use std::io::{self, Read, Write};
+use std::path::{Component, Path, PathBuf};
+use std::sync::atomic::{AtomicU64, Ordering};
+use std::time::{SystemTime, UNIX_EPOCH};
+
+use fs2::FileExt;
+use sha2::{Digest, Sha256};
+use thiserror::Error;
+
+use super::OcrOptions;
+
+/// Environment variable overriding the default local model cache.
+pub const MODEL_CACHE_ENV: &str = "PDF_INSPECTOR_MODEL_CACHE";
+
+/// Role of an artifact within a local model set.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
+#[non_exhaustive]
+pub enum ModelArtifactKind {
+    /// Text detection ONNX graph.
+    TextDetection,
+    /// Text recognition ONNX graph.
+    TextRecognition,
+    /// Recognition character dictionary.
+    CharacterDictionary,
+    /// Learned document-layout ONNX graph.
+    Layout,
+}
+
+/// One immutable file in a model manifest.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct ModelArtifact {
+    /// Artifact role.
+    pub kind: ModelArtifactKind,
+    /// Cache filename without directory components.
+    pub filename: &'static str,
+    /// Canonical HTTPS download location.
+    pub url: &'static str,
+    /// Lowercase SHA-256 digest.
+    pub sha256: &'static str,
+    /// Exact expected file size.
+    pub size: u64,
+}
+
+/// Versioned set of files required by one model configuration.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct ModelManifest {
+    /// Manifest schema version.
+    pub schema_version: u32,
+    /// Stable model-set identifier.
+    pub id: &'static str,
+    /// Immutable upstream artifact revision.
+    pub revision: &'static str,
+    /// Required artifacts.
+    pub artifacts: &'static [ModelArtifact],
+}
+
+const PP_OCR_V6_SMALL_ARTIFACTS: &[ModelArtifact] = &[
+    ModelArtifact {
+        kind: ModelArtifactKind::TextDetection,
+        filename: "pp-ocrv6_small_det.onnx",
+        url: "https://github.com/GreatV/oar-ocr/releases/download/v0.7.0/pp-ocrv6_small_det.onnx",
+        sha256: "d73e0058b7a8086bbd57f3d10b8bcd4ff95363f67e06e2762b5e814fe9c9410e",
+        size: 9_880_512,
+    },
+    ModelArtifact {
+        kind: ModelArtifactKind::TextRecognition,
+        filename: "pp-ocrv6_small_rec.onnx",
+        url: "https://github.com/GreatV/oar-ocr/releases/download/v0.7.0/pp-ocrv6_small_rec.onnx",
+        sha256: "5435fd747c9e0efe15a96d0b378d5bd157e9492ed8fd80edf08f30d02fa24634",
+        size: 21_159_378,
+    },
+    ModelArtifact {
+        kind: ModelArtifactKind::CharacterDictionary,
+        filename: "ppocrv6_dict.txt",
+        url: "https://github.com/GreatV/oar-ocr/releases/download/v0.7.0/ppocrv6_dict.txt",
+        sha256: "b5f2bfe2bdd9448429e3e82b51c789775d9b42f2403d082b00662eb77e401c5d",
+        size: 74_947,
+    },
+];
+
+/// Pinned PP-OCRv6 Small detection/recognition model set.
+///
+/// The artifact hashes match the registry shipped by `oar-ocr-core` 0.9.1;
+/// the revision identifies the upstream release that owns the files.
+pub const PP_OCR_V6_SMALL: ModelManifest = ModelManifest {
+    schema_version: 1,
+    id: "pp-ocrv6-small",
+    revision: "oar-ocr-v0.7.0",
+    artifacts: PP_OCR_V6_SMALL_ARTIFACTS,
+};
+
+/// Resolved, verified filesystem paths for one model manifest.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ModelPaths {
+    manifest_id: String,
+    revision: String,
+    artifacts: BTreeMap<ModelArtifactKind, PathBuf>,
+}
+
+impl ModelPaths {
+    /// Stable model-set identifier.
+    pub fn manifest_id(&self) -> &str {
+        &self.manifest_id
+    }
+
+    /// Immutable artifact revision.
+    pub fn revision(&self) -> &str {
+        &self.revision
+    }
+
+    /// Verified path for an artifact role.
+    pub fn get(&self, kind: ModelArtifactKind) -> Option<&Path> {
+        self.artifacts.get(&kind).map(PathBuf::as_path)
+    }
+
+    /// Iterates over verified artifact paths.
+    pub fn iter(&self) -> impl Iterator<Item = (ModelArtifactKind, &Path)> {
+        self.artifacts
+            .iter()
+            .map(|(&kind, path)| (kind, path.as_path()))
+    }
+}
+
+/// Checksum-verified model cache with an optional offline directory override.
+///
+/// This type never accesses the network. [`resolve`](Self::resolve) verifies a
+/// warm cache or explicit directory, and [`install`](Self::install) atomically
+/// installs bytes supplied by a higher-level downloader. Keeping acquisition
+/// separate makes offline behavior enforceable and straightforward to test.
+#[derive(Debug, Clone)]
+pub struct ModelStore {
+    cache_root: PathBuf,
+    override_root: Option<PathBuf>,
+}
+
+impl ModelStore {
+    /// Creates a model store rooted at an explicit cache directory.
+    pub fn new(cache_root: impl Into<PathBuf>) -> Self {
+        Self {
+            cache_root: cache_root.into(),
+            override_root: None,
+        }
+    }
+
+    /// Builds a store from OCR options and the platform cache directory.
+    ///
+    /// `PDF_INSPECTOR_MODEL_CACHE` overrides the platform default. An explicit
+    /// [`OcrOptions::model_directory`] replaces the managed cache at resolve
+    /// time so offline packaging is deterministic.
+    pub fn from_options(options: &OcrOptions) -> Result<Self, ModelStoreError> {
+        let cache_root = match std::env::var_os(MODEL_CACHE_ENV) {
+            Some(path) if !path.is_empty() => PathBuf::from(path),
+            _ => dirs::cache_dir()
+                .ok_or(ModelStoreError::CacheDirectoryUnavailable)?
+                .join("pdf-inspector")
+                .join("models"),
+        };
+        Ok(Self {
+            cache_root,
+            override_root: options.model_directory.clone(),
+        })
+    }
+
+    /// Checks an explicit offline model directory before the managed cache.
+    pub fn override_root(mut self, root: impl Into<PathBuf>) -> Self {
+        self.override_root = Some(root.into());
+        self
+    }
+
+    /// Managed cache root.
+    pub fn cache_root(&self) -> &Path {
+        &self.cache_root
+    }
+
+    /// 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 mut artifacts = BTreeMap::new();
+        for artifact in manifest.artifacts {
+            let path = root.join(artifact.filename);
+            verify_artifact(&path, artifact)?;
+            artifacts.insert(artifact.kind, path);
+        }
+        Ok(ModelPaths {
+            manifest_id: manifest.id.to_string(),
+            revision: manifest.revision.to_string(),
+            artifacts,
+        })
+    }
+
+    /// Atomically installs one artifact from a reader after validating its
+    /// exact size and SHA-256 digest.
+    ///
+    /// A cross-process file lock serializes installs of the same artifact.
+    /// Already-valid cached files are reused without consuming the reader.
+    pub fn install(
+        &self,
+        manifest: &ModelManifest,
+        kind: ModelArtifactKind,
+        mut reader: impl Read,
+    ) -> Result<PathBuf, ModelStoreError> {
+        validate_manifest(manifest)?;
+        let artifact = manifest
+            .artifacts
+            .iter()
+            .find(|artifact| artifact.kind == kind)
+            .ok_or(ModelStoreError::ArtifactNotInManifest { kind })?;
+        let root = self.manifest_cache_root(manifest);
+        fs::create_dir_all(&root).map_err(|source| ModelStoreError::Io {
+            path: root.clone(),
+            source,
+        })?;
+
+        let target = root.join(artifact.filename);
+        let lock_path = root.join(format!(".{}.lock", artifact.filename));
+        let lock = OpenOptions::new()
+            .create(true)
+            .read(true)
+            .write(true)
+            .truncate(false)
+            .open(&lock_path)
+            .map_err(|source| ModelStoreError::Io {
+                path: lock_path.clone(),
+                source,
+            })?;
+        FileExt::lock_exclusive(&lock).map_err(|source| ModelStoreError::Io {
+            path: lock_path,
+            source,
+        })?;
+
+        if verify_artifact(&target, artifact).is_ok() {
+            return Ok(target);
+        }
+
+        sweep_stale_install_files(&root, artifact.filename)?;
+        let (temporary, mut output) = create_temporary_file(&root, artifact.filename)?;
+        let result = (|| {
+            let mut limited = reader.by_ref().take(artifact.size.saturating_add(1));
+            let (size, digest) =
+                copy_and_hash(&mut limited, &mut output).map_err(|source| ModelStoreError::Io {
+                    path: temporary.clone(),
+                    source,
+                })?;
+            output.sync_all().map_err(|source| ModelStoreError::Io {
+                path: temporary.clone(),
+                source,
+            })?;
+            validate_size_and_hash(artifact, size, &digest, &temporary)?;
+
+            replace_file_atomic(&temporary, &target).map_err(|source| ModelStoreError::Io {
+                path: target.clone(),
+                source,
+            })?;
+            Ok(target.clone())
+        })();
+
+        if result.is_err() {
+            let _ = fs::remove_file(&temporary);
+        }
+        result
+    }
+
+    fn manifest_cache_root(&self, manifest: &ModelManifest) -> PathBuf {
+        self.cache_root.join(manifest.id).join(manifest.revision)
+    }
+}
+
+/// Failures while validating or installing model artifacts.
+#[derive(Debug, Error)]
+#[non_exhaustive]
+pub enum ModelStoreError {
+    /// No platform cache location is available.
+    #[error("no platform cache directory is available; set {MODEL_CACHE_ENV}")]
+    CacheDirectoryUnavailable,
+    /// The static/custom manifest is malformed.
+    #[error("invalid model manifest: {0}")]
+    InvalidManifest(String),
+    /// A requested artifact role is not in the manifest.
+    #[error("artifact role {kind:?} is not present in the model manifest")]
+    ArtifactNotInManifest {
+        /// Missing role.
+        kind: ModelArtifactKind,
+    },
+    /// A required artifact is not installed.
+    #[error("model artifact is missing: {path}")]
+    MissingArtifact {
+        /// Expected local path.
+        path: PathBuf,
+        /// Canonical download URL for an allowed higher-level fetcher.
+        download_url: &'static str,
+    },
+    /// Artifact byte size differs from the manifest.
+    #[error("model artifact {path} has {actual} bytes; expected {expected}")]
+    SizeMismatch {
+        /// Artifact path.
+        path: PathBuf,
+        /// Expected byte count.
+        expected: u64,
+        /// Actual byte count.
+        actual: u64,
+    },
+    /// Artifact digest differs from the manifest.
+    #[error("model artifact checksum mismatch at {path}: expected {expected}, got {actual}")]
+    ChecksumMismatch {
+        /// Artifact path.
+        path: PathBuf,
+        /// Expected lowercase SHA-256.
+        expected: &'static str,
+        /// Actual lowercase SHA-256.
+        actual: String,
+    },
+    /// Filesystem or stream I/O failed.
+    #[error("model cache I/O failed at {path}: {source}")]
+    Io {
+        /// Path involved in the operation.
+        path: PathBuf,
+        /// Underlying I/O error.
+        #[source]
+        source: io::Error,
+    },
+}
+
+fn validate_manifest(manifest: &ModelManifest) -> Result<(), ModelStoreError> {
+    if manifest.schema_version != 1 {
+        return Err(ModelStoreError::InvalidManifest(format!(
+            "unsupported schema version {}",
+            manifest.schema_version
+        )));
+    }
+    if manifest.id.is_empty() || manifest.revision.is_empty() || manifest.artifacts.is_empty() {
+        return Err(ModelStoreError::InvalidManifest(
+            "id, revision, and artifacts must be non-empty".to_string(),
+        ));
+    }
+    for (field, value) in [("id", manifest.id), ("revision", manifest.revision)] {
+        if !is_single_normal_path_component(value) {
+            return Err(ModelStoreError::InvalidManifest(format!(
+                "{field} must be a single path component: {value}"
+            )));
+        }
+    }
+
+    let mut kinds = BTreeSet::new();
+    let mut filenames = BTreeSet::new();
+    for artifact in manifest.artifacts {
+        if !is_single_normal_path_component(artifact.filename) {
+            return Err(ModelStoreError::InvalidManifest(format!(
+                "artifact filename must be a single path component: {}",
+                artifact.filename
+            )));
+        }
+        if artifact.size == 0 {
+            return Err(ModelStoreError::InvalidManifest(format!(
+                "artifact {} has zero size",
+                artifact.filename
+            )));
+        }
+        if artifact.sha256.len() != 64
+            || !artifact
+                .sha256
+                .bytes()
+                .all(|byte| byte.is_ascii_hexdigit() && !byte.is_ascii_uppercase())
+        {
+            return Err(ModelStoreError::InvalidManifest(format!(
+                "artifact {} has an invalid SHA-256",
+                artifact.filename
+            )));
+        }
+        if !artifact.url.starts_with("https://") {
+            return Err(ModelStoreError::InvalidManifest(format!(
+                "artifact {} must use HTTPS",
+                artifact.filename
+            )));
+        }
+        if !kinds.insert(artifact.kind) || !filenames.insert(artifact.filename) {
+            return Err(ModelStoreError::InvalidManifest(format!(
+                "artifact {} duplicates a kind or filename",
+                artifact.filename
+            )));
+        }
+    }
+    Ok(())
+}
+
+fn is_single_normal_path_component(value: &str) -> bool {
+    if value.is_empty() || Path::new(value).file_name() != Some(OsStr::new(value)) {
+        return false;
+    }
+    let mut components = Path::new(value).components();
+    matches!(components.next(), Some(Component::Normal(_))) && components.next().is_none()
+}
+
+fn sweep_stale_install_files(root: &Path, filename: &str) -> Result<(), ModelStoreError> {
+    let prefix = format!(".{filename}.");
+    for entry in fs::read_dir(root).map_err(|source| ModelStoreError::Io {
+        path: root.to_path_buf(),
+        source,
+    })? {
+        let entry = entry.map_err(|source| ModelStoreError::Io {
+            path: root.to_path_buf(),
+            source,
+        })?;
+        let name = entry.file_name();
+        let name = name.to_string_lossy();
+        if name.starts_with(&prefix) && name.ends_with(".part") {
+            let path = entry.path();
+            fs::remove_file(&path).map_err(|source| ModelStoreError::Io { path, source })?;
+        }
+    }
+    Ok(())
+}
+
+fn create_temporary_file(root: &Path, filename: &str) -> Result<(PathBuf, File), ModelStoreError> {
+    static TEMP_COUNTER: AtomicU64 = AtomicU64::new(0);
+    for _ in 0..16 {
+        let sequence = TEMP_COUNTER.fetch_add(1, Ordering::Relaxed);
+        let timestamp = SystemTime::now()
+            .duration_since(UNIX_EPOCH)
+            .unwrap_or_default()
+            .as_nanos();
+        let path = root.join(format!(
+            ".{filename}.{}.{}.{}.part",
+            std::process::id(),
+            timestamp,
+            sequence
+        ));
+        match OpenOptions::new().create_new(true).write(true).open(&path) {
+            Ok(file) => return Ok((path, file)),
+            Err(source) if source.kind() == io::ErrorKind::AlreadyExists => continue,
+            Err(source) => return Err(ModelStoreError::Io { path, source }),
+        }
+    }
+    let path = root.join(format!(".{filename}.part"));
+    Err(ModelStoreError::Io {
+        path,
+        source: io::Error::new(
+            io::ErrorKind::AlreadyExists,
+            "could not allocate a unique model install file",
+        ),
+    })
+}
+
+#[cfg(not(windows))]
+fn replace_file_atomic(source: &Path, target: &Path) -> io::Result<()> {
+    fs::rename(source, target)
+}
+
+#[cfg(windows)]
+fn replace_file_atomic(source: &Path, target: &Path) -> io::Result<()> {
+    use std::os::windows::ffi::OsStrExt;
+    use windows_sys::Win32::Storage::FileSystem::{
+        MoveFileExW, MOVEFILE_REPLACE_EXISTING, MOVEFILE_WRITE_THROUGH,
+    };
+
+    let source: Vec<u16> = source.as_os_str().encode_wide().chain(Some(0)).collect();
+    let target: Vec<u16> = target.as_os_str().encode_wide().chain(Some(0)).collect();
+    let result = unsafe {
+        MoveFileExW(
+            source.as_ptr(),
+            target.as_ptr(),
+            MOVEFILE_REPLACE_EXISTING | MOVEFILE_WRITE_THROUGH,
+        )
+    };
+    if result == 0 {
+        Err(io::Error::last_os_error())
+    } else {
+        Ok(())
+    }
+}
+
+fn verify_artifact(path: &Path, artifact: &ModelArtifact) -> Result<(), ModelStoreError> {
+    let metadata = match fs::metadata(path) {
+        Ok(metadata) => metadata,
+        Err(source) if source.kind() == io::ErrorKind::NotFound => {
+            return Err(ModelStoreError::MissingArtifact {
+                path: path.to_path_buf(),
+                download_url: artifact.url,
+            });
+        }
+        Err(source) => {
+            return Err(ModelStoreError::Io {
+                path: path.to_path_buf(),
+                source,
+            });
+        }
+    };
+    if metadata.len() != artifact.size {
+        return Err(ModelStoreError::SizeMismatch {
+            path: path.to_path_buf(),
+            expected: artifact.size,
+            actual: metadata.len(),
+        });
+    }
+
+    let mut file = File::open(path).map_err(|source| ModelStoreError::Io {
+        path: path.to_path_buf(),
+        source,
+    })?;
+    let mut hasher = Sha256::new();
+    io::copy(&mut file, &mut DigestWriter(&mut hasher)).map_err(|source| ModelStoreError::Io {
+        path: path.to_path_buf(),
+        source,
+    })?;
+    let digest = digest_hex(hasher.finalize());
+    validate_size_and_hash(artifact, metadata.len(), &digest, path)
+}
+
+fn copy_and_hash(reader: &mut impl Read, writer: &mut impl Write) -> io::Result<(u64, String)> {
+    let mut hasher = Sha256::new();
+    let mut buffer = [0_u8; 64 * 1024];
+    let mut size = 0_u64;
+    loop {
+        let read = reader.read(&mut buffer)?;
+        if read == 0 {
+            break;
+        }
+        writer.write_all(&buffer[..read])?;
+        hasher.update(&buffer[..read]);
+        size = size
+            .checked_add(read as u64)
+            .ok_or_else(|| io::Error::other("model artifact size overflow"))?;
+    }
+    Ok((size, digest_hex(hasher.finalize())))
+}
+
+fn digest_hex(digest: impl AsRef<[u8]>) -> String {
+    const HEX: &[u8; 16] = b"0123456789abcdef";
+    let bytes = digest.as_ref();
+    let mut encoded = String::with_capacity(bytes.len() * 2);
+    for &byte in bytes {
+        encoded.push(HEX[(byte >> 4) as usize] as char);
+        encoded.push(HEX[(byte & 0x0f) as usize] as char);
+    }
+    encoded
+}
+
+fn validate_size_and_hash(
+    artifact: &ModelArtifact,
+    size: u64,
+    digest: &str,
+    path: &Path,
+) -> Result<(), ModelStoreError> {
+    if size != artifact.size {
+        return Err(ModelStoreError::SizeMismatch {
+            path: path.to_path_buf(),
+            expected: artifact.size,
+            actual: size,
+        });
+    }
+    if digest != artifact.sha256 {
+        return Err(ModelStoreError::ChecksumMismatch {
+            path: path.to_path_buf(),
+            expected: artifact.sha256,
+            actual: digest.to_string(),
+        });
+    }
+    Ok(())
+}
+
+struct DigestWriter<'a>(&'a mut Sha256);
+
+impl Write for DigestWriter<'_> {
+    fn write(&mut self, buffer: &[u8]) -> io::Result<usize> {
+        self.0.update(buffer);
+        Ok(buffer.len())
+    }
+
+    fn flush(&mut self) -> io::Result<()> {
+        Ok(())
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    const TEST_ARTIFACTS: &[ModelArtifact] = &[ModelArtifact {
+        kind: ModelArtifactKind::CharacterDictionary,
+        filename: "hello.txt",
+        url: "https://example.com/hello.txt",
+        sha256: "2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824",
+        size: 5,
+    }];
+    const TEST_MANIFEST: ModelManifest = ModelManifest {
+        schema_version: 1,
+        id: "test-model",
+        revision: "v1",
+        artifacts: TEST_ARTIFACTS,
+    };
+
+    #[test]
+    fn pinned_pp_ocr_manifest_is_well_formed() {
+        validate_manifest(&PP_OCR_V6_SMALL).unwrap();
+        assert_eq!(PP_OCR_V6_SMALL.artifacts.len(), 3);
+    }
+
+    #[test]
+    fn installs_and_resolves_verified_artifact() {
+        let temp = tempfile::tempdir().unwrap();
+        let store = ModelStore::new(temp.path());
+        let installed = store
+            .install(
+                &TEST_MANIFEST,
+                ModelArtifactKind::CharacterDictionary,
+                &b"hello"[..],
+            )
+            .unwrap();
+        assert!(installed.ends_with("hello.txt"));
+
+        let resolved = store.resolve(&TEST_MANIFEST).unwrap();
+        assert_eq!(
+            resolved.get(ModelArtifactKind::CharacterDictionary),
+            Some(installed.as_path())
+        );
+    }
+
+    #[test]
+    fn rejected_install_does_not_poison_cache() {
+        let temp = tempfile::tempdir().unwrap();
+        let store = ModelStore::new(temp.path());
+        assert!(matches!(
+            store.install(
+                &TEST_MANIFEST,
+                ModelArtifactKind::CharacterDictionary,
+                &b"HELLO"[..],
+            ),
+            Err(ModelStoreError::ChecksumMismatch { .. })
+        ));
+        assert!(matches!(
+            store.resolve(&TEST_MANIFEST),
+            Err(ModelStoreError::MissingArtifact { .. })
+        ));
+    }
+
+    #[test]
+    fn oversized_install_stops_after_one_extra_byte() {
+        let temp = tempfile::tempdir().unwrap();
+        let store = ModelStore::new(temp.path());
+        assert!(matches!(
+            store.install(
+                &TEST_MANIFEST,
+                ModelArtifactKind::CharacterDictionary,
+                &b"hello and far too much data"[..],
+            ),
+            Err(ModelStoreError::SizeMismatch {
+                expected: 5,
+                actual: 6,
+                ..
+            })
+        ));
+    }
+
+    #[test]
+    fn install_replaces_invalid_cache_atomically() {
+        let temp = tempfile::tempdir().unwrap();
+        let store = ModelStore::new(temp.path());
+        let root = store.manifest_cache_root(&TEST_MANIFEST);
+        fs::create_dir_all(&root).unwrap();
+        fs::write(root.join("hello.txt"), b"HELLO").unwrap();
+
+        store
+            .install(
+                &TEST_MANIFEST,
+                ModelArtifactKind::CharacterDictionary,
+                &b"hello"[..],
+            )
+            .unwrap();
+        assert_eq!(fs::read(root.join("hello.txt")).unwrap(), b"hello");
+    }
+
+    #[test]
+    fn stale_partial_installs_are_swept_under_the_lock() {
+        let temp = tempfile::tempdir().unwrap();
+        let store = ModelStore::new(temp.path());
+        let root = store.manifest_cache_root(&TEST_MANIFEST);
+        fs::create_dir_all(&root).unwrap();
+        let stale = root.join(".hello.txt.123.0.part");
+        fs::write(&stale, b"stale").unwrap();
+
+        store
+            .install(
+                &TEST_MANIFEST,
+                ModelArtifactKind::CharacterDictionary,
+                &b"hello"[..],
+            )
+            .unwrap();
+        assert!(!stale.exists());
+    }
+
+    #[test]
+    fn manifest_paths_cannot_escape_the_cache() {
+        const BAD_ID: ModelManifest = ModelManifest {
+            id: "../escape",
+            ..TEST_MANIFEST
+        };
+        const BAD_REVISION: ModelManifest = ModelManifest {
+            revision: "nested/revision",
+            ..TEST_MANIFEST
+        };
+        const BAD_FILENAME_ARTIFACTS: &[ModelArtifact] = &[ModelArtifact {
+            filename: "hello.txt/",
+            ..TEST_ARTIFACTS[0]
+        }];
+        const BAD_FILENAME: ModelManifest = ModelManifest {
+            artifacts: BAD_FILENAME_ARTIFACTS,
+            ..TEST_MANIFEST
+        };
+
+        for manifest in [&BAD_ID, &BAD_REVISION, &BAD_FILENAME] {
+            assert!(matches!(
+                validate_manifest(manifest),
+                Err(ModelStoreError::InvalidManifest(_))
+            ));
+        }
+    }
+
+    #[test]
+    fn explicit_override_is_verified_without_copying() {
+        let cache = tempfile::tempdir().unwrap();
+        let override_dir = tempfile::tempdir().unwrap();
+        fs::write(override_dir.path().join("hello.txt"), b"hello").unwrap();
+        let store = ModelStore::new(cache.path()).override_root(override_dir.path());
+        let resolved = store.resolve(&TEST_MANIFEST).unwrap();
+        assert_eq!(
+            resolved.get(ModelArtifactKind::CharacterDictionary),
+            Some(override_dir.path().join("hello.txt").as_path())
+        );
+    }
+
+    #[test]
+    fn concurrent_installs_converge_on_one_verified_file() {
+        let temp = tempfile::tempdir().unwrap();
+        let first_store = ModelStore::new(temp.path());
+        let second_store = first_store.clone();
+        let first = std::thread::spawn(move || {
+            first_store.install(
+                &TEST_MANIFEST,
+                ModelArtifactKind::CharacterDictionary,
+                &b"hello"[..],
+            )
+        });
+        let second = std::thread::spawn(move || {
+            second_store.install(
+                &TEST_MANIFEST,
+                ModelArtifactKind::CharacterDictionary,
+                &b"hello"[..],
+            )
+        });
+        let first = first.join().unwrap().unwrap();
+        let second = second.join().unwrap().unwrap();
+        assert_eq!(first, second);
+        assert_eq!(fs::read(first).unwrap(), b"hello");
+    }
+}

src/vision/pdfium.rs

@@ -0,0 +1,266 @@
+//! PDFium-backed implementation of the renderer-neutral page contract.
+
+use std::path::Path;
+
+use firecrawl_pdfium::{Pdfium, PixelFormat, PixelPoint, RenderConfig};
+use thiserror::Error;
+
+use super::{
+    PageRenderer, PageTransform, RenderBufferError, RenderOptions, RenderPixelFormat, RenderedPage,
+};
+
+impl RenderPixelFormat {
+    fn pdfium_format(self) -> PixelFormat {
+        match self {
+            // PDFium produces BGR directly; `rendered_page_from_pdfium`
+            // swaps the red and blue channels in place.
+            Self::Rgb8 => PixelFormat::Bgr8,
+            Self::Rgba8 => PixelFormat::Rgba8,
+            Self::Gray8 => PixelFormat::Gray8,
+        }
+    }
+}
+
+impl RenderOptions {
+    fn pdfium_config(&self) -> RenderConfig {
+        RenderConfig::new()
+            .dpi(self.dpi)
+            .pixel_format(self.pixel_format.pdfium_format())
+            .annotations(self.annotations)
+            .form_fields(self.form_fields)
+            .max_output_bytes(self.max_output_bytes_per_page)
+    }
+}
+
+/// Errors produced by the optional local renderer.
+#[derive(Debug, Error)]
+#[non_exhaustive]
+pub enum RenderError {
+    /// Page numbers in pdf-inspector APIs are 1-indexed, so zero is invalid.
+    #[error("page numbers are 1-indexed; page 0 is invalid")]
+    InvalidPageNumber,
+    /// The requested 1-indexed page is not present in the document.
+    #[error("page {page} is out of bounds for a {page_count}-page document")]
+    PageOutOfBounds {
+        /// Requested 1-indexed page.
+        page: u32,
+        /// Number of pages in the document.
+        page_count: usize,
+    },
+    /// PDFium loading, document parsing, form setup, or rendering failed.
+    #[error(transparent)]
+    Pdfium(#[from] firecrawl_pdfium::Error),
+    /// PDFium returned an internally inconsistent bitmap or transform.
+    #[error(transparent)]
+    Buffer(#[from] RenderBufferError),
+}
+
+/// Loaded PDFium renderer used to prepare pages for OCR.
+///
+/// PDFium calls are safe from concurrent threads but serialize inside the
+/// underlying binding. Returned [`RenderedPage`] values are ordinary owned
+/// data and can be processed concurrently after rendering.
+#[derive(Debug, Clone, Copy)]
+pub struct PdfiumRenderer {
+    pdfium: Pdfium,
+}
+
+impl PdfiumRenderer {
+    /// Loads PDFium using `firecrawl-pdfium`'s documented discovery chain.
+    pub fn load() -> Result<Self, RenderError> {
+        Ok(Self {
+            pdfium: Pdfium::load()?,
+        })
+    }
+
+    /// Loads PDFium from an explicit native library path.
+    pub fn load_from_path(path: impl AsRef<Path>) -> Result<Self, RenderError> {
+        Ok(Self {
+            pdfium: Pdfium::load_from_path(path)?,
+        })
+    }
+
+    /// Path of the active PDFium library, if it was loaded from a concrete
+    /// file rather than through the system loader.
+    pub fn loaded_from(&self) -> Option<&Path> {
+        self.pdfium.loaded_from()
+    }
+
+    /// Renders selected 1-indexed pages in the same order as `pages`.
+    ///
+    /// This inherent method mirrors [`PageRenderer`] so existing callers do
+    /// not need to import the trait.
+    pub fn render_pages(
+        &self,
+        pdf_bytes: &[u8],
+        pages: &[u32],
+        password: Option<&str>,
+        options: &RenderOptions,
+    ) -> Result<Vec<RenderedPage>, RenderError> {
+        self.render_pages_impl(pdf_bytes, pages, password, options)
+    }
+
+    fn render_pages_impl(
+        &self,
+        pdf_bytes: &[u8],
+        pages: &[u32],
+        password: Option<&str>,
+        options: &RenderOptions,
+    ) -> Result<Vec<RenderedPage>, RenderError> {
+        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 });
+        }
+
+        if options.form_fields {
+            document.enable_form_rendering()?;
+        }
+
+        let config = options.pdfium_config();
+        let mut rendered_pages = Vec::with_capacity(pages.len());
+        for &page_number in pages {
+            let page = document.page(page_number as usize - 1)?;
+            let size = page.size();
+            let rendered = page.render(&config)?;
+            rendered_pages.push(rendered_page_from_pdfium(
+                page_number,
+                size.width,
+                size.height,
+                options.pixel_format,
+                rendered,
+            )?);
+        }
+
+        Ok(rendered_pages)
+    }
+}
+
+impl PageRenderer for PdfiumRenderer {
+    type Error = RenderError;
+
+    fn render_pages(
+        &self,
+        pdf_bytes: &[u8],
+        pages: &[u32],
+        password: Option<&str>,
+        options: &RenderOptions,
+    ) -> Result<Vec<RenderedPage>, Self::Error> {
+        self.render_pages_impl(pdf_bytes, pages, password, options)
+    }
+}
+
+fn rendered_page_from_pdfium(
+    page: u32,
+    page_width: f32,
+    page_height: f32,
+    format: RenderPixelFormat,
+    rendered: firecrawl_pdfium::RenderedPage,
+) -> Result<RenderedPage, RenderBufferError> {
+    let width = rendered.width();
+    let height = rendered.height();
+    let stride = rendered.stride();
+    let pdfium_transform = *rendered.transform();
+    let corner = |x, y| {
+        let point = pdfium_transform.pixel_to_page(PixelPoint::new(x, y));
+        (point.x, point.y)
+    };
+    let transform = PageTransform::from_corners(
+        width,
+        height,
+        corner(0.0, 0.0),
+        corner(f64::from(width), 0.0),
+        corner(0.0, f64::from(height)),
+    )
+    .ok_or(RenderBufferError::InvalidTransform)?;
+    let mut pixels = rendered.into_pixels();
+
+    if format == RenderPixelFormat::Rgb8 {
+        bgr_to_rgb_in_place(&mut pixels, width, height, stride)?;
+    }
+
+    RenderedPage::new(
+        page,
+        page_width,
+        page_height,
+        width,
+        height,
+        stride,
+        format,
+        pixels,
+        transform,
+    )
+}
+
+fn bgr_to_rgb_in_place(
+    pixels: &mut [u8],
+    width: u32,
+    height: u32,
+    stride: usize,
+) -> Result<(), RenderBufferError> {
+    let row_bytes = (width as usize)
+        .checked_mul(RenderPixelFormat::Rgb8.bytes_per_pixel())
+        .ok_or(RenderBufferError::SizeOverflow)?;
+    if stride < row_bytes {
+        return Err(RenderBufferError::InvalidStride {
+            stride,
+            minimum: row_bytes,
+        });
+    }
+    let expected = stride
+        .checked_mul(height as usize)
+        .ok_or(RenderBufferError::SizeOverflow)?;
+    if pixels.len() != expected {
+        return Err(RenderBufferError::InvalidBufferLength {
+            actual: pixels.len(),
+            expected,
+        });
+    }
+
+    for row in pixels.chunks_exact_mut(stride) {
+        for pixel in row[..row_bytes].chunks_exact_mut(3) {
+            pixel.swap(0, 2);
+        }
+    }
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn bgr_pixels_are_converted_to_rgb_in_place() {
+        let mut pixels = vec![1, 2, 3, 4, 5, 6];
+        bgr_to_rgb_in_place(&mut pixels, 2, 1, 6).unwrap();
+        assert_eq!(pixels, [3, 2, 1, 6, 5, 4]);
+    }
+
+    #[test]
+    fn bgr_conversion_skips_row_padding() {
+        let mut pixels = vec![1, 2, 3, 9, 7, 8, 9, 6];
+        bgr_to_rgb_in_place(&mut pixels, 1, 2, 4).unwrap();
+        assert_eq!(pixels, [3, 2, 1, 9, 9, 8, 7, 6]);
+    }
+
+    #[test]
+    fn malformed_bgr_buffers_return_errors() {
+        assert!(matches!(
+            bgr_to_rgb_in_place(&mut [0; 6], 2, 1, 5),
+            Err(RenderBufferError::InvalidStride { .. })
+        ));
+        assert!(matches!(
+            bgr_to_rgb_in_place(&mut [0; 5], 1, 2, 3),
+            Err(RenderBufferError::InvalidBufferLength { .. })
+        ));
+    }
+}

src/vision/render.rs

@@ -0,0 +1,552 @@
+//! Renderer-neutral page bitmap and coordinate types.
+
+use thiserror::Error;
+
+use crate::PdfRect;
+
+/// Default rendering resolution for OCR.
+pub const DEFAULT_RENDER_DPI: f32 = 150.0;
+
+/// Default maximum size of one rendered page: 256 MiB.
+pub const DEFAULT_MAX_OUTPUT_BYTES: u64 = 256 * 1024 * 1024;
+
+/// Pixel layout returned by [`RenderedPage`].
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
+#[non_exhaustive]
+pub enum RenderPixelFormat {
+    /// Three bytes per pixel in red, green, blue order. This is the default
+    /// because OCR preprocessors conventionally consume RGB images.
+    #[default]
+    Rgb8,
+    /// Four bytes per pixel in red, green, blue, alpha order.
+    Rgba8,
+    /// One luminance byte per pixel.
+    Gray8,
+}
+
+impl RenderPixelFormat {
+    /// Number of bytes used by one pixel.
+    pub fn bytes_per_pixel(self) -> usize {
+        match self {
+            Self::Rgb8 => 3,
+            Self::Rgba8 => 4,
+            Self::Gray8 => 1,
+        }
+    }
+}
+
+/// Configuration for pages rendered as input to a local vision pipeline.
+#[derive(Debug, Clone, PartialEq)]
+pub struct RenderOptions {
+    /// Output resolution. Defaults to 150 DPI.
+    pub dpi: f32,
+    /// Pixel layout. Defaults to three-channel RGB.
+    pub pixel_format: RenderPixelFormat,
+    /// Include PDF annotations in the rendered bitmap.
+    pub annotations: bool,
+    /// Include visible static AcroForm field appearances.
+    pub form_fields: bool,
+    /// Maximum allocation for each rendered page.
+    pub max_output_bytes_per_page: u64,
+}
+
+impl Default for RenderOptions {
+    fn default() -> Self {
+        Self {
+            dpi: DEFAULT_RENDER_DPI,
+            pixel_format: RenderPixelFormat::Rgb8,
+            annotations: true,
+            form_fields: true,
+            max_output_bytes_per_page: DEFAULT_MAX_OUTPUT_BYTES,
+        }
+    }
+}
+
+impl RenderOptions {
+    /// Creates local-rendering options with OCR-oriented defaults.
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    /// Sets the output resolution in dots per inch.
+    pub fn dpi(mut self, dpi: f32) -> Self {
+        self.dpi = dpi;
+        self
+    }
+
+    /// Sets the output pixel layout.
+    pub fn pixel_format(mut self, pixel_format: RenderPixelFormat) -> Self {
+        self.pixel_format = pixel_format;
+        self
+    }
+
+    /// Toggles annotation rendering.
+    pub fn annotations(mut self, annotations: bool) -> Self {
+        self.annotations = annotations;
+        self
+    }
+
+    /// Toggles visible static form-field rendering.
+    pub fn form_fields(mut self, form_fields: bool) -> Self {
+        self.form_fields = form_fields;
+        self
+    }
+
+    /// Sets the maximum allocation for each rendered page.
+    pub fn max_output_bytes_per_page(mut self, bytes: u64) -> Self {
+        self.max_output_bytes_per_page = bytes;
+        self
+    }
+}
+
+/// A point in PDF page space, measured in points from the bottom-left.
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct PagePoint {
+    /// Horizontal position in PDF points.
+    pub x: f32,
+    /// Vertical position in PDF points, increasing upward.
+    pub y: f32,
+}
+
+/// Affine transform between top-left pixel space and PDF page space.
+///
+/// Renderers create this from the page-space images of the bitmap corners.
+/// Keeping the coefficients in pdf-inspector makes [`RenderedPage`] neutral
+/// to the renderer implementation that produced it.
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct PageTransform {
+    forward: [f64; 6],
+    inverse: [f64; 6],
+    pixel_width: u32,
+    pixel_height: u32,
+}
+
+impl PageTransform {
+    /// Builds a transform from the PDF-space images of device corners
+    /// `(0, 0)`, `(pixel_width, 0)`, and `(0, pixel_height)`.
+    pub fn from_corners(
+        pixel_width: u32,
+        pixel_height: u32,
+        origin: (f64, f64),
+        x_axis: (f64, f64),
+        y_axis: (f64, f64),
+    ) -> Option<Self> {
+        if pixel_width == 0 || pixel_height == 0 {
+            return None;
+        }
+
+        let values = [origin.0, origin.1, x_axis.0, x_axis.1, y_axis.0, y_axis.1];
+        if values.iter().any(|value| !value.is_finite()) {
+            return None;
+        }
+
+        let width = f64::from(pixel_width);
+        let height = f64::from(pixel_height);
+        let a = (x_axis.0 - origin.0) / width;
+        let c = (x_axis.1 - origin.1) / width;
+        let b = (y_axis.0 - origin.0) / height;
+        let d = (y_axis.1 - origin.1) / height;
+        let (e, f) = origin;
+        let forward = [a, b, c, d, e, f];
+        if forward.iter().any(|coefficient| !coefficient.is_finite()) {
+            return None;
+        }
+        let determinant = a * d - b * c;
+        if determinant == 0.0 || !determinant.is_finite() {
+            return None;
+        }
+
+        let inverse_a = d / determinant;
+        let inverse_b = -b / determinant;
+        let inverse_c = -c / determinant;
+        let inverse_d = a / determinant;
+        let inverse_e = -(inverse_a * e + inverse_b * f);
+        let inverse_f = -(inverse_c * e + inverse_d * f);
+        let inverse = [
+            inverse_a, inverse_b, inverse_c, inverse_d, inverse_e, inverse_f,
+        ];
+        if inverse.iter().any(|coefficient| !coefficient.is_finite()) {
+            return None;
+        }
+
+        Some(Self {
+            forward,
+            inverse,
+            pixel_width,
+            pixel_height,
+        })
+    }
+
+    /// Width of the bitmap this transform describes.
+    pub fn pixel_width(&self) -> u32 {
+        self.pixel_width
+    }
+
+    /// Height of the bitmap this transform describes.
+    pub fn pixel_height(&self) -> u32 {
+        self.pixel_height
+    }
+
+    /// Converts a bitmap point to PDF page space.
+    pub fn pixel_to_page(&self, x: f64, y: f64) -> PagePoint {
+        let [a, b, c, d, e, f] = self.forward;
+        PagePoint {
+            x: (a * x + b * y + e) as f32,
+            y: (c * x + d * y + f) as f32,
+        }
+    }
+
+    /// Converts a PDF page-space point to bitmap coordinates.
+    pub fn page_to_pixel(&self, x: f64, y: f64) -> (f64, f64) {
+        let [a, b, c, d, e, f] = self.inverse;
+        (a * x + b * y + e, c * x + d * y + f)
+    }
+}
+
+/// Invalid renderer output rejected by [`RenderedPage::new`].
+#[derive(Debug, Error, Clone, PartialEq, Eq)]
+#[non_exhaustive]
+pub enum RenderBufferError {
+    /// Page numbers are 1-indexed.
+    #[error("rendered page number must be at least 1")]
+    InvalidPageNumber,
+    /// Bitmap dimensions must be non-zero.
+    #[error("rendered bitmap dimensions must be non-zero")]
+    InvalidDimensions,
+    /// Page dimensions must be positive finite numbers.
+    #[error("rendered PDF page dimensions must be positive and finite")]
+    InvalidPageDimensions,
+    /// Transform dimensions must match the bitmap dimensions.
+    #[error("coordinate transform dimensions do not match the rendered bitmap")]
+    TransformDimensions,
+    /// Renderer did not provide an invertible finite coordinate transform.
+    #[error("renderer returned an invalid coordinate transform")]
+    InvalidTransform,
+    /// The stride cannot hold one active row of pixels.
+    #[error("pixel stride {stride} is shorter than the active row size {minimum}")]
+    InvalidStride {
+        /// Supplied bytes per row.
+        stride: usize,
+        /// Minimum bytes required for one row.
+        minimum: usize,
+    },
+    /// Pixel buffer size is inconsistent with height and stride.
+    #[error("pixel buffer has {actual} bytes; expected {expected}")]
+    InvalidBufferLength {
+        /// Actual byte count.
+        actual: usize,
+        /// Required byte count.
+        expected: usize,
+    },
+    /// Dimension arithmetic overflowed the host address space.
+    #[error("rendered bitmap dimensions overflow the host address space")]
+    SizeOverflow,
+}
+
+/// One rendered page with owned pixels and its pixel-to-PDF transform.
+///
+/// The value contains no live renderer, page, or document handles. It can be
+/// moved to an OCR worker and retained after rendering returns.
+#[derive(Debug, Clone)]
+pub struct RenderedPage {
+    page: u32,
+    page_width: f32,
+    page_height: f32,
+    width: u32,
+    height: u32,
+    stride: usize,
+    format: RenderPixelFormat,
+    pixels: Vec<u8>,
+    transform: PageTransform,
+}
+
+impl RenderedPage {
+    /// Creates a renderer-neutral owned page after validating its buffer.
+    #[allow(clippy::too_many_arguments)]
+    pub fn new(
+        page: u32,
+        page_width: f32,
+        page_height: f32,
+        width: u32,
+        height: u32,
+        stride: usize,
+        format: RenderPixelFormat,
+        pixels: Vec<u8>,
+        transform: PageTransform,
+    ) -> Result<Self, RenderBufferError> {
+        if page == 0 {
+            return Err(RenderBufferError::InvalidPageNumber);
+        }
+        if width == 0 || height == 0 {
+            return Err(RenderBufferError::InvalidDimensions);
+        }
+        if page_width <= 0.0
+            || page_height <= 0.0
+            || !page_width.is_finite()
+            || !page_height.is_finite()
+        {
+            return Err(RenderBufferError::InvalidPageDimensions);
+        }
+        if transform.pixel_width() != width || transform.pixel_height() != height {
+            return Err(RenderBufferError::TransformDimensions);
+        }
+
+        let row_bytes = (width as usize)
+            .checked_mul(format.bytes_per_pixel())
+            .ok_or(RenderBufferError::SizeOverflow)?;
+        if stride < row_bytes {
+            return Err(RenderBufferError::InvalidStride {
+                stride,
+                minimum: row_bytes,
+            });
+        }
+        let expected = stride
+            .checked_mul(height as usize)
+            .ok_or(RenderBufferError::SizeOverflow)?;
+        if pixels.len() != expected {
+            return Err(RenderBufferError::InvalidBufferLength {
+                actual: pixels.len(),
+                expected,
+            });
+        }
+
+        Ok(Self {
+            page,
+            page_width,
+            page_height,
+            width,
+            height,
+            stride,
+            format,
+            pixels,
+            transform,
+        })
+    }
+
+    /// 1-indexed page number.
+    pub fn page(&self) -> u32 {
+        self.page
+    }
+
+    /// Page width in PDF points after applying the page's rotation.
+    pub fn page_width(&self) -> f32 {
+        self.page_width
+    }
+
+    /// Page height in PDF points after applying the page's rotation.
+    pub fn page_height(&self) -> f32 {
+        self.page_height
+    }
+
+    /// Bitmap width in pixels.
+    pub fn width(&self) -> u32 {
+        self.width
+    }
+
+    /// Bitmap height in pixels.
+    pub fn height(&self) -> u32 {
+        self.height
+    }
+
+    /// Number of bytes between adjacent bitmap rows.
+    pub fn stride(&self) -> usize {
+        self.stride
+    }
+
+    /// Pixel layout of [`pixels`](Self::pixels).
+    pub fn format(&self) -> RenderPixelFormat {
+        self.format
+    }
+
+    /// Owned bitmap bytes, with rows ordered top-to-bottom.
+    pub fn pixels(&self) -> &[u8] {
+        &self.pixels
+    }
+
+    /// Consumes the page and returns its pixel buffer.
+    pub fn into_pixels(self) -> Vec<u8> {
+        self.pixels
+    }
+
+    /// Coordinate transform associated with the rendered page.
+    pub fn transform(&self) -> PageTransform {
+        self.transform
+    }
+
+    /// Converts a bitmap point (top-left origin, y-down) to PDF page space
+    /// (bottom-left origin, y-up).
+    pub fn pixel_to_page(&self, x: f64, y: f64) -> PagePoint {
+        self.transform.pixel_to_page(x, y)
+    }
+
+    /// Converts a bitmap rectangle to the repository's existing PDF-space
+    /// rectangle type. The returned page number remains 1-indexed.
+    pub fn pixel_rect_to_pdf_rect(&self, x: f64, y: f64, width: f64, height: f64) -> PdfRect {
+        let points = [
+            self.transform.pixel_to_page(x, y),
+            self.transform.pixel_to_page(x + width, y),
+            self.transform.pixel_to_page(x, y + height),
+            self.transform.pixel_to_page(x + width, y + height),
+        ];
+        let left = points
+            .iter()
+            .map(|point| point.x)
+            .fold(f32::INFINITY, f32::min);
+        let right = points
+            .iter()
+            .map(|point| point.x)
+            .fold(f32::NEG_INFINITY, f32::max);
+        let bottom = points
+            .iter()
+            .map(|point| point.y)
+            .fold(f32::INFINITY, f32::min);
+        let top = points
+            .iter()
+            .map(|point| point.y)
+            .fold(f32::NEG_INFINITY, f32::max);
+        PdfRect {
+            x: left,
+            y: bottom,
+            width: right - left,
+            height: top - bottom,
+            page: self.page,
+        }
+    }
+
+    /// Converts a PDF-space rectangle to bitmap coordinates
+    /// `(x, y, width, height)` with a top-left origin.
+    pub fn pdf_rect_to_pixel(&self, rect: &PdfRect) -> (f64, f64, f64, f64) {
+        let left = f64::from(rect.x);
+        let right = f64::from(rect.x + rect.width);
+        let bottom = f64::from(rect.y);
+        let top = f64::from(rect.y + rect.height);
+        let points = [
+            self.transform.page_to_pixel(left, bottom),
+            self.transform.page_to_pixel(right, bottom),
+            self.transform.page_to_pixel(left, top),
+            self.transform.page_to_pixel(right, top),
+        ];
+        let min_x = points
+            .iter()
+            .map(|point| point.0)
+            .fold(f64::INFINITY, f64::min);
+        let max_x = points
+            .iter()
+            .map(|point| point.0)
+            .fold(f64::NEG_INFINITY, f64::max);
+        let min_y = points
+            .iter()
+            .map(|point| point.1)
+            .fold(f64::INFINITY, f64::min);
+        let max_y = points
+            .iter()
+            .map(|point| point.1)
+            .fold(f64::NEG_INFINITY, f64::max);
+        (min_x, min_y, max_x - min_x, max_y - min_y)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn transform() -> PageTransform {
+        PageTransform::from_corners(400, 200, (0.0, 100.0), (200.0, 100.0), (0.0, 0.0)).unwrap()
+    }
+
+    #[test]
+    fn transform_maps_both_directions_at_non_identity_scale() {
+        let transform = transform();
+        let point = transform.pixel_to_page(100.0, 50.0);
+        assert!((point.x - 50.0).abs() < 1e-6);
+        assert!((point.y - 75.0).abs() < 1e-6);
+        let pixel = transform.page_to_pixel(f64::from(point.x), f64::from(point.y));
+        assert!((pixel.0 - 100.0).abs() < 1e-6);
+        assert!((pixel.1 - 50.0).abs() < 1e-6);
+    }
+
+    #[test]
+    fn rendered_page_accepts_padding_and_validates_length() {
+        let page = RenderedPage::new(
+            1,
+            200.0,
+            100.0,
+            400,
+            200,
+            1_204,
+            RenderPixelFormat::Rgb8,
+            vec![0; 1_204 * 200],
+            transform(),
+        )
+        .unwrap();
+        assert_eq!(page.stride(), 1_204);
+
+        assert!(matches!(
+            RenderedPage::new(
+                1,
+                200.0,
+                100.0,
+                400,
+                200,
+                1_204,
+                RenderPixelFormat::Rgb8,
+                vec![0; 5],
+                transform(),
+            ),
+            Err(RenderBufferError::InvalidBufferLength { .. })
+        ));
+    }
+
+    #[test]
+    fn rotated_transform_round_trips_rectangles() {
+        let transform =
+            PageTransform::from_corners(100, 200, (0.0, 0.0), (0.0, 100.0), (200.0, 0.0)).unwrap();
+        let page = RenderedPage::new(
+            1,
+            200.0,
+            100.0,
+            100,
+            200,
+            300,
+            RenderPixelFormat::Rgb8,
+            vec![0; 300 * 200],
+            transform,
+        )
+        .unwrap();
+        let pdf = page.pixel_rect_to_pdf_rect(10.0, 20.0, 30.0, 40.0);
+        let pixel = page.pdf_rect_to_pixel(&pdf);
+        assert!((pixel.0 - 10.0).abs() < 1e-5);
+        assert!((pixel.1 - 20.0).abs() < 1e-5);
+        assert!((pixel.2 - 30.0).abs() < 1e-5);
+        assert!((pixel.3 - 40.0).abs() < 1e-5);
+    }
+
+    #[test]
+    fn skewed_transform_bounds_all_rectangle_corners() {
+        let transform =
+            PageTransform::from_corners(100, 100, (0.0, 100.0), (100.0, 125.0), (25.0, 0.0))
+                .unwrap();
+        let page = RenderedPage::new(
+            1,
+            125.0,
+            125.0,
+            100,
+            100,
+            300,
+            RenderPixelFormat::Rgb8,
+            vec![0; 30_000],
+            transform,
+        )
+        .unwrap();
+
+        let pdf = page.pixel_rect_to_pdf_rect(10.0, 20.0, 30.0, 40.0);
+        assert!((pdf.x - 15.0).abs() < 1e-5);
+        assert!((pdf.y - 42.5).abs() < 1e-5);
+        assert!((pdf.width - 40.0).abs() < 1e-5);
+        assert!((pdf.height - 47.5).abs() < 1e-5);
+
+        let pixels = page.pdf_rect_to_pixel(&pdf);
+        assert!(pixels.0 <= 10.0 && pixels.1 <= 20.0);
+        assert!(pixels.0 + pixels.2 >= 40.0 && pixels.1 + pixels.3 >= 60.0);
+    }
+}

tests/local_render_tests.rs

@@ -0,0 +1,65 @@
+#![cfg(all(feature = "render-pdfium", not(target_arch = "wasm32")))]
+
+use pdf_inspector::vision::{PdfiumRenderer, RenderError, RenderOptions, RenderPixelFormat};
+
+fn load_renderer() -> Option<PdfiumRenderer> {
+    match PdfiumRenderer::load() {
+        Ok(renderer) => Some(renderer),
+        Err(RenderError::Pdfium(firecrawl_pdfium::Error::Load(
+            firecrawl_pdfium::LoadError::LibraryNotFound { .. },
+        ))) => {
+            eprintln!("skipping PDFium runtime test because no native library is installed");
+            None
+        }
+        Err(error) => panic!("failed to load PDFium: {error}"),
+    }
+}
+
+#[test]
+fn renders_owned_rgb_page_and_round_trips_coordinates() {
+    let Some(renderer) = load_renderer() else {
+        return;
+    };
+    let bytes = std::fs::read("tests/fixtures/thermo-freon12.pdf").unwrap();
+    let pages = renderer
+        .render_pages(
+            &bytes,
+            &[1],
+            None,
+            &RenderOptions::new().dpi(150.0).form_fields(false),
+        )
+        .unwrap();
+
+    assert_eq!(pages.len(), 1);
+    let page = &pages[0];
+    assert_eq!(page.page(), 1);
+    assert_eq!(page.format(), RenderPixelFormat::Rgb8);
+    assert_eq!(page.stride(), page.width() as usize * 3);
+    assert_eq!(page.pixels().len(), page.stride() * page.height() as usize);
+    assert!((page.width() as f32 - page.page_width()).abs() > 1.0);
+
+    let pdf_rect = page.pixel_rect_to_pdf_rect(10.0, 10.0, 20.0, 12.0);
+    let pixel_rect = page.pdf_rect_to_pixel(&pdf_rect);
+    assert!((pixel_rect.0 - 10.0).abs() < 0.01);
+    assert!((pixel_rect.1 - 10.0).abs() < 0.01);
+    assert!((pixel_rect.2 - 20.0).abs() < 0.01);
+    assert!((pixel_rect.3 - 12.0).abs() < 0.01);
+}
+
+#[test]
+fn rejects_zero_and_out_of_range_page_numbers() {
+    let Some(renderer) = load_renderer() else {
+        return;
+    };
+    let bytes = std::fs::read("tests/fixtures/thermo-freon12.pdf").unwrap();
+
+    assert!(matches!(
+        renderer.render_pages(&bytes, &[0], None, &RenderOptions::new()),
+        Err(RenderError::InvalidPageNumber)
+    ));
+
+    assert!(matches!(
+        renderer.render_pages(&bytes, &[u32::MAX], None, &RenderOptions::new()),
+        Err(RenderError::PageOutOfBounds { .. })
+    ));
+}

tests/snapshots/real-estate-pricing.md

@@ -46,9 +46,9 @@ more about investing in tax losses than burst, cap rates spreads steadily com- r
 
 8 6 Z E L L / L U R I E R E A L E S T A T E C E N T E R
 
-ingdebtspreadswerepartoforiginalpro formamodels.Thiscapratespreadcom- pressionoffsetweakcashflowsinapost- recessionary economy from 2002 to 2005, while continued compression, combined with improved cash flows, pushed property values skyward in 2006 throughmid-2007. Cap rate compression reduced the importance of the ability to add value. After all, if all you had to do to make moneywastoleveragetothehiltwhilecap ratesfell,whytakeontheextraworkand riskofattemptingtoaddvalue?Stateddif- ferently: Why print money if it is laying everywhereonthestreets? In Tables III and IV, we demonstrate thepowerofcapratecompressionviavery simple pro forma cash flow analyses that assume Year 1 NOI of $100; a going-in cap rate of 9 percent; an LTV of 70 per- cent; and an interest rate of 7 percent. Withineachfigure,wedisplaytwoscenar- ios, which vary based on NOI growth assumptions.ScenarioIassumesthatNOI growsby3percentperyear,whileScenario IIassumesavalue-addNOIgrowthof20 percentbetweenyearstwoandthree. The only other difference between TablesIIIandIVisinresidualcaprates, which are assumed to be 6 percent and 9 percent, respectively. Based on these assumptions, we calculate the equity IRRs. It is clear that cap rate compres- sion is a significant factor in driving
+ingdebtspreadswerepartoforiginalpro formamodels.Thiscapratespreadcom- pressionoffsetweakcashflowsinapost- recessionary economy from 2002 to 2005, while continued compression, combined with improved cash flows, pushed property values skyward in 2006 throughmid-2007. Cap rate compression reduced the importance of the ability to add value. After all, if all you had to do to make moneywastoleveragetothehiltwhilecap ratesfell,whytakeontheextraworkand riskofattemptingtoaddvalue?Stateddif- ferently: Why print money if it is laying everywhereonthestreets? In Tables III and IV, we demonstrate thepowerofcapratecompressionviavery simple pro forma cash flow analyses that assume Year 1 NOI of $100; a going-in cap rate of 9 percent; an LTV of 70 percent; and an interest rate of 7 percent. Withineachfigure,wedisplaytwoscenar- ios, which vary based on NOI growth assumptions.ScenarioIassumesthatNOI growsby3percentperyear,whileScenario IIassumesavalue-addNOIgrowthof20 percentbetweenyearstwoandthree. The only other difference between TablesIIIandIVisinresidualcaprates, which are assumed to be 6 percent and 9 percent, respectively. Based on these assumptions, we calculate the equity IRRs. It is clear that cap rate compression is a significant factor in driving
 
-returns. That is, cap rate compression from 9 percent to 6 percent increased IRR on leveraged stabilized properties by 250 percent, to a staggering 57 per- cent. Who needs to take on value add riskatthisreturnforstabilizedassets? Intheearly1980s,moneywasmadein real estate by mastering the creation and syndication of tax gimmicks. In the late 1980s, one made money by mastering bank and S&L connections to over-lever- age.Intheearly1990s,onemademoneyin realestatebyhavingaccesstoequity—the morethebetter.Duringthelate1990s,one made money from real estate by realizing large spreads between cap rates and debt costs.And,overthepastfiveyears,theway to make money in real estate was to own realestateonahighlyleveragedbasisascap ratesplunged. Theclassicassetpricingmodelisthe capital asset pricing model (CAPM). CAPM is a simple, yet elegant, model that relates asset pricing to the risk-free rate(F),theabilityofanassettoreduce portfolio variance (B), and the expected rate of return on the market bundle of investableassets(M).CAPMisfarfrom perfect,butprovidesacrudebenchmark for asset pricing, around which discrep- ancies and novelties arise. Specifically, CAPM states that an asset’s price is set suchthattheexpectedreturnforanasset
+returns. That is, cap rate compression from 9 percent to 6 percent increased IRR on leveraged stabilized properties by 250 percent, to a staggering 57 percent. Who needs to take on value add riskatthisreturnforstabilizedassets? Intheearly1980s,moneywasmadein real estate by mastering the creation and syndication of tax gimmicks. In the late 1980s, one made money by mastering bank and S&L connections to over-leverage.Intheearly1990s,onemademoneyin realestatebyhavingaccesstoequity—the morethebetter.Duringthelate1990s,one made money from real estate by realizing large spreads between cap rates and debt costs.And,overthepastfiveyears,theway to make money in real estate was to own realestateonahighlyleveragedbasisascap ratesplunged. Theclassicassetpricingmodelisthe capital asset pricing model (CAPM). CAPM is a simple, yet elegant, model that relates asset pricing to the risk-free rate(F),theabilityofanassettoreduce portfolio variance (B), and the expected rate of return on the market bundle of investableassets(M).CAPMisfarfrom perfect,butprovidesacrudebenchmark for asset pricing, around which discrep- ancies and novelties arise. Specifically, CAPM states that an asset’s price is set suchthattheexpectedreturnforanasset
 
 (R)is R=F+ β(M-F).
 R E V I E W 8 7

tests/snapshots/shannon-entropy-p1-2.md

@@ -14,7 +14,7 @@ basis for such a theory is contained in the important papers of Nyquist¹ and Ha
 
 1. It is practically more useful. Parameters of engineering importance such as time, bandwidth, number of relays, etc., tend to vary linearly with the logarithm of the number of possibilities. For example, adding one relay to a group doubles the number of possible states of the relays. It adds 1 to the base 2 logarithm of this number. Doubling the time roughly squares the number of possible messages, or doubles the logarithm, etc.
 2. It is nearer to our intuitive feeling as to the proper measure. This is closely related to (1) since we in- tuitively measures entities by linear comparison with common standards. One feels, for example, that two punched cards should have twice the capacity of one for information storage, and two identical channels twice the capacity of one for transmitting information.
-3. It is mathematically more suitable. Many of the limiting operations are simple in terms of the loga- rithm but would require clumsy restatement in terms of the number of possibilities. The choice of a logarithmic base corresponds to the choice of a unit for measuring information. If the
+3. It is mathematically more suitable. Many of the limiting operations are simple in terms of the logarithm but would require clumsy restatement in terms of the number of possibilities. The choice of a logarithmic base corresponds to the choice of a unit for measuring information. If the
 base 2 is used the resulting units may be called binary digits, or more briefly *bits,* a word suggested by
 
 J. W. Tukey. A device with two stable positions, such as a relay or a flip-flop circuit, can store one bit of information. *N* such devices can store*N* bits, since the total number of possible states is 2
@@ -34,8 +34,8 @@ Fig. 1 — Schematic diagram of a general communication system.
 
 a decimal digit is about 3 13 bits. A digit wheel on a desk computing machine has ten stable positions and therefore has a storage capacity of one decimal digit. In analytical work where integration and differentiation are involved the base *e* is sometimes useful. The resulting units of information will be called natural units. Change from the base *a* to base *b* merely requires multiplication by log*ba*. By a communication system we will mean a system of the type indicated schematically in Fig. 1. It consists of essentially five parts:
 
-1. An *information source* which produces a message or sequence of messages to be communicated to the receiving terminal. The message may be of various types: (a) A sequence of letters as in a telegraph of teletype system; (b) A single function of time *f* (*t*) as in radio or telephony; (c) A function of time and other variables as in black and white television — here the message may be thought of as a function *f* (*x*; *y*;*t*) of two space coordinates and time, the light intensity at point (*x*; *y*) and time *t* on a pickup tube plate; (d) Two or more functions of time, say *f* (*t*), *g*(*t*), *h*(*t*) — this is the case in “three- dimensional” sound transmission or if the system is intended to service several individual channels in multiplex; (e) Several functions of several variables — in color television the message consists of three functions *f* (*x*; *y*;*t*), *g*(*x*; *y*;*t*), *h*(*x*; *y*;*t*) defined in a three-dimensional continuum — we may also think of these three functions as components of a vector field defined in the region — similarly, several black and white television sources would produce “messages” consisting of a number of functions of three variables; (f) Various combinations also occur, for example in television with an associated audio channel.
-2. A *transmitter* which operates on the message in some way to produce a signal suitable for trans- mission over the channel. In telephony this operation consists merely of changing sound pressure into a proportional electrical current. In telegraphy we have an encoding operation which produces a sequence of dots, dashes and spaces on the channel corresponding to the message. In a multiplex PCM system the different speech functions must be sampled, compressed, quantized and encoded, and finally interleaved properly to construct the signal. Vocoder systems, television and frequency modulation are other examples of complex operations applied to the message to obtain the signal.
+1. An *information source* which produces a message or sequence of messages to be communicated to the receiving terminal. The message may be of various types: (a) A sequence of letters as in a telegraph of teletype system; (b) A single function of time *f* (*t*) as in radio or telephony; (c) A function of time and other variables as in black and white television — here the message may be thought of as a function *f* (*x*; *y*;*t*) of two space coordinates and time, the light intensity at point (*x*; *y*) and time *t* on a pickup tube plate; (d) Two or more functions of time, say *f* (*t*), *g*(*t*), *h*(*t*) — this is the case in “three-dimensional” sound transmission or if the system is intended to service several individual channels in multiplex; (e) Several functions of several variables — in color television the message consists of three functions *f* (*x*; *y*;*t*), *g*(*x*; *y*;*t*), *h*(*x*; *y*;*t*) defined in a three-dimensional continuum — we may also think of these three functions as components of a vector field defined in the region — similarly, several black and white television sources would produce “messages” consisting of a number of functions of three variables; (f) Various combinations also occur, for example in television with an associated audio channel.
+2. A *transmitter* which operates on the message in some way to produce a signal suitable for transmission over the channel. In telephony this operation consists merely of changing sound pressure into a proportional electrical current. In telegraphy we have an encoding operation which produces a sequence of dots, dashes and spaces on the channel corresponding to the message. In a multiplex PCM system the different speech functions must be sampled, compressed, quantized and encoded, and finally interleaved properly to construct the signal. Vocoder systems, television and frequency modulation are other examples of complex operations applied to the message to obtain the signal.
 3. The *channel* is merely the medium used to transmit the signal from transmitter to receiver. It may be a pair of wires, a coaxial cable, a band of radio frequencies, a beam of light, etc.
 4. The *receiver* ordinarily performs the inverse operation of that done by the transmitter, reconstructing the message from the signal.
 5. The *destination* is the person (or thing) for whom the message is intended. We wish to consider certain general problems involving communication systems. To do this it is first