fix: TSR auto-fallback bugs found in review, v1.7.2

Three fixes to extract_tables_with_structure_auto_mem (added in
1.7.1) caught by external review:

1. multi_row_in_cell over-triggered on legitimate multi-line cells.
   The previous threshold (item span > 1.3× either smallest cell or
   tallest item height) fires on any cell with 2+ y-separated text
   items — including rowspan>1 cells, wrapped descriptions, and
   superscript/subscript runs. Replaced with two gates:
   - skip cells whose declared rowspan > 1 (intentional multi-line)
   - require an actual whitespace gap (>~half a line height)
     between the bottom of one item and the top of the next, in
     PDF-native y-coordinates. Same-line items with tall glyphs or
     superscripts have negative or near-zero gap; truly separate
     visual rows have gap ≈ leading − line-height.
   FNBO regression test still passes; new test covers a rowspan=2
   cell with two visible text lines and verifies no fallback fires.

2. Heuristic returning empty silently replaced TSR markdown with
   "". The auto wrapper now keeps the TSR markdown when the
   heuristic markdown is empty/whitespace and tags fallback_reason
   with `_heuristic_empty` suffix (e.g.
   `multi_row_in_cell_heuristic_empty`). Worst case we ship the
   same wrong-but-non-empty TSR output we'd have shipped before
   1.7.1; we never replace useful output with literally nothing.

3. One bad input blanked the whole batch. Errors from
   detect_tsr_quality_issue or extract_tables_in_regions_mem now
   stay scoped to the single input — that input falls through to
   raw TSR markdown with a `_error` reason label so callers can
   metric on it. Other inputs in the batch are unaffected.

3 new integration tests:
- test_auto_does_not_fire_on_legit_rowspan_cell
- test_auto_keeps_tsr_markdown_when_heuristic_returns_empty
- test_auto_isolates_per_input_failures

All 6 auto tests + full 123-test suite pass. FNBO local replay
still triggers fallback (phantom_empty_row signal in this run) and
emits correct Shawnee/BVP/Sonoma rows with correct census tracts.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

napi/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@firecrawl/pdf-inspector",
-  "version": "1.7.0",
+  "version": "1.7.2",
   "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/src/lib.rs

@@ -422,6 +422,52 @@ pub fn extract_tables_with_structure_cells(
     })
 }
 
+/// One result from `extractTablesWithStructureAuto` — markdown plus a
+/// diagnostic flag identifying which path produced it.
+///
+/// `fallbackReason` is `null` when the TSR-hybrid path produced the
+/// markdown directly. When stage 1's quality check fires (the cells
+/// look like a SLANet detection pathology — phantom rows or multi-row
+/// content in a single cell), the heuristic table extractor is run on
+/// the same region instead, and `fallbackReason` carries the diagnostic
+/// label (`"phantom_empty_row"`, `"multi_row_in_cell"`).
+#[napi(object)]
+pub struct TableExtractionResultJs {
+    pub markdown: String,
+    pub fallback_reason: Option<String>,
+}
+
+/// Auto-fallback variant of [`extractTablesWithStructure`].
+///
+/// Runs the TSR-hybrid path, checks the resulting cells for known
+/// SLANet detection pathologies, and falls back to the heuristic
+/// `extractTablesInRegions` for any input where the TSR path looks
+/// compromised.
+///
+/// On clean inputs this returns identical markdown to
+/// `extractTablesWithStructure`; on flagged inputs the heuristic
+/// markdown replaces the TSR markdown and `fallbackReason` is set.
+#[napi]
+pub fn extract_tables_with_structure_auto(
+    buffer: Buffer,
+    inputs: Vec<TsrTableInputJs>,
+) -> Result<Vec<TableExtractionResultJs>> {
+    let bytes: Vec<u8> = buffer.to_vec();
+    let parsed = parse_tsr_inputs(&inputs);
+
+    catch_panic("extract_tables_with_structure_auto", move || {
+        let result = pdf_inspector::extract_tables_with_structure_auto_mem(&bytes, &parsed)
+            .map_err(|e| to_napi_err(e, "extract_tables_with_structure_auto"))?;
+        Ok(result
+            .into_iter()
+            .map(|r| TableExtractionResultJs {
+                markdown: r.markdown,
+                fallback_reason: r.fallback_reason,
+            })
+            .collect())
+    })
+}
+
 fn parse_tsr_inputs(inputs: &[TsrTableInputJs]) -> Vec<pdf_inspector::TsrTableInput> {
     inputs
         .iter()

src/lib.rs

@@ -1185,6 +1185,262 @@ pub fn extract_tables_with_structure_mem(
         .collect())
 }
 
+/// Markdown for one extracted table plus a diagnostic flag describing
+/// which path produced it.
+///
+/// `fallback_reason` is `None` when the TSR-hybrid path produced the
+/// markdown directly; `Some(<short identifier>)` when stage 1's quality
+/// check fired and the heuristic `extract_tables_in_regions_mem` was
+/// substituted instead. The reason string is stable enough to use as a
+/// metric label (e.g. `phantom_empty_row`, `multi_row_in_cell`).
+#[derive(Debug, Clone)]
+pub struct TableExtractionResult {
+    pub markdown: String,
+    pub fallback_reason: Option<String>,
+}
+
+/// Detect quality issues in the TSR-hybrid output for a single input.
+///
+/// Returns `Some(reason)` if the cells look like they reflect a known
+/// SLANet detection pathology that the heuristic table extractor would
+/// likely handle better. Reasons (also used as metric labels):
+///
+/// * `phantom_empty_row` — a row whose every cell is empty, surrounded
+///   above and below by rows with content. SLANet sometimes emits an
+///   extra row that doesn't correspond to any visible PDF row.
+/// * `multi_row_in_cell` — at least one `rowspan==1` cell encloses
+///   PDF text items that cluster into two distinct visual lines
+///   separated by a whitespace gap larger than the line height. Cells
+///   declared as `rowspan>1` are excluded since they are *expected*
+///   to span multiple lines. SLANet's row under-detection on
+///   tightly-packed tables produces the rowspan==1-but-multi-line
+///   pattern (the FNBO failure mode).
+fn detect_tsr_quality_issue(
+    buffer: &[u8],
+    input: &TsrTableInput,
+    cells: &[tables::StructuredCell],
+) -> Result<Option<String>, PdfError> {
+    if cells.is_empty() {
+        return Ok(None);
+    }
+
+    // Phantom row: cheap, computed from cell metadata alone.
+    let max_row = cells.iter().map(|c| c.row).max().unwrap_or(0);
+    if max_row >= 2 {
+        let mut row_has_content = vec![false; max_row + 1];
+        for cell in cells {
+            if !cell.text.trim().is_empty() {
+                row_has_content[cell.row] = true;
+            }
+        }
+        for r in 1..max_row {
+            if !row_has_content[r] && row_has_content[r - 1] && row_has_content[r + 1] {
+                return Ok(Some("phantom_empty_row".to_string()));
+            }
+        }
+    }
+
+    // Multi-row-in-cell: re-extract PDF text items in the page and look
+    // for `rowspan==1` cells that contain items grouped into ≥2 visual
+    // lines separated by a real whitespace gap. This is the FNBO mode:
+    // a tall TSR cell catches text from two adjacent PDF rows that
+    // SLANet failed to separate. Cells declared `rowspan>1` are
+    // expected to be multi-line and are excluded.
+    let (doc, _page_count) = load_document_from_mem(buffer)?;
+    let pages = doc.get_pages();
+    let page_1idx = input.page + 1;
+    let Some(&page_id) = pages.get(&page_1idx) else {
+        return Ok(None);
+    };
+    let page_h = get_page_height(&doc, page_id).unwrap_or(792.0);
+    let mut needed: HashSet<u32> = HashSet::new();
+    needed.insert(page_1idx);
+    let font_cmaps = FontCMaps::from_doc_pages_fast(&doc, Some(&needed));
+    let ((mut items, _rects, _lines), _has_gid, coords_rotated) =
+        extractor::content_stream::extract_page_text_items(
+            &doc,
+            page_id,
+            page_1idx,
+            &font_cmaps,
+            false,
+        )?;
+    let _ = text_utils::fix_letterspaced_items(&mut items);
+    let coords = if coords_rotated {
+        RegionCoordSpace::Rotated90Ccw
+    } else {
+        RegionCoordSpace::Standard
+    };
+
+    for cell in cells {
+        // rowspan>1 cells are intentionally multi-line — skip them.
+        if cell.rowspan > 1 {
+            continue;
+        }
+        if cell.text.trim().is_empty() {
+            continue;
+        }
+        let [x1, y1, x2, y2] = cell.page_pt_bbox;
+        if x1 >= x2 || y1 >= y2 {
+            continue;
+        }
+        let bounds = region_bounds(x1, y1, x2, y2, page_h, coords);
+
+        // Collect the items inside this cell, with their y-centers and
+        // half-heights so we can cluster them into visual lines.
+        let mut cell_items: Vec<(f32, f32)> = Vec::new();
+        for item in &items {
+            if tsr_region_contains_item(item, bounds) {
+                let cy = item.y + item.height * 0.5;
+                let half_h = (item.height * 0.5).max(2.5);
+                cell_items.push((cy, half_h));
+            }
+        }
+        if cell_items.len() < 2 {
+            continue;
+        }
+        // Sort by y-center descending (top-of-page first in PDF native
+        // coords where y grows upward) — direction doesn't matter, we
+        // just need consecutive items to be neighbors in the sort.
+        cell_items.sort_by(|a, b| b.0.total_cmp(&a.0));
+
+        // Walk pairs and see if there's a real whitespace gap between
+        // any two adjacent items — defined as their bounding-box edges
+        // separated by more than half a line height. This rules out
+        // tall glyphs / superscripts / accents on a single visual line.
+        let max_half_h = cell_items
+            .iter()
+            .map(|(_, h)| *h)
+            .fold(0f32, f32::max)
+            .max(2.5);
+        let gap_threshold = max_half_h; // ≈ half a line height
+        let mut found_gap = false;
+        for w in cell_items.windows(2) {
+            let (cy_a, h_a) = w[0];
+            let (cy_b, h_b) = w[1];
+            // Gap = distance between the bottom of the upper item and
+            // the top of the lower item, measured in PDF-native coords
+            // (y grows upward, so the upper item has the larger cy).
+            let upper_bottom = cy_a - h_a;
+            let lower_top = cy_b + h_b;
+            let gap = upper_bottom - lower_top;
+            if gap > gap_threshold {
+                found_gap = true;
+                break;
+            }
+        }
+        if found_gap {
+            return Ok(Some("multi_row_in_cell".to_string()));
+        }
+    }
+
+    Ok(None)
+}
+
+/// Auto-fallback variant of [`extract_tables_with_structure_mem`]:
+/// runs the TSR-hybrid path, checks the resulting cells for known
+/// SLANet detection pathologies (phantom rows, multi-row-in-cell text),
+/// and falls back to the heuristic [`extract_tables_in_regions_mem`]
+/// for any input where the TSR path looks compromised.
+///
+/// On clean inputs this is identical to the markdown variant.
+/// On flagged inputs the heuristic markdown replaces the TSR markdown
+/// and the result's `fallback_reason` is set to the diagnostic label.
+///
+/// Two failure modes are guarded against per-input:
+///
+/// * **Empty heuristic**: if the heuristic returns empty/whitespace
+///   markdown for a flagged region, the original TSR markdown is
+///   preserved and `fallback_reason` is suffixed with
+///   `_heuristic_empty` (e.g. `multi_row_in_cell_heuristic_empty`).
+///   This avoids replacing a usable wrong-but-non-empty TSR output
+///   with literally nothing.
+/// * **Per-input errors**: any failure in detection or heuristic
+///   extraction for a single input is contained — that input
+///   returns the raw TSR markdown with `fallback_reason` set to
+///   an `_error` label so callers can metric on it. Other inputs
+///   in the same batch are unaffected.
+///
+/// Use this from production callers that want self-healing output.
+/// Use [`extract_tables_with_structure_mem`] when you want raw TSR
+/// output regardless of quality (e.g. eval harnesses comparing the
+/// two paths).
+pub fn extract_tables_with_structure_auto_mem(
+    buffer: &[u8],
+    inputs: &[TsrTableInput],
+) -> Result<Vec<TableExtractionResult>, PdfError> {
+    let tsr_cells = extract_tables_with_structure_cells_mem(buffer, inputs)?;
+    let mut results = Vec::with_capacity(inputs.len());
+
+    for (i, input) in inputs.iter().enumerate() {
+        let cells = &tsr_cells[i];
+        let tsr_md = if cells.is_empty() {
+            String::new()
+        } else {
+            tables::cells_to_markdown(cells)
+        };
+
+        let issue = match detect_tsr_quality_issue(buffer, input, cells) {
+            Ok(opt) => opt,
+            Err(_) => {
+                // Detection failed for this input — fall through with
+                // the raw TSR markdown so the rest of the batch is
+                // unaffected. Tag the reason for caller metrics.
+                results.push(TableExtractionResult {
+                    markdown: tsr_md,
+                    fallback_reason: Some("detection_error".to_string()),
+                });
+                continue;
+            }
+        };
+
+        let result = match issue {
+            None => TableExtractionResult {
+                markdown: tsr_md,
+                fallback_reason: None,
+            },
+            Some(reason) => {
+                // Fall back to heuristic on the input's table region.
+                // The crop's PDF-pt bbox IS the table region.
+                let heuristic_md = match extract_tables_in_regions_mem(
+                    buffer,
+                    &[(input.page, vec![input.crop_pdf_pt_bbox])],
+                ) {
+                    Ok(pages) => pages
+                        .into_iter()
+                        .next()
+                        .and_then(|p| p.regions.into_iter().next().map(|r| r.text))
+                        .unwrap_or_default(),
+                    Err(_) => {
+                        // Heuristic threw — keep raw TSR markdown.
+                        results.push(TableExtractionResult {
+                            markdown: tsr_md,
+                            fallback_reason: Some(format!("{reason}_heuristic_error")),
+                        });
+                        continue;
+                    }
+                };
+                if heuristic_md.trim().is_empty() {
+                    // Heuristic produced nothing useful — keep TSR
+                    // markdown rather than ship empty. The reason
+                    // suffix lets callers count this case.
+                    TableExtractionResult {
+                        markdown: tsr_md,
+                        fallback_reason: Some(format!("{reason}_heuristic_empty")),
+                    }
+                } else {
+                    TableExtractionResult {
+                        markdown: heuristic_md,
+                        fallback_reason: Some(reason),
+                    }
+                }
+            }
+        };
+        results.push(result);
+    }
+
+    Ok(results)
+}
+
 /// Get page height in points from MediaBox.
 fn get_page_height(doc: &Document, page_id: lopdf::ObjectId) -> Option<f32> {
     let page_dict = doc.get_dictionary(page_id).ok()?;

tests/integration_tests.rs

@@ -2052,6 +2052,357 @@ fn test_extract_tables_with_structure_separator_after_thead() {
     assert_eq!(mds[0], "|Department|Core Courses|\n|---|---|\n|BIO|8.23|\n");
 }
 
+// =========================================================================
+// extract_tables_with_structure_auto_mem tests (TSR + heuristic fallback)
+// =========================================================================
+
+#[test]
+fn test_auto_passes_through_clean_tsr_output() {
+    use pdf_inspector::{extract_tables_with_structure_auto_mem, TsrTableInput};
+
+    let buf = synthetic_dense_table_pdf();
+    let tokens: Vec<String> = [
+        "<table>",
+        "<thead>",
+        "<tr>",
+        "<th></th>",
+        "<th></th>",
+        "</tr>",
+        "</thead>",
+        "<tbody>",
+        "<tr>",
+        "<td></td>",
+        "<td></td>",
+        "</tr>",
+        "<tr>",
+        "<td></td>",
+        "<td></td>",
+        "</tr>",
+        "</tbody>",
+        "</table>",
+    ]
+    .into_iter()
+    .map(String::from)
+    .collect();
+    // Cells fit each visible row cleanly. Same shape as the existing
+    // dense-overlap regression test — TSR should produce clean output
+    // and the auto wrapper should pass through with no fallback.
+    let cell_bboxes = vec![
+        poly(10.0, 72.0, 100.0, 112.0),
+        poly(90.0, 72.0, 180.0, 112.0),
+        poly(10.0, 88.8, 100.0, 128.8),
+        poly(90.0, 88.8, 180.0, 128.8),
+        poly(10.0, 105.6, 100.0, 145.6),
+        poly(90.0, 105.6, 180.0, 145.6),
+    ];
+
+    let results = extract_tables_with_structure_auto_mem(
+        &buf,
+        &[TsrTableInput {
+            page: 0,
+            crop_pdf_pt_bbox: [0.0, 0.0, 200.0, 800.0],
+            render_dpi: 72.0,
+            structure_tokens: tokens,
+            cell_bboxes,
+        }],
+    )
+    .unwrap();
+    assert_eq!(results.len(), 1);
+    assert!(
+        results[0].fallback_reason.is_none(),
+        "expected no fallback, got {:?}",
+        results[0].fallback_reason
+    );
+    assert!(results[0].markdown.contains("Oak Street"));
+    assert!(results[0].markdown.contains("Boardwalk"));
+    assert!(!results[0].markdown.contains("Oak Street Boardwalk"));
+}
+
+#[test]
+fn test_auto_falls_back_on_multi_row_in_cell() {
+    use pdf_inspector::{extract_tables_with_structure_auto_mem, TsrTableInput};
+
+    let buf = synthetic_dense_table_pdf();
+    // TSR returns only 2 rows for what's actually 3 visible PDF rows.
+    // Row 1's cells are tall enough to encompass both Oak Street and
+    // Boardwalk text — the FNBO row-undercount pattern.
+    let tokens: Vec<String> = [
+        "<table>",
+        "<thead>",
+        "<tr>",
+        "<th></th>",
+        "<th></th>",
+        "</tr>",
+        "</thead>",
+        "<tbody>",
+        "<tr>",
+        "<td></td>",
+        "<td></td>",
+        "</tr>",
+        "</tbody>",
+        "</table>",
+    ]
+    .into_iter()
+    .map(String::from)
+    .collect();
+    // Header row at top-left y=[88, 105] (covers "Branch Name"/"Deposits"
+    // at native y=700, top-left y≈92-103). The "data" row at top-left
+    // y=[105, 145] is intentionally tall — covers BOTH the Oak Street
+    // line (top-left y≈108-119) AND the Boardwalk line (y≈124-135).
+    let cell_bboxes = vec![
+        poly(10.0, 88.0, 100.0, 105.0),
+        poly(90.0, 88.0, 180.0, 105.0),
+        poly(10.0, 105.0, 100.0, 145.0),
+        poly(90.0, 105.0, 180.0, 145.0),
+    ];
+
+    let results = extract_tables_with_structure_auto_mem(
+        &buf,
+        &[TsrTableInput {
+            page: 0,
+            crop_pdf_pt_bbox: [0.0, 0.0, 200.0, 800.0],
+            render_dpi: 72.0,
+            structure_tokens: tokens,
+            cell_bboxes,
+        }],
+    )
+    .unwrap();
+    assert_eq!(results.len(), 1);
+    assert_eq!(
+        results[0].fallback_reason.as_deref(),
+        Some("multi_row_in_cell"),
+        "expected multi_row_in_cell fallback, got {:?}",
+        results[0].fallback_reason
+    );
+    // The heuristic-fallback markdown should preserve all three PDF rows.
+    let md = &results[0].markdown;
+    assert!(md.contains("Oak Street"), "missing Oak Street: {md}");
+    assert!(md.contains("Boardwalk"), "missing Boardwalk: {md}");
+    assert!(md.contains("100"), "missing 100: {md}");
+    assert!(md.contains("200"), "missing 200: {md}");
+}
+
+#[test]
+fn test_auto_returns_empty_inputs() {
+    use pdf_inspector::extract_tables_with_structure_auto_mem;
+    let buf = synthetic_dense_table_pdf();
+    let results = extract_tables_with_structure_auto_mem(&buf, &[]).unwrap();
+    assert!(results.is_empty());
+}
+
+#[test]
+fn test_auto_does_not_fire_on_legit_rowspan_cell() {
+    use pdf_inspector::{extract_tables_with_structure_auto_mem, TsrTableInput};
+
+    let buf = synthetic_dense_table_pdf();
+    // 2 columns, 3 rows in the visible PDF. SLANet emits a 2-row table
+    // where the LEFT cell of row 1 is a rowspan=2 cell that legitimately
+    // covers Oak Street + Boardwalk on two visual lines. The right
+    // column has two normal rows. multi_row_in_cell must NOT fire on
+    // the rowspan=2 cell.
+    let tokens: Vec<String> = [
+        "<table>",
+        "<thead>",
+        "<tr>",
+        "<th></th>",
+        "<th></th>",
+        "</tr>",
+        "</thead>",
+        "<tbody>",
+        "<tr>",
+        // First data cell explicitly declares rowspan=2.
+        "<td",
+        " rowspan=\"2\"",
+        ">",
+        "</td>",
+        "<td></td>",
+        "</tr>",
+        "<tr>",
+        "<td></td>",
+        "</tr>",
+        "</tbody>",
+        "</table>",
+    ]
+    .into_iter()
+    .map(String::from)
+    .collect();
+    // Header row, then a tall left cell covering both data lines, plus
+    // two narrow right cells (one per line).
+    let cell_bboxes = vec![
+        poly(10.0, 88.0, 100.0, 105.0),
+        poly(90.0, 88.0, 180.0, 105.0),
+        poly(10.0, 105.0, 100.0, 145.0), // rowspan=2 — covers both lines
+        poly(90.0, 105.0, 180.0, 122.0), // row 1 only
+        poly(90.0, 122.0, 180.0, 145.0), // row 2 only
+    ];
+
+    let results = extract_tables_with_structure_auto_mem(
+        &buf,
+        &[TsrTableInput {
+            page: 0,
+            crop_pdf_pt_bbox: [0.0, 0.0, 200.0, 800.0],
+            render_dpi: 72.0,
+            structure_tokens: tokens,
+            cell_bboxes,
+        }],
+    )
+    .unwrap();
+    assert_eq!(results.len(), 1);
+    assert!(
+        results[0].fallback_reason.is_none(),
+        "rowspan=2 cell containing 2 visual lines should not trip multi_row_in_cell, got reason={:?}",
+        results[0].fallback_reason,
+    );
+}
+
+#[test]
+fn test_auto_keeps_tsr_markdown_when_heuristic_returns_empty() {
+    use pdf_inspector::{extract_tables_with_structure_auto_mem, TsrTableInput};
+
+    let buf = synthetic_dense_table_pdf();
+    // Same shape as the multi_row_in_cell regression — a tall data cell
+    // that catches Oak Street + Boardwalk. But the crop bbox we pass
+    // points at a strip of the page that has NO text items, so the
+    // heuristic's region will be empty when it tries to extract there.
+    // The auto wrapper must keep the TSR markdown rather than ship "".
+    let tokens: Vec<String> = [
+        "<table>",
+        "<thead>",
+        "<tr>",
+        "<th></th>",
+        "<th></th>",
+        "</tr>",
+        "</thead>",
+        "<tbody>",
+        "<tr>",
+        "<td></td>",
+        "<td></td>",
+        "</tr>",
+        "</tbody>",
+        "</table>",
+    ]
+    .into_iter()
+    .map(String::from)
+    .collect();
+    // Cell bboxes overlap the actual PDF text (so multi_row_in_cell
+    // fires) — but the crop_pdf_pt_bbox we hand to the heuristic is a
+    // wholly-empty region of the page. The heuristic should return "".
+    let cell_bboxes = vec![
+        poly(10.0, 88.0, 100.0, 105.0),
+        poly(90.0, 88.0, 180.0, 105.0),
+        poly(10.0, 105.0, 100.0, 145.0),
+        poly(90.0, 105.0, 180.0, 145.0),
+    ];
+
+    let results = extract_tables_with_structure_auto_mem(
+        &buf,
+        &[TsrTableInput {
+            page: 0,
+            // Crop is at the BOTTOM of the page where there's no text.
+            crop_pdf_pt_bbox: [0.0, 0.0, 200.0, 50.0],
+            render_dpi: 72.0,
+            structure_tokens: tokens,
+            cell_bboxes,
+        }],
+    )
+    .unwrap();
+    assert_eq!(results.len(), 1);
+    let r = &results[0];
+    assert_eq!(
+        r.fallback_reason.as_deref(),
+        Some("multi_row_in_cell_heuristic_empty"),
+        "expected _heuristic_empty suffix, got {:?}",
+        r.fallback_reason,
+    );
+    // TSR markdown should be preserved — non-empty, contains the cell
+    // text we know was assigned by the TSR path.
+    assert!(
+        !r.markdown.trim().is_empty(),
+        "expected TSR markdown to be preserved, got empty",
+    );
+    assert!(
+        r.markdown.contains("Oak Street") || r.markdown.contains("Boardwalk"),
+        "expected TSR markdown to contain at least one row, got: {}",
+        r.markdown,
+    );
+}
+
+#[test]
+fn test_auto_isolates_per_input_failures() {
+    use pdf_inspector::{extract_tables_with_structure_auto_mem, TsrTableInput};
+
+    let buf = synthetic_dense_table_pdf();
+    let good_tokens: Vec<String> = [
+        "<table>",
+        "<thead>",
+        "<tr>",
+        "<th></th>",
+        "<th></th>",
+        "</tr>",
+        "</thead>",
+        "<tbody>",
+        "<tr>",
+        "<td></td>",
+        "<td></td>",
+        "</tr>",
+        "<tr>",
+        "<td></td>",
+        "<td></td>",
+        "</tr>",
+        "</tbody>",
+        "</table>",
+    ]
+    .into_iter()
+    .map(String::from)
+    .collect();
+    // A clean input that should pass through with no fallback.
+    let good_input = TsrTableInput {
+        page: 0,
+        crop_pdf_pt_bbox: [0.0, 0.0, 200.0, 800.0],
+        render_dpi: 72.0,
+        structure_tokens: good_tokens,
+        cell_bboxes: vec![
+            poly(10.0, 72.0, 100.0, 112.0),
+            poly(90.0, 72.0, 180.0, 112.0),
+            poly(10.0, 88.8, 100.0, 128.8),
+            poly(90.0, 88.8, 180.0, 128.8),
+            poly(10.0, 105.6, 100.0, 145.6),
+            poly(90.0, 105.6, 180.0, 145.6),
+        ],
+    };
+    // A bad input that targets a non-existent page. The detection
+    // helper short-circuits on missing pages with Ok(None), so this
+    // shouldn't itself crash, but pairing it with a flagged input
+    // exercises the per-input control flow regardless. The point of
+    // this test is that one input's outcome doesn't poison the other.
+    let bad_input = TsrTableInput {
+        page: 9999,
+        crop_pdf_pt_bbox: [0.0, 0.0, 100.0, 100.0],
+        render_dpi: 72.0,
+        structure_tokens: vec![
+            "<table>".into(),
+            "<tr>".into(),
+            "<td></td>".into(),
+            "</tr>".into(),
+            "</table>".into(),
+        ],
+        cell_bboxes: vec![poly(0.0, 0.0, 50.0, 50.0)],
+    };
+
+    let results = extract_tables_with_structure_auto_mem(&buf, &[good_input, bad_input]).unwrap();
+    assert_eq!(results.len(), 2);
+    // Good input still produces non-empty TSR markdown with no fallback.
+    assert!(
+        results[0].fallback_reason.is_none(),
+        "good input should pass through, got reason={:?}",
+        results[0].fallback_reason,
+    );
+    assert!(results[0].markdown.contains("Oak Street"));
+    // Bad input collapses to empty markdown but doesn't take the
+    // batch down with it.
+    assert_eq!(results[1].markdown, "");
+}
+
 // =========================================================================
 // extract_pages_markdown_mem tests
 // =========================================================================