Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 8 additions & 6 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`
Expand Down Expand Up @@ -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`.
Expand Down
6 changes: 3 additions & 3 deletions docs/adr/0004-pdf-handler-spi-extension.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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:
Expand Down
2 changes: 1 addition & 1 deletion docs/api-stability.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
12 changes: 8 additions & 4 deletions docs/architecture/overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
8 changes: 4 additions & 4 deletions docs/contributing/implementation-guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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`

Expand Down
3 changes: 2 additions & 1 deletion docs/migration/v1.8.0-fonts.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
<dependency>
Expand Down
2 changes: 1 addition & 1 deletion docs/templates/v1-classic/authoring.md
Original file line number Diff line number Diff line change
Expand Up @@ -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) |
4 changes: 2 additions & 2 deletions docs/templates/v2-layered/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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**:
Expand Down
2 changes: 1 addition & 1 deletion docs/templates/v2-layered/authoring-presets.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
2 changes: 1 addition & 1 deletion docs/templates/v2-layered/contributor-guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -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/
Expand Down
2 changes: 1 addition & 1 deletion docs/templates/v2-layered/quickstart.md
Original file line number Diff line number Diff line change
Expand Up @@ -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) |
4 changes: 2 additions & 2 deletions docs/templates/v2-layered/using-templates.md
Original file line number Diff line number Diff line change
Expand Up @@ -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).

---

Expand Down Expand Up @@ -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)