build: extract the PDF backend into graph-compose-render-pdf

.github/workflows/ci.yml

@@ -76,7 +76,7 @@ jobs:
         # cross-module suites (which need the testing module + the engine test-jar on
         # the classpath and so cannot live in the engine's own test scope). -am pulls
         # the fonts / emoji upstreams; bundle / examples / benchmarks are excluded.
-        run: ./mvnw -B -ntp -f aggregator/pom.xml clean verify -pl :graph-compose-core,:graph-compose-render-docx,:graph-compose-render-pptx,:graph-compose-testing,:graph-compose-qa -am
+        run: ./mvnw -B -ntp -f aggregator/pom.xml clean verify -pl :graph-compose-core,:graph-compose-render-pdf,:graph-compose-render-docx,:graph-compose-render-pptx,:graph-compose-testing,:graph-compose-qa -am
 
       - name: Generate Javadoc
         # Run only on the baseline JDK — Javadoc output is identical
@@ -119,10 +119,16 @@ jobs:
       - name: Install root artifact (graph-compose-core)
         run: ./mvnw -B -ntp -DskipTests install -pl .
 
+      - name: Install graph-compose-render-pdf (the PDF backend the wrapper brings)
+        # The graph-compose wrapper depends on render-pdf so a bare graph-compose
+        # renders PDF; install it after the core (its only dependency) and before
+        # the wrapper.
+        run: ./mvnw -B -ntp -f render-pdf/pom.xml -DskipTests install
+
       - name: Install graph-compose (the compat wrapper, consumed by the examples module)
         # examples depends on the graph-compose coordinate — the empty jar wrapper
-        # over graph-compose-core. Install it after the core so the examples build
-        # resolves it (and the engine classes transitively).
+        # over graph-compose-core + render-pdf. Install it after those so the
+        # examples build resolves it (and the engine + PDF backend transitively).
         run: ./mvnw -B -ntp -f wrapper/pom.xml -DskipTests install
 
       - name: Install graph-compose-render-docx (consumed by the examples module)
@@ -226,6 +232,12 @@ jobs:
       - name: Install root artifact
         run: ./mvnw -B -ntp -DskipTests install -pl .
 
+      - name: Install graph-compose-render-pdf (consumed by the benchmarks module)
+        # benchmarks call buildPdf and reference the PDF backend types directly, so
+        # it depends on render-pdf; install it after the core, before the benchmarks
+        # build resolves it.
+        run: ./mvnw -B -ntp -f render-pdf/pom.xml -DskipTests install
+
       - name: Compile benchmarks module
         run: ./mvnw -B -ntp -f benchmarks/pom.xml clean compile
 
@@ -294,6 +306,12 @@ jobs:
       - name: Install root artifact
         run: ./mvnw -B -ntp -DskipTests install -pl .
 
+      - name: Install graph-compose-render-pdf (consumed by the benchmarks module)
+        # benchmarks call buildPdf and reference the PDF backend types directly, so
+        # it depends on render-pdf; install it after the core, before the benchmarks
+        # build resolves it.
+        run: ./mvnw -B -ntp -f render-pdf/pom.xml -DskipTests install
+
       - name: Compile benchmarks module
         run: ./mvnw -B -ntp -f benchmarks/pom.xml clean compile
 

.github/workflows/publish.yml

@@ -99,10 +99,20 @@ jobs:
           CENTRAL_TOKEN: ${{ secrets.CENTRAL_TOKEN }}
           MAVEN_GPG_PASSPHRASE: ${{ secrets.MAVEN_GPG_PASSPHRASE }}
 
+      - name: Publish render-pdf to Maven Central
+        # The PDF render backend, lockstep-versioned with the engine (ships on the
+        # same v* tag). graph-compose-core resolves from the local repo installed by
+        # the engine deploy above; the wrapper below depends on this.
+        run: ./mvnw -B -ntp -f render-pdf/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 graph-compose (compat wrapper) to Maven Central
         # The empty jar that keeps the `graph-compose` coordinate a drop-in: it
-        # depends on graph-compose-core, resolved from the local repo installed by
-        # the engine (core) deploy above. Ships on the same v* tag, lockstep.
+        # depends on graph-compose-core + graph-compose-render-pdf, resolved from the
+        # local repo installed by the deploys above. Ships on the same v* tag.
         run: ./mvnw -B -ntp -f wrapper/pom.xml -P release -DskipTests -Dgpg.skip=false deploy
         env:
           CENTRAL_USERNAME: ${{ secrets.CENTRAL_USERNAME }}

.gitignore

@@ -39,6 +39,7 @@ build/
 /logs/
 benchmarks/logs/
 qa/logs/
+render-pdf/logs/
 /CV_Generated.pdf
 *.pdf
 # Allow PDF previews that are committed README assets.

CHANGELOG.md

@@ -36,12 +36,21 @@ for this cycle.
   existing `graph-compose` dependency keeps compiling and rendering PDF unchanged.
   Consumer-testing support (`graph-compose-testing`) and the semantic DOCX / PPTX
   backends (`graph-compose-render-docx` / `graph-compose-render-pptx`) are already
-  separate artifacts; the PDF
-  render backend and the built-in templates move into their own modules over the
-  rest of the 2.0 cycle, at which point `graph-compose` aggregates the PDF backend
-  and `graph-compose-core` becomes the lean, bring-your-own-backend coordinate. The
+  separate artifacts; the **PDF render backend now lives in
+  `graph-compose-render-pdf`**, which the `graph-compose` wrapper aggregates so a
+  bare `graph-compose` still renders PDF, while `graph-compose-core` alone is lean
+  (it throws `MissingBackendException` if asked to render without a backend). The
+  built-in templates move into their own module over the rest of the 2.0 cycle. The
   optional `graph-compose-fonts` / `graph-compose-emoji` artifacts are unchanged.
   Full install guidance ships with 2.0.0.
+- `graph-compose-render-pdf` is a separate artifact: the entire PDFBox backend —
+  `document.backend.fixed.pdf.**` and the `engine.render.pdf.**` render tree — plus
+  PDFBox, zxing (barcodes), and the commons-logging→SLF4J bridge leave
+  `graph-compose-core`. The core keeps the `DocumentSession` API and the
+  `ServiceLoader` seam (`FixedLayoutBackendProvider` / `FontMetricsProvider`); the
+  PDF provider ships in render-pdf and is discovered at runtime. Depend on
+  `graph-compose` (or `graph-compose-render-pdf` directly) for PDF; a bare
+  `graph-compose-core` renders nothing until a backend is on the classpath.
 - The semantic office backends are separate artifacts and Apache POI leaves the
   engine: `DocxSemanticBackend` ships in `graph-compose-render-docx` (which brings
   POI transitively — add it to export DOCX), and `PptxSemanticBackend` ships in its

aggregator/pom.xml

@@ -58,6 +58,7 @@
     -->
     <modules>
         <module>..</module>
+        <module>../render-pdf</module>
         <module>../wrapper</module>
         <module>../fonts</module>
         <module>../emoji</module>

benchmarks/pom.xml

@@ -53,6 +53,13 @@
             <artifactId>graph-compose-core</artifactId>
             <version>${graphcompose.version}</version>
         </dependency>
+        <!-- The PDF backend: benchmarks call buildPdf and reference the backend
+             types (PdfFixedLayoutBackend, PdfMeasurementResources, …) directly. -->
+        <dependency>
+            <groupId>io.github.demchaav</groupId>
+            <artifactId>graph-compose-render-pdf</artifactId>
+            <version>${graphcompose.version}</version>
+        </dependency>
 
         <!--
             Bundled Google fonts, split out of the engine jar in v1.8.0. The

pom.xml

@@ -49,10 +49,8 @@
         <flexmark.version>0.64.8</flexmark.version>
         <logback.version>1.5.37</logback.version>
         <lombok.version>1.18.46</lombok.version>
-        <pdfbox.version>3.0.7</pdfbox.version>
         <javafx.version>21.0.2</javafx.version>
         <slf4j.version>2.0.18</slf4j.version>
-        <zxing.version>3.5.4</zxing.version>
 
         <!-- Test dependencies -->
         <assertj.version>3.27.7</assertj.version>
@@ -119,33 +117,6 @@
             <artifactId>slf4j-api</artifactId>
             <version>${slf4j.version}</version>
         </dependency>
-        <!--
-            commons-logging → SLF4J bridge. PDFBox's static initializer
-            (`PDDocument.<clinit>`) still calls `org.apache.commons.logging.
-            LogFactory` directly. We exclude PDFBox's own `commons-logging`
-            artefact to keep a single logging facade and route those calls
-            through SLF4J via this drop-in replacement. Previously this
-            class was on the classpath transitively via `flexmark-all` —
-            F3 (v1.6.7) narrowed flexmark to its core modules and made
-            the bridge explicit so the build is reproducible.
-        -->
-        <dependency>
-            <groupId>org.slf4j</groupId>
-            <artifactId>jcl-over-slf4j</artifactId>
-            <version>${slf4j.version}</version>
-        </dependency>
-
-        <dependency>
-            <groupId>org.apache.pdfbox</groupId>
-            <artifactId>pdfbox</artifactId>
-            <version>${pdfbox.version}</version>
-            <exclusions>
-                <exclusion>
-                    <groupId>commons-logging</groupId>
-                    <artifactId>commons-logging</artifactId>
-                </exclusion>
-            </exclusions>
-        </dependency>
 
         <!--
             Flexmark markdown parser. F3 (v1.6.7) narrowed `flexmark-all`
@@ -173,12 +144,6 @@
             <version>${flexmark.version}</version>
         </dependency>
 
-        <dependency>
-            <groupId>com.google.zxing</groupId>
-            <artifactId>core</artifactId>
-            <version>${zxing.version}</version>
-        </dependency>
-
         <!-- Test dependencies -->
         <!--
             The bundled Google fonts and colour-emoji glyphs live in the sibling

qa/pom.xml

@@ -43,6 +43,7 @@
         <mockito.version>5.23.0</mockito.version>
         <logback.version>1.5.37</logback.version>
         <pdfbox.version>3.0.7</pdfbox.version>
+        <javafx.version>21.0.2</javafx.version>
         <!-- graphcompose.fonts.version / graphcompose.emoji.version and
              maven.deploy.skip=true are inherited from the aggregator parent. -->
     </properties>
@@ -76,6 +77,23 @@
             <version>${project.version}</version>
             <scope>test</scope>
         </dependency>
+        <!-- The PDF backend (provider on the classpath so the relocated render
+             suites resolve a backend) plus its tests-classifier jar, which carries
+             the shared render harness (EngineComposerHarness + engine.assembly). -->
+        <dependency>
+            <groupId>io.github.demchaav</groupId>
+            <artifactId>graph-compose-render-pdf</artifactId>
+            <version>${project.version}</version>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>io.github.demchaav</groupId>
+            <artifactId>graph-compose-render-pdf</artifactId>
+            <version>${project.version}</version>
+            <type>test-jar</type>
+            <classifier>tests</classifier>
+            <scope>test</scope>
+        </dependency>
         <dependency>
             <groupId>io.github.demchaav</groupId>
             <artifactId>graph-compose-fonts</artifactId>
@@ -132,6 +150,19 @@
             <version>${logback.version}</version>
             <scope>test</scope>
         </dependency>
+        <!-- The relocated JavaFX dev-preview tool (com.demcha.compose.devtool.*). -->
+        <dependency>
+            <groupId>org.openjfx</groupId>
+            <artifactId>javafx-controls</artifactId>
+            <version>${javafx.version}</version>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.openjfx</groupId>
+            <artifactId>javafx-swing</artifactId>
+            <version>${javafx.version}</version>
+            <scope>test</scope>
+        </dependency>
     </dependencies>
 
     <build>

qa/src/test/java/com/demcha/compose/document/backend/fixed/pdf/FontShowcaseLayoutSnapshotTest.java

@@ -3,6 +3,7 @@
 import com.demcha.compose.GraphCompose;
 import com.demcha.compose.document.api.DocumentPageSize;
 import com.demcha.compose.document.api.DocumentSession;
+import com.demcha.compose.document.showcase.FontShowcase;
 import com.demcha.compose.testing.layout.LayoutSnapshotAssertions;
 import org.junit.jupiter.api.Test;
 

src/test/java/com/demcha/compose/engine/integration/ImageIntegrationTest.java → qa/src/test/java/com/demcha/compose/engine/integration/ImageIntegrationTest.java

@@ -1,4 +1,5 @@
 package com.demcha.compose.engine.integration;
+import com.demcha.compose.qa.RepoPaths;
 
 import com.demcha.compose.GraphCompose;
 import com.demcha.compose.testsupport.engine.assembly.ComponentBuilder;
@@ -26,7 +27,7 @@
 
 class ImageIntegrationTest {
 
-    private static final Path COVER_ASSET = Path.of("assets", "GraphComposeCover.png");
+    private static final Path COVER_ASSET = RepoPaths.resolve("assets", "GraphComposeCover.png");
 
     @Test
     void shouldRenderSingleImageWithGuides() throws Exception {

src/test/java/com/demcha/compose/font/FontLibraryIntegrationTest.java → qa/src/test/java/com/demcha/compose/font/FontLibraryIntegrationTest.java

@@ -1,4 +1,5 @@
 package com.demcha.compose.font;
+import com.demcha.compose.qa.RepoPaths;
 
 import com.demcha.compose.GraphCompose;
 import com.demcha.compose.document.backend.fixed.pdf.PdfFontLibraryFactory;
@@ -41,7 +42,7 @@ void shouldRegisterCustomFontFamilyFromFilePaths() throws Exception {
         // The bundled fonts moved to the graph-compose-fonts module in v1.8.0.
         // This test exercises file-based registration, so it reads the real TTFs
         // from that module's resources (engine test cwd is the repo root).
-        Path fontsRoot = Path.of("fonts", "src", "main", "resources", "fonts", "google", "lato");
+        Path fontsRoot = RepoPaths.resolve("fonts", "src", "main", "resources", "fonts", "google", "lato");
 
         try (EngineComposerHarness composer = com.demcha.compose.testsupport.EngineComposerHarness.pdf()
                 .registerFontFamily(

qa/src/test/java/com/demcha/compose/qa/RepoPaths.java

@@ -0,0 +1,44 @@
+package com.demcha.compose.qa;
+
+import java.nio.file.Files;
+import java.nio.file.Path;
+
+/**
+ * Resolves repository-root-relative paths independently of which module's working
+ * directory the suite runs from. Several cross-module suites moved into qa read
+ * sibling-module sources or repo-root assets (e.g. {@code fonts/src/...},
+ * {@code examples/src/...}, {@code assets/...}); those paths resolved from the
+ * engine module's basedir (the repo root) but not from qa's, so they go through
+ * here instead.
+ */
+public final class RepoPaths {
+
+    private RepoPaths() {
+    }
+
+    /**
+     * The repository root, located by walking up from the working directory until a
+     * directory that contains {@code aggregator/pom.xml} is found.
+     *
+     * @return the absolute repository-root path
+     */
+    public static Path repoRoot() {
+        for (Path dir = Path.of("").toAbsolutePath(); dir != null; dir = dir.getParent()) {
+            if (Files.exists(dir.resolve("aggregator/pom.xml"))) {
+                return dir;
+            }
+        }
+        return Path.of("").toAbsolutePath();
+    }
+
+    /**
+     * Resolves a repository-root-relative path.
+     *
+     * @param first the first path segment (may itself contain separators)
+     * @param more  additional path segments
+     * @return the resolved absolute path under the repository root
+     */
+    public static Path resolve(String first, String... more) {
+        return repoRoot().resolve(Path.of(first, more));
+    }
+}

src/test/java/com/demcha/documentation/DocumentationExamplesTest.java → qa/src/test/java/com/demcha/documentation/DocumentationExamplesTest.java

@@ -1,4 +1,5 @@
 package com.demcha.documentation;
+import com.demcha.compose.qa.RepoPaths;
 
 import com.demcha.compose.GraphCompose;
 import com.demcha.compose.document.api.DocumentPageSize;
@@ -178,7 +179,7 @@ void shouldRenderComposeFirstBuiltInTemplateExampleToFile() throws Exception {
 
     @Test
     void runnableExamplesShouldUseCanonicalDocumentTemplates() throws IOException {
-        Path examplesRoot = Path.of("examples/src/main/java/com/demcha/examples").toAbsolutePath().normalize();
+        Path examplesRoot = RepoPaths.resolve("examples/src/main/java/com/demcha/examples").toAbsolutePath().normalize();
 
         try (var paths = Files.walk(examplesRoot)) {
             List<String> violations = new TreeSet<>(paths

render-docx/pom.xml

@@ -87,6 +87,14 @@
             <artifactId>poi-ooxml</artifactId>
             <version>${poi.version}</version>
         </dependency>
+        <!-- The export test builds a DocumentSession, which lays out through the
+             font-metrics seam now provided by graph-compose-render-pdf. -->
+        <dependency>
+            <groupId>io.github.demchaav</groupId>
+            <artifactId>graph-compose-render-pdf</artifactId>
+            <version>${project.version}</version>
+            <scope>test</scope>
+        </dependency>
 
         <!-- Test dependencies -->
         <dependency>