chore(engine): deprecate the legacy ECS PDF renderer (F11 follow-up)

CHANGELOG.md

@@ -144,6 +144,24 @@ Open cycle — bug-fix / housekeeping. Entries land here as they merge.
   until the baseline advances past this release. No canonical 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

CONTRIBUTING.md

@@ -168,10 +168,11 @@ not need any of them.
 - Engine render markers implement backend-neutral `Render`. Do not
   add backend-specific render interfaces back into
   `engine/components`.
-- PDF rendering logic lives in
-  `src/main/java/com/demcha/compose/engine/render/pdf/handlers/`.
+- PDF rendering logic for the legacy ECS renderer (deprecated; canonical PDF
+  output goes through `com.demcha.compose.document.backend.fixed.pdf`) lives in
+  `src/main/java/com/demcha/compose/engine/render/pdf/ecs/handlers/`.
   Backend-only helper objects live in
-  `com.demcha.compose.engine.render.pdf.helpers`, not in
+  `com.demcha.compose.engine.render.pdf.ecs.helpers`, not in
   `components/renderable`.
 - Builders and layout code get text width and line metrics from
   `TextMeasurementSystem`, not from
@@ -208,7 +209,7 @@ The rules above are enforced by tests:
   [EnginePdfBoundaryTest.java](./src/test/java/com/demcha/compose/engine/architecture/EnginePdfBoundaryTest.java),
   [CanonicalTemplateComposerPdfBoundaryTest.java](./src/test/java/com/demcha/compose/document/templates/architecture/CanonicalTemplateComposerPdfBoundaryTest.java),
   [PdfRenderInterfaceGuardTest.java](./src/test/java/com/demcha/compose/engine/render/pdf/PdfRenderInterfaceGuardTest.java),
-  [PdfRenderingSystemECSDispatchTest.java](./src/test/java/com/demcha/compose/engine/render/pdf/PdfRenderingSystemECSDispatchTest.java)
+  [PdfRenderingSystemECSDispatchTest.java](./src/test/java/com/demcha/compose/engine/render/pdf/ecs/PdfRenderingSystemECSDispatchTest.java)
 
 ## Adding a new feature
 
@@ -325,7 +326,7 @@ Choose the smallest tests that match the change:
 - For low-level test harness changes:
   [ComponentBuilderTest.java](./src/test/java/com/demcha/compose/engine/components/ComponentBuilderTest.java)
 - For render-marker dispatch changes:
-  [PdfRenderingSystemECSDispatchTest.java](./src/test/java/com/demcha/compose/engine/render/pdf/PdfRenderingSystemECSDispatchTest.java)
+  [PdfRenderingSystemECSDispatchTest.java](./src/test/java/com/demcha/compose/engine/render/pdf/ecs/PdfRenderingSystemECSDispatchTest.java)
 - For layout/positioning behavior:
   [ComputedPositionTest.java](./src/test/java/com/demcha/compose/engine/components/layout/ComputedPositionTest.java)
 - For pagination and multi-page behavior:

docs/architecture/overview.md

@@ -231,8 +231,8 @@ code should not need any of them.
   into the active renderer
 - render marker components identify *what* needs to be rendered;
   *how* it is drawn lives in renderer-owned handler packages such as
-  `...render.pdf.handlers` (with helper objects under
-  `...render.pdf.helpers`)
+  `...render.pdf.ecs.handlers` (with helper objects under
+  `...render.pdf.ecs.helpers`)
 - `RenderStream` acts as a session factory, not as a per-entity
   content-stream opener
 - `RenderPassSession` is the shared seam for page lifetime and

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

@@ -259,7 +259,7 @@ Relevant files:
 
 - [TableBuilder.java](./../src/test/java/com/demcha/compose/testsupport/engine/assembly/TableBuilder.java)
 - [TableRow.java](./../src/main/java/com/demcha/compose/engine/components/renderable/TableRow.java)
-- [TableCellBox.java](./../src/main/java/com/demcha/compose/engine/render/pdf/helpers/TableCellBox.java)
+- [TableCellBox.java](./../src/main/java/com/demcha/compose/engine/render/pdf/ecs/helpers/TableCellBox.java)
 - [TableResolvedCell.java](./../src/main/java/com/demcha/compose/engine/components/content/table/TableResolvedCell.java)
 
 Rule of thumb:
@@ -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>
                                     <!--
                                         engine.measurement.TextMeasurementSystem dropped its vestigial
                                         SystemECS super-interface (and the no-op process(EntityManager)

src/main/java/com/demcha/compose/engine/render/pdf/PdfCanvas.java → 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;

src/main/java/com/demcha/compose/engine/render/pdf/PdfFileManagerSystem.java → 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;

src/main/java/com/demcha/compose/engine/render/pdf/PdfGuidesRenderer.java → 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;

src/main/java/com/demcha/compose/engine/render/pdf/PdfImageCache.java → 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;

src/main/java/com/demcha/compose/engine/render/pdf/PdfRenderSession.java → 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;

src/main/java/com/demcha/compose/engine/render/pdf/PdfRenderingSystemECS.java → 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;

src/main/java/com/demcha/compose/engine/render/pdf/PdfStream.java → src/main/java/com/demcha/compose/engine/render/pdf/ecs/PdfStream.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.render.RenderPassSession;

src/main/java/com/demcha/compose/engine/render/pdf/handlers/PdfBarcodeRenderHandler.java → src/main/java/com/demcha/compose/engine/render/pdf/ecs/handlers/PdfBarcodeRenderHandler.java

@@ -1,4 +1,4 @@
-package com.demcha.compose.engine.render.pdf.handlers;
+package com.demcha.compose.engine.render.pdf.ecs.handlers;
 
 import com.demcha.compose.engine.components.content.barcode.BarcodeData;
 import com.demcha.compose.engine.components.content.barcode.BarcodeType;
@@ -7,7 +7,7 @@
 import com.demcha.compose.engine.components.renderable.BarcodeComponent;
 import com.demcha.compose.engine.components.style.Padding;
 import com.demcha.compose.engine.core.EntityManager;
-import com.demcha.compose.engine.render.pdf.PdfRenderingSystemECS;
+import com.demcha.compose.engine.render.pdf.ecs.PdfRenderingSystemECS;
 import com.demcha.compose.engine.render.guides.GuidesRenderer;
 import com.demcha.compose.engine.render.RenderHandler;
 import com.google.zxing.BarcodeFormat;

src/main/java/com/demcha/compose/engine/render/pdf/handlers/PdfBlockTextRenderHandler.java → src/main/java/com/demcha/compose/engine/render/pdf/ecs/handlers/PdfBlockTextRenderHandler.java

@@ -1,4 +1,4 @@
-package com.demcha.compose.engine.render.pdf.handlers;
+package com.demcha.compose.engine.render.pdf.ecs.handlers;
 
 import com.demcha.compose.engine.components.content.text.LineTextData;
 import com.demcha.compose.engine.components.content.text.TextDataBody;
@@ -8,7 +8,7 @@
 import com.demcha.compose.engine.core.EntityManager;
 import com.demcha.compose.engine.render.pdf.GlyphFallbackLogger;
 import com.demcha.compose.engine.render.pdf.PdfFont;
-import com.demcha.compose.engine.render.pdf.PdfRenderingSystemECS;
+import com.demcha.compose.engine.render.pdf.ecs.PdfRenderingSystemECS;
 import com.demcha.compose.engine.render.guides.GuidesRenderer;
 import com.demcha.compose.engine.render.RenderHandler;
 import lombok.extern.slf4j.Slf4j;

src/main/java/com/demcha/compose/engine/render/pdf/handlers/PdfChunkedBlockTextRenderHandler.java → src/main/java/com/demcha/compose/engine/render/pdf/ecs/handlers/PdfChunkedBlockTextRenderHandler.java

@@ -1,4 +1,4 @@
-package com.demcha.compose.engine.render.pdf.handlers;
+package com.demcha.compose.engine.render.pdf.ecs.handlers;
 
 import com.demcha.compose.engine.components.content.text.BlockTextData;
 import com.demcha.compose.engine.components.content.text.LineTextData;
@@ -11,7 +11,7 @@
 import com.demcha.compose.engine.core.EntityManager;
 import com.demcha.compose.engine.exceptions.RenderGuideLinesException;
 import com.demcha.compose.engine.render.pdf.PdfFont;
-import com.demcha.compose.engine.render.pdf.PdfRenderingSystemECS;
+import com.demcha.compose.engine.render.pdf.ecs.PdfRenderingSystemECS;
 import com.demcha.compose.engine.render.guides.GuidesRenderer;
 import com.demcha.compose.engine.render.RenderHandler;
 import lombok.extern.slf4j.Slf4j;

src/main/java/com/demcha/compose/engine/render/pdf/handlers/PdfCircleRenderHandler.java → src/main/java/com/demcha/compose/engine/render/pdf/ecs/handlers/PdfCircleRenderHandler.java

@@ -1,4 +1,4 @@
-package com.demcha.compose.engine.render.pdf.handlers;
+package com.demcha.compose.engine.render.pdf.ecs.handlers;
 
 import com.demcha.compose.engine.components.content.shape.FillColor;
 import com.demcha.compose.engine.components.content.shape.Stroke;
@@ -7,7 +7,7 @@
 import com.demcha.compose.engine.components.renderable.Circle;
 import com.demcha.compose.engine.components.style.Padding;
 import com.demcha.compose.engine.core.EntityManager;
-import com.demcha.compose.engine.render.pdf.PdfRenderingSystemECS;
+import com.demcha.compose.engine.render.pdf.ecs.PdfRenderingSystemECS;
 import com.demcha.compose.engine.render.guides.GuidesRenderer;
 import com.demcha.compose.engine.render.RenderHandler;
 import lombok.extern.slf4j.Slf4j;

src/main/java/com/demcha/compose/engine/render/pdf/handlers/PdfContainerRenderHandler.java → src/main/java/com/demcha/compose/engine/render/pdf/ecs/handlers/PdfContainerRenderHandler.java

@@ -1,9 +1,9 @@
-package com.demcha.compose.engine.render.pdf.handlers;
+package com.demcha.compose.engine.render.pdf.ecs.handlers;
 
 import com.demcha.compose.engine.components.core.Entity;
 import com.demcha.compose.engine.components.renderable.Container;
 import com.demcha.compose.engine.core.EntityManager;
-import com.demcha.compose.engine.render.pdf.PdfRenderingSystemECS;
+import com.demcha.compose.engine.render.pdf.ecs.PdfRenderingSystemECS;
 import com.demcha.compose.engine.render.RenderHandler;
 
 import java.io.IOException;

src/main/java/com/demcha/compose/engine/render/pdf/handlers/PdfElementRenderHandler.java → src/main/java/com/demcha/compose/engine/render/pdf/ecs/handlers/PdfElementRenderHandler.java

@@ -1,9 +1,9 @@
-package com.demcha.compose.engine.render.pdf.handlers;
+package com.demcha.compose.engine.render.pdf.ecs.handlers;
 
 import com.demcha.compose.engine.components.core.Entity;
 import com.demcha.compose.engine.components.renderable.Element;
 import com.demcha.compose.engine.core.EntityManager;
-import com.demcha.compose.engine.render.pdf.PdfRenderingSystemECS;
+import com.demcha.compose.engine.render.pdf.ecs.PdfRenderingSystemECS;
 import com.demcha.compose.engine.render.guides.GuidesRenderer;
 import com.demcha.compose.engine.render.RenderHandler;