fix(docx): set a later layer where the page does when its edge reaches above

CHANGELOG.md

@@ -8,6 +8,31 @@ follow semantic versioning; release dates are ISO 8601.
 
 ### Public API
 
+- **A DOCX export sets a later layer where the page does when its first block's edge reaches
+  above the layers before it.** A layer written after another starts at the page's gap below
+  them, less what its first block writes above its content itself. Where the block held more
+  than that gap, the rest was dropped and the block wrote all of it.
+  - Measured in Word and LibreOffice on Windows:
+    - a caption with a 20pt margin starting 7pt under the line above stood 12.7pt low, with
+      nothing named, and so did one centred by an alignment wrapper;
+    - a table with a 20pt margin stood 12.6pt low, with nothing named;
+    - a caption with a 20pt padding stood 12.7pt low, and a picture contained in a box level with
+      that line 12.9pt. The report said each was written under the line, though the page sets it
+      below.
+  - The block's own edge now gives that back, in a band and in a column's cell, where the block is
+    a paragraph, a picture, a list or a table in its layer's own flow (under plain sections and
+    containers, alignment and anchor wrappers alone), its edge above at zero or more. Each measured
+    one stands within 0.4pt of the page's distance from the line above, and the
+    padded caption and the picture are no longer named. A block in a row, a panel or a nested stack
+    writes its edge inside them, and keeps the old gap and the overlap measured from its box, as
+    does a block with an edge below zero.
+  - A list a layer opens now keeps its own margin and padding after the layer's gap, as a table
+    does. The gap took their place: a list with a 20pt margin opening a band stood 20pt high, one
+    with 10pt 10pt high, and one in a later layer 7pt high. Each now stands within 0.4pt.
+  - A layer whose content the page starts above the layers before it is still written under them
+    and named. A caption over a photo's foot with a 6pt margin stood that much lower again; it now
+    gives the margin back.
+  - None of the corpus's 62 DOCX changes, and none of its 1246 notes.
 - **A DOCX export keeps a band of layers and a shape container on the page the layout puts them
   on.** The layout moves a layer stack or a shape container to a new page whole. A stack of more
   than one layer is written as a band, its layers one after the other, and Word was told nothing

docs/architecture/backend-capability-matrix.md

@@ -123,7 +123,7 @@ honour an option ignores it (documented contract).
 | 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 |
 | Keep a block on one page (`keepTogether()`, `keepWithNext()`) | ✅ resolved by `LayoutCompiler` before any backend runs | ✅ same — the slides are the laid-out pages | ✅ `DocxSemanticBackend.keepOnOnePage` — Word re-paginates, so a block the layout placed on one page is told to stay there: `w:keepLines` on each of its paragraphs and `w:keepNext` on every one but the last (on the last too for `keepWithNext`), a table inside it chained row by row. A layer stack or a shape container in the flow is kept so too, as the layout moves it to a new page whole, a band of layers included; the first block of a band the layout moves to a new page — a paragraph, a picture or a spacer, a backdrop drawn before it or not — holds the space above it there, as one in the flow does: in a line kept with it, or in a spacer's own line. A block that ran over a page break in the layout is taller than a page and is left to flow, as the layout left it. A body table of one row kept with what follows, its cells holding paragraphs alone, is written with a row that may break (`letTheOneRowTablesKeptWithTheNextBreak`): LibreOffice reads a one-row table whose row may not break as one that may not split, and keeps such a table with nothing |
-| Layer stack — layers drawn over one another (`addLayerStack`) | ✅ each layer's fragments at the place the layout gave it | ✅ same | ⚠️ `DocxSemanticBackend` — Word has no layers, so a stack's children are written one after the other, without their positions. The exception is a stack whose layers are side-by-side columns (`DocxLayerColumns`): every layer a plain container at the stack's top-left corner, the bands their padding leaves either the same or apart. That is written as one table row, a cell per band, the way a two-column CV lays its columns out as layers to draw the name first. Layers sharing a band follow one another in its cell. A spacer the layout placed level with content of another layer of the same band only keeps that content's place, and is not written. The space above a later layer's first block is the gap the page shows below the content before it. Each layer is held to its box across, past the stack's edge where the page sets it past it, by an indent below zero; in a table cell no further left than the indents round it give, the rest named. The one layer of a stack of one layer is held the same way, its offset across kept and its measure with it; in a table cell, composed in a table's cell with no place of its own, and for an offset down or up, which moves it without making room for it, it is written where the stack starts and named — not where a band or a column's layer sets it at the page's distance below what is above it, which holds the offset. A shape container written as a panel in a table cell keeps its padding round its outline, as the page does — the table's indent and the space above and below it; where its table ends its cell, Word sets the cell's content at its middle or foot without the space below, which a centred cell takes off the space above, the rest named — sets what its cell holds at the top, middle or foot as its first written layer is set, holds a paragraph across to its box, and names a written layer after the first (written under the ones before it), an offset down or up, a box past the shape's side, and a layer set across by a box the layout does not give (`layer offset`). A layer the page starts above where those before it end — a caption over its photo, a label in a card's corner — is written under them, in a column's cell as in a band, and the report names it; a stack composed in a table cell, or exported with no layout, has no place of its own, and one writing more than one of its layers is named with them not measured. What the page draws inside another layer's fill comes after that fill. Drawings stack as the page paints them, by their z-index, each given its place (`wp:anchor/@relativeHeight`) from where the page paints its fragment, whatever order the layers are written in — among the drawings behind the text, and among those in front of it, as Word draws every one behind under every one in front. Measured in LibreOffice: `CharcoalGold`, `SidebarPortrait` and `SlateOrange` fit on one page, as on the page; `NavySidebar` runs one line onto a second page. A stack or shape container the page gives no room — its margins taking back its whole height, as `LumaStudioInvoice`'s sidebar over the page's top margin — is laid over the flow (`laidOverTheFlow`): its drawings where the page draws them, each paragraph in a text box in front of the text where the page sets it, nothing in the flow. Not in a table cell or a panel, and not when it holds anything but drawing and plain paragraphs — a link, an anchor, a picture, a list or a table keeps it in the flow as above. A canvas is written as its contents — what it writes one block after another, its drawings where it places them — and holds its height: the room under what it writes is the space below it, and one that only draws holds its whole box where nothing round it — a band before its layer's first block, drawings held whole, an overlay it is a layer of — measures that room already. The report names the places and the width it loses, as it does a column's fixed width narrower than its band, and what it writes running past its height, a drawing in what it writes that takes no room in Word, or a height not measured |
+| Layer stack — layers drawn over one another (`addLayerStack`) | ✅ each layer's fragments at the place the layout gave it | ✅ same | ⚠️ `DocxSemanticBackend` — Word has no layers, so a stack's children are written one after the other, without their positions. The exception is a stack whose layers are side-by-side columns (`DocxLayerColumns`): every layer a plain container at the stack's top-left corner, the bands their padding leaves either the same or apart. That is written as one table row, a cell per band, the way a two-column CV lays its columns out as layers to draw the name first. Layers sharing a band follow one another in its cell. A spacer the layout placed level with content of another layer of the same band only keeps that content's place, and is not written. The space above a later layer's first block is the gap the page shows below the content before it, to the block's content: what the block holds above that content past the gap — its margin, its padding, a contained picture's room — comes out of its own edge (`DocxLayerColumns.resume`) where it is a paragraph, a picture, a list or a table in its layer's own flow with its edge above at zero or more, and a list keeps its own edges after the gap, as a table does. Each layer is held to its box across, past the stack's edge where the page sets it past it, by an indent below zero; in a table cell no further left than the indents round it give, the rest named. The one layer of a stack of one layer is held the same way, its offset across kept and its measure with it; in a table cell, composed in a table's cell with no place of its own, and for an offset down or up, which moves it without making room for it, it is written where the stack starts and named — not where a band or a column's layer sets it at the page's distance below what is above it, which holds the offset. A shape container written as a panel in a table cell keeps its padding round its outline, as the page does — the table's indent and the space above and below it; where its table ends its cell, Word sets the cell's content at its middle or foot without the space below, which a centred cell takes off the space above, the rest named — sets what its cell holds at the top, middle or foot as its first written layer is set, holds a paragraph across to its box, and names a written layer after the first (written under the ones before it), an offset down or up, a box past the shape's side, and a layer set across by a box the layout does not give (`layer offset`). A layer whose content the page starts above where those before it end — a caption over its photo, a label in a card's corner, not a block giving back its edge whose padding or contained picture's room alone reaches there — is written under them, in a column's cell as in a band, and the report names it; a stack composed in a table cell, or exported with no layout, has no place of its own, and one writing more than one of its layers is named with them not measured. What the page draws inside another layer's fill comes after that fill. Drawings stack as the page paints them, by their z-index, each given its place (`wp:anchor/@relativeHeight`) from where the page paints its fragment, whatever order the layers are written in — among the drawings behind the text, and among those in front of it, as Word draws every one behind under every one in front. Measured in LibreOffice: `CharcoalGold`, `SidebarPortrait` and `SlateOrange` fit on one page, as on the page; `NavySidebar` runs one line onto a second page. A stack or shape container the page gives no room — its margins taking back its whole height, as `LumaStudioInvoice`'s sidebar over the page's top margin — is laid over the flow (`laidOverTheFlow`): its drawings where the page draws them, each paragraph in a text box in front of the text where the page sets it, nothing in the flow. Not in a table cell or a panel, and not when it holds anything but drawing and plain paragraphs — a link, an anchor, a picture, a list or a table keeps it in the flow as above. A canvas is written as its contents — what it writes one block after another, its drawings where it places them — and holds its height: the room under what it writes is the space below it, and one that only draws holds its whole box where nothing round it — a band before its layer's first block, drawings held whole, an overlay it is a layer of — measures that room already. The report names the places and the width it loses, as it does a column's fixed width narrower than its band, and what it writes running past its height, a drawing in what it writes that takes no room in Word, or a height not measured |
 
 ## Output surface and lifecycle
 

docs/recipes/docx-export.md

@@ -855,7 +855,19 @@ recolour what is under it in Word and it keeps the colour it was flattened to.
   spacer level with another layer's content only keeps its place and is not
   written, the space above the first block written and below the last is the
   page's distance from the stack's edges, and a later layer resumes the page's
-  distance below the blocks above it. A badge — a ring, drawn, with initials centred
+  distance below the blocks above it, to its first block's content. What that block
+  holds above its content past that distance — a margin, a padding, a contained
+  picture's room reaching above where the layers before it end — comes out of its own
+  edge, in a band as in a column's cell, where the block is a paragraph, a picture, a
+  list or a table in its layer's own flow — under plain sections and containers, and
+  alignment and anchor wrappers — its edge above at zero or more; not in a row,
+  a panel or a nested stack, which keep the gap to the block's box and name the overlap
+  from it. Kept whole, a caption with a 20pt margin 7pt under the line above stood 12.7pt
+  low in Word and LibreOffice, a picture contained in a box level with that line 12.9pt,
+  and a table with a 20pt margin 12.6pt. A list a layer opens keeps its own margin and
+  padding after the layer's resume, as a table does: lost there, a list with a 20pt
+  margin opening a band stood 20pt high, and one in a later layer 7pt. A badge — a ring,
+  drawn, with initials centred
   in it, over a spacer that keeps its place in the flow — writes its initials where
   the ring centres them and keeps its height below them. Each layer, here and in a
   shape container, is held in across to its box in the stack, with a few points to