diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0744a53fe..6a5d917cc 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -89,12 +89,14 @@ See [docs/contributing/release-process.md](./docs/contributing/release-process.m Public canonical authoring surface — `DocumentSession`, the DSL builders, semantic node records, public style values, table types, image types, backend-neutral output options (metadata / watermark / protection / header-footer), and snapshot DTOs - `src/main/java/com/demcha/compose/document/layout` Canonical functional layout pipeline: `LayoutCompiler`, `BuiltInNodeDefinitions`, `TableLayoutSupport`, `PreparedNode`, `PlacedFragment` -- `src/main/java/com/demcha/compose/document/backend/fixed/pdf` - PDF backend: `PdfFixedLayoutBackend`, fragment handlers, the option translators that bridge canonical types to PDFBox, and `FontShowcase` (bundled-font preview renderer) -- `src/main/java/com/demcha/compose/document/backend/semantic` - Semantic exporters: `DocxSemanticBackend` (Apache POI based), `PptxSemanticBackend` (manifest skeleton) -- `src/main/java/com/demcha/compose/document/templates/*` +- `render-pdf/src/main/java/com/demcha/compose/document/backend/fixed/pdf` — module **graph-compose-render-pdf** + PDF backend: `PdfFixedLayoutBackend`, fragment handlers, and the option translators that bridge canonical types to PDFBox +- `render-docx/` and `render-pptx/` — modules **graph-compose-render-docx** / **graph-compose-render-pptx** + Semantic exporters `DocxSemanticBackend` (Apache POI based) and `PptxSemanticBackend` (manifest skeleton), under `com.demcha.compose.document.backend.semantic.{docx,pptx}` +- `templates/src/main/java/com/demcha/compose/document/templates/*` — module **graph-compose-templates** Built-in templates (CV, cover letter, invoice, proposal, weekly schedule), DTOs, themes, registries, and scene composition helpers +- `src/main/java/com/demcha/compose/document/showcase` + `FontShowcase` (bundled-font preview renderer) — stays in the core engine - `src/main/java/com/demcha/compose/engine/*` Internal shared engine foundation under the canonical surface (measure, paginate, place, render). Not part of the recommended public API - `src/main/java/com/demcha/compose/font` @@ -170,7 +172,7 @@ not need any of them. `engine/components`. - 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/`. + `render-pdf/src/main/java/com/demcha/compose/engine/render/pdf/ecs/handlers/`. Backend-only helper objects live in `com.demcha.compose.engine.render.pdf.ecs.helpers`, not in `components/renderable`. diff --git a/docs/adr/0004-pdf-handler-spi-extension.md b/docs/adr/0004-pdf-handler-spi-extension.md index 9ca8b9524..14d1ce12f 100644 --- a/docs/adr/0004-pdf-handler-spi-extension.md +++ b/docs/adr/0004-pdf-handler-spi-extension.md @@ -45,7 +45,7 @@ Concretely: Javadoc is rewritten to declare it a public extension point with stateless invariant. The "package-private" wording is gone. 2. A new method - [`PdfFixedLayoutBackend.Builder#addHandler(PdfFragmentRenderHandler)`](../../src/main/java/com/demcha/compose/document/backend/fixed/pdf/PdfFixedLayoutBackend.java) + [`PdfFixedLayoutBackend.Builder#addHandler(PdfFragmentRenderHandler)`](../../render-pdf/src/main/java/com/demcha/compose/document/backend/fixed/pdf/PdfFixedLayoutBackend.java) accepts a custom handler. It is additive: omitting it reproduces the existing default-handler set. Calling it with a payload type already covered by a default replaces the default for the resulting backend @@ -62,10 +62,10 @@ Concretely: ## Coverage -- [`PdfFragmentRenderHandler`](../../src/main/java/com/demcha/compose/document/backend/fixed/pdf/PdfFragmentRenderHandler.java) +- [`PdfFragmentRenderHandler`](../../render-pdf/src/main/java/com/demcha/compose/document/backend/fixed/pdf/PdfFragmentRenderHandler.java) Javadoc names `Builder.addHandler(...)` as the registration path and states the stateless invariant explicitly. -- [`PdfFixedLayoutBackend.Builder#addHandler`](../../src/main/java/com/demcha/compose/document/backend/fixed/pdf/PdfFixedLayoutBackend.java) +- [`PdfFixedLayoutBackend.Builder#addHandler`](../../render-pdf/src/main/java/com/demcha/compose/document/backend/fixed/pdf/PdfFixedLayoutBackend.java) is the new entry point. - [`PdfBackendExtensibilityTest`](../../src/test/java/com/demcha/compose/document/backend/fixed/pdf/PdfBackendExtensibilityTest.java) pins three behaviours: diff --git a/docs/api-stability.md b/docs/api-stability.md index ab6bc2dbf..6460e2805 100644 --- a/docs/api-stability.md +++ b/docs/api-stability.md @@ -64,7 +64,7 @@ are: - [`ChartSize`](../src/main/java/com/demcha/compose/document/chart/ChartSize.java) (Stable) - [`ChartSpec`](../src/main/java/com/demcha/compose/document/chart/ChartSpec.java) (Stable) -- [`CvSection`](../src/main/java/com/demcha/compose/document/templates/cv/data/CvSection.java) (Stable) +- [`CvSection`](../templates/src/main/java/com/demcha/compose/document/templates/cv/data/CvSection.java) (Stable) - [`DocumentLinkTarget`](../src/main/java/com/demcha/compose/document/node/DocumentLinkTarget.java) (Stable) - [`DocumentPaint`](../src/main/java/com/demcha/compose/document/style/DocumentPaint.java) (Stable) - [`DocumentPathSegment`](../src/main/java/com/demcha/compose/document/style/DocumentPathSegment.java) (Stable) diff --git a/docs/architecture/overview.md b/docs/architecture/overview.md index a30d2031b..97742958a 100644 --- a/docs/architecture/overview.md +++ b/docs/architecture/overview.md @@ -250,13 +250,17 @@ Canonical-first ordering — public roots come first, internal foundation last: - `com.demcha.compose.document.*` — **public canonical surface**. - Authoring API, layout graph, backends, exceptions, snapshots, and - built-in templates. + Authoring API, layout graph, exceptions, snapshots. The render backends + (`document.backend.fixed.pdf` in **graph-compose-render-pdf**, + `document.backend.semantic.*` in the docx / pptx modules) and the built-in + templates (`document.templates.*` in **graph-compose-templates**) share this + namespace but ship as separate, opt-in artifacts over `graph-compose-core`. - `com.demcha.compose.font.*` — public font names, backend-neutral family descriptors, registration, lookup, and showcase helpers. - `com.demcha.compose.engine.*` — **internal engine foundation**. - Measurement, layout resolution, pagination, render-pass session, and - PDF rendering systems. + Measurement, layout resolution, pagination, and render-pass session in + `graph-compose-core`; the PDF rendering systems (`engine.render.pdf.*`) ship + in **graph-compose-render-pdf**. - `com.demcha.compose.engine.text.*` — internal text utilities used by layout and render hot paths. - `com.demcha.compose.engine.text.markdown.*` — internal diff --git a/docs/contributing/implementation-guide.md b/docs/contributing/implementation-guide.md index 53130370a..2d9119677 100644 --- a/docs/contributing/implementation-guide.md +++ b/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/ecs/helpers/TableCellBox.java) +- [TableCellBox.java](../../render-pdf/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: @@ -334,8 +334,8 @@ 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/ecs/PdfRenderingSystemECS.java) -- [PdfRenderSession.java](../../src/main/java/com/demcha/compose/engine/render/pdf/ecs/PdfRenderSession.java) +- [PdfRenderingSystemECS.java](../../render-pdf/src/main/java/com/demcha/compose/engine/render/pdf/ecs/PdfRenderingSystemECS.java) +- [PdfRenderSession.java](../../render-pdf/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: @@ -448,7 +448,7 @@ Do not add a method there if the new object is only an internal helper for templ - container: [ModuleBuilder.java](../../src/test/java/com/demcha/compose/testsupport/engine/assembly/ModuleBuilder.java) - template-level composition helper: - [SectionDispatcher.java](../../src/main/java/com/demcha/compose/document/templates/cv/components/SectionDispatcher.java) + [SectionDispatcher.java](../../templates/src/main/java/com/demcha/compose/document/templates/cv/components/SectionDispatcher.java) ## Overlay primitive: `LayerStackNode` diff --git a/docs/migration/v1.8.0-fonts.md b/docs/migration/v1.8.0-fonts.md index f6903bc2d..6f6c36f74 100644 --- a/docs/migration/v1.8.0-fonts.md +++ b/docs/migration/v1.8.0-fonts.md @@ -61,7 +61,8 @@ version, and vice-versa. ### Option B — one coordinate, batteries included -Depend on the bundle, which pulls a compatible engine + fonts pair: +Depend on the bundle, which pulls a compatible batteries-included set — the +default PDF engine, the built-in templates, the fonts, and the colour emoji: ```xml diff --git a/docs/templates/v1-classic/authoring.md b/docs/templates/v1-classic/authoring.md index a5255b45f..23eeed76c 100644 --- a/docs/templates/v1-classic/authoring.md +++ b/docs/templates/v1-classic/authoring.md @@ -436,5 +436,5 @@ and | Snapshot-based regression workflow | [`recipes/extending.md` § 4](../../recipes/extending.md#4-validate-a-custom-nodes-layout-via-snapshots) | | Migrating from v1.4 to v1.5 | [`migration-v1-4-to-v1-5.md`](../../roadmaps/migration-v1-4-to-v1-5.md) | | Architecture decision records | [`adr/`](../../adr/) | -| Reference V2 templates | [`InvoiceTemplateV2`](../../../src/main/java/com/demcha/compose/document/templates/builtins/InvoiceTemplateV2.java), [`ProposalTemplateV2`](../../../src/main/java/com/demcha/compose/document/templates/builtins/ProposalTemplateV2.java) | +| Reference templates | [`ModernInvoice`](../../../templates/src/main/java/com/demcha/compose/document/templates/invoice/presets/ModernInvoice.java), [`ModernProposal`](../../../templates/src/main/java/com/demcha/compose/document/templates/proposal/presets/ModernProposal.java) | | Hand-built theme example | [`CustomBusinessThemeExample`](../../../examples/src/main/java/com/demcha/examples/features/themes/CustomBusinessThemeExample.java) | diff --git a/docs/templates/v2-layered/README.md b/docs/templates/v2-layered/README.md index 0c273abe3..290e1d8b6 100644 --- a/docs/templates/v2-layered/README.md +++ b/docs/templates/v2-layered/README.md @@ -113,10 +113,10 @@ The detailed contract for each layer is in ## See also - **Per-package JavaDocs**: - [`cv/package-info.java`](../../../src/main/java/com/demcha/compose/document/templates/cv/package-info.java) + [`cv/package-info.java`](../../../templates/src/main/java/com/demcha/compose/document/templates/cv/package-info.java) has the ASCII diagram and 4-step author walkthrough. - **AUTHORS.md**: - [`cv/AUTHORS.md`](../../../src/main/java/com/demcha/compose/document/templates/cv/AUTHORS.md) + [`cv/AUTHORS.md`](../../../templates/src/main/java/com/demcha/compose/document/templates/cv/AUTHORS.md) is the recipe cookbook — 7 hands-on recipes from "change a bullet glyph" to "add a new section subtype". - **Examples**: diff --git a/docs/templates/v2-layered/authoring-presets.md b/docs/templates/v2-layered/authoring-presets.md index 4b9e3f3b1..1d2e234f1 100644 --- a/docs/templates/v2-layered/authoring-presets.md +++ b/docs/templates/v2-layered/authoring-presets.md @@ -412,4 +412,4 @@ cover-letter-v2) following the same layered shape? → The full recipe cookbook (with code for every customisation combo): -[`cv/AUTHORS.md`](../../../src/main/java/com/demcha/compose/document/templates/cv/AUTHORS.md) +[`cv/AUTHORS.md`](../../../templates/src/main/java/com/demcha/compose/document/templates/cv/AUTHORS.md) diff --git a/docs/templates/v2-layered/contributor-guide.md b/docs/templates/v2-layered/contributor-guide.md index 4de4d60b3..ee4c662ef 100644 --- a/docs/templates/v2-layered/contributor-guide.md +++ b/docs/templates/v2-layered/contributor-guide.md @@ -64,7 +64,7 @@ data differs; the *layering* is identical. Mirror the CV v2 layout. Concrete example for invoice: ``` -src/main/java/com/demcha/compose/document/templates/invoice/ +templates/src/main/java/com/demcha/compose/document/templates/invoice/ ├── package-info.java ← ASCII diagram + 4-step walkthrough ├── AUTHORS.md ← recipe cookbook ├── data/ diff --git a/docs/templates/v2-layered/quickstart.md b/docs/templates/v2-layered/quickstart.md index f535564dd..21251b55c 100644 --- a/docs/templates/v2-layered/quickstart.md +++ b/docs/templates/v2-layered/quickstart.md @@ -150,5 +150,5 @@ touch a renderer. A new widget doesn't touch the data model. | Render your own CV with your data | [using-templates.md](using-templates.md) | | Make a new visual style | [authoring-presets.md](authoring-presets.md) | | Add a new template family to the library (invoice, cover-letter) | [contributor-guide.md](contributor-guide.md) | -| See hands-on recipes (change a bullet, swap colours, …) | [`cv/AUTHORS.md`](../../../src/main/java/com/demcha/compose/document/templates/cv/AUTHORS.md) | +| See hands-on recipes (change a bullet, swap colours, …) | [`cv/AUTHORS.md`](../../../templates/src/main/java/com/demcha/compose/document/templates/cv/AUTHORS.md) | | Run the shipped examples | [`examples/cv/v2/`](../../examples/src/main/java/com/demcha/examples/templates/cv/v2) | diff --git a/docs/templates/v2-layered/using-templates.md b/docs/templates/v2-layered/using-templates.md index 0f24d3d01..bcfaf31fd 100644 --- a/docs/templates/v2-layered/using-templates.md +++ b/docs/templates/v2-layered/using-templates.md @@ -291,7 +291,7 @@ BrandTheme theme = new BrandTheme( ``` For more recipes (compact spacing, alternative typography scales, -etc.) see [`cv/AUTHORS.md`](../../../src/main/java/com/demcha/compose/document/templates/cv/AUTHORS.md). +etc.) see [`cv/AUTHORS.md`](../../../templates/src/main/java/com/demcha/compose/document/templates/cv/AUTHORS.md). --- @@ -391,4 +391,4 @@ No GitHub, no Projects, no Tech Skills — and the API doesn't notice. [**authoring-presets.md**](authoring-presets.md) → Reference for every recipe (change bullet, swap colours, …) -[`cv/AUTHORS.md`](../../../src/main/java/com/demcha/compose/document/templates/cv/AUTHORS.md) +[`cv/AUTHORS.md`](../../../templates/src/main/java/com/demcha/compose/document/templates/cv/AUTHORS.md)