extract_tables: reject font-decode failures via text-density floor

Some PDFs have fonts whose ToUnicode CMap is missing or broken —
Identity-H fonts without unicode metadata, Type-3 fonts where every
glyph maps to garbage. The page extractor returns punctuation-only
fragments or single-glyph repeats; the rendered image still carries
the visible text, so the region should fall back to OCR rather than
serve a partial table.

The existing captured_only_a_fragment guard can't catch this case
because region_text_chars itself collapses under font-decode failure —
captured vs extracted is symmetrically low, and the ratio still looks
acceptable.

Add a complementary area-based density guard: when a region has lots
of pixel real estate but very few text chars, the page extractor
hit a font failure. Bbox area is independent of extraction success,
so the symmetry breaks.

Threshold 0.003 chars/sq pt sits between observed clean extractions
(≥0.005 on full-page A4 ledgers, key/value layouts, archival
catalogs) and observed font-decode failures (≤0.0014 on prod-traffic
samples). Three guards keep it from misfiring:
  - text_chars < 20 skipped: synthetic / fragmentary fixtures
  - area < 30,000 sq pt skipped: tiny stat blocks
  - area > 400,000 sq pt skipped: near-whole-A4 bboxes where
    density is unreliable (large white-space margins)

Verified against three reproducible cases from prod shadow logs
that previously served partial output:
  - Cyrillic page with punctuation-only decode (46 chars, density
    0.00045) → flagged, routes to OCR
  - Cyrillic page where every glyph collapsed to one letter (89
    chars, density 0.00025) → flagged, routes to OCR
  - Materials-test region where text extracted fine but the table
    body extends beyond the bbox (96 chars, density 0.00131)
    → flagged, routes to OCR

Existing fixtures (full-page A4 ledger, multi-row key/value with
paragraph values, archival catalog, bits_pilani whole-page tests,
synthetic line-grid test) all retain identical behavior.

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

.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

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

napi/package.json

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

@@ -1394,13 +1394,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 +1634,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 +1763,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 +2191,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 +2634,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 +3432,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,63 @@ 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 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 +242,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,23 +282,64 @@ 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 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));
         // 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())
@@ -257,11 +358,17 @@ 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
             && !is_short_subheader;
 
         let is_continuation = is_classic_continuation || is_wrapped_continuation;
@@ -459,6 +566,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

@@ -1648,6 +1648,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)
 // =========================================================================