diff --git a/CHANGELOG.md b/CHANGELOG.md index 35b33bb27..76df4809d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -117,6 +117,22 @@ 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 — 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`, + `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..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 @@ -1,30 +1,36 @@ /** - * 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 ({@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.

* - *
    - *
  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. - *
+ *

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 package is intentionally split further into subpackages with narrower - * responsibilities:

+ *

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.

* - * - * - *

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 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; 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;