fix staggered newspaper column ordering

* fix(extractor): flag garbled text spans for OCR

* fix(extractor): apply text quality checks to regions

* chore(napi): bump npm package version

.github/workflows/ci.yml

@@ -20,17 +20,7 @@ jobs:
         uses: dtolnay/rust-toolchain@stable
 
       - name: Cache cargo
-        uses: actions/cache@v4
-        with:
-          path: |
-            ~/.cargo/bin/
-            ~/.cargo/registry/index/
-            ~/.cargo/registry/cache/
-            ~/.cargo/git/db/
-            target/
-          key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}
-          restore-keys: |
-            ${{ runner.os }}-cargo-
+        uses: Swatinem/rust-cache@v2
 
       - name: Run tests
         run: cargo test --verbose
@@ -61,17 +51,9 @@ jobs:
           components: clippy
 
       - name: Cache cargo
-        uses: actions/cache@v4
+        uses: Swatinem/rust-cache@v2
         with:
-          path: |
-            ~/.cargo/bin/
-            ~/.cargo/registry/index/
-            ~/.cargo/registry/cache/
-            ~/.cargo/git/db/
-            target/
-          key: ${{ runner.os }}-cargo-clippy-${{ hashFiles('**/Cargo.lock') }}
-          restore-keys: |
-            ${{ runner.os }}-cargo-clippy-
+          key: clippy
 
       - name: Run clippy
         run: cargo clippy -- -D warnings
@@ -89,17 +71,9 @@ jobs:
         uses: dtolnay/rust-toolchain@stable
 
       - name: Cache cargo
-        uses: actions/cache@v4
+        uses: Swatinem/rust-cache@v2
         with:
-          path: |
-            ~/.cargo/bin/
-            ~/.cargo/registry/index/
-            ~/.cargo/registry/cache/
-            ~/.cargo/git/db/
-            target/
-          key: ${{ runner.os }}-cargo-build-${{ hashFiles('**/Cargo.lock') }}
-          restore-keys: |
-            ${{ runner.os }}-cargo-build-
+          key: build
 
       - name: Build
         run: cargo build --release --verbose

.github/workflows/publish-crate.yml

@@ -0,0 +1,87 @@
+name: Publish Rust crate
+
+on:
+  push:
+    branches: [main]
+    paths: ['Cargo.toml']
+
+permissions:
+  contents: read
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  check-version:
+    name: Check version change
+    runs-on: ubuntu-latest
+    outputs:
+      changed: ${{ steps.check.outputs.changed }}
+      published: ${{ steps.check.outputs.published }}
+      version: ${{ steps.check.outputs.version }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 2
+
+      - name: Check if version changed
+        id: check
+        run: |
+          NEW_VERSION=$(python3 -c 'import pathlib, tomllib; print(tomllib.loads(pathlib.Path("Cargo.toml").read_text())["package"]["version"])')
+          OLD_VERSION=$(git show HEAD~1:Cargo.toml | python3 -c 'import sys, tomllib; print(tomllib.loads(sys.stdin.read())["package"]["version"])')
+          echo "old=$OLD_VERSION new=$NEW_VERSION"
+          echo "version=$NEW_VERSION" >> "$GITHUB_OUTPUT"
+
+          if [ "$NEW_VERSION" = "$OLD_VERSION" ]; then
+            echo "changed=false" >> "$GITHUB_OUTPUT"
+            echo "published=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          echo "changed=true" >> "$GITHUB_OUTPUT"
+
+          HTTP_STATUS=$(curl --silent --show-error --output /tmp/crate-version.json --write-out "%{http_code}" \
+            -H "User-Agent: firecrawl/pdf-inspector publish workflow (https://github.com/firecrawl/pdf-inspector)" \
+            "https://crates.io/api/v1/crates/pdf-inspector/$NEW_VERSION")
+
+          case "$HTTP_STATUS" in
+            200)
+              echo "published=true" >> "$GITHUB_OUTPUT"
+              echo "pdf-inspector v$NEW_VERSION is already published"
+              ;;
+            404)
+              echo "published=false" >> "$GITHUB_OUTPUT"
+              ;;
+            *)
+              cat /tmp/crate-version.json
+              echo "Unexpected crates.io response: $HTTP_STATUS" >&2
+              exit 1
+              ;;
+          esac
+
+  publish:
+    name: Publish to crates.io
+    needs: check-version
+    if: needs.check-version.outputs.changed == 'true' && needs.check-version.outputs.published == 'false'
+    runs-on: ubuntu-latest
+    environment: crates-io
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Rust
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Verify package
+        run: cargo publish --dry-run
+
+      - name: Authenticate with crates.io
+        id: auth
+        uses: rust-lang/crates-io-auth-action@v1
+
+      - name: Publish crate
+        run: cargo publish
+        env:
+          CARGO_REGISTRY_TOKEN: ${{ steps.auth.outputs.token }}

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "pdf-inspector"
-version = "0.1.0"
+version = "0.1.2"
 edition = "2021"
 autobins = false
 authors = ["Firecrawl Team"]
@@ -17,7 +17,7 @@ crate-type = ["lib", "cdylib"]
 pyo3 = { version = "0.25", features = ["extension-module"], optional = true }
 
 # PDF parsing
-lopdf = { git = "https://github.com/J-F-Liu/lopdf", rev = "7a05512d831415b1f2b1ce522391d6beab8a1284", features = ["rayon"] }
+lopdf = { version = "0.41.0", features = ["rayon"] }
 
 # Error handling
 thiserror = "2.0"

README.md

@@ -1,5 +1,8 @@
 # pdf-inspector
 
+[![Crates.io](https://img.shields.io/crates/v/pdf-inspector.svg)](https://crates.io/crates/pdf-inspector)
+[![npm](https://img.shields.io/npm/v/@firecrawl/pdf-inspector.svg)](https://www.npmjs.com/package/@firecrawl/pdf-inspector)
+
 Fast Rust library for 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. Includes bindings for [Python](docs/python.md) and [Node.js](napi/README.md).
 
 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.
@@ -71,9 +74,17 @@ console.log(result.markdown);  // Markdown string or null
 
 ### Rust
 
+Install from [crates.io](https://crates.io/crates/pdf-inspector):
+
+```bash
+cargo add pdf-inspector
+```
+
+Or add it manually:
+
 ```toml
 [dependencies]
-pdf-inspector = { git = "https://github.com/firecrawl/pdf-inspector" }
+pdf-inspector = "0.1"
 ```
 
 ```rust
@@ -91,29 +102,34 @@ if let Some(markdown) = &result.markdown {
 ### CLI
 
 ```bash
+# Install the CLI tools
+cargo install pdf-inspector
+
 # Convert PDF to Markdown
-cargo run --bin pdf2md -- document.pdf
+pdf2md document.pdf
 
 # JSON output (for piping)
-cargo run --bin pdf2md -- document.pdf --json
+pdf2md document.pdf --json
 
 # Raw markdown only (no headers)
-cargo run --bin pdf2md -- document.pdf --raw
+pdf2md document.pdf --raw
 
 # Insert page break markers (<!-- Page N -->)
-cargo run --bin pdf2md -- document.pdf --pages
+pdf2md document.pdf --pages
 
 # Process only specific pages
-cargo run --bin pdf2md -- document.pdf --select-pages 1,3,5-10
+pdf2md document.pdf --select-pages 1,3,5-10
 
 # Detection only (no extraction)
-cargo run --bin detect-pdf -- document.pdf
-cargo run --bin detect-pdf -- document.pdf --json
+detect-pdf document.pdf
+detect-pdf document.pdf --json
 
 # Detection + layout analysis (tables, columns)
-cargo run --bin detect-pdf -- document.pdf --analyze --json
+detect-pdf document.pdf --analyze --json
 ```
 
+From a source checkout, use `cargo run --bin pdf2md -- document.pdf` or `cargo run --bin detect-pdf -- document.pdf` instead.
+
 ## Architecture
 
 ```

SECURITY.md

@@ -0,0 +1,33 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+If you believe you've found a security vulnerability in pdf-inspector, please
+report it privately so we can fix it before public disclosure.
+
+**Preferred:** Email **help@firecrawl.dev** with:
+
+- A description of the issue and its impact
+- Steps to reproduce (a minimal PDF or input that triggers the bug is ideal)
+- The version or commit hash of pdf-inspector you tested against
+
+**Alternative:** Use GitHub's private vulnerability reporting under the
+[Security tab](https://github.com/firecrawl/pdf-inspector/security/advisories/new).
+
+We'll acknowledge your report in a timely manner and keep you updated on
+remediation progress. Please do not open a public GitHub issue for security
+bugs.
+
+## Scope
+
+In scope:
+- Memory-safety issues (panics, OOB reads, UB) reachable from a crafted PDF
+- Denial-of-service vectors (unbounded allocation, infinite loops) on
+  reasonably-sized inputs
+- Bugs in the `pdf2md` / `detect-pdf` binaries or the `pdf-inspector` crate
+  that affect downstream consumers
+
+Out of scope:
+- Bugs in upstream dependencies (`lopdf`, etc.) — please report those upstream
+- Extraction quality issues (wrong text, missing tables) — open a regular
+  GitHub issue instead

docs/publishing.md

@@ -0,0 +1,21 @@
+# Publishing
+
+The Rust crate is published to [crates.io](https://crates.io/crates/pdf-inspector) with trusted publishing from GitHub Actions. The first release was published manually; future releases publish from `.github/workflows/publish-crate.yml` when a `Cargo.toml` version change lands on `main`.
+
+## crates.io Trusted Publisher
+
+Configure the trusted publisher for the `pdf-inspector` crate with:
+
+- Repository: `firecrawl/pdf-inspector`
+- Workflow: `publish-crate.yml`
+- Environment: `crates-io`
+
+The workflow uses `rust-lang/crates-io-auth-action@v1` to exchange GitHub's OIDC token for a short-lived crates.io token, then passes it to `cargo publish`.
+
+## Release Steps
+
+1. Update `version` in `Cargo.toml`.
+2. Merge the version bump to `main`.
+3. The publish workflow compares the new `Cargo.toml` version with `HEAD~1`, runs `cargo publish --dry-run`, then publishes if that version is not already on crates.io.
+
+If `Cargo.toml` changes without a package version bump, the workflow exits without publishing.

napi/Cargo.lock

@@ -672,8 +672,9 @@ checksum = "5e5032e24019045c762d3c0f28f5b6b8bbf38563a65908389bf7978758920897"
 
 [[package]]
 name = "lopdf"
-version = "0.40.0"
-source = "git+https://github.com/J-F-Liu/lopdf?rev=7a05512d831415b1f2b1ce522391d6beab8a1284#7a05512d831415b1f2b1ce522391d6beab8a1284"
+version = "0.41.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "67513274c50a2b51e5f75d9e682fcf4ab064a8a9c9ae2c3c59309084882bb24d"
 dependencies = [
  "aes",
  "bitflags",
@@ -829,7 +830,7 @@ checksum = "384b8ab6d37215f3c5301a95a4accb5d64aa607f1fcb26a11b5303878451b4fe"
 
 [[package]]
 name = "pdf-inspector"
-version = "0.1.0"
+version = "0.1.1"
 dependencies = [
  "env_logger",
  "log",
@@ -844,7 +845,7 @@ dependencies = [
 
 [[package]]
 name = "pdf-inspector-napi"
-version = "0.2.0"
+version = "0.2.1"
 dependencies = [
  "napi",
  "napi-build",

napi/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "pdf-inspector-napi"
-version = "0.2.0"
+version = "0.2.1"
 edition = "2021"
 
 [lib]

napi/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@firecrawl/pdf-inspector",
-  "version": "1.8.7",
+  "version": "1.9.7",
   "description": "Fast PDF classification and text extraction. Detect text-based vs scanned PDFs, extract text by region with quality checks. Native Rust performance via napi-rs.",
   "main": "index.js",
   "types": "index.d.ts",

napi/probe-doc.mjs

@@ -1,64 +0,0 @@
-#!/usr/bin/env node
-// Generalized one-shot probe: run detectVectorGridInRegion against a single
-// PDF + region without spinning up the api or the bench.
-//
-// Usage:
-//   node probe-doc.mjs <pdf-path> [page] [bbox] [dpi]
-//
-// pdf-path : path to a PDF on disk (required)
-// page     : 0-indexed page number (default 0)
-// bbox     : "x0,y0,x1,y1" in PDF points (default = full standard letter)
-// dpi      : render dpi (default 200)
-//
-// Examples:
-//   node probe-doc.mjs ~/Code/opendataloader-bench/pdfs/01030000000127.pdf 0
-//   node probe-doc.mjs /tmp/foo.pdf 3 "50,100,560,700" 200
-//   node probe-doc.mjs /tmp/foo.pdf       # page 0, full page, dpi 200
-//
-// Prints: cells / rows / cols / null. Useful for fast pdf-inspector loops:
-//   cargo build --release && bun run build:debug && node probe-doc.mjs ...
-
-import { readFileSync, existsSync } from "node:fs";
-import { createRequire } from "node:module";
-
-const require = createRequire(import.meta.url);
-const { detectVectorGridInRegion } = require("./index.js");
-
-const [, , pdfPath, pageArg, bboxArg, dpiArg] = process.argv;
-
-if (!pdfPath) {
-  console.error("usage: node probe-doc.mjs <pdf-path> [page] [bbox] [dpi]");
-  process.exit(2);
-}
-if (!existsSync(pdfPath)) {
-  console.error(`pdf not found: ${pdfPath}`);
-  process.exit(2);
-}
-
-const page = pageArg !== undefined ? Number(pageArg) : 0;
-const bbox = bboxArg
-  ? bboxArg.split(",").map(Number)
-  : [0, 0, 612, 792]; // standard US letter
-const dpi = dpiArg !== undefined ? Number(dpiArg) : 200;
-
-if (bbox.length !== 4 || bbox.some(Number.isNaN)) {
-  console.error(`invalid bbox "${bboxArg}", expected "x0,y0,x1,y1"`);
-  process.exit(2);
-}
-
-const pdf = readFileSync(pdfPath);
-
-const t0 = Date.now();
-const result = detectVectorGridInRegion(pdf, page, bbox, dpi);
-const ms = Date.now() - t0;
-
-if (!result) {
-  console.log(`null (${ms}ms)  page=${page} bbox=${bbox.join(",")} dpi=${dpi}`);
-  process.exit(0);
-}
-
-const rows = result.structureTokens.filter((t) => t === "<tr>").length;
-const cols = rows > 0 ? result.cellBboxes.length / rows : 0;
-console.log(
-  `cells=${result.cellBboxes.length} rows=${rows} cols=${cols} (${ms}ms)  page=${page} bbox=${bbox.join(",")} dpi=${dpi}`,
-);

src/extractor/content_stream.rs

@@ -18,7 +18,7 @@ use super::fonts::{
     get_font_file2_obj_num, get_operand_bytes, CMapDecisionCache,
 };
 use super::xobjects::{extract_form_xobject_text, get_page_xobjects, XObjectType};
-use super::{get_number, multiply_matrices};
+use super::{get_number, image_bbox_from_ctm, multiply_matrices};
 
 /// Strip PDF comments (% to end of line) from content stream bytes.
 ///
@@ -188,7 +188,17 @@ pub(crate) fn extract_page_text_items(
     // Graphics state tracking
     let mut ctm = [1.0f32, 0.0, 0.0, 1.0, 0.0, 0.0]; // Current Transformation Matrix
     let mut text_rendering_mode: i32 = 0; // 0=fill, 1=stroke, 2=fill+stroke, 3=invisible
-    let mut gstate_stack: Vec<([f32; 6], i32, f32, f32)> = Vec::new();
+    #[derive(Clone)]
+    struct SavedGraphicsState {
+        ctm: [f32; 6],
+        text_rendering_mode: i32,
+        char_spacing: f32,
+        word_spacing: f32,
+        text_leading: f32,
+        current_font: String,
+        current_font_size: f32,
+    }
+    let mut gstate_stack: Vec<SavedGraphicsState> = Vec::new();
 
     // Text state tracking
     let mut current_font = String::new();
@@ -227,15 +237,26 @@ pub(crate) fn extract_page_text_items(
         match op.operator.as_str() {
             "q" => {
                 // Save graphics state
-                gstate_stack.push((ctm, text_rendering_mode, char_spacing, word_spacing));
+                gstate_stack.push(SavedGraphicsState {
+                    ctm,
+                    text_rendering_mode,
+                    char_spacing,
+                    word_spacing,
+                    text_leading,
+                    current_font: current_font.clone(),
+                    current_font_size,
+                });
             }
             "Q" => {
                 // Restore graphics state
-                if let Some((saved_ctm, saved_tr, saved_tc, saved_tw)) = gstate_stack.pop() {
-                    ctm = saved_ctm;
-                    text_rendering_mode = saved_tr;
-                    char_spacing = saved_tc;
-                    word_spacing = saved_tw;
+                if let Some(saved) = gstate_stack.pop() {
+                    ctm = saved.ctm;
+                    text_rendering_mode = saved.text_rendering_mode;
+                    char_spacing = saved.char_spacing;
+                    word_spacing = saved.word_spacing;
+                    text_leading = saved.text_leading;
+                    current_font = saved.current_font;
+                    current_font_size = saved.current_font_size;
                 }
             }
             "cm" => {
@@ -664,7 +685,29 @@ pub(crate) fn extract_page_text_items(
                         if let Some(xobj_type) = xobjects.get(&xobj_name) {
                             match xobj_type {
                                 XObjectType::Image => {
-                                    // Skip images — text extraction only
+                                    // Emit a positional placeholder for the image
+                                    // so downstream consumers (layout-aware
+                                    // pipelines, figure-OCR routers) can locate
+                                    // raster figures without parsing the PDF
+                                    // again. The text field carries the
+                                    // XObject resource name in the legacy
+                                    // `[Image: Im0]` format that the markdown
+                                    // emitter already recognizes.
+                                    let (x, y, width, height) = image_bbox_from_ctm(&ctm);
+                                    items.push(TextItem {
+                                        text: format!("[Image: {}]", xobj_name),
+                                        x,
+                                        y,
+                                        width,
+                                        height,
+                                        font: String::new(),
+                                        font_size: 0.0,
+                                        page: page_num,
+                                        is_bold: false,
+                                        is_italic: false,
+                                        item_type: ItemType::Image,
+                                        mcid: current_mcid(&marked_content_stack),
+                                    });
                                 }
                                 XObjectType::Form(form_id) => {
                                     // Extract text from Form XObject
@@ -1264,6 +1307,91 @@ mod tests {
         assert!(lines.is_empty());
     }
 
+    #[test]
+    fn test_q_restores_current_font_for_text_decoding() {
+        use crate::tounicode::FontCMaps;
+        use lopdf::{dictionary, Object, Stream};
+
+        fn cmap_stream(dst_hex: &str) -> Stream {
+            let cmap = format!(
+                r#"/CIDInit /ProcSet findresource begin
+12 dict begin
+begincmap
+/CIDSystemInfo << /Registry (Adobe) /Ordering (UCS) /Supplement 0 >> def
+/CMapName /Test-UCS def
+/CMapType 2 def
+1 begincodespacerange
+<00> <FF>
+endcodespacerange
+1 beginbfchar
+<41> <{dst_hex}>
+endbfchar
+endcmap
+CMapName currentdict /CMap defineresource pop
+end
+end"#
+            );
+            Stream::new(dictionary! {}, cmap.into_bytes())
+        }
+
+        let mut doc = lopdf::Document::new();
+        let f1_cmap = doc.add_object(Object::Stream(cmap_stream("0058"))); // X
+        let f2_cmap = doc.add_object(Object::Stream(cmap_stream("0059"))); // Y
+        let f1 = doc.add_object(dictionary! {
+            "Type" => "Font",
+            "Subtype" => "Type1",
+            "BaseFont" => "Helvetica",
+            "ToUnicode" => Object::Reference(f1_cmap),
+        });
+        let f2 = doc.add_object(dictionary! {
+            "Type" => "Font",
+            "Subtype" => "Type1",
+            "BaseFont" => "Helvetica",
+            "ToUnicode" => Object::Reference(f2_cmap),
+        });
+
+        let content = b"BT /F1 12 Tf 10 700 Tm <41> Tj ET
+q
+BT /F2 12 Tf 20 700 Tm <41> Tj ET
+Q
+BT 30 700 Tm <41> Tj ET";
+        let content_id = doc.add_object(Object::Stream(Stream::new(
+            dictionary! {},
+            content.to_vec(),
+        )));
+        let page_id = doc.add_object(dictionary! {
+            "Type" => "Page",
+            "Contents" => Object::Reference(content_id),
+            "Resources" => dictionary! {
+                "Font" => dictionary! {
+                    "F1" => Object::Reference(f1),
+                    "F2" => Object::Reference(f2),
+                },
+            },
+            "MediaBox" => vec![0.into(), 0.into(), 612.into(), 792.into()],
+        });
+        let pages_id = doc.add_object(dictionary! {
+            "Type" => "Pages",
+            "Count" => Object::Integer(1),
+            "Kids" => vec![Object::Reference(page_id)],
+        });
+        let catalog_id = doc.add_object(dictionary! {
+            "Type" => "Catalog",
+            "Pages" => Object::Reference(pages_id),
+        });
+        doc.trailer.set("Root", Object::Reference(catalog_id));
+
+        let font_cmaps = FontCMaps::from_doc(&doc);
+        let ((items, _, _), _, _) =
+            extract_page_text_items(&doc, page_id, 1, &font_cmaps, false).unwrap();
+        let text = items
+            .iter()
+            .map(|item| item.text.as_str())
+            .collect::<String>();
+
+        assert_eq!(text, "XYX");
+    }
+
     #[test]
     fn test_strip_pdf_comments() {
         // Basic comment stripping

src/extractor/fonts.rs

@@ -858,6 +858,13 @@ pub(crate) fn extract_text_from_operand(
             // unmapped. Don't fall through to text-interpretation fallbacks
             // (Latin-1, UTF-16, etc.) which would misinterpret CID bytes as
             // character codes (e.g. CID 0x01A9 → Latin-1 "©").
+            if is_type0_cid_font && bytes.iter().any(|&b| b > 0x7F) {
+                // 2-byte CIDs (Identity-H) are by far the common case; for
+                // an odd byte count we still emit at least one marker so
+                // detection downstream fires.
+                let cid_count = (bytes.len() / 2).max(1);
+                return Some("\u{FFFD}".repeat(cid_count));
+            }
 
             // Try our custom encoding map from Differences arrays.
             // The Differences array overrides specific codes in a base encoding (typically
@@ -966,27 +973,6 @@ pub(crate) fn extract_text_from_operand(
                 return Some(symbol_text);
             }
 
-            // Latin-1 fallback. Safe ONLY for fonts that use single-byte
-            // encodings — for these, an unmapped byte is a valid character
-            // code in Latin-1/WinAnsi space. CID fonts (Type0 / Identity-H)
-            // emit multi-byte CIDs that aren't characters; per-byte Latin-1
-            // produces mojibake (e.g. 2-byte CID 0xCDD9 → "ÍÙ" for the
-            // production scrape_id 019de78c-... samples).
-            //
-            // For a CID font (has_cmap is set OR a /ToUnicode reference
-            // exists) with any non-ASCII bytes, emit a single U+FFFD per
-            // CID instead. This both replaces the mojibake with a proper
-            // "decode failed" marker AND keeps `detect_encoding_issues`
-            // tripping so the page is flagged for OCR — the existing
-            // garbage-detection path that the high-Latin-1 mojibake used
-            // to satisfy by accident.
-            if is_type0_cid_font && bytes.iter().any(|&b| b > 0x7F) {
-                // 2-byte CIDs (Identity-H) are by far the common case; for
-                // an odd byte count we still emit at least one marker so
-                // detection downstream fires.
-                let cid_count = (bytes.len() / 2).max(1);
-                return Some("\u{FFFD}".repeat(cid_count));
-            }
             // Pure ASCII bytes round-trip safely (Latin-1 == ASCII for
             // 0x00..=0x7F), and non-CID (Type1 / TrueType / Type3) fonts
             // use single-byte encodings where Latin-1 fallback is the

src/extractor/layout.rs

@@ -29,8 +29,12 @@ pub(crate) fn detect_columns(
     const MIN_ITEMS_PER_COLUMN: usize = 10;
     const NOISE_FRACTION: f32 = 0.15;
 
-    // Get items for this page
-    let page_items: Vec<&TextItem> = items.iter().filter(|i| i.page == page).collect();
+    // Get items for this page. Strip Image placeholders — an image's left edge
+    // would otherwise count toward the column projection profile.
+    let page_items: Vec<&TextItem> = items
+        .iter()
+        .filter(|i| i.page == page && crate::extractor::is_text_layout_item(i))
+        .collect();
 
     if page_items.is_empty() {
         return vec![];
@@ -1258,9 +1262,9 @@ pub(crate) fn group_into_lines_with_thresholds(
 
             if is_newspaper {
                 // Newspaper: columns are independent text flows.
-                // 1. Split each column into its densest cluster (core) and stragglers
-                // 2. Use core columns to determine the above/below threshold
-                // 3. Emit: above items → core columns sequentially → below items
+                // 1. Split each column into its densest cluster (core) and stragglers.
+                // 2. Promote only true top matter above all column starts.
+                // 3. Emit: above items → each complete column flow → below spanning items.
                 let mut core_columns: Vec<Vec<TextLine>> = Vec::new();
                 let mut col_stragglers: Vec<Vec<TextLine>> = Vec::new();
                 for col in per_column_lines {
@@ -1269,12 +1273,15 @@ pub(crate) fn group_into_lines_with_thresholds(
                     col_stragglers.push(stragglers);
                 }
 
-                // col_top = min of max Y across core columns
-                let col_top = core_columns
+                // Use the highest core top as the top-matter cutoff. A column
+                // that starts lower because of a figure or large gap should not
+                // pull another column's opening prose above the abstract/title
+                // area; those fragments still belong to that column's flow.
+                let top_matter_cutoff = core_columns
                     .iter()
                     .filter(|c| !c.is_empty())
                     .map(|c| c.iter().map(|l| l.y).fold(f32::NEG_INFINITY, f32::max))
-                    .fold(f32::INFINITY, f32::min);
+                    .fold(f32::NEG_INFINITY, f32::max);
                 let margin = 5.0;
 
                 let mut above: Vec<TextLine> = Vec::new();
@@ -1282,37 +1289,37 @@ pub(crate) fn group_into_lines_with_thresholds(
 
                 // Spanning items: above or below the column region
                 for line in spanning_lines {
-                    if line.y > col_top + margin {
+                    if line.y > top_matter_cutoff + margin {
                         above.push(line);
                     } else {
                         below_spanning.push(line);
                     }
                 }
 
-                // Column stragglers above col_top go to "above";
-                // below col_top they stay with their column to avoid
-                // re-interleaving when sorted by Y.
-                let mut col_below: Vec<Vec<TextLine>> = vec![Vec::new(); core_columns.len()];
-                for (ci, stragglers) in col_stragglers.into_iter().enumerate() {
+                let mut column_flows: Vec<Vec<TextLine>> = Vec::with_capacity(core_columns.len());
+                for (ci, mut flow) in core_columns.into_iter().enumerate() {
+                    let stragglers = col_stragglers
+                        .get_mut(ci)
+                        .map(std::mem::take)
+                        .unwrap_or_default();
                     for line in stragglers {
-                        if line.y > col_top + margin {
+                        if line.y > top_matter_cutoff + margin {
                             above.push(line);
                         } else {
-                            col_below[ci].push(line);
+                            flow.push(line);
                         }
                     }
+                    flow.sort_by(|a, b| b.y.total_cmp(&a.y));
+                    column_flows.push(flow);
                 }
 
                 above.sort_by(|a, b| b.y.total_cmp(&a.y));
                 below_spanning.sort_by(|a, b| b.y.total_cmp(&a.y));
 
                 all_lines.extend(above);
-                for col in core_columns {
+                for col in column_flows {
                     all_lines.extend(col);
                 }
-                for cb in col_below {
-                    all_lines.extend(cb);
-                }
                 all_lines.extend(below_spanning);
             } else {
                 // Tabular: Y-interleaved merge — rows at the same Y from
@@ -1913,4 +1920,63 @@ mod tests {
         let spanning_count = mask.iter().filter(|&&m| m).count();
         assert_eq!(spanning_count, 0, "Narrow header should NOT be pre-masked");
     }
+
+    #[test]
+    fn newspaper_keeps_staggered_right_column_fragment_in_column_flow() {
+        let mut items = Vec::new();
+
+        for i in 0..30 {
+            let text = if i == 0 {
+                "ABSTRACT".to_string()
+            } else {
+                format!("Left body line {i}")
+            };
+            let mut item = make_item(1, 54.0, 588.0 - i as f32 * 10.0, &text);
+            item.width = 220.0;
+            items.push(item);
+        }
+
+        for i in 0..4 {
+            let text = if i == 0 {
+                "options, people often need comments".to_string()
+            } else {
+                format!("Right opening fragment {i}")
+            };
+            let mut item = make_item(1, 318.0, 592.0 - i as f32 * 10.0, &text);
+            item.width = 220.0;
+            items.push(item);
+        }
+
+        for i in 0..20 {
+            let text = if i == 0 {
+                "Figure 1 caption starts here".to_string()
+            } else {
+                format!("Right lower body line {i}")
+            };
+            let mut item = make_item(1, 318.0, 330.0 - i as f32 * 10.0, &text);
+            item.width = 220.0;
+            items.push(item);
+        }
+
+        let lines = group_into_lines_with_thresholds(items, &HashMap::new(), &HashSet::new());
+        let texts: Vec<String> = lines.iter().map(TextLine::text).collect();
+        let abstract_pos = texts.iter().position(|text| text == "ABSTRACT").unwrap();
+        let options_pos = texts
+            .iter()
+            .position(|text| text.starts_with("options, people often"))
+            .unwrap();
+        let figure_pos = texts
+            .iter()
+            .position(|text| text.starts_with("Figure 1 caption"))
+            .unwrap();
+
+        assert!(
+            abstract_pos < options_pos,
+            "right-column opening fragment must not be promoted above the abstract: {texts:?}"
+        );
+        assert!(
+            options_pos < figure_pos,
+            "right-column opening fragment should stay before the lower right-column core"
+        );
+    }
 }

src/extractor/mod.rs

@@ -227,6 +227,69 @@ fn extract_positioned_text_impl(
 // Shared helpers (used by submodules via `super::`)
 // ---------------------------------------------------------------------------
 
+/// Return true when this item should participate in text-layout
+/// heuristics (column detection, table grid detection, line grouping).
+///
+/// Image XObjects emit a positional placeholder via
+/// `extract_text_with_positions` (so layout-aware callers can crop +
+/// caption figures), but their bboxes don't carry text glyphs and would
+/// skew column/row clustering if they reached the heuristics. Hyperlinks
+/// and form fields *do* participate — the existing logic treats them as
+/// text-like and we keep that.
+pub(crate) fn is_text_layout_item(item: &crate::types::TextItem) -> bool {
+    !matches!(item.item_type, crate::types::ItemType::Image)
+}
+
+/// Map a (u, v) point in unit-square coordinates through the 6-element CTM
+/// to page-space. CTM format is `[a, b, c, d, e, f]` per
+/// [`multiply_matrices`].
+fn apply_ctm_point(ctm: &[f32; 6], u: f32, v: f32) -> (f32, f32) {
+    (
+        u * ctm[0] + v * ctm[2] + ctm[4],
+        u * ctm[1] + v * ctm[3] + ctm[5],
+    )
+}
+
+/// Compute the page-space axis-aligned bounding box of an Image XObject
+/// invoked under the given CTM.
+///
+/// Per the PDF spec, an image XObject is always rendered into a unit
+/// square `(0,0)–(1,1)` in its local coordinate system, and the `Do`
+/// operator applies the current CTM to position/scale/rotate that square
+/// onto the page. For the common axis-aligned case (no rotation/shear),
+/// the CTM reduces to `[w, 0, 0, h, x, y]` and the bbox is just
+/// `(x, y, w, h)`. For rotated/sheared images we transform all four
+/// corners and return their axis-aligned bbox so the caller always gets
+/// an upright rectangle.
+///
+/// Coordinates are PDF user space (origin at bottom-left, y-up). Width
+/// and height are non-negative.
+pub(crate) fn image_bbox_from_ctm(ctm: &[f32; 6]) -> (f32, f32, f32, f32) {
+    let corners = [
+        apply_ctm_point(ctm, 0.0, 0.0),
+        apply_ctm_point(ctm, 1.0, 0.0),
+        apply_ctm_point(ctm, 1.0, 1.0),
+        apply_ctm_point(ctm, 0.0, 1.0),
+    ];
+    let (mut x_min, mut x_max) = (corners[0].0, corners[0].0);
+    let (mut y_min, mut y_max) = (corners[0].1, corners[0].1);
+    for (cx, cy) in corners.iter().skip(1) {
+        if *cx < x_min {
+            x_min = *cx;
+        }
+        if *cx > x_max {
+            x_max = *cx;
+        }
+        if *cy < y_min {
+            y_min = *cy;
+        }
+        if *cy > y_max {
+            y_max = *cy;
+        }
+    }
+    (x_min, y_min, x_max - x_min, y_max - y_min)
+}
+
 /// Multiply two 2D transformation matrices
 /// Matrix format: [a, b, c, d, e, f] representing:
 /// | a  b  0 |

src/extractor/xobjects.rs

@@ -10,7 +10,7 @@ use super::fonts::{
     build_font_encodings, build_font_widths, compute_string_width_ts, extract_text_from_operand,
     get_font_file2_obj_num, get_operand_bytes, CMapDecisionCache,
 };
-use super::{get_number, multiply_matrices};
+use super::{get_number, image_bbox_from_ctm, multiply_matrices};
 
 const MAX_FORM_XOBJECT_DEPTH: u8 = 5;
 
@@ -262,19 +262,43 @@ fn extract_form_xobject_text_inner(
                 if !op.operands.is_empty() {
                     if let Ok(name) = op.operands[0].as_name() {
                         let xobj_name = String::from_utf8_lossy(name).to_string();
-                        if let Some(XObjectType::Form(nested_id)) = form_xobjects.get(&xobj_name) {
-                            if depth < MAX_FORM_XOBJECT_DEPTH {
-                                let nested_items = extract_form_xobject_text_inner(
-                                    doc,
-                                    *nested_id,
-                                    page_num,
-                                    font_cmaps,
-                                    &ctm,
-                                    cmap_decisions,
-                                    depth + 1,
-                                );
-                                items.extend(nested_items);
+                        match form_xobjects.get(&xobj_name) {
+                            Some(XObjectType::Form(nested_id)) => {
+                                if depth < MAX_FORM_XOBJECT_DEPTH {
+                                    let nested_items = extract_form_xobject_text_inner(
+                                        doc,
+                                        *nested_id,
+                                        page_num,
+                                        font_cmaps,
+                                        &ctm,
+                                        cmap_decisions,
+                                        depth + 1,
+                                    );
+                                    items.extend(nested_items);
+                                }
                             }
+                            Some(XObjectType::Image) => {
+                                // Mirror the top-level Image-XObject emission
+                                // in content_stream.rs so figures embedded
+                                // inside Form XObjects (common in print-to-PDF
+                                // workflows) aren't silently dropped.
+                                let (x, y, width, height) = image_bbox_from_ctm(&ctm);
+                                items.push(TextItem {
+                                    text: format!("[Image: {}]", xobj_name),
+                                    x,
+                                    y,
+                                    width,
+                                    height,
+                                    font: String::new(),
+                                    font_size: 0.0,
+                                    page: page_num,
+                                    is_bold: false,
+                                    is_italic: false,
+                                    item_type: ItemType::Image,
+                                    mcid: None,
+                                });
+                            }
+                            None => {}
                         }
                     }
                 }

src/markdown/convert.rs

@@ -149,6 +149,79 @@ fn find_isolated_lines(lines: &[TextLine], base_size: f32, para_threshold: f32)
     set
 }
 
+/// Pre-scan body-size all-bold runs that are too long to be headings.
+///
+/// Some academic PDFs use an all-bold abstract/summary paragraph immediately
+/// after the author block.  A line-local bold heading heuristic sees each
+/// wrapped visual line as "standalone" once the first line is misclassified,
+/// producing a stack of `##` headings.  Multi-line body-size bold runs with a
+/// paragraph-sized word count should stay paragraph text.
+fn find_wrapped_bold_paragraph_lines(
+    lines: &[TextLine],
+    base_size: f32,
+    para_threshold: f32,
+) -> HashSet<usize> {
+    let mut set = HashSet::new();
+    let mut i = 0usize;
+
+    while i < lines.len() {
+        if !is_body_size_all_bold_line(&lines[i], base_size) {
+            i += 1;
+            continue;
+        }
+
+        let start = i;
+        let mut end = i;
+        let mut word_count = lines[i].text().split_whitespace().count();
+
+        while end + 1 < lines.len()
+            && is_body_size_all_bold_line(&lines[end + 1], base_size)
+            && is_wrapped_same_style_line(&lines[end], &lines[end + 1], para_threshold)
+        {
+            end += 1;
+            word_count += lines[end].text().split_whitespace().count();
+        }
+
+        let line_count = end - start + 1;
+        if line_count >= 3 && word_count > 20 {
+            for idx in start..=end {
+                set.insert(idx);
+            }
+        }
+
+        i = end + 1;
+    }
+
+    set
+}
+
+fn is_body_size_all_bold_line(line: &TextLine, base_size: f32) -> bool {
+    let Some(first) = line.items.first() else {
+        return false;
+    };
+    first.font_size >= base_size * 0.95
+        && first.font_size < base_size * 1.2
+        && line
+            .items
+            .iter()
+            .all(|item| item.is_bold && (item.font_size - first.font_size).abs() < 0.5)
+}
+
+fn is_wrapped_same_style_line(prev: &TextLine, next: &TextLine, para_threshold: f32) -> bool {
+    if prev.page != next.page {
+        return false;
+    }
+
+    let y_gap = prev.y - next.y;
+    if !(y_gap > 0.0 && y_gap <= para_threshold) {
+        return false;
+    }
+
+    let prev_x = prev.items.first().map(|item| item.x).unwrap_or(0.0);
+    let next_x = next.items.first().map(|item| item.x).unwrap_or(0.0);
+    (prev_x - next_x).abs() <= 40.0
+}
+
 /// Resolve the dominant structure role for a text line by looking up its items' MCIDs.
 ///
 /// Returns the first non-container role found (skipping Document/Part/Sect/Div/NonStruct/Span).
@@ -397,6 +470,8 @@ pub(super) fn to_markdown_from_lines_with_tables_and_images(
     // between paragraphs at body font size. Inspired by opendataloader's
     // lookahead in HeadingProcessor (prevNode/nextNode context).
     let isolated_lines = find_isolated_lines(&lines, base_size, para_threshold);
+    let wrapped_bold_paragraph_lines =
+        find_wrapped_bold_paragraph_lines(&lines, base_size, para_threshold);
 
     // Detect struct heading levels that are overused (body text mistagged as headings)
     let overused_heading_levels = detect_overused_struct_heading_levels(&lines, struct_roles);
@@ -410,6 +485,7 @@ pub(super) fn to_markdown_from_lines_with_tables_and_images(
     let mut last_list_x: Option<f32> = None;
     let mut in_code_block = false;
     let mut prev_had_dot_leaders = false;
+    let mut paragraph_in_wrapped_bold_run = false;
     let mut inserted_tables: HashSet<(u32, usize)> = HashSet::new();
     let mut inserted_images: HashSet<(u32, usize)> = HashSet::new();
 
@@ -475,6 +551,7 @@ pub(super) fn to_markdown_from_lines_with_tables_and_images(
             current_page = line.page;
             prev_y = f32::MAX;
             prev_x = 0.0;
+            paragraph_in_wrapped_bold_run = false;
 
             if options.include_page_numbers {
                 output.push_str(&format!("<!-- Page {} -->\n\n", current_page));
@@ -489,6 +566,7 @@ pub(super) fn to_markdown_from_lines_with_tables_and_images(
                     if in_paragraph {
                         output.push_str("\n\n");
                         in_paragraph = false;
+                        paragraph_in_wrapped_bold_run = false;
                     }
                     output.push('\n');
                     output.push_str(table_md);
@@ -506,6 +584,7 @@ pub(super) fn to_markdown_from_lines_with_tables_and_images(
                     if in_paragraph {
                         output.push_str("\n\n");
                         in_paragraph = false;
+                        paragraph_in_wrapped_bold_run = false;
                     }
                     output.push('\n');
                     output.push_str(image_md);
@@ -527,9 +606,18 @@ pub(super) fn to_markdown_from_lines_with_tables_and_images(
             && y_gap.abs() <= para_threshold
             && (prev_x - line_x).abs() > 50.0
             && prev_y < f32::MAX;
-        if (is_para_break || is_band_switch) && in_paragraph {
+        let line_all_bold = !line.items.is_empty() && line.items.iter().all(|item| item.is_bold);
+        let line_in_wrapped_bold_run = wrapped_bold_paragraph_lines.contains(&line_idx);
+        let is_bold_to_regular_break = in_paragraph
+            && paragraph_in_wrapped_bold_run
+            && !line_in_wrapped_bold_run
+            && !line_all_bold
+            && y_gap > base_size * 1.2
+            && y_gap <= para_threshold;
+        if (is_para_break || is_band_switch || is_bold_to_regular_break) && in_paragraph {
             output.push_str("\n\n");
             in_paragraph = false;
+            paragraph_in_wrapped_bold_run = false;
         }
         // Don't immediately end list on paragraph break
         // Let the continuation check below decide if we're still in a list
@@ -572,6 +660,7 @@ pub(super) fn to_markdown_from_lines_with_tables_and_images(
             if in_paragraph {
                 output.push_str("\n\n");
                 in_paragraph = false;
+                paragraph_in_wrapped_bold_run = false;
             }
             output.push_str(trimmed);
             output.push_str("\n\n");
@@ -625,6 +714,9 @@ pub(super) fn to_markdown_from_lines_with_tables_and_images(
                 if !(1..=15).contains(&word_count) {
                     return None;
                 }
+                if wrapped_bold_paragraph_lines.contains(&line_idx) {
+                    return None;
+                }
                 let rarity = font_size_rarity(line_font_size, &font_stats);
                 let all_bold = !line.items.is_empty() && line.items.iter().all(|i| i.is_bold);
                 let standalone = !in_paragraph;
@@ -656,6 +748,7 @@ pub(super) fn to_markdown_from_lines_with_tables_and_images(
             if in_paragraph {
                 output.push_str("\n\n");
                 in_paragraph = false;
+                paragraph_in_wrapped_bold_run = false;
             }
             let prefix = "#".repeat(level);
             // Use plain text for headers to avoid redundant formatting
@@ -678,6 +771,7 @@ pub(super) fn to_markdown_from_lines_with_tables_and_images(
             if in_paragraph {
                 output.push_str("\n\n");
                 in_paragraph = false;
+                paragraph_in_wrapped_bold_run = false;
             }
             output.push_str(&format!("- {}", trimmed));
             output.push('\n');
@@ -691,6 +785,7 @@ pub(super) fn to_markdown_from_lines_with_tables_and_images(
             if in_paragraph {
                 output.push_str("\n\n");
                 in_paragraph = false;
+                paragraph_in_wrapped_bold_run = false;
             }
             let formatted = format_list_item(trimmed);
             output.push_str(&formatted);
@@ -737,6 +832,7 @@ pub(super) fn to_markdown_from_lines_with_tables_and_images(
             if in_paragraph {
                 output.push_str("\n\n");
                 in_paragraph = false;
+                paragraph_in_wrapped_bold_run = false;
             }
             output.push_str(&format!("> {}\n", trimmed));
             continue;
@@ -747,6 +843,7 @@ pub(super) fn to_markdown_from_lines_with_tables_and_images(
             if in_paragraph {
                 output.push_str("\n\n");
                 in_paragraph = false;
+                paragraph_in_wrapped_bold_run = false;
             }
             if !in_code_block {
                 output.push_str("```\n");
@@ -767,6 +864,11 @@ pub(super) fn to_markdown_from_lines_with_tables_and_images(
             }
         }
         output.push_str(trimmed);
+        paragraph_in_wrapped_bold_run = if in_paragraph {
+            paragraph_in_wrapped_bold_run || line_in_wrapped_bold_run
+        } else {
+            line_in_wrapped_bold_run
+        };
         in_paragraph = true;
         prev_had_dot_leaders = cur_dot_leaders;
     }
@@ -836,6 +938,8 @@ pub fn to_markdown_from_lines(lines: Vec<TextLine>, options: MarkdownOptions) ->
     let para_threshold = compute_paragraph_threshold(&lines, base_size);
 
     let isolated_lines = find_isolated_lines(&lines, base_size, para_threshold);
+    let wrapped_bold_paragraph_lines =
+        find_wrapped_bold_paragraph_lines(&lines, base_size, para_threshold);
 
     let mut output = String::new();
     let mut current_page = 0u32;
@@ -844,6 +948,7 @@ pub fn to_markdown_from_lines(lines: Vec<TextLine>, options: MarkdownOptions) ->
     let mut in_paragraph = false;
     let mut last_list_x: Option<f32> = None;
     let mut prev_had_dot_leaders = false;
+    let mut paragraph_in_wrapped_bold_run = false;
 
     for (line_idx, line) in lines.iter().enumerate() {
         // Page break
@@ -860,6 +965,7 @@ pub fn to_markdown_from_lines(lines: Vec<TextLine>, options: MarkdownOptions) ->
             in_list = false;
             last_list_x = None;
             prev_had_dot_leaders = false;
+            paragraph_in_wrapped_bold_run = false;
 
             if options.include_page_numbers {
                 output.push_str(&format!("<!-- Page {} -->\n\n", current_page));
@@ -870,9 +976,18 @@ pub fn to_markdown_from_lines(lines: Vec<TextLine>, options: MarkdownOptions) ->
         // (newspaper columns emitted sequentially on the same page).
         let y_gap = prev_y - line.y;
         let is_para_break = y_gap.abs() > para_threshold;
-        if is_para_break && in_paragraph {
+        let line_all_bold = !line.items.is_empty() && line.items.iter().all(|item| item.is_bold);
+        let line_in_wrapped_bold_run = wrapped_bold_paragraph_lines.contains(&line_idx);
+        let is_bold_to_regular_break = in_paragraph
+            && paragraph_in_wrapped_bold_run
+            && !line_in_wrapped_bold_run
+            && !line_all_bold
+            && y_gap > base_size * 1.2
+            && y_gap <= para_threshold;
+        if (is_para_break || is_bold_to_regular_break) && in_paragraph {
             output.push_str("\n\n");
             in_paragraph = false;
+            paragraph_in_wrapped_bold_run = false;
         }
         // Don't immediately end list on paragraph break
         // Let the continuation check below decide if we're still in a list
@@ -896,6 +1011,7 @@ pub fn to_markdown_from_lines(lines: Vec<TextLine>, options: MarkdownOptions) ->
             if in_paragraph {
                 output.push_str("\n\n");
                 in_paragraph = false;
+                paragraph_in_wrapped_bold_run = false;
             }
             output.push_str(trimmed);
             output.push_str("\n\n");
@@ -918,6 +1034,9 @@ pub fn to_markdown_from_lines(lines: Vec<TextLine>, options: MarkdownOptions) ->
                     if !(1..=15).contains(&word_count) {
                         return None;
                     }
+                    if wrapped_bold_paragraph_lines.contains(&line_idx) {
+                        return None;
+                    }
                     let rarity = font_size_rarity(line_font_size, &font_stats);
                     let all_bold = !line.items.is_empty() && line.items.iter().all(|i| i.is_bold);
                     let standalone = !in_paragraph;
@@ -935,6 +1054,7 @@ pub fn to_markdown_from_lines(lines: Vec<TextLine>, options: MarkdownOptions) ->
                 if in_paragraph {
                     output.push_str("\n\n");
                     in_paragraph = false;
+                    paragraph_in_wrapped_bold_run = false;
                 }
                 let prefix = "#".repeat(header_level);
                 // Use plain text for headers to avoid redundant formatting
@@ -949,6 +1069,7 @@ pub fn to_markdown_from_lines(lines: Vec<TextLine>, options: MarkdownOptions) ->
             if in_paragraph {
                 output.push_str("\n\n");
                 in_paragraph = false;
+                paragraph_in_wrapped_bold_run = false;
             }
             let formatted = format_list_item(trimmed);
             output.push_str(&formatted);
@@ -993,6 +1114,7 @@ pub fn to_markdown_from_lines(lines: Vec<TextLine>, options: MarkdownOptions) ->
                 if in_paragraph {
                     output.push_str("\n\n");
                     in_paragraph = false;
+                    paragraph_in_wrapped_bold_run = false;
                 }
                 // Use plain text for code blocks
                 output.push_str(&format!("```\n{}\n```\n", plain_trimmed));
@@ -1010,6 +1132,11 @@ pub fn to_markdown_from_lines(lines: Vec<TextLine>, options: MarkdownOptions) ->
             }
         }
         output.push_str(trimmed);
+        paragraph_in_wrapped_bold_run = if in_paragraph {
+            paragraph_in_wrapped_bold_run || line_in_wrapped_bold_run
+        } else {
+            line_in_wrapped_bold_run
+        };
         in_paragraph = true;
         prev_had_dot_leaders = cur_dot_leaders;
     }
@@ -1356,6 +1483,109 @@ mod tests {
         );
     }
 
+    #[test]
+    fn test_wrapped_bold_abstract_is_not_split_into_headings() {
+        // Regression for arXiv 1107.1353: the opening abstract paragraph is
+        // entirely bold at body size. The first wrapped lines used to become
+        // separate H2 headings, and the following body paragraph was joined to
+        // the bold abstract because the paragraph gap is modest.
+        let make = |text: &str, y: f32, font_size: f32, bold: bool| {
+            let mut item = make_item(text, 1, None);
+            item.y = y;
+            item.font_size = font_size;
+            item.height = font_size;
+            item.is_bold = bold;
+            item
+        };
+
+        let lines = vec![
+            make_line(vec![make(
+                "Quantum Nature of Light Measured With a Single Detector",
+                747.7,
+                25.0,
+                true,
+            )]),
+            make_line(vec![make(
+                "Gesine A. Steudle1*, Stefan Schietinger1, David Höckel1",
+                651.1,
+                11.0,
+                false,
+            )]),
+            make_line(vec![make(
+                "Zwiller2, and Oliver Benson1",
+                638.5,
+                11.0,
+                false,
+            )]),
+            make_line(vec![make(
+                "The introduction of light quanta by Einstein in 1905 triggered strong efforts to",
+                607.5,
+                11.0,
+                true,
+            )]),
+            make_line(vec![make(
+                "demonstrate the quantum properties of light directly, without involving matter",
+                594.8,
+                11.0,
+                true,
+            )]),
+            make_line(vec![make(
+                "quantization. It however took more than seven decades for the quantum granularity",
+                582.2,
+                11.0,
+                true,
+            )]),
+            make_line(vec![make(
+                "of light to be observed in the fluorescence of single atoms. Single atoms emit",
+                569.5,
+                11.0,
+                true,
+            )]),
+            make_line(vec![make(
+                "photons one at a time, this is typically demonstrated with a Hanbury-Brown-Twiss",
+                556.9,
+                11.0,
+                true,
+            )]),
+            make_line(vec![make(
+                "Our work significantly simplifies a widely used photon-correlation technique.",
+                544.2,
+                11.0,
+                true,
+            )]),
+            make_line(vec![make(
+                "A photon is a single excitation of a mode of the electromagnetic field.",
+                528.7,
+                11.0,
+                false,
+            )]),
+        ];
+
+        let md = to_markdown_from_lines_with_tables_and_images(
+            lines,
+            MarkdownOptions::default(),
+            HashMap::new(),
+            HashMap::new(),
+            &std::collections::HashSet::new(),
+            None,
+        );
+
+        assert!(
+            md.contains("# Quantum Nature of Light Measured With a Single Detector"),
+            "title should remain a heading: {md}"
+        );
+        assert!(
+            !md.contains("## The introduction")
+                && !md.contains("## demonstrate")
+                && !md.contains("## quantization"),
+            "bold abstract lines should not become headings: {md}"
+        );
+        assert!(
+            md.contains("technique.**\n\nA photon is a single excitation"),
+            "body paragraph should be separated from bold abstract: {md}"
+        );
+    }
+
     #[test]
     fn test_struct_role_code_multiline_accumulation() {
         let mut line1 = make_item("fn main() {", 1, Some(0));

src/markdown/mod.rs

@@ -422,7 +422,16 @@ impl Default for MarkdownOptions {
             fix_hyphenation: true,
             detect_bold: true,
             detect_italic: true,
-            include_images: true,
+            // `include_images: false` is intentional. The content-stream walker
+            // now emits `ItemType::Image` `TextItem`s for every Image XObject
+            // it encounters (see `extractor/content_stream.rs`). If we rendered
+            // those into markdown by default, every existing caller would
+            // suddenly see `![Image: Im0](image)` placeholders inserted
+            // throughout their output — a silent regression for anyone who
+            // upgrades. Image bboxes are still available via
+            // `extract_text_with_positions` for callers (e.g. layout-aware
+            // pipelines) that want to crop + caption figures themselves.
+            include_images: false,
             include_links: true,
             include_page_numbers: false,
             strip_headers_footers: true,

src/markdown/postprocess.rs

@@ -29,6 +29,7 @@ pub(crate) fn clean_markdown(mut text: String, options: &MarkdownOptions) -> Str
     // text item, which combine with gap-based space insertion to produce
     // double spaces ("Vice  President" instead of "Vice President").
     collapse_consecutive_spaces(&mut text);
+    remove_spaces_before_closing_brackets(&mut text);
 
     // Remove excessive newlines (more than 2 in a row)
     while text.contains("\n\n\n") {
@@ -71,6 +72,20 @@ fn collapse_consecutive_spaces(text: &mut String) {
     *text = result;
 }
 
+/// Remove spaces before closing square brackets.
+/// Unit markers and markdown links occasionally pick up a gap-inserted space
+/// before `]` (e.g. `[kg/m3 ]`), which is cosmetic padding.
+fn remove_spaces_before_closing_brackets(text: &mut String) {
+    let mut result = String::with_capacity(text.len());
+    for ch in text.chars() {
+        if ch == ']' && result.ends_with(' ') {
+            result.pop();
+        }
+        result.push(ch);
+    }
+    *text = result;
+}
+
 /// Collapse dot leaders (runs of 4+ dots) into " ... "
 /// Common in tables of contents: "Introduction...............................1" -> "Introduction ... 1"
 fn collapse_dot_leaders(text: &str) -> String {
@@ -342,6 +357,18 @@ mod tests {
         assert!(result.contains("Chapter 2 ... 20"));
     }
 
+    // --- remove_spaces_before_closing_brackets ---
+
+    #[test]
+    fn test_remove_spaces_before_closing_brackets() {
+        let mut input = "Density [kg/m3 ] and [linked text ](https://example.com)".to_string();
+        remove_spaces_before_closing_brackets(&mut input);
+        assert_eq!(
+            input,
+            "Density [kg/m3] and [linked text](https://example.com)"
+        );
+    }
+
     // --- fix_hyphenation ---
 
     #[test]

src/tables/detect_lines.rs

@@ -4,11 +4,74 @@
 //! gridlines.  Many IRS forms and government PDFs use these instead of
 //! `re` (rectangle) operators.
 
+use std::collections::HashSet;
+
 use crate::tables::Table;
 use crate::types::{PdfLine, TextItem};
 
 use super::detect_rects::{assign_items_to_grid, snap_edges};
 
+/// Derive column edges from the x-endpoints of horizontal-rule
+/// segments when no vertical lines were drawn.
+///
+/// Catalog and archival-finding-aid tables are commonly drawn with
+/// per-row horizontal rules broken into N segments (one segment per
+/// cell), with no vertical dividers at all. The segment break points
+/// (e.g. `[50, 127], [127, 485], [485, 562]` per row) implicitly
+/// encode the column boundaries.
+///
+/// Returns column edges if ≥3 distinct x-positions each show up as a
+/// segment endpoint on ≥50% of the unique horizontal-line rows.
+/// Returns `None` otherwise — decorative rules with varying widths
+/// shouldn't be mistaken for a table.
+fn derive_columns_from_horizontal_segments(horizontals: &[(f32, f32, f32)]) -> Option<Vec<f32>> {
+    if horizontals.len() < 3 {
+        return None;
+    }
+
+    let mut endpoints: Vec<f32> = Vec::with_capacity(horizontals.len() * 2);
+    for &(_, x_min, x_max) in horizontals {
+        endpoints.push(x_min);
+        endpoints.push(x_max);
+    }
+    let clusters = snap_edges(&endpoints, 5.0);
+    if clusters.len() < 3 {
+        return None;
+    }
+
+    // Bucket y-values to count unique rows. Tolerance ~0.1pt (×10
+    // rounding) tolerates the snap_edges 3pt clustering used later
+    // for row edges.
+    let unique_rows: HashSet<i32> = horizontals
+        .iter()
+        .map(|&(y, _, _)| (y * 10.0).round() as i32)
+        .collect();
+    if unique_rows.len() < 2 {
+        return None;
+    }
+    let min_rows = (unique_rows.len() as f32 * 0.5).ceil() as usize;
+
+    let qualifying: Vec<f32> = clusters
+        .iter()
+        .copied()
+        .filter(|&cluster_x| {
+            let rows_touched: HashSet<i32> = horizontals
+                .iter()
+                .filter(|&&(_, x_min, x_max)| {
+                    (x_min - cluster_x).abs() < 5.0 || (x_max - cluster_x).abs() < 5.0
+                })
+                .map(|&(y, _, _)| (y * 10.0).round() as i32)
+                .collect();
+            rows_touched.len() >= min_rows
+        })
+        .collect();
+
+    if qualifying.len() < 3 {
+        return None;
+    }
+    Some(qualifying)
+}
+
 /// Detect tables from line segments on a given page.
 ///
 /// Lines are classified as horizontal or vertical, snapped into grid edges,
@@ -52,25 +115,50 @@ pub fn detect_tables_from_lines(items: &[TextItem], lines: &[PdfLine], page: u32
         // Diagonal lines are ignored
     }
 
-    if horizontals.len() < 3 || verticals.len() < 2 {
+    if horizontals.len() < 3 {
         return Vec::new();
     }
 
+    // If no/very-few vertical lines are drawn, try to derive column edges
+    // from the x-endpoints of the horizontal-rule segments. Catalog and
+    // archival-finding-aid layouts commonly draw each row's horizontal
+    // rule as N segments (one per cell), with no vertical dividers at
+    // all — the segment break points encode the column boundaries.
+    let implicit_col_edges: Option<Vec<f32>> = if verticals.len() < 2 {
+        derive_columns_from_horizontal_segments(&horizontals)
+    } else {
+        None
+    };
+    if verticals.len() < 2 && implicit_col_edges.is_none() {
+        return Vec::new();
+    }
+    let cols_from_segments = implicit_col_edges.is_some();
+
     log::debug!(
-        "detect_lines p{}: {} horiz, {} vert lines (of {} total on page)",
+        "detect_lines p{}: {} horiz, {} vert lines (of {} total on page){}",
         page,
         horizontals.len(),
         verticals.len(),
-        page_lines.len()
+        page_lines.len(),
+        if cols_from_segments {
+            " — columns from horizontal segments"
+        } else {
+            ""
+        }
     );
 
     // Snap Y-values of horizontal lines → row edges
     let h_ys: Vec<f32> = horizontals.iter().map(|(y, _, _)| *y).collect();
     let row_edges = snap_edges(&h_ys, 3.0);
 
-    // Snap X-values of vertical lines → column edges
-    let v_xs: Vec<f32> = verticals.iter().map(|(x, _, _)| *x).collect();
-    let col_edges = snap_edges(&v_xs, 3.0);
+    // Column edges from drawn verticals when present, else from the
+    // horizontal-segment endpoints derived above.
+    let col_edges = if let Some(c) = implicit_col_edges {
+        c
+    } else {
+        let v_xs: Vec<f32> = verticals.iter().map(|(x, _, _)| *x).collect();
+        snap_edges(&v_xs, 3.0)
+    };
 
     log::debug!(
         "detect_lines p{}: {} row edges, {} col edges after snap",
@@ -110,15 +198,21 @@ pub fn detect_tables_from_lines(items: &[TextItem], lines: &[PdfLine], page: u32
         return Vec::new();
     }
 
-    // Reject page-spanning frames: if the grid covers >90% of a standard page
-    // dimension in both axes, it's a border frame, not a table.
+    // Reject page-spanning frames: a decorative outer border has just 4
+    // edges (top/bottom/left/right). Real full-page tables — common in
+    // governmental ledgers, financial reports, etc. — span the same A4 /
+    // Letter dimensions but have many internal row/column rules. Only
+    // reject when the line set looks like a bare frame, not a grid.
     // Standard pages are ~595×842 (A4) or ~612×792 (Letter).
-    if table_width > 500.0 && table_height > 700.0 {
+    if table_width > 500.0 && table_height > 700.0 && horizontals.len() <= 4 && verticals.len() <= 4
+    {
         log::debug!(
-            "detect_lines p{}: rejected — page-spanning frame ({:.0}×{:.0})",
+            "detect_lines p{}: rejected — page-spanning frame ({:.0}×{:.0}, {} h + {} v)",
             page,
             table_width,
-            table_height
+            table_height,
+            horizontals.len(),
+            verticals.len()
         );
         return Vec::new();
     }
@@ -146,24 +240,33 @@ pub fn detect_tables_from_lines(items: &[TextItem], lines: &[PdfLine], page: u32
 
     // Validate vertical lines: at least 2 should span a meaningful height.
     // Full spanning (>30%) is ideal, but accept many shorter lines (>10%)
-    // for tables with partial column separators.
-    let spanning_v = verticals
-        .iter()
-        .filter(|(_, y_min, y_max)| (y_max - y_min) > table_height * 0.3)
-        .count();
-    let partial_v = verticals
-        .iter()
-        .filter(|(_, y_min, y_max)| (y_max - y_min) > table_height * 0.10)
-        .count();
-    if spanning_v < 2 && partial_v < 4 {
-        log::debug!(
-            "detect_lines p{}: rejected — {} spanning + {} partial V lines",
-            page,
-            spanning_v,
-            partial_v
-        );
-        return Vec::new();
-    }
+    // for tables with partial column separators. Skipped entirely when
+    // columns came from horizontal-segment endpoints — there are no
+    // vertical lines to validate against, and the segment-endpoint
+    // consistency check in `derive_columns_from_horizontal_segments`
+    // is the equivalent guard.
+    let spanning_v = if cols_from_segments {
+        0
+    } else {
+        let s = verticals
+            .iter()
+            .filter(|(_, y_min, y_max)| (y_max - y_min) > table_height * 0.3)
+            .count();
+        let p = verticals
+            .iter()
+            .filter(|(_, y_min, y_max)| (y_max - y_min) > table_height * 0.10)
+            .count();
+        if s < 2 && p < 4 {
+            log::debug!(
+                "detect_lines p{}: rejected — {} spanning + {} partial V lines",
+                page,
+                s,
+                p
+            );
+            return Vec::new();
+        }
+        s
+    };
 
     // Row edges need to be in descending order (top of page = higher Y first)
     let mut row_edges_desc = row_edges;
@@ -410,6 +513,135 @@ mod tests {
         assert!(tables.is_empty());
     }
 
+    #[test]
+    fn test_horizontal_segments_only_implicit_columns_accepted() {
+        // Catalog/finding-aid pattern: each row's horizontal rule is
+        // drawn as 3 segments at consistent x-endpoints (50, 127, 485,
+        // 562), with no vertical lines anywhere. The segment break
+        // points must be inferred as column edges.
+        let mut lines = Vec::new();
+        // Slightly uneven row spacing so the chart-gridline rejector
+        // (CV < 0.02) doesn't fire.
+        let row_ys = [80.0_f32, 145.0, 215.0, 280.0, 350.0, 415.0, 485.0];
+        for &y in &row_ys {
+            lines.push(make_hline(y, 50.0, 127.0, 1));
+            lines.push(make_hline(y, 127.0, 485.0, 1));
+            lines.push(make_hline(y, 485.0, 562.0, 1));
+        }
+        // Populate every cell so capture / density checks pass.
+        let mut items = Vec::new();
+        for w in row_ys.windows(2) {
+            let row_y = (w[0] + w[1]) / 2.0;
+            items.push(make_item("id", 80.0, row_y, 1));
+            items.push(make_item("description here", 200.0, row_y, 1));
+            items.push(make_item("date", 510.0, row_y, 1));
+        }
+        let tables = detect_tables_from_lines(&items, &lines, 1);
+        assert_eq!(
+            tables.len(),
+            1,
+            "horizontal-segment-only grid should be accepted"
+        );
+        let t = &tables[0];
+        assert!(
+            t.cells.len() >= 4,
+            "expected ≥4 rows, got {}",
+            t.cells.len()
+        );
+        assert_eq!(t.cells[0].len(), 3, "expected 3 columns");
+    }
+
+    #[test]
+    fn test_horizontal_segments_with_inconsistent_endpoints_rejected() {
+        // Decorative rules of varying widths shouldn't be detected as a
+        // table — each line has its own x-endpoints, no consistent
+        // column boundary survives the 50%-of-rows threshold.
+        let lines = vec![
+            make_hline(100.0, 50.0, 150.0, 1),
+            make_hline(200.0, 50.0, 220.0, 1),
+            make_hline(300.0, 50.0, 310.0, 1),
+            make_hline(400.0, 50.0, 470.0, 1),
+        ];
+        let items = vec![
+            make_item("decorative", 100.0, 150.0, 1),
+            make_item("text", 100.0, 250.0, 1),
+        ];
+        let tables = detect_tables_from_lines(&items, &lines, 1);
+        assert!(
+            tables.is_empty(),
+            "varying-width decorative rules should not be detected"
+        );
+    }
+
+    #[test]
+    fn test_page_spanning_bare_frame_rejected() {
+        // Just an outer A4-sized rectangle: 2 horizontals + 2 verticals.
+        // No internal structure → decorative border, not a table.
+        let lines = vec![
+            make_hline(20.0, 20.0, 575.0, 1),  // top
+            make_hline(820.0, 20.0, 575.0, 1), // bottom
+            make_vline(20.0, 20.0, 820.0, 1),  // left
+            make_vline(575.0, 20.0, 820.0, 1), // right
+        ];
+        let items = vec![
+            make_item("title", 100.0, 100.0, 1),
+            make_item("body", 100.0, 200.0, 1),
+        ];
+        let tables = detect_tables_from_lines(&items, &lines, 1);
+        assert!(
+            tables.is_empty(),
+            "Page-sized 4-edge frame should be rejected as decoration"
+        );
+    }
+
+    #[test]
+    fn test_page_spanning_grid_with_internal_lines_accepted() {
+        // Full-page table (governmental-ledger pattern): A4-sized grid
+        // that previously hit the "page-spanning frame" early reject
+        // before downstream validation could even look at it.
+        // Verticals span the full table height so we isolate the
+        // frame-vs-grid decision under test.
+        let mut lines = Vec::new();
+        // 13 horizontal rules: header + 12 row separators
+        let h_ys = [
+            22.5, 37.9, 95.5, 144.5, 184.9, 233.9, 291.7, 340.7, 415.8, 499.6, 574.7, 623.7, 698.8,
+        ];
+        for &y in &h_ys {
+            lines.push(make_hline(y, 22.6, 566.6, 1));
+        }
+        // 7 column dividers spanning full table height.
+        let v_xs = [22.6, 66.3, 116.3, 186.6, 263.1, 493.5, 566.5];
+        for &x in &v_xs {
+            lines.push(make_vline(x, 22.5, 698.8, 1));
+        }
+        // Populate every cell so the capture-ratio + density checks pass.
+        let mut items = Vec::new();
+        for r in 0..(h_ys.len() - 1) {
+            let row_y = (h_ys[r] + h_ys[r + 1]) / 2.0;
+            for c in 0..(v_xs.len() - 1) {
+                let col_x = (v_xs[c] + v_xs[c + 1]) / 2.0;
+                items.push(make_item("x", col_x, row_y, 1));
+            }
+        }
+        let tables = detect_tables_from_lines(&items, &lines, 1);
+        assert_eq!(
+            tables.len(),
+            1,
+            "Full-page table with internal grid should be accepted"
+        );
+        let t = &tables[0];
+        assert!(
+            t.cells.len() >= 6,
+            "expected ≥6 rows, got {}",
+            t.cells.len()
+        );
+        assert!(
+            t.cells[0].len() >= 3,
+            "expected ≥3 columns, got {}",
+            t.cells[0].len()
+        );
+    }
+
     #[test]
     fn test_single_column_rejected() {
         // Only 2 col edges (1 column) — not a table even with verticals

src/tables/detect_rects.rs

@@ -231,6 +231,15 @@ pub fn detect_tables_from_rects(
     rects: &[PdfRect],
     page: u32,
 ) -> (Vec<Table>, Vec<RectHintRegion>) {
+    // Strip Image placeholders before column/row clustering — an image's bbox
+    // would otherwise show up as a spurious column edge. See `is_text_layout_item`.
+    let items_owned: Vec<TextItem> = items
+        .iter()
+        .filter(|i| crate::extractor::is_text_layout_item(i))
+        .cloned()
+        .collect();
+    let items = items_owned.as_slice();
+
     // Filter rects on this page; normalize negative widths/heights; skip tiny rects.
     let mut page_rects: Vec<(f32, f32, f32, f32)> = Vec::new(); // (x, y, w, h) normalized
     for r in rects {
@@ -1394,13 +1403,15 @@ fn detect_row_stripe_table(
         .max()
         .unwrap_or(0);
     // Allow longer cells for multi-column tables (descriptions in one column
-    // are common).  Single-column or 2-column "tables" with giant cells are
-    // almost always layout backgrounds.
+    // are common). Narrow grids with giant cells are usually layout
+    // backgrounds — but only when the row count is also small. A 4+-row
+    // key/value table with one descriptive column reads as a real table
+    // on every other gate, so don't reject it on cell length alone.
     let max_allowed = if num_cols >= 3 { 2000 } else { 500 };
-    if max_cell_len > max_allowed {
+    if max_cell_len > max_allowed && non_empty_rows < 4 {
         debug!(
-            "  row-stripe rejected: max cell length {} > {} (layout background)",
-            max_cell_len, max_allowed
+            "  row-stripe rejected: max cell length {} > {} (layout background, {} rows)",
+            max_cell_len, max_allowed, non_empty_rows
         );
         return None;
     }
@@ -1632,7 +1643,49 @@ fn detect_row_stripe_table_from_cell_rects(
         }
     };
 
+    // For wired-grid tables whose header text is centered/right-aligned but
+    // whose data is left-aligned, cluster_x_positions can drop the header-only
+    // x-cluster in its singleton-filter pass and merge adjacent data clusters
+    // when the gap is below threshold, losing a column. Rect borders are
+    // ground truth in that case — but only when each rect column actually
+    // holds text. Decorative or background rects (prose laid out in a frame,
+    // cell-fill rects with extra borders) can produce more rect-derived
+    // columns than the text supports; preferring rects there would split a
+    // logical column into spurious sub-columns.
+    let rect_cols_match_text = match (&rect_col_edges, &text_col_edges) {
+        (Some(rect_edges), _) if rect_edges.len() >= 4 => {
+            let num_rect_cols = rect_edges.len() - 1;
+            let mut col_item_counts = vec![0usize; num_rect_cols];
+            for (_, item) in &page_items {
+                let cx = item.x + item.width / 2.0;
+                for c in 0..num_rect_cols {
+                    if cx >= rect_edges[c] - 2.0 && cx <= rect_edges[c + 1] + 2.0 {
+                        col_item_counts[c] += 1;
+                        break;
+                    }
+                }
+            }
+            // Require every rect column to hold multiple text items. A rect
+            // column with no (or only one) item is decorative or the rect grid
+            // is detecting a spurious column the data does not need; in those
+            // cases the old text-cluster preference is the safer fallback.
+            col_item_counts.iter().all(|&n| n >= 2)
+        }
+        _ => false,
+    };
+
     let (col_edges, columns_from_text) = match (rect_col_edges, text_col_edges) {
+        (Some(rect_edges), text_edges_opt) if rect_cols_match_text => {
+            debug!(
+                "  cell-rect using {} rect-derived columns (text clusters: {}; rect cols well-distributed)",
+                rect_edges.len() - 1,
+                text_edges_opt
+                    .as_ref()
+                    .map(|e| (e.len() - 1) as i32)
+                    .unwrap_or(-1)
+            );
+            (rect_edges, false)
+        }
         (Some(rect_edges), Some(text_edges)) if rect_edges.len() <= text_edges.len() => {
             debug!(
                 "  cell-rect using {} rect-derived columns over {} text clusters",
@@ -1719,17 +1772,21 @@ fn detect_row_stripe_table_from_cell_rects(
         return None;
     }
 
-    // Reject tables with paragraph-length cells (layout backgrounds, not tables)
+    // Reject tables with paragraph-length cells — typically layout
+    // backgrounds (sidebars, banners) where a single big rectangle
+    // contains a wall of prose.  Spare multi-row key/value tables where
+    // the value column is a multi-bullet description: those pass every
+    // other gate and shouldn't get killed on cell length alone.
     let max_cell_len = cells
         .iter()
         .flat_map(|row| row.iter())
         .map(|c| c.len())
         .max()
         .unwrap_or(0);
-    if max_cell_len > 500 {
+    if max_cell_len > 500 && non_empty_rows < 4 {
         debug!(
-            "  cell-rect rejected: max cell length {} > 500",
-            max_cell_len
+            "  cell-rect rejected: max cell length {} > 500 ({} rows, layout background)",
+            max_cell_len, non_empty_rows
         );
         return None;
     }
@@ -2143,18 +2200,20 @@ fn detect_merged_cluster_table(
         return None;
     }
 
-    // Reject if any cell has excessive text — layout background rects produce
-    // "cells" containing paragraphs, not short data-table values.
+    // Reject if any cell has excessive text — layout background rects
+    // produce "cells" containing paragraphs, not short data-table values.
+    // Multi-row key/value tables can legitimately have one column of
+    // long descriptive text, so only reject narrow-row layouts here.
     let max_cell_len = cells
         .iter()
         .flat_map(|row| row.iter())
         .map(|c| c.len())
         .max()
         .unwrap_or(0);
-    if max_cell_len > 500 {
+    if max_cell_len > 500 && non_empty_rows < 4 {
         debug!(
-            "  merged-cluster rejected: max cell length {} > 500 (layout background)",
-            max_cell_len
+            "  merged-cluster rejected: max cell length {} > 500 ({} rows, layout background)",
+            max_cell_len, non_empty_rows
         );
         return None;
     }
@@ -2584,6 +2643,46 @@ mod tests {
         );
     }
 
+    #[test]
+    fn test_row_stripe_accepts_multi_row_key_value_long_cells() {
+        // Multi-row 2-column key/value table where one value cell holds
+        // a paragraph (>500 chars).  The old `max_cell_len > 500` check
+        // rejected this shape as a "layout background"; with the
+        // multi-row guard, it should be accepted.
+        let mut rects = Vec::new();
+        let row_h = 25.0_f32;
+        let y_top = 700.0_f32;
+        for i in 0..8 {
+            let y = y_top - (i as f32) * row_h;
+            rects.push((40.0, y, 510.0, row_h));
+        }
+        let mut items = Vec::new();
+        for i in 0..8 {
+            let row_center_y = y_top - (i as f32) * row_h + row_h / 2.0;
+            // Left column: short label
+            items.push(make_item(&format!("Field {}", i), 45.0, row_center_y, 10.0));
+            // Right column: short value, except the last row which is a paragraph
+            let value = if i == 7 {
+                "X".repeat(800)
+            } else {
+                "value".to_string()
+            };
+            items.push(make_item(&value, 300.0, row_center_y, 10.0));
+        }
+        let result = detect_row_stripe_table(&items, &rects, 1);
+        assert!(
+            result.is_some(),
+            "multi-row key/value table with one long cell should be accepted"
+        );
+        let t = result.unwrap();
+        assert!(
+            t.cells.len() >= 4,
+            "expected ≥4 rows, got {}",
+            t.cells.len()
+        );
+        assert_eq!(t.cells[0].len(), 2, "expected 2 columns");
+    }
+
     // --- propagate_merged_cells ---
 
     #[test]
@@ -3342,6 +3441,88 @@ mod tests {
         assert!(table.cells[2][1].contains("deny unauthorized"));
     }
 
+    /// Wire-bordered 4-column table whose header text is centered/right-aligned
+    /// inside each cell while the data is left-aligned: cluster_x_positions
+    /// merges adjacent columns (data Item→EAN gap is below threshold) and
+    /// drops the header-only x-clusters in the filter pass, leaving only 3
+    /// text-derived columns. Rect borders are 4 columns of ground truth.
+    /// Before the fix the cell-rect path preferred text edges when they were
+    /// the smaller set — losing a column. After the fix, 3+ rect columns
+    /// always win.
+    #[test]
+    fn wired_header_data_misaligned_keeps_all_columns_from_rects() {
+        let page = 1;
+        // 4 cols: Item | EAN | Nombre | Cant
+        let col_xs = [380.0_f32, 410.0, 470.0, 660.0, 700.0];
+        // Header + 9 data rows at 15pt tall each (y descending).
+        let row_ys: Vec<f32> = (0..=10).map(|r| 400.0 - 15.0 * r as f32).collect();
+
+        let mut rects: Vec<(f32, f32, f32, f32)> = Vec::new();
+        for r in 0..10 {
+            let y_top = row_ys[r];
+            let y_bot = row_ys[r + 1];
+            for c in 0..4 {
+                rects.push((col_xs[c], y_bot, col_xs[c + 1] - col_xs[c], y_top - y_bot));
+            }
+        }
+
+        let mut items: Vec<TextItem> = Vec::new();
+        // Header row (y ≈ 392.5): headers sit further to the right than data
+        // because they are centered/right-aligned in the cells.
+        items.push(make_item("Item", 389.0, 392.5, 9.0));
+        items.push(make_item("EAN", 432.0, 392.5, 9.0));
+        items.push(make_item("Nombre", 552.0, 392.5, 9.0));
+        items.push(make_item("Cant", 672.0, 392.5, 9.0));
+
+        let names = [
+            "Arnes Frontal",
+            "Arnes Motor",
+            "Arnes Piso",
+            "Arnes Techo",
+            "Arnes Puerta",
+            "Arnes Tablero",
+            "Arnes Trasero",
+            "Arnes Lateral",
+            "Arnes Sensor",
+        ];
+        for r in 0..9 {
+            let y = 377.5 - 15.0 * r as f32;
+            items.push(make_item(&(r + 1).to_string(), 396.0, y, 9.0));
+            items.push(make_item("7701023403016", 410.0, y, 9.0));
+            items.push(make_item(names[r], 480.0, y, 9.0));
+            items.push(make_item("1", 680.0, y, 9.0));
+        }
+
+        let table = detect_row_stripe_table_from_cell_rects(&items, &rects, page)
+            .expect("wired 4-column table with header/data x-misalignment must detect");
+        assert_eq!(
+            table.columns.len(),
+            4,
+            "expected 4 columns from rect borders; cells: {:?}",
+            table.cells
+        );
+        for c in 0..4 {
+            let any_populated = table.cells.iter().any(|row| !row[c].trim().is_empty());
+            assert!(
+                any_populated,
+                "column {} empty across all rows; cells: {:?}",
+                c, table.cells
+            );
+        }
+        // Header row populated in all 4 cells.
+        let header = &table.cells[0];
+        assert_eq!(header[0].trim(), "Item");
+        assert_eq!(header[1].trim(), "EAN");
+        assert_eq!(header[2].trim(), "Nombre");
+        assert_eq!(header[3].trim(), "Cant");
+        // First data row: Item="1", EAN, name, count="1" — no Item↔EAN merge.
+        let data1 = &table.cells[1];
+        assert_eq!(data1[0].trim(), "1");
+        assert_eq!(data1[1].trim(), "7701023403016");
+        assert!(data1[2].trim().contains("Arnes"));
+        assert_eq!(data1[3].trim(), "1");
+    }
+
     #[test]
     fn failed_cluster_no_hint_without_items() {
         // Rects with no text items inside → no failed-cluster hint generated.

src/tables/format.rs

@@ -160,6 +160,81 @@ fn starts_with_uppercase_word(cell: &str) -> bool {
         .is_some_and(|c| c.is_uppercase())
 }
 
+fn starts_with_uppercase_alpha(cell: &str) -> bool {
+    cell.chars()
+        .find(|c| c.is_alphabetic())
+        .is_some_and(|c| c.is_uppercase())
+}
+
+fn starts_with_lowercase_alpha(cell: &str) -> bool {
+    cell.chars()
+        .find(|c| c.is_alphabetic())
+        .is_some_and(|c| c.is_lowercase())
+}
+
+fn starts_with_numbered_label(cell: &str) -> bool {
+    let trimmed = cell.trim_start();
+    let digit_count = trimmed.chars().take_while(|c| c.is_ascii_digit()).count();
+
+    digit_count > 0
+        && digit_count <= 3
+        && trimmed
+            .chars()
+            .nth(digit_count)
+            .is_some_and(|c| matches!(c, '.' | ')' | '-' | ':'))
+}
+
+fn alpha_word_count(cell: &str) -> usize {
+    cell.split_whitespace()
+        .filter(|word| word.chars().any(|c| c.is_alphabetic()))
+        .count()
+}
+
+fn looks_like_compact_entry_label(cell: &str) -> bool {
+    let trimmed = cell.trim();
+    if trimmed.len() < 3 || trimmed.len() > 80 {
+        return false;
+    }
+
+    if !starts_with_uppercase_alpha(trimmed) && !starts_with_numbered_label(trimmed) {
+        return false;
+    }
+
+    if trimmed.ends_with(['.', ',', ';', ':']) {
+        return false;
+    }
+
+    let words = alpha_word_count(trimmed);
+    (1..=6).contains(&words)
+}
+
+fn looks_like_plain_section_label(cell: &str) -> bool {
+    let trimmed = cell.trim();
+    if trimmed.len() < 4 || trimmed.len() > 40 {
+        return false;
+    }
+    if trimmed.ends_with(['.', ',', ';', ':']) || trimmed.contains(|ch: char| ch.is_ascii_digit()) {
+        return false;
+    }
+    if trimmed.len() <= 4 && trimmed.chars().all(|ch| !ch.is_lowercase()) {
+        return false;
+    }
+    trimmed
+        .chars()
+        .all(|ch| ch.is_alphabetic() || ch.is_whitespace() || matches!(ch, '&' | '/' | '-'))
+        && starts_with_uppercase_alpha(trimmed)
+        && (1..=4).contains(&alpha_word_count(trimmed))
+}
+
+fn ends_like_incomplete_phrase(cell: &str) -> bool {
+    let lower = cell.trim_end().to_ascii_lowercase();
+    lower.ends_with(" and")
+        || lower.ends_with(" or")
+        || lower.ends_with(',')
+        || lower.ends_with('-')
+        || lower.ends_with('/')
+}
+
 /// Clean up table cells: merge continuation rows, extract footnotes, remove empty rows
 fn clean_table_cells(cells: &[Vec<String>]) -> (Vec<Vec<String>>, Vec<String>) {
     let mut cleaned: Vec<Vec<String>> = Vec::new();
@@ -185,6 +260,9 @@ fn clean_table_cells(cells: &[Vec<String>]) -> (Vec<Vec<String>>, Vec<String>) {
             continue;
         }
 
+        let num_cols = row.len();
+        let filled_cells = row.iter().filter(|c| !c.trim().is_empty()).count();
+
         // Check if this is a continuation row (first column is empty but others have content).
         // A row with only 1 short non-empty cell (besides the first) is more likely a
         // section sub-header (e.g. "JAN", "FEB") than overflow text — don't merge it.
@@ -222,31 +300,76 @@ fn clean_table_cells(cells: &[Vec<String>]) -> (Vec<Vec<String>>, Vec<String>) {
             .iter()
             .filter(|cell| starts_with_uppercase_word(cell))
             .count();
+        let first_non_empty_col = row.iter().position(|c| !c.trim().is_empty());
+        let first_non_empty_cell = first_non_empty_col
+            .and_then(|idx| row.get(idx))
+            .map(|c| c.trim())
+            .unwrap_or("");
+        let title_like_later_cells = first_non_empty_col
+            .map(|idx| {
+                row.iter()
+                    .skip(idx + 1)
+                    .map(|c| c.trim())
+                    .filter(|c| !c.is_empty() && starts_with_uppercase_alpha(c))
+                    .count()
+            })
+            .unwrap_or(0);
+        let prev_first_cell_empty = cleaned
+            .last()
+            .and_then(|r| r.first())
+            .is_some_and(|c| c.trim().is_empty());
+        let prev_first_cell = cleaned
+            .last()
+            .and_then(|r| r.first())
+            .map(|c| c.trim())
+            .unwrap_or("");
+        let header_filled = cleaned
+            .first()
+            .map(|r| r.iter().filter(|c| !c.trim().is_empty()).count())
+            .unwrap_or(num_cols);
         let looks_like_spanning_first_column_row = first_cell.is_empty()
             && row.len() >= 4
             && non_first_cells.len() == row.len().saturating_sub(1)
             && uppercase_leading_cells >= non_first_cells.len().saturating_sub(1);
+        // Hierarchical tables often use a row-spanned first column: sub-rows
+        // leave column 0 blank, then start a compact title-like label in
+        // column 1.  Wrapped continuations in the existing fixtures start
+        // mid-sentence/lowercase ("continued text here", "with 3.5%...") or
+        // carry lowercase fragments in the later cells, so keep those mergeable.
+        let looks_like_hierarchical_subrow = first_cell.is_empty()
+            && row.len() >= 3
+            && first_non_empty_col == Some(1)
+            && looks_like_compact_entry_label(first_non_empty_cell)
+            && ((non_first_cells.len() >= 2 && title_like_later_cells > 0)
+                || (non_first_cells.len() == 1
+                    && prev_first_cell_empty
+                    && alpha_word_count(first_non_empty_cell) >= 2));
+        let looks_like_new_first_column_entry = !first_cell.is_empty()
+            && (starts_with_numbered_label(first_cell) || starts_with_uppercase_alpha(first_cell))
+            && filled_cells >= 2
+            && non_first_cells
+                .iter()
+                .any(|cell| looks_like_compact_entry_label(cell));
+        let looks_like_section_label_row = !first_cell.is_empty()
+            && filled_cells == 1
+            && header_filled >= 3
+            && looks_like_plain_section_label(first_cell);
         // Classic continuation: first cell empty, content in other cells
         let is_classic_continuation = first_cell.is_empty()
             && !non_first_cells.is_empty()
             && !is_short_subheader
             && !looks_like_data_row
             && !looks_like_spanning_first_column_row
+            && !looks_like_hierarchical_subrow
             && cleaned.len() > 1;
 
         // Wrapped-cell continuation: row has fewer filled cells than the header
         // row, suggesting it's overflow text from the previous row's cells.
         // Only trigger when the previous row has significantly more filled cells.
-        let num_cols = row.len();
-        let filled_cells = row.iter().filter(|c| !c.trim().is_empty()).count();
         let prev_filled = cleaned
             .last()
             .map(|r| r.iter().filter(|c| !c.trim().is_empty()).count())
             .unwrap_or(0);
-        let header_filled = cleaned
-            .first()
-            .map(|r| r.iter().filter(|c| !c.trim().is_empty()).count())
-            .unwrap_or(num_cols);
         // Merge when the row has significantly fewer filled cells than header.
         // For wide tables (5+ cols), require ≤50% of header cells.
         // For narrow tables (2-4 cols), require fewer than header cells.
@@ -257,11 +380,18 @@ fn clean_table_cells(cells: &[Vec<String>]) -> (Vec<Vec<String>>, Vec<String>) {
         } else {
             header_filled.saturating_sub(1)
         };
+        let continues_wrapped_first_column_label = !first_cell.is_empty()
+            && starts_with_lowercase_alpha(first_cell)
+            && ends_like_incomplete_phrase(prev_first_cell);
         let is_wrapped_continuation = cleaned.len() > 1
             && filled_cells <= max_filled_for_merge
-            && prev_filled > filled_cells
+            && (prev_filled > filled_cells
+                || (continues_wrapped_first_column_label && prev_filled >= filled_cells))
             && !looks_like_data_row
             && !looks_like_spanning_first_column_row
+            && !looks_like_hierarchical_subrow
+            && !looks_like_new_first_column_entry
+            && !looks_like_section_label_row
             && !is_short_subheader;
 
         let is_continuation = is_classic_continuation || is_wrapped_continuation;
@@ -407,6 +537,44 @@ mod tests {
         assert!(cleaned[1][1].contains("continued text here"));
     }
 
+    #[test]
+    fn test_clean_table_cells_first_column_section_label_not_merged() {
+        let cells = vec![
+            vec![
+                "Properties".into(),
+                "Conditions".into(),
+                "Method".into(),
+                "Typical values".into(),
+                "Units".into(),
+            ],
+            vec![
+                "Melt Flow Rate".into(),
+                "230 C/2.16 kg".into(),
+                "ASTM D1238".into(),
+                "3.0".into(),
+                "g/10 min".into(),
+            ],
+            vec![
+                "Mechanical".into(),
+                "".into(),
+                "".into(),
+                "".into(),
+                "".into(),
+            ],
+            vec![
+                "Tensile Stress at Yield".into(),
+                "50 mm/min".into(),
+                "ASTM D638".into(),
+                "31".into(),
+                "MPa".into(),
+            ],
+        ];
+        let (cleaned, _) = clean_table_cells(&cells);
+
+        assert_eq!(cleaned.len(), 4);
+        assert_eq!(cleaned[2][0], "Mechanical");
+    }
+
     #[test]
     fn test_clean_table_cells_short_subheader_not_merged() {
         let cells = vec![
@@ -459,6 +627,100 @@ mod tests {
         assert_eq!(cleaned[2][1], "Uncertainty around other copies");
     }
 
+    #[test]
+    fn test_clean_table_cells_numbered_hierarchy_rows_not_overmerged() {
+        let cells = vec![
+            vec![
+                "Group".into(),
+                "Task".into(),
+                "Detail".into(),
+                "Benefit".into(),
+            ],
+            vec![
+                "1. Group alpha".into(),
+                "Task setup and".into(),
+                "Begin setup".into(),
+                "Faster start".into(),
+            ],
+            vec![
+                "".into(),
+                "management".into(),
+                "recommended profile".into(),
+                "with saved defaults".into(),
+            ],
+            vec![
+                "2. Group beta and".into(),
+                "Storage setup".into(),
+                "Provides upload tools".into(),
+                "".into(),
+            ],
+            vec![
+                "fine-tuning".into(),
+                "".into(),
+                "for filtered inputs".into(),
+                "service".into(),
+            ],
+            vec![
+                "".into(),
+                "Label workspace".into(),
+                "Creates review sets".into(),
+                "Lets teams review".into(),
+            ],
+            vec![
+                "".into(),
+                "Model training".into(),
+                "".into(),
+                "Supports custom model".into(),
+            ],
+        ];
+        let (cleaned, _) = clean_table_cells(&cells);
+
+        assert_eq!(cleaned.len(), 5);
+        assert_eq!(cleaned[1][0], "1. Group alpha");
+        assert_eq!(cleaned[1][1], "Task setup and management");
+        assert_eq!(cleaned[2][0], "2. Group beta and fine-tuning");
+        assert_eq!(cleaned[2][1], "Storage setup");
+        assert_eq!(cleaned[3][1], "Label workspace");
+        assert_eq!(cleaned[4][1], "Model training");
+    }
+
+    #[test]
+    fn test_clean_table_cells_partial_hierarchical_subrow_not_merged() {
+        let cells = vec![
+            vec![
+                "Group".into(),
+                "Task".into(),
+                "Detail".into(),
+                "Benefit".into(),
+            ],
+            vec![
+                "Group A".into(),
+                "Alpha task".into(),
+                "Initial detail".into(),
+                "Initial benefit".into(),
+            ],
+            vec![
+                "".into(),
+                "Beta task".into(),
+                "Parallel detail".into(),
+                "".into(),
+            ],
+            vec![
+                "".into(),
+                "second line".into(),
+                "additional detail".into(),
+                "".into(),
+            ],
+        ];
+        let (cleaned, _) = clean_table_cells(&cells);
+
+        assert_eq!(cleaned.len(), 3);
+        assert_eq!(cleaned[1][1], "Alpha task");
+        assert_eq!(cleaned[2][0], "");
+        assert_eq!(cleaned[2][1], "Beta task second line");
+        assert_eq!(cleaned[2][2], "Parallel detail additional detail");
+    }
+
     #[test]
     fn test_clean_table_cells_full_width_continuation_row_still_merges_when_lowercase() {
         let cells = vec![

tests/integration_tests.rs

@@ -2,13 +2,14 @@
 
 use pdf_inspector::detector::{estimate_page_count_from_bytes, DetectionConfig, ScanStrategy};
 use pdf_inspector::extractor::group_into_lines;
+use pdf_inspector::types::ItemType;
 use pdf_inspector::types::TextLine;
 use pdf_inspector::{
     detect_pdf_type, detect_vector_grid_in_region_mem, extract_pages_markdown,
     extract_pages_markdown_mem, extract_tables_in_regions_mem, extract_text,
-    extract_text_in_regions_mem, extract_text_with_positions, process_pdf_mem,
-    process_pdf_with_options, to_markdown, MarkdownOptions, PdfError, PdfOptions, PdfType,
-    TextItem,
+    extract_text_in_regions_mem, extract_text_with_positions, extract_text_with_positions_mem,
+    process_pdf_mem, process_pdf_with_options, to_markdown, MarkdownOptions, PdfError, PdfOptions,
+    PdfType, TextItem,
 };
 use std::collections::HashSet;
 
@@ -1648,6 +1649,33 @@ fn test_bits_pilani_page8_table_detection() {
     assert!(!region.needs_ocr, "Page 8 table should still be detected");
 }
 
+#[test]
+fn test_extract_tables_in_regions_uses_line_grid() {
+    // Stroked-grid table (m/l/S path operators forming a 2x2 grid).
+    // The heuristic text-only detector handles the same cells already,
+    // so this guards that the line-backed path doesn't regress: the
+    // markdown still contains all four data cells.
+    let buf = synthetic_vector_grid_pdf(false);
+    let results =
+        extract_tables_in_regions_mem(&buf, &[(0, vec![[40.0, 50.0, 220.0, 760.0]])]).unwrap();
+    let region = &results[0].regions[0];
+    assert!(
+        !region.needs_ocr,
+        "stroked-grid table should be extracted, got needs_ocr=true"
+    );
+    for tok in ["A1", "B1", "A2", "B2"] {
+        assert!(
+            region.text.contains(tok),
+            "expected '{tok}' in output, got: {}",
+            region.text
+        );
+    }
+    assert!(
+        region.text.contains('|'),
+        "expected pipe-delimited markdown"
+    );
+}
+
 // =========================================================================
 // extract_tables_with_structure_mem tests (TSR-aware path)
 // =========================================================================
@@ -3364,3 +3392,186 @@ fn test_synthetic_type0_broken_tounicode_emits_fffd_not_latin1_mojibake() {
         result.pages_needing_ocr
     );
 }
+
+// ============================================================================
+// Image XObject emission
+// ============================================================================
+
+/// Build a minimal PDF containing one Image XObject placed at a known CTM.
+/// `image_ctm` is the 6-element matrix applied to the unit square by the
+/// `Do` operator (per PDF spec section 8.9.5 "Image Coordinate System").
+/// For an axis-aligned image at `(x, y)` with size `w × h`, that's
+/// `[w, 0, 0, h, x, y]`.
+fn make_pdf_with_image(image_ctm: [f32; 6]) -> Vec<u8> {
+    let mut pdf = b"%PDF-1.4\n".to_vec();
+    let mut offsets = vec![0usize];
+
+    fn add_object(pdf: &mut Vec<u8>, offsets: &mut Vec<usize>, id: usize, body: &str) {
+        offsets.push(pdf.len());
+        pdf.extend_from_slice(format!("{id} 0 obj\n").as_bytes());
+        pdf.extend_from_slice(body.as_bytes());
+        pdf.extend_from_slice(b"\nendobj\n");
+    }
+    fn add_stream_object(
+        pdf: &mut Vec<u8>,
+        offsets: &mut Vec<usize>,
+        id: usize,
+        dict: &str,
+        stream_bytes: &[u8],
+    ) {
+        offsets.push(pdf.len());
+        pdf.extend_from_slice(format!("{id} 0 obj\n").as_bytes());
+        pdf.extend_from_slice(
+            format!("<< {} /Length {} >>\nstream\n", dict, stream_bytes.len()).as_bytes(),
+        );
+        pdf.extend_from_slice(stream_bytes);
+        pdf.extend_from_slice(b"\nendstream\nendobj\n");
+    }
+
+    // 1: catalog → 2: pages → 3: page with XObject /Im0 → 4: content stream
+    // 5: font → 6: image XObject (1×1 grayscale)
+    add_object(
+        &mut pdf,
+        &mut offsets,
+        1,
+        "<< /Type /Catalog /Pages 2 0 R >>",
+    );
+    add_object(
+        &mut pdf,
+        &mut offsets,
+        2,
+        "<< /Type /Pages /Kids [3 0 R] /Count 1 >>",
+    );
+    add_object(
+        &mut pdf,
+        &mut offsets,
+        3,
+        "<< /Type /Page /Parent 2 0 R /MediaBox [0 0 612 792] \
+         /Resources << /Font << /F1 5 0 R >> /XObject << /Im0 6 0 R >> >> \
+         /Contents 4 0 R >>",
+    );
+    let [a, b, c, d, e, f] = image_ctm;
+    // BT/ET around a small text item just so the page isn't classified as
+    // image-only (which would route to a different code path). Then save
+    // graphics state, apply the image CTM, invoke Im0, restore.
+    let content = format!(
+        "BT /F1 12 Tf 100 700 Td (Hi) Tj ET\nq {} {} {} {} {} {} cm /Im0 Do Q",
+        a, b, c, d, e, f
+    );
+    add_stream_object(&mut pdf, &mut offsets, 4, "", content.as_bytes());
+    add_object(
+        &mut pdf,
+        &mut offsets,
+        5,
+        "<< /Type /Font /Subtype /Type1 /BaseFont /Helvetica >>",
+    );
+    // 1×1 grayscale image; the single byte is mid-gray. Contents don't
+    // matter to the extractor — it only cares about the XObject's
+    // /Subtype and the CTM at the `Do` operator.
+    let image_pixel = [128u8];
+    add_stream_object(
+        &mut pdf,
+        &mut offsets,
+        6,
+        "/Type /XObject /Subtype /Image /Width 1 /Height 1 \
+         /ColorSpace /DeviceGray /BitsPerComponent 8",
+        &image_pixel,
+    );
+
+    let xref_start = pdf.len();
+    pdf.extend_from_slice(format!("xref\n0 {}\n", offsets.len()).as_bytes());
+    pdf.extend_from_slice(b"0000000000 65535 f \n");
+    for offset in offsets.iter().skip(1) {
+        pdf.extend_from_slice(format!("{offset:010} 00000 n \n").as_bytes());
+    }
+    pdf.extend_from_slice(
+        format!(
+            "trailer\n<< /Size {} /Root 1 0 R >>\nstartxref\n{}\n%%EOF",
+            offsets.len(),
+            xref_start
+        )
+        .as_bytes(),
+    );
+    pdf
+}
+
+#[test]
+fn test_extract_text_with_positions_emits_image_bboxes() {
+    // Place a 200×100 image at (50, 600) in PDF user space (origin
+    // bottom-left). The Do operator applies the CTM to a unit square,
+    // so for an axis-aligned image, CTM = [w, 0, 0, h, x, y].
+    let pdf = make_pdf_with_image([200.0, 0.0, 0.0, 100.0, 50.0, 600.0]);
+    let items = extract_text_with_positions_mem(&pdf).expect("extract");
+
+    let images: Vec<&TextItem> = items
+        .iter()
+        .filter(|i| matches!(i.item_type, ItemType::Image))
+        .collect();
+    assert_eq!(
+        images.len(),
+        1,
+        "expected exactly one Image item, got items: {:?}",
+        items
+            .iter()
+            .map(|i| (&i.text, &i.item_type))
+            .collect::<Vec<_>>()
+    );
+    let img = images[0];
+    assert!((img.x - 50.0).abs() < 0.01, "x={}", img.x);
+    assert!((img.y - 600.0).abs() < 0.01, "y={}", img.y);
+    assert!((img.width - 200.0).abs() < 0.01, "width={}", img.width);
+    assert!((img.height - 100.0).abs() < 0.01, "height={}", img.height);
+    assert_eq!(img.page, 1);
+    // text field carries the legacy `[Image: <resource-name>]` form that
+    // the markdown emitter already knows how to parse.
+    assert_eq!(img.text, "[Image: Im0]");
+}
+
+#[test]
+fn test_image_xobject_bbox_handles_rotated_ctm() {
+    // 90° rotation CTM: a unit square at the origin maps to a square
+    // rotated counter-clockwise about (0,0), then translated to (200, 300).
+    // For a 100×100 image, that's CTM = [0, 100, -100, 0, 200, 300]
+    // (apply the rotation: (1,0) → (0,100); (0,1) → (-100,0)).
+    // The page-space corners are:
+    //   (0,0) → (200, 300)
+    //   (1,0) → (200, 400)
+    //   (1,1) → (100, 400)
+    //   (0,1) → (100, 300)
+    // → AABB: x=100..200 (w=100), y=300..400 (h=100).
+    let pdf = make_pdf_with_image([0.0, 100.0, -100.0, 0.0, 200.0, 300.0]);
+    let items = extract_text_with_positions_mem(&pdf).expect("extract");
+    let img = items
+        .iter()
+        .find(|i| matches!(i.item_type, ItemType::Image))
+        .expect("image item");
+    assert!((img.x - 100.0).abs() < 0.01, "x={}", img.x);
+    assert!((img.y - 300.0).abs() < 0.01, "y={}", img.y);
+    assert!((img.width - 100.0).abs() < 0.01, "width={}", img.width);
+    assert!((img.height - 100.0).abs() < 0.01, "height={}", img.height);
+}
+
+#[test]
+fn test_image_emission_does_not_change_default_markdown() {
+    // Default `MarkdownOptions::include_images = false` — adding image
+    // emission MUST NOT make `extract_pages_markdown` start producing
+    // `![Image: …]` placeholders for everyone. Existing callers that
+    // upgrade should see no diff in their markdown.
+    let pdf = make_pdf_with_image([200.0, 0.0, 0.0, 100.0, 50.0, 600.0]);
+    let result = extract_pages_markdown_mem(&pdf, None).expect("extract");
+    assert_eq!(result.pages.len(), 1);
+    assert!(
+        !result.pages[0].markdown.contains("Image:"),
+        "default markdown leaked an image placeholder: {:?}",
+        result.pages[0].markdown
+    );
+}
+
+#[test]
+fn test_markdown_options_default_has_include_images_false() {
+    // Explicit assertion so anyone flipping this back catches it in CI.
+    // See `MarkdownOptions::default` in src/markdown/mod.rs for the
+    // long-form rationale.
+    let opts = MarkdownOptions::default();
+    assert!(!opts.include_images);
+}