build: extract the semantic DOCX/PPTX backend into graph-compose-render-docx

.github/workflows/ci.yml

@@ -114,6 +114,12 @@ jobs:
       - name: Install root artifact
         run: ./mvnw -B -ntp -DskipTests install -pl .
 
+      - name: Install graph-compose-render-docx (consumed by the examples module)
+        # The DOCX export example depends on the render-docx backend module, which
+        # is not on Central. Install it after the engine (its graph-compose
+        # dependency) so the examples build resolves it.
+        run: ./mvnw -B -ntp -f render-docx/pom.xml -DskipTests install
+
       - name: Compile examples module
         run: ./mvnw -B -ntp -f examples/pom.xml clean compile
 
@@ -137,34 +143,6 @@ jobs:
           path: examples/target/generated-pdfs/**
           if-no-files-found: error
 
-  no-poi-suite:
-    name: Test suite without poi-ooxml (optional-deps regression)
-    if: github.event_name == 'pull_request'
-    needs: architecture-and-documentation-guards
-    runs-on: ubuntu-latest
-    env:
-      JAVA_TOOL_OPTIONS: -Djava.awt.headless=true
-
-    steps:
-      - name: Check out repository
-        uses: actions/checkout@v7
-
-      - name: Set up Temurin JDK 17
-        uses: actions/setup-java@v5
-        with:
-          distribution: temurin
-          java-version: '17'
-          cache: maven
-
-      - name: Run suite under -P no-poi
-        # poi-ooxml is declared <optional>true</optional>; this job
-        # validates that callers who don't render DOCX still get a
-        # green suite without the POI footprint. Tests that require
-        # poi (DocxSemanticBackend output) carry
-        # @DisabledIfSystemProperty(named = "no.poi", matches = "true")
-        # and skip cleanly. See Track I1 in the readiness taskboard.
-        run: ./mvnw -B -ntp test -pl . -P no-poi
-
   binary-compat:
     name: Binary Compatibility (japicmp vs pom baseline)
     if: github.event_name == 'pull_request'

.github/workflows/publish.yml

@@ -99,6 +99,16 @@ jobs:
           CENTRAL_TOKEN: ${{ secrets.CENTRAL_TOKEN }}
           MAVEN_GPG_PASSPHRASE: ${{ secrets.MAVEN_GPG_PASSPHRASE }}
 
+      - name: Publish render-docx to Maven Central
+        # The semantic DOCX/PPTX backend, lockstep-versioned with the engine
+        # (ships on the same v* tag). graph-compose resolves from the local repo
+        # installed by the engine deploy above.
+        run: ./mvnw -B -ntp -f render-docx/pom.xml -P release -DskipTests -Dgpg.skip=false deploy
+        env:
+          CENTRAL_USERNAME: ${{ secrets.CENTRAL_USERNAME }}
+          CENTRAL_TOKEN: ${{ secrets.CENTRAL_TOKEN }}
+          MAVEN_GPG_PASSPHRASE: ${{ secrets.MAVEN_GPG_PASSPHRASE }}
+
       - name: Publish bundle to Maven Central
         # The graph-compose-bundle convenience aggregate pins this engine
         # version + a compatible graph-compose-fonts version. It tracks the

CHANGELOG.md

@@ -40,6 +40,12 @@ for this cycle.
   (core + render-pdf + templates + fonts + emoji). The optional
   `graph-compose-fonts` and `graph-compose-emoji` artifacts are unchanged. Full
   install guidance ships with 2.0.0.
+- `graph-compose-render-docx` is now a separate artifact: the semantic DOCX/PPTX
+  backend and Apache POI leave the `graph-compose` jar. `DocxSemanticBackend` moves
+  to `com.demcha.compose.document.backend.semantic.docx` and `PptxSemanticBackend`
+  to `com.demcha.compose.document.backend.semantic.pptx`; add
+  `graph-compose-render-docx` (it brings POI transitively) to export DOCX. The
+  `no-poi` build profile is retired.
 
 ## v1.9.0 — 2026-06-29
 

aggregator/pom.xml

@@ -60,6 +60,7 @@
         <module>..</module>
         <module>../fonts</module>
         <module>../emoji</module>
+        <module>../render-docx</module>
         <module>../bundle</module>
         <module>../examples</module>
         <module>../benchmarks</module>

docs/recipes/docx-export.md

@@ -9,7 +9,7 @@ the recipient needs to *edit* the document; use PDF when pixels must match.
 ## Exporting a session
 
 ```java
-import com.demcha.compose.document.backend.semantic.DocxSemanticBackend;
+import com.demcha.compose.document.backend.semantic.docx.DocxSemanticBackend;
 
 try (DocumentSession document = GraphCompose.document()
         .pageSize(595, 842)
@@ -32,10 +32,10 @@ try (DocumentSession document = GraphCompose.document()
 default output file when one was given to `GraphCompose.document(path)`;
 the two-argument overload targets an explicit path.
 
-**Dependency note:** the backend requires `org.apache.poi:poi-ooxml` on
-the classpath. GraphCompose declares it **optional** in its POM, so
-consumers who export DOCX must add it explicitly — consumers who only
-render PDF carry no POI footprint.
+**Dependency note:** the DOCX backend ships in the
+`io.github.demchaav:graph-compose-render-docx` artifact, which brings Apache POI
+transitively. Add that one dependency to export DOCX — consumers who only render
+PDF never pull POI.
 
 ## What maps 1:1
 
@@ -77,4 +77,4 @@ designs, precise placement — export PDF for the reader and DOCX only as
 an editable companion.
 
 Round-trip coverage (paragraphs, tables, metadata, chart fallback) lives in
-[`DocxSemanticBackendTest`](../../src/test/java/com/demcha/compose/document/backend/semantic/DocxSemanticBackendTest.java).
+[`DocxSemanticBackendTest`](../../render-docx/src/test/java/com/demcha/compose/document/backend/semantic/docx/DocxSemanticBackendTest.java).

docs/troubleshooting.md

@@ -43,14 +43,14 @@ GraphCompose marks one heavy, rarely-needed dependency **optional** so
 PDF-only consumers don't pay for it. If you use DOCX export, add the
 dependency to **your** project.
 
-**DOCX export** — `document.export(new DocxSemanticBackend())` needs
-Apache POI on your classpath:
+**DOCX export** — `document.export(new DocxSemanticBackend())` ships in the
+`graph-compose-render-docx` artifact, which brings Apache POI transitively:
 
 ```xml
 <dependency>
-  <groupId>org.apache.poi</groupId>
-  <artifactId>poi-ooxml</artifactId>
-  <version>5.5.1</version>
+  <groupId>io.github.demchaav</groupId>
+  <artifactId>graph-compose-render-docx</artifactId>
+  <version>2.0.0</version>
 </dependency>
 ```
 

examples/README.md

@@ -943,8 +943,8 @@ images, spacers, and page breaks map 1:1; session metadata lands in the
 Word core properties. Charts export as their categories-by-series data
 table (one capability warning per export), shape containers flatten to
 inline layers, and pure geometry — dividers, shapes, barcodes — stays
-PDF-only by design. Requires `org.apache.poi:poi-ooxml` on the
-classpath (the dependency is optional in the GraphCompose POM).
+PDF-only by design. Requires the `graph-compose-render-docx` artifact
+on the classpath (it brings Apache POI transitively).
 
 [📄 View PDF](../assets/readme/examples/word-export-companion.pdf) ·
 [📝 Word file](../assets/readme/examples/word-export-companion.docx) ·

examples/pom.xml

@@ -67,13 +67,13 @@
             <version>${graphcompose.emoji.version}</version>
         </dependency>
 
-        <!-- DOCX export (WordExportExample): poi-ooxml is optional in the
-             GraphCompose POM, so consumers add it explicitly.
-             Keep in lockstep with the root pom's poi.version. -->
+        <!-- DOCX export (WordExportExample): the semantic DOCX backend ships in
+             graph-compose-render-docx since 2.0, which brings Apache POI
+             transitively. -->
         <dependency>
-            <groupId>org.apache.poi</groupId>
-            <artifactId>poi-ooxml</artifactId>
-            <version>5.5.1</version>
+            <groupId>io.github.demchaav</groupId>
+            <artifactId>graph-compose-render-docx</artifactId>
+            <version>${graphcompose.version}</version>
         </dependency>
 
         <dependency>

examples/src/main/java/com/demcha/examples/features/docx/WordExportExample.java

@@ -2,7 +2,7 @@
 
 import com.demcha.compose.GraphCompose;
 import com.demcha.compose.document.api.DocumentSession;
-import com.demcha.compose.document.backend.semantic.DocxSemanticBackend;
+import com.demcha.compose.document.backend.semantic.docx.DocxSemanticBackend;
 import com.demcha.compose.document.chart.ChartData;
 import com.demcha.compose.document.chart.ChartSpec;
 import com.demcha.compose.document.image.DocumentImageData;

pom.xml

@@ -51,7 +51,6 @@
         <logback.version>1.5.37</logback.version>
         <lombok.version>1.18.46</lombok.version>
         <pdfbox.version>3.0.7</pdfbox.version>
-        <poi.version>5.5.1</poi.version>
         <javafx.version>21.0.2</javafx.version>
         <slf4j.version>2.0.18</slf4j.version>
         <zxing.version>3.5.4</zxing.version>
@@ -182,19 +181,6 @@
             <version>${flexmark.version}</version>
         </dependency>
 
-        <!--
-            Apache POI powers the canonical DOCX semantic backend. Marked
-            optional so library consumers that only render PDFs do not pull
-            in ~10MB of POI runtime; apps that call DocumentSession.export(new
-            DocxSemanticBackend()) must add poi-ooxml to their own classpath.
-        -->
-        <dependency>
-            <groupId>org.apache.poi</groupId>
-            <artifactId>poi-ooxml</artifactId>
-            <version>${poi.version}</version>
-            <optional>true</optional>
-        </dependency>
-
         <dependency>
             <groupId>com.fasterxml.jackson.core</groupId>
             <artifactId>jackson-annotations</artifactId>
@@ -649,39 +635,6 @@
             </build>
         </profile>
 
-        <!--
-            Optional-deps regression: runs the canonical suite with
-            `poi-ooxml` (and its transitives) excluded from the test
-            classpath, so callers that don't render DOCX validate that
-            our DocxSemanticBackend is genuinely optional. Tests that
-            require POI carry @DisabledIfSystemProperty(named = "no.poi",
-            matches = "true") and skip cleanly under this profile.
-            Activate with `-P no-poi`. Tracked in v1.6.6 stabilization
-            (Track I1).
-        -->
-        <profile>
-            <id>no-poi</id>
-            <build>
-                <plugins>
-                    <plugin>
-                        <groupId>org.apache.maven.plugins</groupId>
-                        <artifactId>maven-surefire-plugin</artifactId>
-                        <version>${maven.surefire.plugin.version}</version>
-                        <configuration>
-                            <classpathDependencyExcludes>
-                                <classpathDependencyExclude>org.apache.poi:poi-ooxml</classpathDependencyExclude>
-                                <classpathDependencyExclude>org.apache.poi:poi</classpathDependencyExclude>
-                                <classpathDependencyExclude>org.apache.poi:poi-ooxml-lite</classpathDependencyExclude>
-                            </classpathDependencyExcludes>
-                            <systemPropertyVariables>
-                                <no.poi>true</no.poi>
-                            </systemPropertyVariables>
-                        </configuration>
-                    </plugin>
-                </plugins>
-            </build>
-        </profile>
-
         <!--
             Binary-compatibility baseline against the last published
             release. Activated with `-P japicmp`. Resolves the baseline