[r-kamei]

Summary

This change resolves pypdf's intermediate internal-link destination to the target page's indirect reference when the target page is already present in the writer.

When the target page has not yet been added, the existing page-index representation is preserved.

Scope

Based on the current code paths, this change is limited to pypdf's intermediate representation of an internal direct destination:

to_add.get("/Subtype") == "/Link"
and isinstance(destination, DictionaryObject)
and "target_page_index" in destination

Remote and external links should not be affected. URI links and remote or embedded go-to actions are represented through an /A action dictionary, such as /URI, /GoToR, or /GoToE, rather than through the annotation-level intermediate /Dest dictionary handled here.

An already completed explicit destination is represented as an array rather than this intermediate dictionary, so it is also left unchanged.

Compatibility

The discussion in #2450 raised the question of whether allowing an internal link to reference a page that has not yet been added to the writer should be treated as supported behavior or as a bug.
This PR intentionally does not make that decision. If the target page is not yet present in the writer, the existing page-index representation is preserved. The change only resolves the destination to an IndirectObject when the target page is already available.
The remaining behavior for targets added later can therefore be discussed and addressed separately without blocking this limited improvement.

Tests

The added tests verify that:

• an existing target page is represented by its IndirectObject;
• a target page that has not yet been added preserves the existing page-index representation; and
• an already completed destination array is preserved without being processed as pypdf's intermediate destination.

AI usage

I used Microsoft 365 Copilot, based on the GPT-5 reasoning model, to assist with reviewing the code paths related to direct /Dest entries and remote link actions. I reviewed and verified the resulting implementation and tests myself.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.12%. Comparing base (d26df36) to head (c1e7624).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #4076   +/-   ##
=======================================
  Coverage   98.11%   98.12%           
=======================================
  Files          59       59           
  Lines       11489    11494    +5     
  Branches     2150     2151    +1     
=======================================
+ Hits        11273    11278    +5     
  Misses        122      122           
  Partials       94       94           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[r-kamei]

The remaining test_text_extraction_fast failure appears unrelated to this PR. The test PDF ASurveyofImageClassificationBasedTechniques.pdf was missing from tests/pdf_cache, which appears to match the CI download/cache issue reported in #3728.

[stefan6419846]

Looks good to me.