fix(pdf-inspector): relax vector table confidence gates

* emit ItemType::Image bboxes for Image XObjects (was: silently dropped)

Background. ItemType::Image, MarkdownOptions::include_images, and the
markdown emitter's image-collection path have all been in the tree
for a while, but no producer ever populated them — content_stream.rs
explicitly `// Skip images — text extraction only` at the Do
operator, and the nested Form-XObject walker in xobjects.rs only
matched XObjectType::Form, silently dropping Image entries. The
declared types were dead code.

This PR lights them up. At every Do that resolves to an Image
XObject (both top-level and nested inside Form XObjects), we now
compute the page-space bbox from the current CTM via a new
`image_bbox_from_ctm` helper — handling both axis-aligned and
rotated/sheared placements via 4-corner AABB — and emit a TextItem
with `item_type: ItemType::Image` and the legacy `[Image: <name>]`
text payload that the markdown emitter already knows how to render.

Callers can now find raster figures via `extract_text_with_positions`
(and the `_mem` variant, newly re-exported at the crate root) without
needing to re-parse the PDF or run a vision/layout model. The intended
consumer is layout-aware text pipelines that want to crop figures and
caption them out-of-band.

Two backstops to avoid silent breakage for existing callers:

  1. `MarkdownOptions::include_images` default flipped `true → false`.
     If it stayed at `true`, every existing user of
     `extract_pages_markdown` would suddenly see `![Image: Im0](image)`
     placeholders inserted throughout their output the moment they
     upgraded. Image data is still available structurally via
     `extract_text_with_positions`; rendering it into markdown is now
     an opt-in. New regression test asserts `extract_pages_markdown`
     output is unchanged for the image-bearing fixture.

  2. Image items now also skip the layout heuristics
     (`detect_columns`, `detect_tables_from_rects`) via a new
     `is_text_layout_item` predicate. Without this filter, an image's
     left edge would land in the column-projection profile and skew
     table column detection — surfaced by
     `vector_grid_tests::upstage_key_functions_four_cols` going from 4
     detected columns to 5 in CI before the filter was added.

Re-exporting `extract_text_with_positions_mem` at the crate root —
strictly additive; mirrors how `extract_pages_markdown_mem` is already
available there.

Tests:

  - test_extract_text_with_positions_emits_image_bboxes — minimal PDF
    with one 200×100 image at (50, 600); asserts one Image item with
    correct bbox + page + text.
  - test_image_xobject_bbox_handles_rotated_ctm — 90° rotated image
    via shear-component CTM; asserts AABB is correct (handles non-
    axis-aligned placements via 4-corner clamp).
  - test_image_emission_does_not_change_default_markdown — asserts no
    `Image:` token leaks into default markdown output, regression
    guard for the include_images flip.
  - test_markdown_options_default_has_include_images_false — explicit
    sentinel so anyone flipping it back catches it in CI.

* Bump version from 1.8.15 to 1.9.0

napi/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@firecrawl/pdf-inspector",
-  "version": "1.8.15",
+  "version": "1.9.1",
   "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",

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.
 ///
@@ -664,7 +664,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

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![];

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/lib.rs

@@ -47,7 +47,10 @@ pub use detector::{
     detect_pdf_type, detect_pdf_type_mem, detect_pdf_type_mem_with_config,
     detect_pdf_type_with_config, DetectionConfig, PdfType, PdfTypeResult, ScanStrategy,
 };
-pub use extractor::{extract_text, extract_text_with_positions, extract_text_with_positions_pages};
+pub use extractor::{
+    extract_text, extract_text_with_positions, extract_text_with_positions_mem,
+    extract_text_with_positions_pages,
+};
 pub use markdown::{
     to_markdown, to_markdown_from_items, to_markdown_from_items_with_rects, MarkdownOptions,
 };
@@ -820,7 +823,9 @@ pub fn extract_tables_in_regions_mem(
                     // symmetrically low under font-decode failure — this
                     // guard breaks that symmetry by comparing against
                     // bbox area, which is independent of extraction.
-                    if region_text_density_too_low(region_text_chars, region_area) {
+                    if region_text_density_too_low(region_text_chars, region_area)
+                        && !markdown_table_body_is_dense(&md)
+                    {
                         return None;
                     }
                     let shape = markdown_table_shape(&md);
@@ -831,7 +836,9 @@ pub fn extract_tables_in_regions_mem(
                         Some(TableCandidateIssue::LineRowUndercount)
                     } else if wide_table_sparse_prefix_undercount(&md) {
                         Some(TableCandidateIssue::SparseWideUndercount)
-                    } else if text_cluster_column_undercount(&matched, shape) {
+                    } else if source != TableCandidateSource::Line
+                        && text_cluster_column_undercount(&matched, shape)
+                    {
                         Some(TableCandidateIssue::TextColumnUndercount)
                     } else if prose_grid_fragment_needs_ocr(&md) {
                         Some(TableCandidateIssue::ProseGridFragment)
@@ -4250,12 +4257,21 @@ fn looks_like_partial_table_ex(markdown: &str, layout_assisted: bool) -> bool {
     }
 
     // Failure mode 2: header has empty cells in a multi-column table.
-    // When layout-assisted, allow up to 1 empty header cell (common in
-    // tables with merged/spanning header cells that we can't represent).
-    let empty_count = header_cells.iter().filter(|c| c.is_empty()).count();
+    // When layout-assisted, tolerate merged/spanning header gaps if the
+    // body is dense. Region bboxes from a layout model often start at a
+    // visual table whose header cannot be represented faithfully in a
+    // flat pipe table, while the body rows are still complete enough to use.
+    let header_empty_indices: Vec<usize> = header_cells
+        .iter()
+        .enumerate()
+        .filter_map(|(idx, cell)| cell.is_empty().then_some(idx))
+        .collect();
+    let empty_count = header_empty_indices.len();
     if layout_assisted {
-        // Reject only if >1 empty header cell (2+ means serious boundary issue)
-        if n_cols >= 3 && empty_count >= 2 {
+        if n_cols >= 3
+            && empty_count >= 2
+            && !layout_assisted_empty_header_has_dense_body(markdown, n_cols)
+        {
             return true;
         }
     } else if n_cols >= 3 && empty_count >= 1 {
@@ -4293,7 +4309,14 @@ fn looks_like_partial_table_ex(markdown: &str, layout_assisted: bool) -> bool {
             // (totals, subtotals) are common.
             let threshold = if layout_assisted { 2 } else { 3 };
             if n_cols >= 3 && empty_data * threshold >= n_cols {
-                return true;
+                let sparse_row_shares_header_spacer = layout_assisted
+                    && data_inner.iter().enumerate().any(|(idx, cell)| {
+                        cell.trim().is_empty() && header_empty_indices.contains(&idx)
+                    })
+                    && layout_assisted_empty_header_has_dense_body(markdown, n_cols);
+                if !sparse_row_shares_header_spacer {
+                    return true;
+                }
             }
         }
     }
@@ -4351,6 +4374,68 @@ fn looks_like_partial_table_ex(markdown: &str, layout_assisted: bool) -> bool {
     false
 }
 
+fn layout_assisted_empty_header_has_dense_body(markdown: &str, n_cols: usize) -> bool {
+    let rows = markdown_pipe_rows(markdown);
+    let data_rows: Vec<&Vec<&str>> = rows
+        .iter()
+        .skip(1)
+        .filter(|row| row.iter().any(|cell| !cell.trim().is_empty()))
+        .collect();
+    if data_rows.len() < 2 || n_cols < 3 {
+        return false;
+    }
+
+    let total_cells = data_rows.len() * n_cols;
+    let mut filled_cells = 0usize;
+    let mut rows_with_multiple_cells = 0usize;
+    let mut max_filled_in_row = 0usize;
+    for row in &data_rows {
+        let filled = row.iter().filter(|cell| !cell.trim().is_empty()).count();
+        filled_cells += filled;
+        max_filled_in_row = max_filled_in_row.max(filled);
+        if filled >= 2 {
+            rows_with_multiple_cells += 1;
+        }
+    }
+
+    // Dense enough to be a useful extraction despite lossy merged headers.
+    // The row-count gate avoids accepting a single tidy row under a broken
+    // header, and the density gate keeps sparse fragments on the OCR path.
+    rows_with_multiple_cells * 2 >= data_rows.len()
+        && max_filled_in_row >= n_cols.min(3)
+        && filled_cells * 100 >= total_cells * 45
+}
+
+fn markdown_table_body_is_dense(markdown: &str) -> bool {
+    let rows = markdown_pipe_rows(markdown);
+    let data_rows: Vec<&Vec<&str>> = rows
+        .iter()
+        .skip(1)
+        .filter(|row| row.iter().any(|cell| !cell.trim().is_empty()))
+        .collect();
+    if data_rows.len() < 3 {
+        return false;
+    }
+
+    let cols = rows.iter().map(|row| row.len()).max().unwrap_or_default();
+    if cols < 3 {
+        return false;
+    }
+
+    let mut filled_cells = 0usize;
+    let mut rows_with_multiple_cells = 0usize;
+    for row in &data_rows {
+        let filled = row.iter().filter(|cell| !cell.trim().is_empty()).count();
+        filled_cells += filled;
+        if filled >= cols.min(3) {
+            rows_with_multiple_cells += 1;
+        }
+    }
+
+    let total_cells = data_rows.len() * cols;
+    rows_with_multiple_cells * 2 >= data_rows.len() && filled_cells * 100 >= total_cells * 45
+}
+
 /// Original strict validation (no layout assistance). Used by tests and
 /// full-page extraction paths that don't have layout model assistance.
 #[cfg(test)]
@@ -4806,7 +4891,9 @@ mod table_candidate_selection_tests {
 
 #[cfg(test)]
 mod looks_like_partial_table_tests {
-    use super::{looks_like_partial_table, looks_like_partial_table_ex};
+    use super::{
+        looks_like_partial_table, looks_like_partial_table_ex, markdown_table_body_is_dense,
+    };
 
     #[test]
     fn good_table_passes() {
@@ -4941,11 +5028,29 @@ mod looks_like_partial_table_tests {
 
     #[test]
     fn two_empty_headers_still_rejected_when_layout_assisted() {
-        // 2+ empty headers is still bad even with layout assistance.
+        // A single tidy row is not enough evidence to trust a badly gapped header.
         let md = "|A|||D|\n|---|---|---|---|\n|x|y|z|w|";
         assert!(
             looks_like_partial_table_ex(md, true),
-            "2 empty headers rejected even layout-assisted"
+            "2 empty headers with only one body row are rejected even layout-assisted"
+        );
+    }
+
+    #[test]
+    fn dense_body_with_empty_merged_header_passes_when_layout_assisted() {
+        let md = "|Year||Unadjusted Basis|||\n\
+                  |---|---|---|---|---|\n\
+                  |1|.1667|$100,000|$16,670|$16,670|\n\
+                  |2|.3333|$100,000|$33,330|$50,000|\n\
+                  |3|.3333|$100,000|$33,330|$88,330|\n\
+                  |4|.1667|$100,000|$16,670|$100,000|";
+        assert!(
+            looks_like_partial_table(md),
+            "strict mode still rejects merged-header gaps"
+        );
+        assert!(
+            !looks_like_partial_table_ex(md, true),
+            "layout-assisted should trust a dense body under a merged header"
         );
     }
 
@@ -4970,6 +5075,22 @@ mod looks_like_partial_table_tests {
         );
     }
 
+    #[test]
+    fn sparse_first_row_with_header_spacer_passes_when_layout_assisted() {
+        let md = "|Properties|Instruction||Training Datasets Alignment|\n\
+                  |---|---|---|---|\n\
+                  ||Alpaca-GPT4 OpenOrca Synth. Math-Instruct||Orca DPO Pairs Ultrafeedback Cleaned|\n\
+                  |Total # Samples|52K 2.91M 126K||12.9K 60.8K 126K|";
+        assert!(
+            looks_like_partial_table(md),
+            "strict mode rejects the sparse first row"
+        );
+        assert!(
+            !looks_like_partial_table_ex(md, true),
+            "layout-assisted should allow sparse rows that share a header spacer column"
+        );
+    }
+
     #[test]
     fn paragraph_still_rejected_when_layout_assisted() {
         // Paragraph detection is not relaxed — it's a genuine extraction issue.
@@ -5023,6 +5144,27 @@ mod looks_like_partial_table_tests {
             "duplicate headers rejected even layout-assisted"
         );
     }
+
+    #[test]
+    fn dense_numeric_table_body_is_structurally_trusted() {
+        let md = "|Year|3-Year|5-Year|7-Year|\n\
+                  |---|---|---|---|\n\
+                  |1|33.0%|20.00%|14.29%|\n\
+                  |2|44.45%|32.00%|24.49%|\n\
+                  |3|14.81%|19.20%|17.49%|\n\
+                  |4|7.41%|11.52%|12.49%|";
+        assert!(markdown_table_body_is_dense(md));
+    }
+
+    #[test]
+    fn sparse_markdown_fragment_is_not_structurally_trusted() {
+        let md = "|A|B|C|D|\n\
+                  |---|---|---|---|\n\
+                  |x||||\n\
+                  |||y||\n\
+                  ||||z|";
+        assert!(!markdown_table_body_is_dense(md));
+    }
 }
 
 /// Analyse extracted items and rects for layout complexity.

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/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 {

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;
 
@@ -3391,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);
+}