🐞 Reconstruct PDF reading order and safely reorder text objects

[JFWooten4]

Summary

Reconstruct PDF reading order from the printed page layout during --retag, rather than reusing the order of text objects in the content stream. The reported example is Nine to Noon, PDF page 6: attribution → paperback ISBN → hardback ISBN → disclaimer. Its current stream puts the disclaimer before the ISBN lines, causing discontinuous selection/copying in macOS Preview.

• Group adjacent native font/style runs into physical lines without joining across a column gutter.
• Infer single-column and confidently detected two-column bands, respecting full-width headings and section dividers. Preserve stream order where column detection is ambiguous, rather than blindly sorting all lines by vertical position.
• Create marked-content IDs and structure-tree references in reconstructed block order.
• Physically move only independently balanced, self-contained q … Q text drawing scopes, retaining their local clipping/transforms and refusing movement across Form/image or graphics-state barriers. Re-extract text positions after any safe movement so tag offsets do not become stale.
• Preserve the upstream --retag handling of optional-content scopes, existing metadata and bookmarks, and decorative Forms.

Tests and evidence

• Passed here: 8 dependency-free tests in tests/test_reading_order.py: page-6 footer ordering, mixed-font runs, two-column contents with spanning headings, paragraph/gutter separation, safe scoped reordering, Form barriers, and idempotent reconstruction.
• Added, but not run here: tests/test_reading_order_pdf.py, an optional full-book regression that uses the source PDF when PDF_MAGIC_BOOK is set and checks repeated retagging, unchanged raster output, links, bookmarks, metadata, printed wording, and qpdf --check.
• Prior temporary proof of concept: physically moving the independently scoped disclaimer unit after both ISBNs on PDF page 6 preserved page rendering and the original document's page geometry and linked information. This proof of concept did not verify the full retagged structure tree.

Validation still required before merge: run the full PDF integration tests on the actual book, run qpdf --check, and manually drag-select/copy the footer in macOS Preview across all four lines. The current environment lacks the native pikepdf/qpdf test pipeline and macOS Preview. Improved /ActualText or text extraction alone is not evidence that native Preview highlighting or copy/paste works.

Dependency

This is a stacked PR targeting bella-brella, which introduces --retag. Merge the lower PR first, then retarget this one to main before merging. No original book has been replaced or committed.

#4