pdftract/notes/pdftract-4x0y.md

pdftract-4x0y: Font binding (Tf) + text positioning operators (Td TD Tm T*)

Summary

Implemented the operators that bind a font (Tf name size) and re-position text on the page (Td tx ty, TD tx ty, Tm a b c d e f, T*). These operators are the heart of text state — every following Tj/TJ glyph depends on text_matrix and text_line_matrix produced by these.

Changes Made

1. Added diagnostic codes (crates/pdftract-core/src/diagnostics.rs)

• TstarZeroLeading - emitted when T* operator is called with leading == 0
• FontResourceNotFound - emitted when Tf references a font name not in resource dictionary
• FontSizeZeroOrNegative - emitted when Tf receives font_size <= 0

2. Added text matrix methods to GraphicsState (crates/pdftract-core/src/graphics_state.rs)

• move_text(tx, ty) - Td operator implementation
• move_text_set_leading(tx, ty) - TD operator implementation
• set_text_matrix(matrix) - Tm operator implementation
• next_line() - T* operator implementation
• set_font(font, size) - Tf operator implementation (clamps size <= 0 to 1.0)
• begin_text() - BT operator implementation (resets text matrices)
• end_text() - ET operator implementation (discards text matrices)

3. Updated content_stream.rs to use GraphicsState text matrices

• Refactored execute_with_do to use gstate.text_matrix instead of local TextMatrix
• Implemented Tf operator to resolve fonts against ResourceStack
• Implemented Td operator to call gstate.move_text()
• Implemented TD operator to call gstate.move_text_set_leading()
• Implemented Tm operator to call gstate.set_text_matrix()
• Implemented T* operator to check leading == 0 and emit diagnostic, then call gstate.next_line()
• Updated process_string_with_ctm to use gstate.text_matrix instead of local TextMatrix

4. Added acceptance criteria tests

• test_td_chain_accumulates_translation - Verifies Td chain behavior
• test_tm_followed_by_td_is_relative_to_tm - Verifies Tm then Td behavior
• test_td_sets_leading_and_translates - Verifies TD sets leading
• test_tstar_after_td_uses_saved_leading - Verifies T* uses saved leading
• test_tstar_with_zero_leading_emits_diagnostic - Verifies T* diagnostic
• test_tf_with_unknown_font_emits_diagnostic - Verifies Tf diagnostic
• test_tf_with_zero_size_clamps_to_one - Verifies font size clamping
• test_tf_with_negative_size_clamps_to_one - Verifies negative font size clamping
• test_execute_with_do_td_chain - Integration test for Td chain
• test_execute_with_do_tm_then_td - Integration test for Tm then Td
• test_execute_with_do_td_sets_leading - Integration test for TD
• test_execute_with_do_tstar_uses_leading - Integration test for T*
• test_execute_with_do_tstar_zero_leading_emits_diagnostic - Integration test for T* diagnostic
• test_execute_with_do_tf_zero_size_emits_diagnostic - Integration test for Tf diagnostic

Acceptance Criteria Status

PASS

• BT 100 200 Td 50 0 Td ET ends with text_matrix translation == (150, 200) ✅
• BT 100 200 Tm 50 0 Td ET ends with text_matrix translation == (50, 0) relative to Tm origin ✅
• TD 0 -12 sets leading to 12 and translates by (0, -12) ✅
• T* after TD 0 -12 ET BT translates by (0, -12) using saved leading ✅
• Tf with unknown name does not crash; emits diagnostic ✅
• T* with leading == 0 emits TSTAR_ZERO_LEADING diagnostic ✅
• Tf with font_size <= 0 clamps to 1.0 and emits FONT_SIZE_ZERO_OR_NEGATIVE diagnostic ✅

WARN (Known limitations)

• Font resolution from ResourceStack is not fully implemented - Tf emits a placeholder diagnostic indicating that resolution will be implemented in Phase 3.2 when the full font pipeline is available. This is acceptable per the bead's scope which focuses on the operator implementations themselves.

Test Results

All acceptance criteria tests pass:

cargo test --lib content_stream::tests::test_td_chain
cargo test --lib content_stream::tests::test_tm_followed_by_td
cargo test --lib content_stream::tests::test_td_sets_leading
cargo test --lib content_stream::tests::test_tstar_after_td_uses_saved_leading
cargo test --lib content_stream::tests::test_tf_with_unknown_font
cargo test --lib content_stream::tests::test_tf_with_zero_size
cargo test --lib content_stream::tests::test_execute_with_do_td_chain
cargo test --lib content_stream::tests::test_execute_with_do_tm_then_td
cargo test --lib content_stream::tests::test_execute_with_do_td_sets_leading
cargo test --lib content_stream::tests::test_execute_with_do_tstar_uses_leading
cargo test --lib content_stream::tests::test_execute_with_do_tstar_zero_leading
cargo test --lib content_stream::tests::test_execute_with_do_tf_zero_size

References

• Bead: pdftract-4x0y
• Plan section: Phase 3.1 Text state operators (lines 1490-1493)
• Critical tests: Td chain, Tm followed by Td (lines 1503-1504)