Merge remote-tracking branch 'origin/develop' into refactor/font-vertical-metrics-contract

# Conflicts:
#	CHANGELOG.md

Author: DemchaAV

CHANGELOG.md

@@ -124,15 +124,44 @@ Open cycle — bug-fix / housekeeping. Entries land here as they merge.
   (`GraphCompose.document() → DocumentSession → LayoutCompiler`) never runs; it
   imports nothing from them directly, and the former `GraphCompose.pdf(...)`
   entry point has already been removed. The ECS execution engine runs only under
-  the legacy engine regression tests. (One vestigial coupling remains, tracked as
-  a follow-up: the canonical `TextMeasurementSystem` still `extends
-  engine.core.SystemECS` via a no-op `process(...)`.) The
-  packages are now `@Deprecated` (package level, so no deprecation-warning cascade)
+  the legacy engine regression tests. The packages are now `@Deprecated` (package
+  level, so no deprecation-warning cascade)
   with corrected package docs, to stop misdirecting contributors into optimizing a
   dead engine. The genuinely shared engine packages (`engine.components`,
   `engine.measurement`, `engine.font`, `engine.render`) are **not** deprecated.
   No public API or behaviour change.
 
+- **`TextMeasurementSystem` decoupled from `engine.core.SystemECS`.** The shared
+  text-measurement contract (`engine.measurement.TextMeasurementSystem`) dropped
+  its vestigial `extends SystemECS` and the no-op `process(EntityManager)` default
+  it carried — it was never consumed as an ECS system. The legacy ECS engine now
+  obtains the measurement service via `SystemRegistry.registerTextMeasurement(...)`
+  / `textMeasurement()` instead of enrolling it as a `process()`-driven system,
+  completing the isolation of the deprecated `engine.core` from live and shared
+  code (only the legacy engine regression tests still reference it). Dropping the
+  super-interface is binary-incompatible on paper, so
+  `engine.measurement.TextMeasurementSystem` is excluded from the japicmp gate
+  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.
+
 ### Internal
 
 - **Text-measurement line metrics resolve through the `Font` contract instead of a

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,42 @@
                                 -->
                                 <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)
+                                        default) — see CHANGELOG v1.7.1. japicmp reports this as
+                                        INTERFACE_REMOVED, but it is safe: nothing consumes a
+                                        TextMeasurementSystem as a SystemECS. The legacy ECS engine now
+                                        obtains the measurement service via
+                                        SystemRegistry.registerTextMeasurement(...) / textMeasurement()
+                                        instead of enrolling it as a process()-driven system, and the
+                                        canonical pipeline injects it directly. Drop this exclude once the
+                                        japicmp baseline advances to the release that lands the change.
+                                    -->
+                                    <exclude>com.demcha.compose.engine.measurement.TextMeasurementSystem</exclude>
                                 </excludes>
                             </parameter>
                         </configuration>

src/main/java/com/demcha/compose/engine/components/content/text/BlockTextLineMetrics.java

@@ -143,7 +143,7 @@ public static double interLineGap(TextMeasurementSystem.LineMetrics previous,
 
     private static TextMeasurementSystem measurementSystem(EntityManager entityManager) {
         return entityManager.getSystems()
-                .getSystem(TextMeasurementSystem.class)
+                .textMeasurement()
                 .orElseThrow(() -> new IllegalStateException("TextMeasurementSystem is required to resolve block text metrics."));
     }
 }

src/main/java/com/demcha/compose/engine/components/renderable/TextComponent.java

@@ -24,7 +24,7 @@ public static ContentSize autoMeasureText(Entity entity, EntityManager entityMan
         Text text = entity.getComponent(Text.class).orElseThrow();
         TextStyle style = entity.getComponent(TextStyle.class).orElseThrow();
         TextMeasurementSystem measurementSystem = entityManager.getSystems()
-                .getSystem(TextMeasurementSystem.class)
+                .textMeasurement()
                 .orElseThrow(() -> new IllegalStateException("TextMeasurementSystem is required to auto-measure text."));
         ContentSize measured = measurementSystem.measure(style, text.value());
         double width = measured.width();

src/main/java/com/demcha/compose/engine/core/SystemRegistry.java

@@ -1,6 +1,8 @@
 package com.demcha.compose.engine.core;
 
 import com.demcha.compose.engine.core.SystemECS;
+import com.demcha.compose.engine.measurement.TextMeasurementSystem;
+import lombok.AccessLevel;
 import lombok.Getter;
 import lombok.experimental.Accessors;
 import lombok.extern.slf4j.Slf4j;
@@ -23,6 +25,41 @@ public class SystemRegistry {
      */
     private final Map<Class<? extends SystemECS>, SystemECS> systems = new LinkedHashMap<>();
 
+    /**
+     * The text-measurement service provider, held separately from the
+     * process()-driven {@link #systems} map. Measurement exposes font metrics to
+     * builders and layout helpers on demand; it is not a {@link SystemECS} and
+     * never participates in the {@code processSystems()} loop, so it is registered
+     * out-of-band via {@link #registerTextMeasurement(TextMeasurementSystem)}
+     * rather than {@link #addSystem(SystemECS)}.
+     */
+    @Getter(AccessLevel.NONE)
+    private TextMeasurementSystem textMeasurement;
+
+    /**
+     * Registers the text-measurement service exposed to the legacy engine's text
+     * components and layout alignment. Unlike {@link #addSystem(SystemECS)} this
+     * does not enroll the measurement system in the {@code process()} loop — it is
+     * a service provider, not an ECS system.
+     *
+     * @param textMeasurement the measurement service to expose
+     * @since 1.7.1
+     */
+    public void registerTextMeasurement(TextMeasurementSystem textMeasurement) {
+        this.textMeasurement = Objects.requireNonNull(textMeasurement, "textMeasurement");
+    }
+
+    /**
+     * Retrieves the registered text-measurement service, if any.
+     *
+     * @return an Optional containing the measurement service, or empty if none has
+     *     been registered
+     * @since 1.7.1
+     */
+    public Optional<TextMeasurementSystem> textMeasurement() {
+        return Optional.ofNullable(textMeasurement);
+    }
+
     /**
      * Adds a single system to the registry.
      *

src/main/java/com/demcha/compose/engine/core/package-info.java

@@ -12,13 +12,6 @@
  * and the layout / pagination / render systems it drives — is dead: it runs only
  * under the legacy engine regression tests.</p>
  *
- * <p>One vestigial holdover keeps {@code SystemECS} and {@code EntityManager}
- * referenced from live code: the canonical
- * {@code engine.measurement.TextMeasurementSystem} still
- * {@code extends SystemECS} with a no-op {@code process(EntityManager)}.
- * Decoupling that base — so {@code engine.core} becomes genuinely unreferenced by
- * the canonical pipeline — is a tracked follow-up.</p>
- *
  * <p>The genuinely shared engine packages are elsewhere and are <em>not</em>
  * deprecated: {@code engine.components} (value types), {@code engine.measurement}
  * (text-measurement contracts), {@code engine.font}, and
@@ -28,9 +21,8 @@
  * @deprecated Legacy ECS engine, superseded by the canonical
  *     {@code com.demcha.compose.document.layout} pipeline. No public entry point
  *     runs it and it is not on the canonical hot path; it is retained only for the
- *     legacy engine regression tests (aside from the vestigial {@code SystemECS}
- *     base of {@code TextMeasurementSystem}, a tracked cleanup) — a candidate for
- *     removal. Do not extend it or spend optimization effort here.
+ *     legacy engine regression tests — a candidate for removal. Do not extend it or
+ *     spend optimization effort here.
  */
 @Deprecated
 package com.demcha.compose.engine.core;