This phase focuses on making pagination smarter and more predictable for complex documents without breaking the existing public API.

Planned work:

Add data-pdf-split="avoid"

Keep a block together when it fits on one page

Avoid awkward page breaks inside important sections

Preserve existing behavior when the attribute is not used

Add data-pdf-split="container"

Allow large containers to split across pages intelligently

Preserve child structure where possible

Avoid unnecessary blank space

Add break-before support

Add break-after support

Keep compatibility with existing html2pdf__page-break behavior

Make page-break rules consistent across supported render modes

Detect elements larger than a single PDF page

Prevent infinite pagination loops

Fall back to safe splitting when a block cannot fit on one page

Keep generation recoverable for extreme layouts

Support repeated table headers across pages

Reduce broken rows where possible

Improve long-table readability

Keep behavior predictable for large datasets

Add an optional pagination debug overlay

Show detected page boundaries

Highlight forced and automatic breaks

Help developers understand why content moved to a new page

Expose useful pagination information for debugging

Report split decisions when diagnostics are enabled

Keep diagnostics opt-in

Avoid changing generated PDF output by default

Add unit tests for new pagination rules

Add browser E2E coverage

Test portrait and landscape layouts

Test long documents and stress presets

Verify existing users are not affected

Primary goals:

improve pagination quality

reduce awkward content splitting

improve long-document reliability

improve table handling

give developers more control over page breaks

make pagination easier to debug

preserve backward compatibility

avoid unnecessary runtime overhead when advanced pagination features are not used

This phase should be implemented incrementally with regression tests after each step.

Status: Planned