[DemchaAV]

Why

The ways a page breaks inside a panel are each held by unit tests and qa tests that read the written DOCX:

• an explicit page break among a panel's children, at any depth (fix(docx): cut a panel at a page break in a section or panel inside it #960);
• a break the page sets in a row's column or a stack's layer, where it breaks no page (fix(docx): write no page break in a row's column, a stack's layer or a table's cell #961);
• a panel whose table runs over pages, cut into a table a page (fix(docx): cut a panel whose table runs over pages into a table a page #962);
• another page's margins starting a Word section at that cut (fix(docx): end a page-margin section at a panel's cut #963);
• the page break the layout makes after a card, and the space above the block that opens the next page (fix(docx): break a page after a card where the layout breaks it #964).

Each was measured in Word and LibreOffice once, when it was fixed. No document of the DOCX fidelity corpus has any of these shapes, so the gate that holds every line of the corpus where the editor set it — LibreOffice in CI, Word on Windows — would not notice an editor setting one of them off the page again.

What changed

• SyntheticDocxCorpus (new family synthetic): documents built for shapes no preset has on its own fixture.
  • break_in_panel: a card with a page break among its children and a card nested in it with a break of its own, over three pages.
  • break_in_column: page breaks in a row's column and in a stack's layer, on one page.
  • card_over_pages: a bordered card whose table of 60 rows, its header repeated, runs over three pages, the pages after the first set against a larger top margin. It is spaced so that page 1's rows leave room for the paragraph that ends a Word section at the cut: at a gap of 8 or 10pt the export names page 2's margins instead, and both editors set page 2 with page 1's (measured: 52.9pt high).
  • Text in Lato, which the export embeds: in the default Helvetica, which it does not embed, LibreOffice set two lines at other words in a substituted face.
• InvoiceDocxCorpus: obsidian_long (line items ×12: the card run over four pages with other margins from page 2, and the break after the info cards) and metered_long (×9: the gap above the closing row carried onto page 4). Its withLinesRepeated replaces the private copies in InvoicePanelOverPagesDocxTest and InvoiceNaturalPageBreakDocxTest.
• DocxFidelityCorpusTest.corpus() takes the synthetic family: 62 documents → 67.
• Baselines. word-windows and libreoffice-windows take the five documents' rows alone, copied from what their runs measured; the presets' rows stay as recorded. Word here is now 16.0.20527 and the presets' rows were recorded with 16.0.20430: retaking them would carry that build's drift into this change. libreoffice-linux takes the five rows from this PR's first CI run (artifact docx-fidelity-40241271303), where the job failed on those five alone, each not yet in the baseline. A comment under each file's header says where the added rows were measured.
• Docs: CONTRIBUTING.md (the corpus's synthetic documents, where a preset on a longer fixture and a shape no preset has join), the docx-fidelity job's comment in ci.yml, the synopsis of word-fidelity.ps1, the CHANGELOG.

Measured

Pages, lines found, then the median and p90 of the found lines' drift down (pt); the gate holds each line's drift across as well:

Document	Pages	Word 16 (Windows)	LibreOffice 26.8 (Windows)	LibreOffice 24.2 (Linux, CI)
synthetic-break_in_panel	3	3, 8/8, 0.95 / 0.99	3, 8/8, 3.02 / 5.02	3, 8/8, 3.02 / 5.02
synthetic-break_in_column	1	1, 7/7, 0.03 / 0.03	1, 7/7, 0.02 / 0.02	1, 7/7, 0.02 / 0.02
synthetic-card_over_pages	3	3, 114/114, 1.03 / 1.15	3, 114/114, 0.98 / 1.08	3, 114/114, 0.98 / 1.08
invoice-obsidian_long	5	5, 375/375, 0.94 / 1.14	5, 358/375, 0.85 / 0.95	5, 375/375, 4.17 / 8.36
invoice-metered_long	4	4, 350/350, 0.06 / 0.16	4, 350/350, 0.10 / 0.23	4, 334/350, 41.91 / 96.38

• Word sets every line of every document on the page the PDF sets it on. LibreOffice 26.8 sets each on as many pages, but carries ObsidianInvoice's info cards to page 5 (the 17 lines not found; page 5 128.6pt low), where Word and LibreOffice 24.2 keep them on page 4.
• LibreOffice 24.2 (CI) sets each on the pages the PDF does. It sets the two long invoices' line items high — ObsidianInvoice's by up to 10pt; MeteredInvoice's more so page after page, by a median of 52 and 87pt on its second and third pages, 16 of its lines on another page — as it sets the presets' long tables (invoice-metered alone: p90 10.6pt). The last pages, which carry the page break after the cards and the gap above the closing row, stand within 0.8pt: ObsidianInvoice's page 5 at +0.02pt, MeteredInvoice's page 4 at −0.52pt.
• Word's drift down is mostly the top border of a card's part after a cut (1pt, named in the report); ObsidianInvoice's info cards and totals stand up to 1.9pt low. Across, Word sets card_over_pages's amounts 36.4pt left — its table's first column narrower than its grid, 49 of 114 lines — where LibreOffice keeps the grid (0.6pt).
• In LibreOffice 24.2 and 26.8 the parts of break_in_panel's card after its explicit breaks stand 3 to 5pt high. LibreOffice 24.2 also sets a card's text right — 8.6pt in break_in_panel, 7.1pt in card_over_pages — as it does some of the presets' panel lines in its baseline (cv-panel up to 8.6pt); 26.8 on Windows does not.

Tests

• The gate holds the fixture (fail-closed). Each P0-5 fix taken out of the export in turn, render-docx installed, and the corpus run against the extended baselines; each sabotage alone, and every one caught:
  • LibreOffice 26.8 (Windows): a page break in a panel not cut there (fix(docx): cut a panel at a page break in a section or panel inside it #960) fails synthetic-break_in_panel; a break written in a row's column (fix(docx): write no page break in a row's column, a stack's layer or a table's cell #961) fails synthetic-break_in_column; a panel run over pages written as one table (fix(docx): cut a panel whose table runs over pages into a table a page #962), and no section at a panel's cut where the margins change (fix(docx): end a page-margin section at a panel's cut #963), each fail synthetic-card_over_pages; a row opening its page holding no gap carried there (fix(docx): break a page after a card where the layout breaks it #964) fails invoice-metered_long.
  • Word 16: keep-with-next written in a table cell again (fix(docx): break a page after a card where the layout breaks it #964) fails invoice-obsidian_long (17 lines lost, the rest of page 5 123.5pt off); a rule opening its page holding no space above it (fix(docx): break a page after a card where the layout breaks it #964) fails it too (its page-5 lines 13pt high). LibreOffice 26.8 lets that one through: it carries Obsidian's info cards to page 5 either way.
  • CI, LibreOffice 24.2 — not re-run with each sabotage: the export from before fix(docx): break a page after a card where the layout breaks it #964, which held neither the rule's space nor the row's gap, set ObsidianInvoice ×12's page 5 13.0pt high and MeteredInvoice ×9's page 4 12.8pt high in LibreOffice 24.2 (measured for fix(docx): break a page after a card where the layout breaks it #964). Against these rows, page 5 at +0.02pt and page 4 at −0.52pt, that is past the gate's 0.5pt, so CI fails both. Keep-with-next in a cell is held by Word alone: LibreOffice keeps the cards on page 4 with it or without it. For fix(docx): cut a panel at a page break in a section or panel inside it #960 to fix(docx): end a page-margin section at a panel's cut #963, CI sets the three synthetic documents as 26.8 does: the same pages and lines found, the same median and p90 down to the hundredth.
• Word: scripts/docx-visual/word-fidelity.ps1 (Word 16.0.20527) → the corpus test in word mode passes on all 67 documents against the extended word-windows.
• LibreOffice, Windows: -Dgraphcompose.docxFidelity=libreoffice → the five new documents pass against the extended libreoffice-windows; invoice-obsidian and proposal-indigo fail as on 2.5-dev (below).
• Corpus: 67/67 exported; the 62 presets unchanged part for part, their report unchanged (1445 notes); the five new documents add 46 notes.
• Unchanged tests: InvoicePanelOverPagesDocxTest (3) and InvoiceNaturalPageBreakDocxTest (2) pass on the shared withLinesRepeated.
• Gate:
  • ./mvnw -B -ntp -f aggregator/pom.xml clean verify -pl <core, render-pdf, render-docx, render-pptx, templates, testing, qa, coverage> -am → BUILD SUCCESS: core 823, render-pdf 339, render-docx 2256, testing 5, render-pptx 142, templates 127, qa 1835.
  • The JDK 17 knowledge checks pass with the API surfaces unchanged, and core javadoc has 0 warnings.
  • ./mvnw -f examples/pom.xml test → BUILD SUCCESS, 93 tests.

Named, not fixed

• In LibreOffice 24.2 and 26.8 a card's part after an explicit page break stands 3 to 5pt high, where Word sets it within 1pt. Only synthetic-break_in_panel has it; no preset breaks a page inside a panel.
• card_over_pages is spaced around a limit of fix(docx): end a page-margin section at a panel's cut #963: at a gap of 8 or 10pt above the card, page 1's rows leave no room for the paragraph that ends a Word section at the cut, the export names page 2's margins, and both editors set page 2 with page 1's, about 53pt high. A change to a table's metrics can tip it there; the class's Javadoc says so, and the answer is to re-space the fixture.
• LibreOffice 24.2 sets the two long invoices' line items high, MeteredInvoice's more so page after page and with 16 lines on another page, as it does the presets' long tables. The gate compares each line's drift to its baseline's either way, so on those pages a change that moves lines back toward the page passes; their last pages, where the P0-5 shapes are, stand within 0.8pt and are held.
• Word sets the amounts of card_over_pages's table 36.4pt left, the table nested in the card with its first column narrower than its grid; LibreOffice keeps the grid. Nothing to do with the page breaks; the baseline holds it.
• LibreOffice 26.8 on Windows carries ObsidianInvoice's info cards to page 5 with its line items repeated 12 times, where LibreOffice 24.2 and Word keep them on page 4. It did so before the page break after the cards was fixed as well (the same document exported before and after it, converted by the same 26.8: identical). The Windows baseline holds it as it stands.
• Run locally, libreoffice-windows also fails invoice-obsidian and proposal-indigo on 2.5-dev itself: LibreOffice 26.8 sets each on 2 pages against the page's 1. It set them so before the page break after a card was fixed too (the export before that change, converted by the same build); an earlier change since that baseline was taken (2026-10-14) moved them. This change exports both as before, and the five new documents pass it.
• The fixture covers a page break in a painted card and in a painted card nested in it, and the breaks the page ignores in a row's column and in a stack's layer; a composed table cell, a shape container's layer, a canvas and an unpainted section in a card stay held by the unit tests alone.
• A baseline rewritten with -Dgraphcompose.docxFidelity.update=true keeps one note: the comment saying where the five documents' rows were measured goes with it.

Lane: tests (qa). No public API change, and no change to the export.