fix(docx): name in the report where a page zone's parts stand and what its paragraphs lose

CHANGELOG.md

@@ -8,6 +8,38 @@ follow semantic versioning; release dates are ISO 8601.
 
 ### Public API
 
+- **A DOCX export's report names where a page zone's parts stand, and what its paragraphs
+  lose.** A page zone is written as one Word line. Word sets its parts one after another from
+  the page's left margin, and those after the first spacer against its right margin, on one
+  baseline, its tallest part's. The page sets each part by the zone's padding, a row's columns
+  and gap and a paragraph's alignment, and each part's sides, on a baseline of its own. So
+  these moved in Word without a note:
+  - a centred line, a padded zone, a row's column or gap;
+  - a page field's sides;
+  - a smaller part beside a larger one, which Word sets on the larger one's baseline.
+
+  A zone paragraph's right-to-left direction, prefix letters, fitted size and outline entry
+  went unnamed too. A `page zone` note now:
+  - counts the parts that stand off where the page sets them. Each part is read from the
+    layout's zone fragments on the first page the zone is drawn on. A part stands where the
+    page sets it when it meets all of these:
+    - its line starts within a point and a half of Word's, or, against the right margin, ends
+      there;
+    - it sits on Word's baseline: its tallest part's, with the line standing at the zone's edge;
+    - it is one line;
+    - no prefix stands before it, on the line's left side.
+
+    Past a part Word sets at another width, in a zone whose nodes the page names or nests
+    otherwise than the file, and with no layout, the note says where the parts stand is not
+    measured;
+  - names a zone paragraph's right-to-left text written left to right, its prefix's letters,
+    the size its text is fitted to, and its outline entry.
+
+  None of this changes what is written, and no document of the DOCX fidelity corpus has a page
+  zone. In `DocxNodeFieldLedgerTest` a page field's `padding` and `margin` move from a gap to
+  `REPORTED`, and its `align` to `INERT`: the page sets a field in a box a point wider than its
+  number. The `zones` option keeps a gap for the line's height and the room its parts hold above
+  and below, and a zone paragraph's anchor. 1 node-field gap remains, `CanvasLayerNode.height`.
 - **A DOCX export's report names what a paragraph's own fields lose.** Several of a paragraph's
   own fields were lost without a note:
   - an auto-sized paragraph's text was written at its style's size, not the one the page fits it
@@ -34,7 +66,7 @@ follow semantic versioning; release dates are ISO 8601.
     side holds the line's level.
 
   A paragraph set in a text box over the flow carries these on the note it already had. A page
-  zone's paragraphs are not named yet: that stays a gap of the `zones` option. Across
+  zone's paragraphs are named on the zone's own note (`page zone`). Across
   the DOCX fidelity corpus the report names no paragraph: `EngineeringResume`'s auto-sized name
   fits at its own size. None of this changes what is written: the 62 documents of the corpus
   export to the same bytes. In `DocxNodeFieldLedgerTest` a paragraph's `autoSize`,

docs/architecture/backend-capability-matrix.md

@@ -115,7 +115,7 @@ honour an option ignores it (documented contract).
 | Page backgrounds (`DocumentSession.pageBackgrounds`, `PageBackgroundFill` — full page, columns, bands) | ✅ `DocumentPageBackgrounds` adds each fill as a shape fragment under every page's content, drawn by the ordinary shape handler | ✅ the same fragments, drawn as shapes on every slide | ⚠️ `DocxPageBackgrounds` — each fill is a rectangle anchored to the page, behind the text. A section of more than one page, or with a header or footer, carries them in every header part it has (default, first page, even pages), so they are drawn on every page; a section without a header gets an empty one against the page edge to carry them, and a later section without fills gets an empty header of its own rather than inheriting them. On a page with no top margin LibreOffice still sets the first line about 3pt lower under that header. A section of one page with neither draws them from the body instead — in the first cell's paragraph when the page opens with a table — and its lines stand where the page sets them in both editors (the seven sidebar CVs stood 2.6 to 3.3pt low in LibreOffice); they are on that page alone, so a page an editor's text runs onto has none. A fill's alpha is carried as the shape's. A two-column layout still flows its columns one after the other, so a column fill can stand beside text that is not its column's |
 | Watermark (front/back layers) | ✅ `PdfWatermarkRenderer` | ✅ `PptxChromeRenderer` (per-slide shape at the PDF placement math; behind-content applies before fragments, so no z-order surgery) | ❌ (not written; reported `DROPPED`, `watermark`) |
 | Repeating headers / footers | ✅ `PdfHeaderFooterRenderer` — the zone's `fontName` is resolved through the document's own `FontLibrary`, so a zone draws in the family the author named; unnamed means standard-14 Helvetica, and a code point that family cannot encode is substituted with `?` exactly as body text is | ✅ `PptxChromeRenderer` (positioned per-slide text boxes; `{page}` / `{pages}` / `{date}` tokens with the numbering window rules). The named family reaches the slide run through `PptxFontMapping.familyFor`, and the same family measures the slots — a run measured against one face and typeset in another lands off-centre | ✅ `DocxSemanticBackend.writeBand` (`DocxTextBands`) — one line of a Word header or footer part: the left slot, the centre slot at a centre tab and the right slot at a right tab against the margins; `{page}` / `{pages}` as `PAGE` / `NUMPAGES` (`SECTIONPAGES` per section) fields with the roman or alphabetic switch; `{date}` as the date of the export; the separator as the paragraph's border; the header or footer distance from the band's geometry, baseline within 0.1pt in LibreOffice; a band sharing its kind with another band or a page zone stands in a frame (`w:framePr`) at its own height; `showOnFirstPage(false)` or counting from page 2 → an empty first-page part. A band starting after page 2, numbers not counting from 1 on page 1, and a band alone of its kind reaching past the page margin (written as a negative margin, so that Word holds the body at it as the page does; LibreOffice moves the body clear of it) are reported |
-| Page zones (node subtree in the band) | ✅ Spliced into the layout graph by `DocumentPageZones`, so the ordinary fragment handlers draw it — no zone-specific code in the backend | ✅ Same splice, same reason: `PptxFixedLayoutBackend.renderGraph` draws every fragment of the graph | ✅ Written into a real `w:ftr` / `w:hdr` part. The band's children become runs on one Word line: a paragraph contributes its runs, a flex spacer becomes the right tab stop, and `PageContext.pageNumber()` / `pageTotal()` become live `PAGE` / `NUMPAGES` fields. Other node kinds are skipped, logged once a kind and reported once each (`DROPPED`, `page zone content`); a zone row's own fill, outline and side borders are reported as `row paint`. Because Word paginates, `PageContext.number()` refuses here rather than baking a number that would be wrong on every page but one. A zone's `appliesTo` predicate is asked over sample pages (`DocxPageClasses`) and, when it follows Word's first / even / other pages, becomes the matching part — `w:titlePg` for the first page, `w:evenAndOddHeaders` for even pages — with an empty part on the pages it skips; a predicate that picks pages within a kind (the last page) is written on every page and reported |
+| Page zones (node subtree in the band) | ✅ Spliced into the layout graph by `DocumentPageZones`, so the ordinary fragment handlers draw it — no zone-specific code in the backend | ✅ Same splice, same reason: `PptxFixedLayoutBackend.renderGraph` draws every fragment of the graph | ✅ Written into a real `w:ftr` / `w:hdr` part. The band's children become runs on one Word line: a paragraph contributes its runs, a flex spacer becomes the right tab stop, and `PageContext.pageNumber()` / `pageTotal()` become live `PAGE` / `NUMPAGES` fields. Other node kinds are skipped, logged once a kind and reported once each (`DROPPED`, `page zone content`); a zone row's own fill, outline and side borders are reported as `row paint`. Word sets the line's parts one after another from the left margin and, after the first spacer, against the right margin, on one baseline, its tallest part's; the page sets each by the zone's padding, a row's columns and gap, a paragraph's alignment and a part's own sides (a page field's alignment moves nothing: its box is a point wider than its number). The `page zone` note counts the parts the page sets elsewhere — read from the layout's zone fragments: a part stands where the page sets it when its line starts, or against the right margin ends, within a point and a half of Word's, on Word's baseline with the line at the zone's edge, in one line and with no prefix before it on the left side; past a part whose width Word does not keep, or a zone whose nodes the page names or nests otherwise, where a part stands is said to be not measured — and names a zone paragraph's right-to-left direction, prefix letters, fitted size and outline entry, which the line does not carry; the line's height and the room its parts hold above and below are Word's, and a zone paragraph's anchor has no bookmark, none of these yet named. Because Word paginates, `PageContext.number()` refuses here rather than baking a number that would be wrong on every page but one. A zone's `appliesTo` predicate is asked over sample pages (`DocxPageClasses`) and, when it follows Word's first / even / other pages, becomes the matching part — `w:titlePg` for the first page, `w:evenAndOddHeaders` for even pages — with an empty part on the pages it skips; a predicate that picks pages within a kind (the last page) is written on every page and reported |
 | Protection / encryption | ✅ `PdfDocumentPostProcessor` | ❌ (ignored with a one-time warning — no OOXML encryption support planned) | ❌ (not written, so the file opens unprotected; reported `DROPPED`, `protection`) |
 | Viewer preferences | ✅ `applyViewerPreferences` in `PdfFixedLayoutBackend` | ❌ (ignored with a one-time warning — PDF-viewer concept) | n/a (not written; reported `DROPPED`, `viewer preferences`) |
 | Debug guide lines / node labels | ✅ `PdfGuideLinesRenderer`, `PdfNodeLabelRenderer` | ❌ (ignored with a one-time warning — render through the PDF backend to see overlays) | n/a |