[DemchaAV]

Why

render-docx has one package, document.backend.semantic.docx, and it had no package-info.java, so its package page had no overview. The descriptions of the Word export elsewhere predate 2.5:

Where	Said	The code
DocxSemanticBackend class Javadoc	"deliberately ignores fixed-layout concerns (no per-page pagination, no PDF chrome)"	requiresResolvedLayout() returns true and the export reads line heights, column widths and drawing positions from the layout (DocxLayoutMetrics.of). It writes headers, footers, page backgrounds and native Word charts (DocxNativeCharts), and hands a DocxExportReport to a sink.
core semantic/package-info	semantic backends serve formats "where the future writer layer needs semantic nodes rather than pre-resolved PDF coordinates"	the DOCX writer exists, and it is handed the resolved layout (SemanticExportContext.layoutGraph)
DocxSemanticBackend.offerASeat	a shape "is anchored in the first paragraph the nearest of them writes on its page"	the holder's paragraph that can place it at the smallest offset (DocxDrawingAnchors.placeInItsHolder / asTheShapeStandsTo)
docs/architecture/overview.md (3 places), streaming.md	the DOCX exporter "never sees a LayoutGraph", "bypass[es] the layout graph", "ignores fixed-layout concerns"	as above
docs/architecture/package-map.md	"Experimental semantic export contracts"	docs/api-stability.md calls the semantic export SPI "otherwise-Stable", with @Beta on its 2.5 members
canonical-legacy-parity.md, streaming.md	Apache POI must be added by the consumer / is optional	render-docx declares poi-ooxml at compile scope
ClipPolicy Javadoc	the DOCX backend "ignores CLIP_PATH and logs a capability warning"	it writes the clipped content whole, crops a picture that fills an elliptical outline, and names in the report each clip that cuts what the container holds (DocxClipReportTest)

What changed

• semantic.docx/package-info.java (new). It covers:
  • what the export writes, and what it reads from the layout;
  • what an export without a layout leaves out;
  • which types are public: the backend and its Builder, the report and its Note / Severity, and the provider;
  • charts, the report, deterministic output, and ServiceLoader discovery;
  • stability. The package carries no package-level @Beta, because it is not Experimental as a whole. The class, its no-argument constructor, name() and export(graph, context) are Stable, and DocxBetaSurfaceTest pins them unmarked. The 2.5 additions are @Beta one element at a time, as set by fix(docx): mark the Word export's 2.5 API @Beta where it was unmarked #1018. So the package-level convention used for the PPTX packages does not apply.
• DocxSemanticBackend class Javadoc rewritten:
  • what is written as Word's own, and what is carried over from the page: the blocks it kept together;
  • what is read from the layout. Without a layout, drawings are left out and each is named in the report (droppedBecause). Page backgrounds, which only the layout carries, are left out with no note (DocxPageBackgrounds.of);
  • charts as Word charts with an embedded workbook. A chart composed in a cell beside other drawings, or in a table composed in a cell, is drawn over a table of its data instead;
  • the report sink;
  • deterministic output: the same bytes on one platform, within one day when a header prints {date} unpinned. Across platforms the bytes differ where POI ends an XML declaration with the platform's line separator.
• DocxSemanticBackend.offerASeat: the anchoring sentence now matches DocxDrawingAnchors.
• DocxBackendProvider: how SemanticBackendProviders finds it (services file plus format()). The backend it creates has no report sink and writes live dates; use builder() with export(...) for either.
• core:
  • semantic/package-info: what a semantic backend is handed, the discovery and section types, which render-module backend writes a file, and the package's @Beta elements.
  • SemanticBackend.requiresResolvedLayout: a semantic backend may read where a drawing its format floats stands. Drawing every page at layout coordinates is what makes a backend fixed-layout.
  • ClipPolicy: what the DOCX backend does with a clip.
• docs: overview.md, package-map.md, canonical-legacy-parity.md and streaming.md updated as in the table. The overview diagram gains the edge from the resolved layout to the DOCX backend.

Javadoc and Markdown only: no code, signature or annotation changes. No CHANGELOG entry, since nothing a caller sees changes. The knowledge pack is unaffected because it reads package-level annotations, not package Javadoc: extract-api.mjs --from-reactor --check reports the surfaces current.

Verification

• Tests:
  • ./mvnw -B -ntp clean install -pl :graph-compose-render-docx -am: core 842, render-pdf 339, render-docx 2545 tests, 0 failures. Core's documentation guards are included: DocumentationCoverageTest, PackageMapGuardTest, BetaAnnotationDocumentationTest.
  • ./mvnw -B -ntp test -f qa/pom.xml: 1910 tests, 0 failures.
• Javadoc:
  • render-docx builds. Its three warnings are older ones, on lines this change does not touch (DocxExportReport:106,112, Builder.build()). {@link Builder#reportSink(Consumer)} resolves to the method.
  • core, from a fresh run with -Xmaxwarns lifted: none of the doclint warnings is in a file this change touches.
• Knowledge pack: node knowledge/tools/api-surface/extract-api.mjs --from-reactor --check: current.

Lane: documentation (canonical surface Javadoc). No layout or render code changes, so the DOCX corpus is untouched.