docs(matrix): separate what DOCX cannot hold from what it does not do (#448)

The preamble said geometry rows were n/a for the semantic backend by
design, while the table marked them with the symbol the legend defines as
"no implementation, no current plan". The column therefore read as almost
nothing supported, and gave no way to tell an inapplicable concept from a
gap someone could close.

Drawing nodes are not inapplicable: shape, line, ellipse, polygon, path
and barcode all reach writeNode and are dropped there with a logged
warning, and Word expresses floating shapes, pictures and gradient fills.
Those stay ❌. What is genuinely n/a is the fixed-layout SPI —
SemanticBackend carries only name() and export(), so renderSections,
renderToImages and the raster-slide builder option are questions it
cannot be asked. Three cells move.

Three more were overstated. Image fit never reads fitMode or scale, so
CONTAIN and COVER behave as STRETCH and an unsized node falls back to
100x100 pt. Tables write cell text but not colSpan, rowSpan, per-cell
style or fill and border paint. Metadata hits the same OPC limitation the
PPTX row already records.

Author: DemchaAV

README.md

@@ -207,7 +207,7 @@ For a Spring Boot `@RestController` streaming the PDF straight to the response,
 | Format | Status | Notes |
 |---|---|---|
 | PDF | Production | Fixed-layout backend on PDFBox 3.0. Full DSL coverage. |
-| DOCX | Partial | Semantic export via Apache POI — paragraphs, block images, tables and metadata. Word owns the flow, so drawing nodes (`shape`, `line`, `ellipse`, `barcode`) are dropped silently. Beyond geometry, **hyperlinks, bookmarks, headers/footers and multi-section documents are not implemented** — see [render-docx](./render-docx/README.md#what-it-maps-and-what-it-does-not). |
+| DOCX | Partial | Semantic export via Apache POI — paragraphs, lists, block images, tables and metadata. Word owns the flow, so drawing nodes (`shape`, `line`, `ellipse`, `barcode`) are dropped, one logged warning per kind. **Hyperlinks, bookmarks and headers/footers are not implemented**, table `colSpan`/`rowSpan` is not applied, and image fit modes are ignored — see [render-docx](./render-docx/README.md#what-it-maps-and-what-it-does-not). |
 | PPTX | Beta | Fixed-layout export via Apache POI from the same resolved layout — one page per editable slide with native shapes and text frames; clipped regions land as pixel-exact pictures. First shipped in 2.1, marked `@Beta` while the API shape settles. |
 
 ### Text & internationalization

docs/architecture/backend-capability-matrix.md

@@ -30,8 +30,19 @@ Backends:
   while feedback lands (see [../api-stability.md](../api-stability.md)).
 - **DOCX (semantic)** — `graph-compose-render-docx`,
   `DocxSemanticBackend`. Walks the semantic node tree, deliberately
-  ignores fixed-layout geometry; Word owns the flow. Geometry rows are
-  n/a for it by design.
+  ignores fixed-layout geometry; Word owns the flow.
+
+Reading the DOCX column: a row is `n/a` only when the capability is
+declared on the fixed-layout SPI and can never reach a semantic backend —
+`SemanticBackend` carries just `name()` and `export(DocumentGraph,
+SemanticExportContext)`, so `renderSections`, `renderToImages` and the
+raster-slide builder option are not questions it can be asked. Drawing
+nodes are a different case: `ShapeNode`, `LineNode`, `EllipseNode`,
+`PolygonNode`, `PathNode` and `BarcodeNode` all reach
+`DocxSemanticBackend.writeNode` and are dropped there with a logged
+warning, and Word can express floating shapes, pictures and gradient
+fills. Those rows are ❌ — no implementation, no current plan — not
+`n/a`.
 
 The PPTX *semantic* skeleton (`PptxSemanticBackend`, slide-safe node
 validation + manifest, writes no file) is out of scope for this matrix.
@@ -56,9 +67,9 @@ Payload records live in `core` under
 | Linear gradient fill (`DocumentPaint`) | ✅ `PdfShadingSupport` | ✅ `PptxGradientFill` (native `gradFill`; explicit-axis endpoints approximate to the angle) | ❌ |
 | Radial gradient fill (`DocumentPaint`) | ✅ `PdfShadingSupport` | ⚠️ `PptxGradientFill` (`circle` path shade — DrawingML cannot express radius-to-farthest-corner exactly) | ❌ |
 | Gradient strokes | ✅ `PdfPathPainter` (pattern stroking colour) | ✅ `PptxGradientFill` (native `ln`/`gradFill`) | ❌ |
-| Image — STRETCH / CONTAIN / COVER fit (`ImageFragmentPayload`) | ✅ `PdfImageFragmentRenderHandler` | ✅ `PptxImageFragmentRenderHandler` (COVER via the picture source crop) | ✅ semantic images (`DocxSemanticBackend`) |
+| Image — STRETCH / CONTAIN / COVER fit (`ImageFragmentPayload`) | ✅ `PdfImageFragmentRenderHandler` | ✅ `PptxImageFragmentRenderHandler` (COVER via the picture source crop) | ⚠️ `DocxSemanticBackend.writeImage` (the picture is embedded at the node's width/height; `fitMode` and `scale` are never read, so CONTAIN and COVER behave as STRETCH, a node with neither width nor height falls back to 100×100 pt, and every picture is declared `PICTURE_TYPE_PNG`) |
 | Barcode / QR (`BarcodeFragmentPayload`) | ✅ `PdfBarcodeFragmentRenderHandler` (ZXing raster) | ✅ `PptxBarcodeFragmentRenderHandler` (identical ZXing raster) | ❌ |
-| Table rows — resolved cells, row/col spans, two-pass fill/border paint (`TableRowFragmentPayload`) | ✅ `PdfTableRowFragmentRenderHandler` + row grouping in `PdfFixedLayoutBackend` | ✅ `PptxTableRowFragmentRenderHandler` + row grouping in `PptxFixedLayoutBackend` (positioned rectangles, edge lines, and text frames — never native PPTX tables, which re-lay-out content) | ✅ semantic tables (`DocxSemanticBackend`) |
+| Table rows — resolved cells, row/col spans, two-pass fill/border paint (`TableRowFragmentPayload`) | ✅ `PdfTableRowFragmentRenderHandler` + row grouping in `PdfFixedLayoutBackend` | ✅ `PptxTableRowFragmentRenderHandler` + row grouping in `PptxFixedLayoutBackend` (positioned rectangles, edge lines, and text frames — never native PPTX tables, which re-lay-out content) | ⚠️ `DocxSemanticBackend.writeTable` (cell text becomes a real Word table; `colSpan` / `rowSpan`, the per-cell `DocumentTableStyle`, and fill/border paint are not applied, and cell runs carry no text style) |
 | Clip region open/close (`ShapeClipBegin/EndPayload`) | ✅ `PdfShapeClipBegin/EndRenderHandler` (CLIP_BOUNDS + CLIP_PATH) | ✅ `PptxClipSafety` + raster fallback in `PptxFixedLayoutBackend` — a provably no-op clip (padded content that cannot be cut) skips the fallback entirely and stays native, editable shapes; a clip that can cut ink renders through the PDF backend into one transparent picture on the clip bounds (pixel-exact, not editable as shapes; run-level link hotspots are not emitted and custom fragment handlers do not apply inside the picture; `Builder.clipRasterFallback(false)` restores unclipped vectors + warning; the raster targets a 2048px long edge, clamped to between native size and 4x, so a region larger than that is rendered at native resolution rather than downscaled — which also means its transient memory grows with the clip instead of stopping at the target (a 3370pt A0-landscape region costs ~45MB while rendering, against ~17MB for anything up to 2048pt); a true vector clip is tracked in [#413](https://github.com/DemchaAV/GraphCompose/issues/413)) | ⚠️ inline fallback + one-time capability warning |
 | Transform open/close — rotate/scale about fragment centre (`TransformBegin/EndPayload`) | ✅ `PdfTransformBegin/EndRenderHandler` | ✅ `PptxTransformBegin/EndRenderHandler` (group shape; rotation and centre-pivot scaling via the exterior/interior frame ratio) | ⚠️ inline fallback + one-time capability warning |
 | Anchor markers (`AnchorMarkerPayload`) | ✅ `PdfAnchorMarkerRenderHandler` + `PdfInternalLinkWriter` | ✅ `PptxAnchorMarkerRenderHandler` + `PptxNavigationWriter` (slide-jump hyperlinks resolved after all fragments, so forward references work) | ❌ |
@@ -81,7 +92,7 @@ honour an option ignores it (documented contract).
 
 | Capability | PDF (fixed) | PPTX (fixed) | DOCX (semantic) |
 |---|---|---|---|
-| Metadata (title, author, …) | ✅ `PdfDocumentPostProcessor` | ⚠️ `applyMetadata` in `PptxFixedLayoutBackend` (OPC core properties + extended `Application`; OPC has no producer field, so that value is not representable) | ✅ (`DocxSemanticBackend` via `SemanticExportContext`) |
+| Metadata (title, author, …) | ✅ `PdfDocumentPostProcessor` | ⚠️ `applyMetadata` in `PptxFixedLayoutBackend` (OPC core properties + extended `Application`; OPC has no producer field, so that value is not representable) | ⚠️ `applyOutputOptions` (OPC core properties — title, author as creator, subject, keywords; OPC has no producer field here either, so that value is not representable) |
 | Watermark (front/back layers) | ✅ `PdfWatermarkRenderer` | ✅ `PptxChromeRenderer` (per-slide shape at the PDF placement math; behind-content applies before fragments, so no z-order surgery) | ❌ |
 | Repeating headers / footers | ✅ `PdfHeaderFooterRenderer` | ✅ `PptxChromeRenderer` (positioned per-slide text boxes; `{page}` / `{pages}` / `{date}` tokens with the numbering window rules) | ❌ |
 | Protection / encryption | ✅ `PdfDocumentPostProcessor` | ❌ (ignored with a one-time warning — no OOXML encryption support planned) | ❌ |
@@ -93,12 +104,12 @@ honour an option ignores it (documented contract).
 | Capability | PDF (fixed) | PPTX (fixed) | DOCX (semantic) |
 |---|---|---|---|
 | Render to bytes / stream / file (`FixedLayoutRenderer`) | ✅ `PdfFixedLayoutBackend` | ✅ `PptxFixedLayoutBackend` | ✅ `DocxSemanticBackend` (`SemanticBackend<byte[]>`) |
-| Render to images (`renderToImages`) | ✅ PDFBox `PDFRenderer` | ❌ (throws with a pointer to the PDF backend — POI's slide rasterizer cannot honour embedded fonts, and the PDF raster of the same graph is the canonical image output) | ❌ |
-| Raster-slide mode — every page as one full-slide picture, pixel-exact to the PDF/PNG output (`Builder.rasterSlides(dpi)`) | n/a (the PDF raster is the source) | ✅ `PptxFixedLayoutBackend` | ❌ |
-| Multi-section documents (`renderSections`, per-section chrome, cross-section links) | ✅ `buildSectionsDocument` in `PdfFixedLayoutBackend` | ⚠️ `renderSections` in `PptxFixedLayoutBackend` (a deck carries one slide size, so every section must share the same page canvas — differing sizes throw) | ❌ |
+| Render to images (`renderToImages`) | ✅ PDFBox `PDFRenderer` | ❌ (throws with a pointer to the PDF backend — POI's slide rasterizer cannot honour embedded fonts, and the PDF raster of the same graph is the canonical image output) | n/a (a `FixedLayoutRenderer` surface; the semantic SPI has no raster output) |
+| Raster-slide mode — every page as one full-slide picture, pixel-exact to the PDF/PNG output (`Builder.rasterSlides(dpi)`) | n/a (the PDF raster is the source) | ✅ `PptxFixedLayoutBackend` | n/a (a fixed-layout backend builder option) |
+| Multi-section documents (`renderSections`, per-section chrome, cross-section links) | ✅ `buildSectionsDocument` in `PdfFixedLayoutBackend` | ⚠️ `renderSections` in `PptxFixedLayoutBackend` (a deck carries one slide size, so every section must share the same page canvas — differing sizes throw) | n/a (`renderSections` is declared on `FixedLayoutRenderer`; `MultiSectionDocument` drives fixed-layout backends only) |
 | Deterministic output (render twice → identical bytes) | ✅ `PdfDeterminismWriter` | ✅ `PptxDeterminismWriter` (pinned OPC created/modified + zip entry-time normalization) | ❌ |
 | ServiceLoader discovery (`FixedLayoutBackendProvider`) | ✅ `PdfFixedLayoutBackendProvider` (`format() == "pdf"`) | ✅ `PptxFixedLayoutBackendProvider` (`format() == "pptx"`) | n/a (semantic SPI: `SemanticBackend`) |
-| `DocumentSession` convenience methods | ✅ `buildPdf` / `writePdf` / `toPdfBytes` / `toImages` | ✅ `buildPptx` / `writePptx` / `toPptxBytes` (resolved via `BackendProviders.fixedLayout("pptx")`; session chrome applies; fails with `MissingBackendException` naming `graph-compose-render-pptx` when the backend is absent) | via `session.export(new DocxSemanticBackend(...))` |
+| `DocumentSession` convenience methods | ✅ `buildPdf` / `writePdf` / `toPdfBytes` / `toImages` | ✅ `buildPptx` / `writePptx` / `toPptxBytes` (resolved via `BackendProviders.fixedLayout("pptx")`; session chrome applies; fails with `MissingBackendException` naming `graph-compose-render-pptx` when the backend is absent) | ✅ `session.export(new DocxSemanticBackend(...), target)` — the semantic backend is named directly rather than discovered |
 
 ## Fidelity notes (PPTX)
 

render-docx/README.md

@@ -38,16 +38,27 @@ try (var doc = GraphCompose.document().create()) {
 ## What it maps, and what it does not
 
 DOCX walks the **semantic node graph**, not the fixed PDF layout — Word owns the flow, so
-the page geometry the PDF backend resolves is deliberately ignored. Shapes, gradients,
-clips, transforms and alpha have no DOCX counterpart by design; a document that draws with
-them exports its text and tables, not its drawing.
+the page geometry the PDF backend resolves is deliberately ignored. Drawing nodes — shape,
+line, ellipse, polygon, path, barcode — do reach the backend, and are dropped there with one
+logged warning per kind; a clip or transform container renders its children inline, without
+the boundary and without the transform. A document that draws exports its text and tables,
+not its drawing.
 
-What maps: paragraphs (runs, alignment), block images (`STRETCH` / `CONTAIN` / `COVER`),
-table rows including row and column spans, and document metadata. Run styling carries font
-family, size, colour, bold, italic and underline.
+What maps: paragraphs, lists, block images, tables, and document metadata (title, author,
+subject, keywords). Run styling carries font family, size, colour, bold, italic and
+underline.
 
-Beyond geometry, these are **not implemented** even though Word itself can express them —
-check the list before you promise a `.docx` to a reader:
+What maps only in part:
+
+- **Table cells keep their text, not their structure.** `colSpan` and `rowSpan` are not
+  applied, so a table with merged cells exports with its columns misaligned. Per-cell
+  style and fill/border paint are dropped, and cell text carries no run styling.
+- **Image fit is ignored.** The picture is embedded at the node's width and height;
+  `CONTAIN` and `COVER` therefore behave as `STRETCH`, and an image sized only by `scale`
+  falls back to 100 × 100 pt.
+
+These are **not implemented** even though Word itself can express them — check the list
+before you promise a `.docx` to a reader:
 
 - **Hyperlinks are dropped**, external and internal alike; the link text survives as plain text.
 - **No bookmarks and no navigation outline.**
@@ -57,10 +68,12 @@ check the list before you promise a `.docx` to a reader:
 - **Per-run styling in a mixed-style paragraph is flattened.** Every run in a `RichText`
   paragraph is written with the paragraph's style, so a bold or accent-coloured segment
   loses its own styling; the text itself is kept.
-- **Multi-section documents export through the fixed-layout backends only** —
-  `renderSections` is not part of the semantic path.
 - **Output is not byte-deterministic**: rendering twice does not produce identical files.
 
+Multi-section documents are a separate case: `renderSections` is declared on the
+fixed-layout SPI, and `SemanticBackend` carries only `name()` and `export(...)`, so a
+multi-section export runs through the PDF or PPTX backend rather than this one.
+
 Per-capability detail, with the implementing class for every supported cell:
 [backend capability matrix](../docs/architecture/backend-capability-matrix.md).