docs(examples): add the twin-output dual-format hook example and README section

CHANGELOG.md

@@ -176,6 +176,14 @@ follow semantic versioning; release dates are ISO 8601.
 
 ### Documentation
 
+- New `TwinOutputExample` flagship: a single 16:9 page written once and
+  emitted twice from the same session — `buildPdf()` and `buildPptx(Path)`
+  produce a print-ready PDF and a PowerPoint slide with identical geometry.
+  The README gains a dual-output section showing the PDF render next to
+  PowerPoint's own export of the generated slide, plus a screenshot of the
+  deck open in PowerPoint with the headline text frame selected — the
+  committed artifacts land 69 native shapes with only the clip-masked logo
+  as a picture.
 - `docs/architecture/backend-capability-matrix.md` — a per-capability matrix
   of what each render backend supports and which class implements it,
   maintained as part of every capability-changing PR.

README.md

@@ -5,8 +5,8 @@
 </p>
 
 <p align="center">
-  <b>Declarative Java DSL for structured business PDFs.</b><br/>
-  Describe what the document <i>says</i>; the engine resolves layout, pagination, themes, and PDFBox rendering. <b>Cinematic by default.</b>
+  <b>Declarative Java DSL for structured business documents.</b><br/>
+  Describe what the document <i>says</i>; the engine resolves layout, pagination, themes, and backend rendering &mdash; print-ready PDF first, an editable PowerPoint deck from the same source. <b>Cinematic by default.</b>
 </p>
 
 <p align="center">
@@ -42,6 +42,39 @@
   <sub>☝ This banner is itself a GraphCompose document — <a href="./assets/readme/examples/engine-deck-v2.pdf"><b>view the full module-first deck (PDF)</b></a>, rendered by <a href="./examples/src/main/java/com/demcha/examples/flagships/EngineDeckV2Example.java"><code>EngineDeckV2Example</code></a>: the 2.0 module graph, native vector charts, and real comparative benchmarks, all drawn by the engine. It renders its own marketing.</sub>
 </p>
 
+## One source → a PDF <i>and</i> an editable PowerPoint deck
+
+The same `DocumentSession` emits both. The PDF backend prints the resolved layout; the PPTX backend (**beta**) rebuilds it as slides with identical geometry — text, panels, tables, and vectors arrive in PowerPoint as **native, editable shapes**, not screenshots (the page below lands as 69 native shapes; only its clip-masked logo art is a picture).
+
+```java
+Path deck = Path.of("twin-output.pptx");
+try (DocumentSession doc = GraphCompose.document(Path.of("twin-output.pdf"))
+        .pageSize(DocumentPageSize.SLIDE_16_9)
+        .create()) {
+    compose(doc);        // one description
+    doc.buildPdf();      // print-ready PDF
+    doc.buildPptx(deck); // editable PowerPoint
+}
+```
+
+<table>
+<tr>
+<td width="50%" align="center"><sub><b>twin-output.pdf</b> — rendered by the PDF backend</sub></td>
+<td width="50%" align="center"><sub><b>twin-output.pptx</b> — the same page, as <b>PowerPoint itself</b> renders it</sub></td>
+</tr>
+<tr>
+<td><img src="./assets/readme/twin-output-pdf.png" alt="The twin-output page rendered from the PDF"/></td>
+<td><img src="./assets/readme/twin-output-pptx.png" alt="The same page exported as a PNG by PowerPoint from the generated .pptx"/></td>
+</tr>
+</table>
+
+<p align="center">
+  <img src="./assets/readme/twin-output-editing.png" alt="The generated deck open in PowerPoint with the headline text frame selected for editing" width="820"/>
+</p>
+<p align="center">
+  <sub>☝ The generated deck open in PowerPoint — the headline is a selected, editable text frame, and the ribbon is live because the slide is built from native shapes. Artifacts: <a href="./assets/readme/examples/twin-output.pdf"><b>PDF</b></a> · <a href="./assets/readme/examples/twin-output.pptx"><b>PPTX</b></a> · <a href="./examples/src/main/java/com/demcha/examples/flagships/TwinOutputExample.java"><b>source</b></a> (<code>TwinOutputExample</code>, ~370 lines, page included).</sub>
+</p>
+
 ## Why GraphCompose
 
 - **Author intent, not coordinates.** Fluent DSL for sections, paragraphs, tables, lists, layer stacks, themes &mdash; the engine handles measurement, pagination, and rendering.
@@ -175,7 +208,7 @@ For a Spring Boot `@RestController` streaming the PDF straight to the response,
 |---|---|---|
 | PDF | Production | Fixed-layout backend on PDFBox 3.0. Full DSL coverage. |
 | DOCX | Partial | Semantic export via Apache POI. Unsupported nodes (`shape`, `line`, `ellipse`, `barcode`) are dropped silently &mdash; layout fidelity is best-effort for paragraph / list / table content. |
-| PPTX | Skeleton | Validates supported node types and emits a manifest. **Not a real PowerPoint export yet** &mdash; planned only if there is demand. |
+| PPTX | Beta | Fixed-layout export via Apache POI from the same resolved layout &mdash; one page per editable slide with native shapes and text frames; clipped regions land as pixel-exact pictures. First shipped in 2.1, marked `@Beta` while the API shape settles. |
 
 ### Text &amp; internationalization
 

examples/README.md

@@ -62,6 +62,7 @@ are with the canonical DSL, then jump to its detailed section below.
 | [Module-first Profile](#module-first-profile) | Authoring directly against `DocumentSession.module(...).paragraph(...)` — DSL-direct, no template | [PDF](../assets/readme/examples/module-first-profile.pdf) · [Source](src/main/java/com/demcha/examples/flagships/ModuleFirstFileExample.java) |
 | **Engine Showcase** | Single-page cinematic brand promo — semantic-graph → polished-PDFs visual metaphor with rounded clip frame, magazine headline lockup, KPI cards, capability columns; source of the README hero image | [Source](src/main/java/com/demcha/examples/flagships/EngineShowcase.java) |
 | **Engine Deck** | Multi-page **landscape** capability deck — page 1 is a banner infographic (DSL code → engine → backends → **real rendered-document thumbnails**), then an authoring-pipeline walkthrough, and two pages of **real benchmark data** (GraphCompose vs iText 9 vs JasperReports) loaded from a bundled result file and drawn as tables + native charts; the landscape companion to Engine Showcase. The same composition also renders as a **geometry-identical PowerPoint deck** (one page = one editable slide) through `buildPptx()` | [PDF](../assets/readme/examples/engine-deck.pdf) · [Source](src/main/java/com/demcha/examples/flagships/EngineDeckExample.java) · [PPTX source](src/main/java/com/demcha/examples/flagships/EngineDeckPptxExample.java) |
+| **Twin Output** | The dual-output hook stated by the artifact itself — a single 16:9 page written once and emitted **twice from the same session**: `buildPdf()` and `buildPptx(...)` produce a print-ready PDF and a PowerPoint slide with identical geometry where text, panels, and vectors stay native, editable shapes (only the clip-masked logo art lands as a picture); the root README shows PowerPoint's own render of the slide next to the PDF | [PDF](../assets/readme/examples/twin-output.pdf) · [PPTX](../assets/readme/examples/twin-output.pptx) · [Source](src/main/java/com/demcha/examples/flagships/TwinOutputExample.java) |
 
 ### 🧱 Core DSL
 

examples/src/main/java/com/demcha/examples/GenerateAllExamples.java

@@ -50,6 +50,7 @@
 import com.demcha.examples.flagships.FinancialReportExample;
 import com.demcha.examples.flagships.MasterShowcaseExample;
 import com.demcha.examples.flagships.ModuleFirstFileExample;
+import com.demcha.examples.flagships.TwinOutputExample;
 import com.demcha.examples.templates.coverletter.CvBlueBannerLetterV2Example;
 import com.demcha.examples.templates.coverletter.CvBoxedSectionsLetterV2Example;
 import com.demcha.examples.templates.coverletter.CvCenteredHeadlineLetterV2Example;
@@ -214,6 +215,7 @@ public static void main(String[] args) throws Exception {
         System.out.println("Generated: " + BusinessReportExample.generate());
         System.out.println("Generated: " + EngineDeckExample.generate());
         System.out.println("Generated: " + EngineDeckPptxExample.generate());
+        System.out.println("Generated: " + TwinOutputExample.generate());
         System.out.println("Generated: " + FinancialReportExample.generate());
         System.out.println("Generated: " + BookTemplateExample.generate());
         System.out.println("Generated: " + PoetryTitlePageExample.generate());