feat: new pagination engine and Page layout prop

[diegomura]

What

Closes: #3499

Replaces the pagination step with the new @react-pdf/paginate engine and adds a layout prop to Page for per-page chrome (headers, footers, sidebars — anything that repeats around the content).

• Content is measured once; the engine packs it into pages. No more relayout on every split.
• <Page layout={Layout}>: the layout component receives { pageNumber, totalPages, ... } and the page content as children, and runs once per output page.
• One fixed semantic: in-flow fixed elements repeat at the top of every page they span. Footers are the layout's job.
• Legacy engine stays behind a flag for now; it gets deleted before release.

Performance

The old engine relayouts on every split, so cost grows quadratically with document size. The new engine is linear. Same documents, same output page counts:

Document	Legacy	New	Speedup
300 pages of blocks	36.5 s	158 ms	231×
300 pages + page numbers	60.7 s	254 ms	238×
300 pages of text	17.7 s	1.8 s	10×
100 pages of blocks	2.2 s	49 ms	44×
10 pages of blocks	24 ms	6 ms	4×

With a layout on every page: ~1 ms per page, flat at every size.

Breaking

Ships as a major. fixed suffix elements no longer reserve footer space (use layout), flex justify at the page root follows the new stream semantics, and render props handed to @react-pdf/layout directly must return instances (the renderer does this for you). minPresenceAhead is not ported yet — pending decision.

Testing

• 473 layout tests, including a parity suite against the legacy engine and a 150-seed fuzzer comparing both engines
• 103 engine tests with PNG visual regression
• Renderer snapshots byte-identical (98 tests + browser project)

🤖 Generated with Claude Code

Supersedes

Open PRs made obsolete by this engine (closed manually, since the merge predates this note):

• perf: Optimize page splitting and relayout, so both per-iteration costs drop from O(N^2) to O(N) #3390 — pagination perf O(N²) → O(N): this rewrite is the full redesign that thread pointed to; the new engine benches 2000 elements → 200 pages in ~41 ms. Also resolves Performance problem with creating multiple pages #2448 and Slow generation time for PDF with many pages #3181.
• fix(layout): don't squash a container's sole child at a page break (#3449) #3450 — container's sole wrap={false} child squashed/overlapping at a page break: the engine defers it to the next page instead of force-fitting.
• customize styles for wrapped sub-pages #3230 — per-sub-page styles for wrapped content: covered by the Page layout prop (pageNumber/subPageNumber per output page).
• added currentPageCallBack for the process of the current page #2437 — page-progress callback: the stepwise createPaginator API is the natural hook for this now.
• feat: try taffy #3349 — taffy experiment: the perf motivation was resolved by rewriting pagination instead of replacing Yoga.
• getWrap - handle undefined wrap prop #3294 — closed as duplicate of fix: treat wrap={undefined} like an omitted wrap prop #3151 (which still applies on the new engine).

Issues resolved

Each of these was verified by running its repro against the new engine (closed manually):

Squashed / overlapping content at page breaks — the engine defers or splits instead of force-fitting:

• Content taller than one page is squashed/overlapped at the bottom instead of flowing onto the next page #3449, Text in nested view with wrap={false} being compressed/squished after upgrading from v3.1.2 to v3.4.4  #2904, Vertical Compression of Components when using wrap={false} #2763 — wrap={false} content compressed or drawn over itself near a page boundary
• Page break is created but no content is pushed to the new page #2969 — small overflow created an empty page instead of moving the content
• Margin appearing near the bottom of page causes react pdf to hang #2996 — marginBottom near the page bottom hung pagination forever
• Placing a FIXED element last on a wrapping page causes incorrect page wrapping and overlapping #2436, Fixed Content Causes Flex Items to Overflow on Wrapping Page #2922 — a trailing fixed element made content shrink and overlap on wrapping pages
• Content height not calculated propery #3046 — recurring squashed/compressed text blocks
• PDF generation freezes browser tab #2834 — marginBottom near the page bottom froze the browser tab (same root cause as Margin appearing near the bottom of page causes react pdf to hang #2996)

Dynamic nodes — pagination re-runs with real page numbers instead of freezing a partition and relayouting:

• Using the render prop breaks the pagination #3173, Content in pages with dynamic components can get squashed #2476, Text overlaps or squashes at page breaks in dynamic content #3298, Page break depending on the height of dynamic components #2378 — render-prop content had its height ignored or got squashed
• Property 'totalPages' does not exist on render prop of view component #2413, totalPages could be accessible inside <Views> as well #1044, get totalPages prop in render method of Text component #923 — totalPages now reaches every render prop, including Views
• Nested render properties are not called #2258 — nested render props were never called
• Missing styles when using the render prop #2195 — styles were not applied to render prop output
• Dynamic content not showing inside flex elements in v2.0 #1300 — dynamic content inside a fixed flex-row header didn't show
• A way to hide <Text> element on the last page (because <View> is not usable in this case) #1005 — hiding an element on the last page now works from any render prop

minPresenceAhead — reimplemented as a forbid window (#3504):

• minPresenceAhead is not working as expected #2658, minPresenceAhead Not working? #3233, minPresenceAhead - calculating the meaning of 'presence' on next sibling element #955 — the prop was ignored or its semantics unclear; a header near the page bottom now moves to the next page with its content

Other:

• Unbreakable elements taller than the page don't correctly start on next page and wrap, as expected #1676, Wrapping preventation of elements that are larger than page size is buggy #1459 — an unbreakable element taller than the page now starts on its own page instead of overlapping
• Wrap to false on component Page doesn't work #1601 — wrap={false} on Page now yields a single page
• Process hangs indefinitely when using lineHeight property in specific layout contexts #3245 — lineHeight on a Text inside a flex row hung the process forever
• Wrapping of View component that is styled with flexDirection: "row" doesn't render properly in the next page #1456, flexDirection cause the content too long overlapped another cell #1472 — a flexDirection: row view wrapping across pages produced broken geometry / overlapping cells on the next page
• Full page absolute block works as fixed #1564 — a full-page position: absolute block (without fixed) repeated on every page
• [Bug] Text goes into 2nd page leaving big gap #3436 — text near the page bottom moved wholesale to the next page leaving a gap, instead of splitting by lines
• TypeError: Cannot read property 'height' of undefined at setNodeHeight #1400 — setNodeHeight crash on heavy documents (the crashing split path no longer exists)

Enabled by the layout prop (the supported pattern for what these asked for):

• Footer on all pages except the last and a different footer on the last page #1598 — different footer on the last page (totalPages in layout params)
• Pagination isn't visible on the bottom of the page via render function #3308, dynamic content in a fixed view (like a footer) it gets into loop outputting an error over and over #1518 — page numbers / dynamic content in footers
• Determining if a fixed element is wrapped #2274, Allow rendering of a page-wrap indicator #2661 — detecting continuation pages (subPageNumber in layout params)

[changeset-bot]

⚠️ No Changeset found

Latest commit: 758509d

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR