Lazy page-tree loading

HotPDF can retain an ordinary loaded PDF page tree as a compact placeholder table and resolve individual pages only when an API first needs them

Activation

LazyPageTreeThreshold defaults to 4096 pages and applies to valid page trees whose root exposes a usable /Count and /Kids structure

Set the threshold to 0 before loading to disable lazy page-tree handling

Files below the threshold and malformed trees continue through the existing eager recovery path

Random access

The first access to a page follows subtree /Count values to skip unrelated branches and resolves indirect objects through a document-local open-addressed index

The resolved page is stored in its placeholder slot, so repeated access is a direct cache hit

Ordinary loaded-page APIs materialize the requested page transparently, while MaterializeLoadedPage lets callers prepare a known page explicitly

Full expansion and mutation

MaterializeAllLoadedPages expands the remaining tree in canonical page order

Operations that structurally add, delete, copy, replace, move, reverse, swap, rebuild, or save loaded pages perform full expansion before they mutate or serialize the page graph

This preserves existing mutation and save semantics while keeping read-oriented access proportional to the traversed branch depth

Telemetry

GetLoadedPageTreeStatistics reports placeholder storage, materialized pages, traversal depth and work, object-index capacity, cache activity, and full expansions without forcing materialization

A regression gate covers 100,000 pages with a 256 MiB working-set growth ceiling and a 500 ms first random-access ceiling on supported Windows targets