From 6e4db21c857a375871393a61d2878b73c7604752 Mon Sep 17 00:00:00 2001 From: DemchaAV Date: Tue, 9 Jun 2026 11:16:53 +0100 Subject: [PATCH 1/2] chore(engine): deprecate the legacy ECS engine packages engine.core, engine.layout (+ container), and engine.pagination are the original Entity-based layout/pagination engine -- a parallel second engine that no public API reaches (the canonical GraphCompose.document() pipeline imports nothing from them, and GraphCompose.pdf(...) was already removed). They survive only to back the legacy engine regression tests. Mark the three packages @Deprecated at package level (no deprecation-warning cascade) and rewrite their misleading 'shared' / 'normal PDF pipeline' docs to point at the canonical com.demcha.compose.document.layout pipeline, so contributors stop optimizing a dead engine. The genuinely shared engine packages (engine.components / measurement / font / render) are NOT deprecated. No runtime or behaviour change; binary-compatible (japicmp green). --- CHANGELOG.md | 13 ++++++ .../compose/engine/core/package-info.java | 46 +++++++++---------- .../engine/layout/container/package-info.java | 15 ++++-- .../compose/engine/layout/package-info.java | 18 ++++++-- .../engine/pagination/package-info.java | 34 ++++++-------- 5 files changed, 74 insertions(+), 52 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 35b33bb27..8c4e48ca1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -117,6 +117,19 @@ Open cycle — bug-fix / housekeeping. Entries land here as they merge. resolved by the layout compiler. The method is kept for binary compatibility and scheduled for removal in the next major. +- **The legacy ECS engine packages are deprecated.** `com.demcha.compose.engine.core`, + `engine.layout` (and `engine.layout.container`), and `engine.pagination` are the + original `Entity`-based layout/pagination engine. They are a parallel second + engine that no public API reaches — the canonical pipeline + (`GraphCompose.document() → DocumentSession → LayoutCompiler`) imports nothing + from them, and the former `GraphCompose.pdf(...)` entry point has already been + removed. They survive only to back 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. + ### Tests / tooling - **Benchmark regression gate and measurement probe (benchmarks module, not part diff --git a/src/main/java/com/demcha/compose/engine/core/package-info.java b/src/main/java/com/demcha/compose/engine/core/package-info.java index 246b7a605..9c9c84dfe 100644 --- a/src/main/java/com/demcha/compose/engine/core/package-info.java +++ b/src/main/java/com/demcha/compose/engine/core/package-info.java @@ -1,30 +1,28 @@ /** - * Core ECS primitives that hold entity/component graphs and shared traversal - * state. + * Core primitives of the legacy ECS engine — entity/component + * graphs and shared traversal state for the original {@code Entity}-based + * layout / pagination / render pipeline. * - *

This package contains the foundation used by the runtime pipeline. In the - * normal PDF pipeline the high-level flow is:

+ *

This is not the engine behind the public API. The canonical + * pipeline is {@code GraphCompose.document() -> DocumentSession -> + * LayoutCompiler -> LayoutGraph -> PdfFixedLayoutBackend} in + * {@code com.demcha.compose.document.*}, and it imports nothing from this + * package. The ECS stack ({@code engine.core}, {@code engine.layout}, + * {@code engine.pagination}) is a parallel second engine that no public entry + * point reaches — the former {@code GraphCompose.pdf(...)} surface has been + * removed — and it survives only to back the legacy engine regression tests.

* - *
    - *
  1. builders populate {@code Entity} graphs and attach components
    2. - *
  2. {@code LayoutSystem} resolves geometry, hierarchy depth, and layer order
    3. - *
  3. {@code PageBreaker} assigns final page-aware {@code Placement}
    4. - *
  4. a backend renderer such as {@code PdfRenderingSystemECS} consumes the resolved entities
    5. - *
+ *

The genuinely shared engine packages are elsewhere and are not + * deprecated: {@code engine.components} (value types), {@code engine.measurement} + * (text-measurement contracts), {@code engine.font}, and + * {@code engine.render} (backend-neutral render-pass contracts) are all used by + * the canonical pipeline.

* - *

The package is intentionally split further into subpackages with narrower - * responsibilities:

- * - * - * - *

Project policy is to keep backend-specific lifecycle concerns out of the - * shared engine layer wherever possible. The engine should reason in terms of - * resolved geometry, entity ordering, and render-session seams, while PDFBox, - * DOCX, or PPTX specifics stay in backend-owned packages.

+ * @deprecated Legacy ECS engine, superseded by the canonical + * {@code com.demcha.compose.document.layout} pipeline. No public API reaches + * it, it is not on the canonical hot path, and it is retained only for the + * legacy engine regression tests — a candidate for removal once those are + * retired. Do not extend it or spend optimization effort here. */ +@Deprecated package com.demcha.compose.engine.core; diff --git a/src/main/java/com/demcha/compose/engine/layout/container/package-info.java b/src/main/java/com/demcha/compose/engine/layout/container/package-info.java index ce431206b..a5f8b923f 100644 --- a/src/main/java/com/demcha/compose/engine/layout/container/package-info.java +++ b/src/main/java/com/demcha/compose/engine/layout/container/package-info.java @@ -1,7 +1,14 @@ /** - * Internal container layout helpers for alignment, expansion, and module width resolution. + * Container layout helpers (alignment, expansion, module-width resolution) of + * the legacy ECS engine. * - *

Ownership: Owned by the shared engine layout pipeline.

- *

Extension rules: Extend with deterministic helpers that operate on existing components and traversal snapshots.

+ *

Part of the parallel legacy {@code Entity}-based engine; the canonical + * {@code com.demcha.compose.document.layout} pipeline does not use it.

+ * + * @deprecated Legacy ECS engine, superseded by the canonical + * {@code com.demcha.compose.document.layout} pipeline. Not reachable from + * any public API; retained only for legacy regression tests and a candidate + * for removal. Do not extend it or spend optimization effort here. */ -package com.demcha.compose.engine.layout.container; \ No newline at end of file +@Deprecated +package com.demcha.compose.engine.layout.container; diff --git a/src/main/java/com/demcha/compose/engine/layout/package-info.java b/src/main/java/com/demcha/compose/engine/layout/package-info.java index 87ffd83af..7554ebfa6 100644 --- a/src/main/java/com/demcha/compose/engine/layout/package-info.java +++ b/src/main/java/com/demcha/compose/engine/layout/package-info.java @@ -1,7 +1,17 @@ /** - * Shared layout systems that turn low-level entities into resolved geometry. + * Layout systems of the legacy ECS engine — they turn + * low-level {@code Entity} graphs into resolved geometry for the original + * {@code Entity}-based pipeline. * - *

Ownership: Owned by the shared engine layout pipeline.

- *

Extension rules: New layout behavior must preserve deterministic traversal and be covered by layout snapshot tests.

+ *

Despite the former "shared" framing, the canonical pipeline + * ({@code com.demcha.compose.document.layout.LayoutCompiler}) imports nothing + * from this package. It is part of the parallel legacy ECS engine reachable + * only from the legacy engine regression tests.

+ * + * @deprecated Legacy ECS engine, superseded by the canonical + * {@code com.demcha.compose.document.layout} pipeline. Not reachable from + * any public API; retained only for legacy regression tests and a candidate + * for removal. Do not extend it or spend optimization effort here. */ -package com.demcha.compose.engine.layout; \ No newline at end of file +@Deprecated +package com.demcha.compose.engine.layout; diff --git a/src/main/java/com/demcha/compose/engine/pagination/package-info.java b/src/main/java/com/demcha/compose/engine/pagination/package-info.java index 6604a5bdf..9f2097079 100644 --- a/src/main/java/com/demcha/compose/engine/pagination/package-info.java +++ b/src/main/java/com/demcha/compose/engine/pagination/package-info.java @@ -1,25 +1,19 @@ /** - * Pagination and page-placement helpers for resolved GraphCompose entities. + * Pagination and page-placement helpers of the legacy ECS engine. * - *

This package owns the logic that runs after layout has produced - * {@code ComputedPosition} and size metadata but before the renderer writes the - * final document. Its responsibilities include:

+ *

This package paginates the resolved {@code Entity} graph for the original + * {@code Entity}-based pipeline ({@code PageBreaker} for the pagination walk, + * {@code PageLayoutCalculator} for page-coordinate math, {@code TextBlockProcessor} + * for block-text fragmentation, {@code ParentContainerUpdater} for upward + * size/position propagation). It is renderer-neutral, but it is part of the + * parallel legacy ECS engine: the canonical pipeline + * ({@code com.demcha.compose.document.layout}) does its own pagination and + * imports nothing here.

* - * - * - *

The package is intentionally renderer-neutral. It does not open PDF - * streams, create pages directly, or decide backend drawing policy. Instead it - * mutates the entity graph so later renderers can consume one deterministic, - * page-aware layout result.

- * - *

Key classes in this package are {@code PageBreaker} for the pass-level - * pagination walk, {@code PageLayoutCalculator} for page-coordinate math, - * {@code TextBlockProcessor} for block-text fragmentation, and - * {@code ParentContainerUpdater} for upward size/position propagation.

+ * @deprecated Legacy ECS engine, superseded by the canonical + * {@code com.demcha.compose.document.layout} pipeline. Not reachable from + * any public API; retained only for legacy regression tests and a candidate + * for removal. Do not extend it or spend optimization effort here. */ +@Deprecated package com.demcha.compose.engine.pagination; From b213edca310d23c8258d627a0875f26a01c6d459 Mon Sep 17 00:00:00 2001 From: DemchaAV Date: Tue, 9 Jun 2026 11:35:51 +0100 Subject: [PATCH 2/2] docs(engine): correct engine.core isolation claim (review fix) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit PR review of #148 found the engine.core package doc overstated isolation: the canonical TextMeasurementSystem still extends engine.core.SystemECS with a no-op process(EntityManager), so SystemECS/EntityManager are referenced from live code — they do not 'survive only to back the legacy engine regression tests'. Reword the package-info and CHANGELOG to say the ECS *execution* engine is dead while noting the vestigial SystemECS base as a tracked decoupling follow-up. engine.layout/pagination docs were already accurate. Docs-only. --- CHANGELOG.md | 13 ++++---- .../compose/engine/core/package-info.java | 30 ++++++++++++------- 2 files changed, 27 insertions(+), 16 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 8c4e48ca1..76df4809d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -119,11 +119,14 @@ Open cycle — bug-fix / housekeeping. Entries land here as they merge. - **The legacy ECS engine packages are deprecated.** `com.demcha.compose.engine.core`, `engine.layout` (and `engine.layout.container`), and `engine.pagination` are the - original `Entity`-based layout/pagination engine. They are a parallel second - engine that no public API reaches — the canonical pipeline - (`GraphCompose.document() → DocumentSession → LayoutCompiler`) imports nothing - from them, and the former `GraphCompose.pdf(...)` entry point has already been - removed. They survive only to back the legacy engine regression tests. The + original `Entity`-based layout/pagination engine — a parallel second engine + whose execution path the canonical pipeline + (`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) with corrected package docs, to stop misdirecting contributors into optimizing a dead engine. The genuinely shared engine packages (`engine.components`, diff --git a/src/main/java/com/demcha/compose/engine/core/package-info.java b/src/main/java/com/demcha/compose/engine/core/package-info.java index 9c9c84dfe..80c4fb4fa 100644 --- a/src/main/java/com/demcha/compose/engine/core/package-info.java +++ b/src/main/java/com/demcha/compose/engine/core/package-info.java @@ -4,13 +4,20 @@ * layout / pagination / render pipeline. * *

This is not the engine behind the public API. The canonical - * pipeline is {@code GraphCompose.document() -> DocumentSession -> - * LayoutCompiler -> LayoutGraph -> PdfFixedLayoutBackend} in - * {@code com.demcha.compose.document.*}, and it imports nothing from this - * package. The ECS stack ({@code engine.core}, {@code engine.layout}, - * {@code engine.pagination}) is a parallel second engine that no public entry - * point reaches — the former {@code GraphCompose.pdf(...)} surface has been - * removed — and it survives only to back the legacy engine regression tests.

+ * pipeline ({@code GraphCompose.document() -> DocumentSession -> LayoutCompiler + * -> LayoutGraph -> PdfFixedLayoutBackend}) in {@code com.demcha.compose.document.*} + * imports nothing from this package directly, and the former + * {@code GraphCompose.pdf(...)} surface that drove the ECS has been removed. The + * ECS execution engine — the {@code EntityManager.processSystems()} loop + * and the layout / pagination / render systems it drives — is dead: it runs only + * under the legacy engine regression tests.

+ * + *

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.

* *

The genuinely shared engine packages are elsewhere and are not * deprecated: {@code engine.components} (value types), {@code engine.measurement} @@ -19,10 +26,11 @@ * the canonical pipeline.

* * @deprecated Legacy ECS engine, superseded by the canonical - * {@code com.demcha.compose.document.layout} pipeline. No public API reaches - * it, it is not on the canonical hot path, and it is retained only for the - * legacy engine regression tests — a candidate for removal once those are - * retired. Do not extend it or spend optimization effort here. + * {@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. */ @Deprecated package com.demcha.compose.engine.core;