find_tables(): opt-in layout union, grid refinement, merged-cell/header model, and Table.to_html()

[veget-able]

This adds an opt-in table model to page.find_tables(), plus one always-on correctness fix. Harald and Robin have already reviewed the substance of this work on a fork branch; this PR is the same code rebased onto current main with review-oriented comments reduced to normal docstrings. The long-form write-up (decision rationale, measurement appendix) lives here: https://github.com/veget-able/PyMuPDF/blob/single-diff/table-refine-html/UPSTREAM-PROPOSAL.md

What's in it (commit 1):

• find_tables(use_layout=) — explicit opt-out of the 1.28.0 layout gating (default True keeps today's behavior).
• find_tables(refine=) — grid refinement: splits rows the ruling-line grid merged (using cell background shading), under-segmented columns, and over-merged body rows; resolves merged-cell structure into Table.placements (a row-major grid of SpanCell with colspan/rowspan and td/th tags), plus Table.header_rows / Table.section_rows.
• find_tables(use_layout=True, union=) — fuses the layout analyzer's table grids with the line finder's candidates: a candidate can replace a weak grid, split an over-wide one, or be appended where layout missed a table. This also supersedes the make_table_from_bbox path on the layout route, which currently returns empty silently (block-type mismatch; detailed in the write-up).
• Table.to_html() — serializes the tagged model, as a companion to to_markdown() / to_pandas().
• Always-on correctness fix: the detector's global CHARS/EDGES state becomes call-local (ContextVar) and each Table snapshots its characters. In released 1.28.0, re-extracting a table after a later find_tables() call returns wrong text; a deterministic regression test is included.

Commit 2 (independent speed fix): cells_to_tables()'s no-text probe passed the module-global TEXTPAGE to page.get_textbox(), but that global is never assigned — every probe built and Python-walked a fresh full-page TextPage per candidate (~24 ms each). The probe now scans the call's existing CHARS with the same strict-overlap rule as JM_rects_overlap(). Results are hash-identical across a 503-page corpus; find_tables() mean wall time drops 106 → 76 ms/page (−28%).

Measured (ParseBench table group, 503 pages, GTRM): official 1.28.0 stack scores 56.73; with this PR and the companion pymupdf4llm PR opted in, 72.11. Per-stage leave-one-out: union −7.6, refine −6.9, spans −5.0, header tagging −6.5.

Non-opt-in users are unaffected: all new keywords default off (use_layout=True matches 1.28.0), default-path output is byte-identical (verified by output hashing), default timing +~1% before commit 2 and −28% after it.

Structure question for maintainers: the model lives in four private sibling modules (_table_refine.py, _table_spans.py, _table_union.py, _table_headers.py) next to table.py, re-exported through pymupdf.table. If a subpackage, different names, or folding into table.py fits the project better, we're happy to reshape — none of that structure is precious to us.

Coupling: the companion PR on pymupdf/RAG (table_output="html") hard-depends on this one; this PR stands alone.

Tests: 30 added in tests/test_tables.py (stale-CHARS regression, use_layout gating, refine/placements/tags, union fusion and degradation, to_html). docs/ and changes.txt entries to follow once the direction and module layout are confirmed.

---

[github-actions]

All contributors have signed the CLA ✍️ ✅
_{Posted by the CLA Assistant Lite bot.}

[veget-able]

I have read the CLA Document and I hereby sign the CLA

[veget-able]

recheck