fix(layout): don't squash a container's sole child at a page break (#3449)

[billinspiratobell]

Fixes #3449.

Problem

Content overlaps itself at a page break — a block that lands near the bottom of a page is force-fit into the few points of space left, drawing its lines on top of each other, instead of moving to the next page. It shows up with two-column rows / wrap={false} blocks (headers, footers, itinerary-style entries) near a page boundary, and is present on the latest published @react-pdf/layout (4.6.1).

A full step-by-step reproduction (paste-into-REPL) is in REPL.md.

Root cause

In resolvePagination's splitNodes, when a node is split and all of its children move to the next page (leaving an empty shell), the parent is kept on the current page whenever currentChildren.length === 0:

if (child.children.length > 0 && currentChild.children.length === 0) {
  if (currentChildren.length === 0) {
    currentChildren.push(child, ...futureFixedNodes); // kept on the current page
  } else {
    // move to the next page
  }
}

currentChildren.length === 0 is meant to mean "the page is empty, so keep this here (even if it overflows) rather than emit an empty page / loop forever." But currentChildren is the local list for the node's own container — it is 0 simply because the node is the first child of its container, which is not the same as the page being empty. So a node that is the sole child of its container but lands on an already-populated page is force-fit into the space left, and Yoga compresses its lines on top of each other.

Fix

Decide based on whether the page is actually empty above the node, threaded through the split recursion as pageEmpty:

• Page already has content above the node → move the whole node to the next page.
• Page is genuinely empty and the node cannot fit → keep it (allow overflow), which preserves termination and avoids an infinite page loop.

The change is contained to splitNodes / split / splitView / splitChildren.

Tests

Added to packages/layout/tests/steps/resolvePagination.test.ts:

• Overlap regression — asserts zero text-on-text overlap for a wrap={false} two-column entry that is the sole child of its container, swept across several page heights. Fails before this change (7/6/5/3 overlapping spans), passes after.
• Loop guard — a tall fixed-header case where a node fits the content area but never fits the space left under the header; verifies pagination still terminates (no infinite page loop).

All 416 layout tests pass. Also verified end-to-end by rendering a real document that reproduced the overlap: 8 overlapping spans → 0 after the fix (the entry moves cleanly to the next page).

🤖 Generated with Claude Code

[changeset-bot]

🦋 Changeset detected

Latest commit: 38a3154

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 7 packages

Name	Type
@react-pdf/layout	Patch
@react-pdf/renderer	Patch
@react-pdf/math	Patch
@react-pdf/mermaid	Patch
next-14	Patch
next-15	Patch
@react-pdf/vite-example	Patch

Not sure what this means? Click here to learn what changesets are.

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

[billnbell3]

OK this is ready. See my https://react-pdf.org/repl paste in the code above. It also fixes the recursion. test case is there too.

[billnbell3]

CAN WE GET THIS MERGED?

[billnbell3]

ANYONE ELSE look at this?

[billnbell3]

please merge this - it is critical fixes.

[diegomura]

This should be obsolete after pagination overhaul done in #3502

[billnbell3]

This is still not fixed. See the fix I put in.

the legacy path is still the default and still ships the bug, so the fix isn't obsolete until the cutover major lands.

// layout 5.2.0, lib/index.js
const wantsNextPagination = (root) => root.children.some((page) =>
page.props?.experimentalPagination || page.props?.layout);
const paginationStep = (root, fontStore) => wantsNextPagination(root)
? resolvePagination(root, fontStore) // new @react-pdf/paginate engine
: resolvePagination$1(root, fontStore); // legacy — still has your bug