[yhay81]

Closes #624

words, layout, chars, and search with exact_bboxes=True now measure a font that a document does not embed on the fallback face that draws it, as frozen pylopdf does. fallback-exact-boxes retires from evidence/phase1-parity.

Acceptance

• On tests/assets/text/nonembedded-cjk.pdf, words(exact_bboxes=True) matches frozen pylopdf with its CJK extras, and evidence/phase1-parity/causes.toml no longer lists fallback-exact-boxes. run.py measured the merged tree: every output of the 7 pages is equal, and the corpus keeps only the one close raster and the heading of patent-us223898.pdf. PR Read a multi-glyph cluster as its text in other readers (#637) #650 moved nothing in the report. tests/test_parity.py passes with PYROPDF_PARITY_PYLOPDF set.
• Editing doc.fallback_fonts changes the exact boxes that the next call returns, and a call with the same faces reuses the memoized result (test_editing_the_fallback_fonts_changes_the_exact_boxes_of_the_next_call, which counts hits and computations). Other text keeps its memo key (test_the_memo_of_other_text_keeps_its_key_when_the_fallback_fonts_change).
• Without an installed face, exact boxes are as they are now, and a document whose fonts are all embedded reads no fallback face (exact_boxes_measure_a_font_that_a_document_does_not_embed_on_its_face, only_exact_boxes_of_a_font_that_is_not_embedded_read_a_face).
• The API reference of exact_bboxes says that the boxes depend on the fallback faces (Page.words, Page.layout, Document.fallback_fonts).

python tools/check.py --locked passes. No engine API that fuzz/ uses changed: page_text keeps its signature, so Annotation.text and Document.text, which have no exact_bboxes, are untouched too.

Two things that differ from what the issue expected

The faces supply only the ink, in a second interpretation. Interpreting the page through the faces once, as frozen pylopdf does, is not enough on hayro 0.9. hayro 0.8 stretched a substitute's outline to the PDF's width, and hayro 0.9 puts that stretch in the glyph's transform, where nothing tells it apart. Advances taken through it are scaled: with /W [0 65535 500], 計画地 split into three words in exact mode. So the records still come from an interpretation without faces, which also keeps a face's line metrics out of the font's, and the faces give only ink. A watch on the font resolver runs the second interpretation only when a face would draw a font of the page, so other pages cost what they did and read no face.

I checked this against the oracle beyond the Acceptance, on the fixture and on the same pages with explicit half and full /W: words, layout with and without chars and styles, and search with boxes and quads, all with exact_bboxes=True, have no difference over 0.01 point. That script is not committed.

Page 1 was not equal because of CIDFontType0. Frozen pylopdf fills its faces at its first rendering, and text extraction before that gives what it gives without them. The dump rendered each page after reading it, so only page 1 read without faces, and the README's explanation was wrong. dump.py --fallback-fonts now renders first, and the README says so. pyropdf gives the same boxes in any order, so a frozen pylopdf call before any rendering still differs from it, by design.

Beyond the issue's Paths

docs/en/api/ is generated from the docstrings, and docs/en/rendering.md and docs/ja/rendering.md said that text extraction does not use the faces, which is no longer true.

Follow-ups, both filed

• Keep the PDF's advances when hayro stretches a substitute glyph #656: on hayro 0.9, words() and layout() boxes of a non-embedded Latin font move when its /Widths differ from the substitute's (Hello ends at 106.14, against 90.0 in frozen pylopdf). This is the same stretch, without any face, and comes from Move to hayro 0.9 with LaurenzV/hayro#1734 patched in, and read streams that name a file #609, after 0.2.1. It is a regression of 0.2.2 if it ships as it is, and the corpus does not show it. Whether it goes into 0.2.2 is the owner's call.
• Measure the text runs of page.content() on the fallback faces #658: the text runs of page.content() still have no ink on these fonts, where frozen pylopdf measures the faces. The issue's Notes leave it out, since only exact_bboxes=True reads the faces here.

For 0.2.2's changelog

• page.words, page.layout, page.chars, and page.search with exact_bboxes=True measure a CJK font that the document does not embed on the doc.fallback_fonts face that draws it, so these boxes now depend on those faces. Text and other boxes do not change. (Measure the exact boxes of non-embedded CJK fonts on their fallback faces #624)

🤖 Generated with Claude Code