feat(api): render a DocumentSession directly to images

CHANGELOG.md

@@ -118,6 +118,16 @@ PDF `GoTo` actions. External links are unchanged.
   begin/end marker per icon — so it matches the inline fix above. The same
   flag is exposed to the DSL as `LayerStackBuilder.clipToBounds()` — the
   `overflow: hidden` of a stacking box for any layer stack.
+- **Render a document straight to images** (`@since 1.9.0`). `DocumentSession`
+  gains `toImages(int dpi)` → `List<BufferedImage>` (one per page) and
+  `toImage(int pageIndex, int dpi)` → `BufferedImage`, plus `transparent`
+  overloads (`toImages(dpi, transparent)` / `toImage(pageIndex, dpi, transparent)`)
+  that return ARGB instead of opaque white. These rasterize the in-memory document
+  directly, skipping the previous `toPdfBytes()` → reparse round-trip needed to get
+  a preview or thumbnail. The return type is the JDK `java.awt.image.BufferedImage`,
+  so the public surface stays renderer-agnostic; the PDFBox `PDFRenderer` call lives
+  in the PDF backend. `PdfVisualRegression` also gains direct `renderPages(session)` /
+  `assertMatchesBaseline(name, session)` overloads on the same path.
 
 ### Documentation
 
@@ -167,6 +177,14 @@ PDF `GoTo` actions. External links are unchanged.
   rasterizes a colour glyph, a gradient emoji paints its shading, an unknown
   shortcode falls back to literal text, and `RichText.emoji` yields an
   `InlineSvgRun` or a text run accordingly).
+- `DocumentSessionImageTest` (direct render-to-image): `toImages(dpi)` returns one
+  image per page sized to the page at that DPI; dimensions scale with DPI; rendered
+  pages contain painted (non-background) pixels; `transparent` yields an ARGB image
+  with a fully-transparent margin while the default is opaque RGB; `toImage(pageIndex,
+  dpi)` returns the requested page and is pixel-identical to the matching `toImages`
+  entry; a post-processed watermark also lands in the raster; the direct render is
+  pixel-identical to the `toPdfBytes()` round-trip (`PdfVisualRegression` / `ImageDiff`,
+  budget 0); and `dpi <= 0`, an out-of-range page, and an empty document are rejected.
 
 ## v1.8.0 — 2026-06-18
 

docs/recipes/streaming.md

@@ -76,6 +76,38 @@ s3.putObject(bucket, key, RequestBody.fromBytes(pdfBytes));
 with an explicit stream — the in-memory path holds the entire PDF
 before returning.
 
+## Page images (previews and thumbnails)
+
+When you need a raster image of the document — a preview, a thumbnail,
+a pixel diff — render straight to `java.awt.image.BufferedImage` with
+`toImages(int dpi)` (one image per page) or `toImage(int pageIndex, int dpi)`
+(a single page). This rasterizes the in-memory document directly, so you
+skip the `toPdfBytes()` → re-parse round-trip you'd otherwise need.
+
+```java
+import java.awt.image.BufferedImage;
+import javax.imageio.ImageIO;
+
+try (DocumentSession document = GraphCompose.document().create()) {
+    document.pageFlow(page -> page.module("Summary",
+            module -> module.paragraph("Preview me")));
+
+    List<BufferedImage> pages = document.toImages(150); // 150 DPI
+    for (int i = 0; i < pages.size(); i++) {
+        ImageIO.write(pages.get(i), "png", Path.of("page-" + i + ".png").toFile());
+    }
+}
+```
+
+The background is opaque white by default. Pass `transparent = true`
+(`toImages(dpi, true)` / `toImage(pageIndex, dpi, true)`) to get an ARGB
+image with a transparent background instead — useful when compositing a
+single glyph or badge.
+
+The return type is the JDK `BufferedImage`, so this stays free of any
+PDF-renderer types in your call site. (`dpi` must be `> 0`; `pageIndex`
+must be in range.)
+
 ## DOCX semantic export
 
 `DocxSemanticBackend` produces an editable Word document. Apache POI

examples/src/main/java/com/demcha/examples/features/text/EmojiSvgVsPngExample.java

@@ -18,10 +18,6 @@
 import com.demcha.compose.document.table.DocumentTableStyle;
 import com.demcha.compose.font.FontName;
 import com.demcha.examples.support.ExampleOutputPaths;
-import org.apache.pdfbox.Loader;
-import org.apache.pdfbox.pdmodel.PDDocument;
-import org.apache.pdfbox.rendering.ImageType;
-import org.apache.pdfbox.rendering.PDFRenderer;
 
 import javax.imageio.ImageIO;
 import java.awt.image.BufferedImage;
@@ -146,15 +142,13 @@ private static DocumentNode pngCell(byte[] png) {
     /** Renders the glyph alone through the engine, then rasterises that page to PNG bytes. */
     private static byte[] rasterise(SvgIcon icon) throws Exception {
         double box = 24.0;
-        byte[] glyphPdf;
         try (DocumentSession g = GraphCompose.document().pageSize(box, box).margin(0, 0, 0, 0).create()) {
             g.dsl().pageFlow().name("g")
                     .addParagraph(p -> p.inlineSvgIcon(icon, box).margin(DocumentInsets.zero()))
                     .build();
-            glyphPdf = g.toPdfBytes();
-        }
-        try (PDDocument doc = Loader.loadPDF(glyphPdf)) {
-            BufferedImage image = new PDFRenderer(doc).renderImageWithDPI(0, 96f, ImageType.ARGB);
+            // Rasterise the in-memory page directly (transparent ARGB) — no PDF
+            // byte round-trip.
+            BufferedImage image = g.toImage(0, 96, true);
             ByteArrayOutputStream buffer = new ByteArrayOutputStream();
             ImageIO.write(image, "png", buffer);
             return buffer.toByteArray();