feat(api): pageMargins(List<PageMarginRule>) — per-page-range margin overrides

[DemchaAV]

Why

A document had one margin for every page, so a full-bleed cover and a book-margin body could not live in the same file — the cover had to be a separate document or a hand-built full-bleed hack.

What changed

• DocumentSession.pageMargins(List<PageMarginRule>) overrides the page margin for ranges of pages — both horizontally and vertically. PageMarginRule.page(1, DocumentInsets.zero()) for a full-bleed cover, PageMarginRule.from(2, …) for the body. Pages are 1-based; rules apply in list order, last-covering-rule wins (mirrors pageBackgrounds).
• New public types: PageMarginRule (record, factories page() / range() / from()), plus the engine-side PageGeometry / PageMarginOverride resolvers.

How it works

The engine measures content before it knows which page the content lands on, so per-page width is a circular dependency. It's resolved as a fixed point — the same recompile-until-stable loop the page-reference/TOC resolver already uses: compile, record each node's start page, recompile feeding those back, until the assignment settles (capped, unconverged returns the last layout). Each top-level block — and each direct child of the page-flow column — is measured at the content width of the page it begins on. A single block that overflows a margin boundary keeps its start-page column for its whole length (documented; the model is per-page-range, not mid-block).

Lane: canonical API + shared-engine (LayoutCompiler / CompilerState / pagination). A nullable PageGeometry resolver returns the base canvas for every page when no rules are set; the no-rules path compiles once and the per-page branches are guarded, so a document that sets no margins does no extra work.

Verification

• ./mvnw test -pl . — green (1601), 0 changed visual baselines → a document with no rules is laid out byte-for-byte as before. ./mvnw -P japicmp verify — binary-compatible (new types + default interface methods + a delegating ctor, all additive). Javadoc gate clean.
• Perf A/B vs develop (deterministic compile-time probe, default no-rules path, interleaved batched runs): no measurable regression — overall min 1.046 ms (branch) vs 1.067 ms (develop), batch-medians overlap on both. Confirms the structural analysis: one compile, inlined null-checks, no extra allocation.
• PageMarginTest (7) asserts horizontal (placementX 10→70) and vertical (top edge 285→260) per-page geometry off the placed graph — via an explicit page break and via natural overflow (the fixed point) — plus last-rule-wins, empty-rules, the documented block-spanning-a-boundary limitation, and per-page margins coexisting with page references (the unified loop).
• A cold review confirmed byte-identity, the fixed-point convergence/stability (5-pass cap, stable paths), the depth==1 page-column gate, and japicmp; it drove the boundary-limitation and page-reference-coexistence tests.
• Runnable PerPageMarginExample + committed preview: a full-bleed cover (page 1, zero margin) and a book-margin body (pages 2+) in one session.

This is the last of the book-template engine-gap items.