PDF citations: keep page coordinates correct after rotation and cropping

PDF citation boxes must use an explicit coordinate system, especially after page rotation, cropping or rendering. A correct quote can highlight the wrong region when extraction coordinates are treated as screenshot pixels or when a transformation is applied twice by different components.

Identify the coordinate spaces

The PyMuPDF Page reference explains page properties and rotation-related coordinates. Distinguish document coordinates, the visible page rectangle and rendered image pixels. A browser view can introduce another scale or translation. Store the source coordinate space with every extracted box. A bare rectangle without that context is not sufficient to reproduce a highlight after display settings change.

Treat rectangles and transforms separately

The official Rect reference defines rectangle semantics, while the Matrix reference describes transformations. Keep the original box and the applied transform rather than replacing the original coordinates irreversibly. Rotation and translation are not interchangeable operations. A chain that works for an unrotated uncropped page may fail when the visible origin or orientation changes, even though its dimensions still look plausible.

Build a rotated-page fixture

Use a page containing a clearly identifiable warning near a corner. Save the extracted text box, then inspect the highlight in the original view, a rotated view and a cropped view. The warning must remain selected in every view. This fixture should include a box away from the page center because a centered box can hide mistakes in rotation origin or translation.

Representation	Information to preserve
Extracted text box	Original coordinate space and page identity
Rotated display	Rotation transform and orientation
Cropped display	Visible region and origin adjustment
Rendered image	Scale and pixel-space mapping

Diagnose a misplaced highlight

If every box has the same offset, inspect the crop origin or display translation. If the offset grows with distance from the origin, inspect scaling. If boxes land in a different quadrant, inspect rotation and whether it was already applied. If only some citations fail, compare page-specific properties rather than imposing a global correction. Preserve the text associated with each box to verify that the geometry still belongs to the intended passage.

Keep citation geometry reversible

A citation record should contain document revision, page identity, source box, transformation chain and displayed target. Test coordinate round trips within a declared numerical tolerance rather than inventing universal pixel accuracy. Human inspection should confirm the selected text, especially near tables or adjacent columns. This makes geometry failures distinguishable from retrieval failures and protects a technically correct answer from a misleading visual citation that points to unrelated evidence.