[DemchaAV]

Why

render-docx/README.md showed one way to export, doc.export(new DocxSemanticBackend(), file), and WordExportExample used the same. Neither showed session.buildDocx(path), how to receive the DocxExportReport, or a configured backend. The README named deterministic output only as a capability bullet.

Three README statements were false:

• "Other drawing … is not written". Boxes, ellipses, vertical and slanted lines, polygons and paths are drawn as floating shapes where the page draws them (DocxDrawings.of, DocxRuleTest#whatIsNotARuleIsDrawnAsAShapeWhereThePagePutsIt).
• "A layer stack … writes its children in order; columns are the exception." Single-line paragraphs sharing a line at tab stops, and stacks laid over the flow as text boxes, are other forms.
• "A horizontal line … is a paragraph border". Only a level, untransformed line no thicker than 12pt is (DocxRules.MAX_RULE_POINTS); any other line is drawn as a shape.

The example's own document was wrong as well. Its captions said the divider and the badge stay PDF-only, but the export writes them as a paragraph border and as a drawn shape holding its letters; the report run on it says so. A caption said nested lists indent two spaces a level, but they are a Word list level. The PDF also printed ? for →, ◦ and ▪, which Helvetica lacks.

buildDocx, writeDocx and toDocxBytes build a default backend for each export (DocumentRenderingFacade.toSemanticBytes). So they have no report sink and stamp the export with the current date. The report and pinned clocks come only from a configured DocxSemanticBackend. The example exports that way, which also makes its committed preview the same bytes on every run on one platform.

The README's new determinism paragraph and the recipe said those bytes are the same "on every run and machine". They are the same on every run on one platform. Across platforms, the parts POI writes itself (word/document.xml, styles.xml, numbering.xml, settings.xml, docProps/app.xml) end their XML declaration with the platform's line separator; on Windows that is `

`, as measured on the committed file. Both now say so. The drift guard already reduces that difference, so the preview compares equal on the Linux runner.

What changed

Docs and the example only; no public API change.

• render-docx/README.md
  • Usage opens on doc.buildDocx(Path), then says what the three convenience methods lack.
  • It also says that export(backend, path) writes the file directly, not through buildDocx's replace-on-success, and throws a plain Exception.
  • A second compiled snippet shows DocxSemanticBackend.builder().deterministic(true).reportSink(...).
  • New paragraphs say what a DocxExportReport note holds (severity, subject, where, detail; bySubject(), count(...)) and what deterministic output pins, including the {date} caveat.
  • Corrected bullets:
    • Horizontal rules: level, untransformed, at most 12pt, in the flow.
    • Drawing: new bullet under what maps; how a drawing is anchored, and where what it loses is named.
    • Not written: now a drawing painted only with a gradient or without layout (named under its kind), on a page with no paragraph (drawing), or in a page zone (page zone content).
    • Positioning: the other forms a stack takes, with their conditions; a clip is named where it cuts what its layers paint.
    • Watermark / protection / viewer preferences: the subjects are named.
• WordExportExample
  • Exports through the configured backend (deterministic(true), reportSink) and prints the report by subject and path.
  • The Javadoc names buildDocx as the one-call form and what it lacks, and drops "poi-ooxml is optional".
  • The heading, captions and metadata subject say what Word gets.
  • The title and nested markers use characters Helvetica has.
• docs/recipes/docx-export.md: the determinism paragraph says "on one platform" and names the parts whose line separator differs.
• examples/README.md: the "Word export (DOCX)" section follows the example. It used to say charts become a data table and that dividers, shapes and barcodes stay PDF-only.
• assets/readme/examples/word-export-companion.{pdf,docx}: regenerated.
• CHANGELOG.md: v2.5.0 Documentation entry.

Not touched:

• web/examples.json still carries the example's old one-line description. It is generated from ShowcaseMetadata, which already has the current one, and the release script regenerates it.
• docs/troubleshooting.md has older wording on DOCX shapes. It is left for its own change.

Verification

• WordExportExample, run twice in separate JVMs on Windows: the same word-export-companion.docx bytes both times. The report prints 0 dropped and 6 approximated, each line with its severity: the nested list, the chart, the divider as a paragraph border, the badge (its form and its drawing) and line height. No missing-glyph warnings.
• ./mvnw -B -ntp test -f examples/pom.xml: 93 tests, 0 failures, including CommittedAssetDriftTest (3) and AssetContentTest (13).
  • Sabotage: the old word-export-companion.docx put back fails CommittedAssetDriftTest, which names the file.
• ./mvnw -B -ntp test -f qa/pom.xml '-Dtest=com/demcha/documentation/**': 28 tests, 0 failures, including DocumentationSnippetCompileTest (6), which compiles both README snippets.
  • Sabotage: misspelling a method in each snippet fails the test, which names both snippet ids.
• ./mvnw -B -ntp test -pl :graph-compose-core '-Dtest=com/demcha/documentation/**': 172 tests, 0 failures.
• Full reactor clean verify:
  • core 841, render-pdf 339, render-docx 2539, testing 5, render-pptx 142, templates 128, qa 1910 tests, 0 failures;
  • the four knowledge-pack checks pass, and core javadoc gives 0 warnings;
  • after install, examples 93/0, including CommittedAssetDriftTest.