[Feature] Support defining reading order from the layout stage

[jspast]

Requested feature

Some layout models, such as PP-DocLayoutV3, include reading order in their output. Ideally, Docling could support using that order instead of computing it again later in the reading order stage.

Related: #3224, #3233

[wittjeff]

Adding a second and third producer for the same hook, since I think this issue is the right place to design it once.

Who has an order to supply

1. Layout models that emit one, as here (PP-DocLayoutV3).
2. Tagged PDFs. The structure tree defines the logical content order (ISO 32000-2, 14.7; Well-Tagged PDF 1.0, 8.2.3), and for form widgets WTPDF 8.9.3.3 says order comes from the structure tree, not /Tabs. The tagged-structure stage in feat(pdf): derive layout, heading levels and alt text from the tagged-PDF structure tree #4148 (proposal in Proposal: tagged-PDF structure ingestion for PDF/UA-2 beyond forms (companion to #4143) #4146) turns structure elements into pre-labeled clusters, but today the authored order is thrown away because the elements still go through the reading-order predictor. For accessibility consumers this is not a quality question; the authored order is the contract.
3. Native form widgets. feat: integrate native AcroForm widgets as typed fields #4140 emits widgets in native order inside a field region and lists form reading order as future work.

All three need the same thing the issue asks for: a way to tell the reading-order stage "this page's order is already known".

Where it can plug in

ReadingOrderPredictor.predict_reading_order already partitions elements by page, runs _predict_page separately on headers, body and footers, and concatenates pages in page-number order. Nothing crosses page boundaries. So the override is per page and local to ReadingOrderModel.__call__:

• add an optional index on the cluster, e.g. Cluster.reading_order: int | None = None, set by whichever stage knows it (layout engine, tagged-structure stage, form stage) and carried through assembly onto the page element;
• in ReadingOrderModel.__call__, split the assembled elements by page; a page where every body element carries an index is sorted by it, every other page goes to the predictor as now; merge back in page order;
• caption, footnote and merge mapping keep running on the combined sorted list, so the concern raised on feat: add do_reading_order option to PdfPipelineOptions #3233 (that skipping the predictor must not skip those) is met.

A page is all-or-nothing on purpose. Partially tagged pages, or a layout model that orders only some classes, fall back to the predictor for the whole page rather than interleaving two orderings. That keeps the first version small and testable, and a finer merge can come later if a real case needs it.

Relation to #3233

That PR's reorder_elements=False is the degenerate case where the supplied order is "postprocessor order for every page". It could land first as the option flag cau-git asked for, with the per-page index as the second step, or the two could be one change.

I am happy to implement this alongside #4148, since the tagged-structure stage would be its first consumer with a fixture whose expected order is fixed by the file itself (tests/data/pdf/sources/tagged_ua2_sample.pdf, veraPDF PDF/UA-2 pass). If PP-DocLayoutV3 support (#3224) lands with an order output, it would be the second consumer with no further changes to the reading-order stage.