chore(engine): deprecate the legacy ECS PDF renderer

Follow-up to F11/PR #148, which deprecated the engine.core/layout/pagination ECS packages. engine.render.pdf is a canonical-mixed package -- it also holds the canonical-shared PdfFont, GlyphFallbackLogger, and the header/footer + watermark renderers used by document.backend.fixed.pdf -- so the legacy Entity-based PDF renderer could not be marked @deprecated at package level without dragging those along.

Physically split it: move the dead ECS renderer (PdfRenderingSystemECS plus PdfRenderSession/PdfCanvas/PdfStream/PdfImageCache/PdfFileManagerSystem/PdfGuidesRenderer, the 13 render-marker handlers, and the TableCellBox/PdfBookmarkBuilder helpers) into a new engine.render.pdf.ecs with .handlers/.helpers sub-packages, then mark those three packages @deprecated at package level (no deprecation-warning cascade, same pattern as F11). The four canonical-shared types stay in engine.render.pdf; colocated tests move with the package-private classes.

The relocated renderer has no public entry point (canonical PDF output goes through document.backend.fixed.pdf) and carries no binary-compatibility promise, so the package move is excluded from the japicmp gate rather than treated as a breaking removal. Package docs (engine.render.pdf, package-map, implementation-guide) updated to reflect the canonical/legacy split.

No behaviour change; verify -P japicmp green (1152 tests + guards + japicmp).

Author: DemchaAV

CHANGELOG.md

@@ -133,6 +133,24 @@ Open cycle — bug-fix / housekeeping. Entries land here as they merge.
   `engine.measurement`, `engine.font`, `engine.render`) are **not** deprecated.
   No public API or behaviour change.
 
+- **The legacy ECS PDF render pipeline is deprecated.** Follow-up to the ECS
+  engine deprecation above. The `Entity`-based PDFBox renderer
+  (`PdfRenderingSystemECS` and its collaborators — `PdfRenderSession`, `PdfCanvas`,
+  `PdfStream`, `PdfImageCache`, `PdfFileManagerSystem`, `PdfGuidesRenderer`, the
+  render-marker handlers, and the `TableCellBox` / `PdfBookmarkBuilder` helpers) is
+  the renderer for the removed `GraphCompose.pdf(...)` surface and now runs only
+  under the legacy engine regression tests; canonical PDF output goes through
+  `com.demcha.compose.document.backend.fixed.pdf`. Because `engine.render.pdf` is a
+  *mixed* package — it also holds the canonical-shared `PdfFont`,
+  `GlyphFallbackLogger`, and the header/footer + watermark post-processors — the
+  legacy classes were physically moved into a new `engine.render.pdf.ecs`
+  (with `.handlers` / `.helpers` sub-packages), which is then `@Deprecated` at
+  package level (so no deprecation-warning cascade, same pattern as the ECS engine
+  packages). The four genuinely shared `engine.render.pdf` types are **not**
+  deprecated and stay put. No behaviour change. The relocated renderer has no
+  public entry point and carries no binary-compatibility promise, so the move is
+  excluded from the japicmp gate rather than treated as a breaking removal.
+
 ### Tests / tooling
 
 - **Benchmark regression gate and measurement probe (benchmarks module, not part

docs/architecture/package-map.md

@@ -49,7 +49,8 @@ intended.
 | `com.demcha.compose.engine.pagination` | Page-breaking helpers and pagination fallback systems. | Maintain child-first ordering and page-shift propagation rules. |
 | `com.demcha.compose.engine.measurement` | Text measurement contracts and font-backed implementations. | Builders/layout helpers depend on this seam instead of reaching into renderers. |
 | `com.demcha.compose.engine.render` | Backend-neutral render contracts, handler registry, render ordering, and render-pass session lifetime. | Add backend-neutral contracts here, backend-specific drawing elsewhere. |
-| `com.demcha.compose.engine.render.pdf` | Low-level PDF backend internals for ECS rendering. | PDFBox state stays here and in child handler/helper packages. |
+| `com.demcha.compose.engine.render.pdf` | Shared PDFBox primitives for the canonical fixed-layout backend: `PdfFont`, `GlyphFallbackLogger`, and the header/footer + watermark renderers under `helpers`. | Add canonical-shared PDF support here; the legacy ECS renderer lives in the deprecated `ecs` sub-package. |
+| `com.demcha.compose.engine.render.pdf.ecs` | **Deprecated.** Legacy `Entity`-based ECS PDF renderer (`PdfRenderingSystemECS` and collaborators, plus the `ecs.handlers` / `ecs.helpers` sub-packages). | Dead renderer kept only for legacy regression tests; do not extend or optimize. |
 | `com.demcha.compose.engine.render.word` | Experimental Word backend internals. | Treat as research until a supported public surface is designed. |
 | `com.demcha.compose.engine.text` | Internal text hot-path utilities shared by layout and render stages. | Keep helpers backend-neutral and avoid public authoring concepts here. |
 | `com.demcha.compose.engine.text.markdown` | Markdown token parsing used by text preparation. | Keep output backend-neutral. |

docs/contributing/implementation-guide.md

@@ -321,21 +321,29 @@ Preferred extension pattern for new backends:
 4. keep backend-only helper drawing in renderer-owned helper packages when the code is not an entity render marker
 5. keep renderer ordering policy in the rendering layer rather than in pagination utilities
 
+> **Deprecated reference implementation.** The PDF renderer named below
+> (`PdfRenderingSystemECS` and the `engine.render.pdf.ecs` handlers/helpers) is the
+> legacy `Entity`-based ECS renderer, kept only for regression tests; canonical PDF
+> output is produced by `com.demcha.compose.document.backend.fixed.pdf`. The
+> backend-neutral `engine.render` *contracts* (`Render`, `RenderPassSession`,
+> `RenderStream`, `EntityRenderOrder`) are **not** deprecated — only the ECS PDF
+> implementation is. Do not extend the `ecs` renderer.
+
 Important files:
 
 - [Render.java](./../src/main/java/com/demcha/compose/engine/render/Render.java)
 - [RenderPassSession.java](./../src/main/java/com/demcha/compose/engine/render/RenderPassSession.java)
 - [RenderStream.java](./../src/main/java/com/demcha/compose/engine/render/RenderStream.java)
-- [PdfRenderingSystemECS.java](./../src/main/java/com/demcha/compose/engine/render/pdf/PdfRenderingSystemECS.java)
-- [PdfRenderSession.java](./../src/main/java/com/demcha/compose/engine/render/pdf/PdfRenderSession.java)
+- [PdfRenderingSystemECS.java](./../src/main/java/com/demcha/compose/engine/render/pdf/ecs/PdfRenderingSystemECS.java)
+- [PdfRenderSession.java](./../src/main/java/com/demcha/compose/engine/render/pdf/ecs/PdfRenderSession.java)
 - [EntityRenderOrder.java](./../src/main/java/com/demcha/compose/engine/render/EntityRenderOrder.java)
 
 Migration rule for new engine components:
 
 - implement backend-neutral `Render`, not backend-specific render interfaces
-- move PDF drawing into `...render.pdf.handlers`
+- move PDF drawing into `...render.pdf.ecs.handlers`
 - use `TextMeasurementSystem` for text width and line metrics instead of reaching through `LayoutSystem`
-- place PDF-only helper objects in `...render.pdf.helpers`
+- place PDF-only helper objects in `...render.pdf.ecs.helpers`
 - keep page-surface lifetime in a backend-specific `RenderPassSession`, not in engine builders or render markers
 - keep resolved draw ordering in renderer-owned or renderer-neutral rendering helpers such as `EntityRenderOrder`
 - register a render handler for every engine render marker because the PDF entity path no longer supports a backend-specific render fallback

pom.xml

@@ -692,6 +692,29 @@
                                 -->
                                 <excludes>
                                     <exclude>com.demcha.compose.document.layout.payloads</exclude>
+                                    <!--
+                                        Legacy ECS PDF renderer (PdfRenderingSystemECS and its
+                                        collaborators), relocated to
+                                        com.demcha.compose.engine.render.pdf.ecs[.handlers|.helpers]
+                                        and @Deprecated at package level. This is the dead
+                                        Entity-based renderer that no public entry point reaches
+                                        (canonical PDF output goes through
+                                        document.backend.fixed.pdf); it carries no
+                                        binary-compatibility promise. Both the relocated packages
+                                        and the vacated original fully-qualified names are excluded
+                                        so the package split is not flagged as a breaking removal.
+                                    -->
+                                    <exclude>com.demcha.compose.engine.render.pdf.ecs</exclude>
+                                    <exclude>com.demcha.compose.engine.render.pdf.ecs.handlers</exclude>
+                                    <exclude>com.demcha.compose.engine.render.pdf.ecs.helpers</exclude>
+                                    <exclude>com.demcha.compose.engine.render.pdf.handlers</exclude>
+                                    <exclude>com.demcha.compose.engine.render.pdf.PdfRenderingSystemECS</exclude>
+                                    <exclude>com.demcha.compose.engine.render.pdf.PdfCanvas</exclude>
+                                    <exclude>com.demcha.compose.engine.render.pdf.PdfStream</exclude>
+                                    <exclude>com.demcha.compose.engine.render.pdf.PdfFileManagerSystem</exclude>
+                                    <exclude>com.demcha.compose.engine.render.pdf.PdfGuidesRenderer</exclude>
+                                    <exclude>com.demcha.compose.engine.render.pdf.helpers.TableCellBox</exclude>
+                                    <exclude>com.demcha.compose.engine.render.pdf.helpers.PdfBookmarkBuilder</exclude>
                                 </excludes>
                             </parameter>
                         </configuration>

…compose/engine/render/pdf/PdfCanvas.java …ose/engine/render/pdf/ecs/PdfCanvas.javasrc/main/java/com/demcha/compose/engine/render/pdf/PdfCanvas.java renamed to src/main/java/com/demcha/compose/engine/render/pdf/ecs/PdfCanvas.java src/main/java/com/demcha/compose/engine/render/pdf/PdfCanvas.java renamed to src/main/java/com/demcha/compose/engine/render/pdf/ecs/PdfCanvas.java

@@ -1,4 +1,4 @@
-package com.demcha.compose.engine.render.pdf;
+package com.demcha.compose.engine.render.pdf.ecs;
 
 import com.demcha.compose.engine.core.Canvas;
 import com.demcha.compose.engine.components.style.Margin;

…ine/render/pdf/PdfFileManagerSystem.java …render/pdf/ecs/PdfFileManagerSystem.javasrc/main/java/com/demcha/compose/engine/render/pdf/PdfFileManagerSystem.java renamed to src/main/java/com/demcha/compose/engine/render/pdf/ecs/PdfFileManagerSystem.java src/main/java/com/demcha/compose/engine/render/pdf/PdfFileManagerSystem.java renamed to src/main/java/com/demcha/compose/engine/render/pdf/ecs/PdfFileManagerSystem.java

@@ -1,4 +1,4 @@
-package com.demcha.compose.engine.render.pdf;
+package com.demcha.compose.engine.render.pdf.ecs;
 
 import com.demcha.compose.engine.core.EntityManager;
 import com.demcha.compose.engine.io.FileManagerSystem;

…engine/render/pdf/PdfGuidesRenderer.java …ne/render/pdf/ecs/PdfGuidesRenderer.javasrc/main/java/com/demcha/compose/engine/render/pdf/PdfGuidesRenderer.java renamed to src/main/java/com/demcha/compose/engine/render/pdf/ecs/PdfGuidesRenderer.java src/main/java/com/demcha/compose/engine/render/pdf/PdfGuidesRenderer.java renamed to src/main/java/com/demcha/compose/engine/render/pdf/ecs/PdfGuidesRenderer.java

@@ -1,4 +1,4 @@
-package com.demcha.compose.engine.render.pdf;
+package com.demcha.compose.engine.render.pdf.ecs;
 
 import com.demcha.compose.engine.render.guides.GuidesRenderer;
 import com.demcha.compose.engine.render.guides.impl.BoxRenderImpl;

…ose/engine/render/pdf/PdfImageCache.java …engine/render/pdf/ecs/PdfImageCache.javasrc/main/java/com/demcha/compose/engine/render/pdf/PdfImageCache.java renamed to src/main/java/com/demcha/compose/engine/render/pdf/ecs/PdfImageCache.java src/main/java/com/demcha/compose/engine/render/pdf/PdfImageCache.java renamed to src/main/java/com/demcha/compose/engine/render/pdf/ecs/PdfImageCache.java

@@ -1,4 +1,4 @@
-package com.demcha.compose.engine.render.pdf;
+package com.demcha.compose.engine.render.pdf.ecs;
 
 import com.demcha.compose.engine.components.content.ImageData;
 import com.demcha.compose.engine.components.content.ImageMetadata;

…/engine/render/pdf/PdfRenderSession.java …ine/render/pdf/ecs/PdfRenderSession.javasrc/main/java/com/demcha/compose/engine/render/pdf/PdfRenderSession.java renamed to src/main/java/com/demcha/compose/engine/render/pdf/ecs/PdfRenderSession.java src/main/java/com/demcha/compose/engine/render/pdf/PdfRenderSession.java renamed to src/main/java/com/demcha/compose/engine/render/pdf/ecs/PdfRenderSession.java

@@ -1,4 +1,4 @@
-package com.demcha.compose.engine.render.pdf;
+package com.demcha.compose.engine.render.pdf.ecs;
 
 import com.demcha.compose.engine.render.RenderPassSession;
 import org.apache.pdfbox.pdmodel.PDPageContentStream;

…ne/render/pdf/PdfRenderingSystemECS.java …ender/pdf/ecs/PdfRenderingSystemECS.javasrc/main/java/com/demcha/compose/engine/render/pdf/PdfRenderingSystemECS.java renamed to src/main/java/com/demcha/compose/engine/render/pdf/ecs/PdfRenderingSystemECS.java src/main/java/com/demcha/compose/engine/render/pdf/PdfRenderingSystemECS.java renamed to src/main/java/com/demcha/compose/engine/render/pdf/ecs/PdfRenderingSystemECS.java

@@ -1,4 +1,4 @@
-package com.demcha.compose.engine.render.pdf;
+package com.demcha.compose.engine.render.pdf.ecs;
 
 import com.demcha.compose.engine.core.Canvas;
 import com.demcha.compose.engine.components.content.ImageData;
@@ -9,19 +9,19 @@
 import com.demcha.compose.engine.core.EntityManager;
 import com.demcha.compose.engine.render.guides.GuidLineSettings;
 import com.demcha.compose.engine.render.RenderingSystemBase;
-import com.demcha.compose.engine.render.pdf.handlers.PdfBarcodeRenderHandler;
-import com.demcha.compose.engine.render.pdf.handlers.PdfBlockTextRenderHandler;
-import com.demcha.compose.engine.render.pdf.handlers.PdfCircleRenderHandler;
-import com.demcha.compose.engine.render.pdf.handlers.PdfChunkedBlockTextRenderHandler;
-import com.demcha.compose.engine.render.pdf.handlers.PdfContainerRenderHandler;
-import com.demcha.compose.engine.render.pdf.handlers.PdfElementRenderHandler;
-import com.demcha.compose.engine.render.pdf.handlers.PdfImageRenderHandler;
-import com.demcha.compose.engine.render.pdf.handlers.PdfLineRenderHandler;
-import com.demcha.compose.engine.render.pdf.handlers.PdfLinkRenderHandler;
-import com.demcha.compose.engine.render.pdf.handlers.PdfPageBreakRenderHandler;
-import com.demcha.compose.engine.render.pdf.handlers.PdfRectangleRenderHandler;
-import com.demcha.compose.engine.render.pdf.handlers.PdfTableRowRenderHandler;
-import com.demcha.compose.engine.render.pdf.handlers.PdfTextRenderHandler;
+import com.demcha.compose.engine.render.pdf.ecs.handlers.PdfBarcodeRenderHandler;
+import com.demcha.compose.engine.render.pdf.ecs.handlers.PdfBlockTextRenderHandler;
+import com.demcha.compose.engine.render.pdf.ecs.handlers.PdfCircleRenderHandler;
+import com.demcha.compose.engine.render.pdf.ecs.handlers.PdfChunkedBlockTextRenderHandler;
+import com.demcha.compose.engine.render.pdf.ecs.handlers.PdfContainerRenderHandler;
+import com.demcha.compose.engine.render.pdf.ecs.handlers.PdfElementRenderHandler;
+import com.demcha.compose.engine.render.pdf.ecs.handlers.PdfImageRenderHandler;
+import com.demcha.compose.engine.render.pdf.ecs.handlers.PdfLineRenderHandler;
+import com.demcha.compose.engine.render.pdf.ecs.handlers.PdfLinkRenderHandler;
+import com.demcha.compose.engine.render.pdf.ecs.handlers.PdfPageBreakRenderHandler;
+import com.demcha.compose.engine.render.pdf.ecs.handlers.PdfRectangleRenderHandler;
+import com.demcha.compose.engine.render.pdf.ecs.handlers.PdfTableRowRenderHandler;
+import com.demcha.compose.engine.render.pdf.ecs.handlers.PdfTextRenderHandler;
 import com.demcha.compose.engine.render.guides.GuidesRenderer;
 import com.demcha.compose.engine.render.RenderHandler;
 import com.demcha.compose.engine.render.EntityRenderOrder;