Package Map

This document is the source of truth for production package ownership in the canonical engine branch.

Stability markers. Public packages default to the Stable tier of the API stability policy. Engine packages (com.demcha.compose.engine.*, com.demcha.compose.document.layout, render-pipeline internals) carry the @Internal marker at the package level; individual types deliberately exposed as Extension SPI inside an @Internal package carry @Beta on the type itself (NodeDefinition is the current example). The "Extension rule" column below names the extension seam where one is intended.

Public Authoring Surface

Package	Responsibility	Extension rule
com.demcha.compose	Top-level entrypoint, currently GraphCompose.document(...).	Keep this package tiny; new authoring concepts should live under document.*.
com.demcha.compose.document.api	DocumentSession lifecycle and public session operations.	Add only session-level behavior that belongs to every document.
com.demcha.compose.document.dsl	Developer-friendly DSL facade and focused builders: pageFlow, module, paragraph, list, rows, table, image, divider.	Prefer simple domain words over low-level geometry or renderer terms.
com.demcha.compose.document.node	Canonical semantic nodes such as paragraphs, lists, tables, images, sections, and page breaks.	Nodes describe intent; layout/render mechanics belong in document.layout or engine.*.
com.demcha.compose.document.snapshot	Public renderer-neutral layout snapshot DTOs for deterministic diagnostics and regression tests.	Keep values immutable and backend-neutral.
com.demcha.compose.document.style	Public style values such as document colors, spacing, and text styles.	Keep application-facing style values here; convert to engine values inside DSL/backends.
com.demcha.compose.document.table	Public table authoring values such as columns, cells, and table style overrides.	Keep table authoring ergonomic; row layout and PDF drawing stay internal.
com.demcha.compose.document.backend.fixed.pdf.options	Advanced PDF backend options: metadata, protection, watermark, headers, and footers.	Configure through PdfFixedLayoutBackend.builder(); keep PDFBox implementation behind backend internals.
com.demcha.compose.font	Public font names, built-in families, registration, and showcase helpers.	Add explicit font definitions; do not add render handlers here.

Canonical Layout And Backend

Package	Responsibility	Extension rule
com.demcha.compose.document.layout (@Internal at package level)	Semantic layout compiler, node definitions, fragments, split/measure contracts, and layout graph.	NodeDefinition is @Beta — Extension SPI for custom node types. New node behavior must be deterministic and covered by layout or render tests.
com.demcha.compose.document.backend.fixed	Backend-neutral fixed-layout rendering contract.	Keep it independent from PDFBox and semantic template data.
com.demcha.compose.document.backend.fixed.pdf	Canonical fixed-layout PDF backend, fragment handlers, PDF-specific options, and PDF-backed measurement resources.	Keep PDFBox lifecycle internal; normal callers should use DocumentSession and default PDF convenience methods.
com.demcha.compose.document.dsl.internal	Internal helpers for public DSL builders such as semantic name normalization and builder callback application.	Do not expose these helpers in examples; move reusable authoring concepts to public builder classes instead.
com.demcha.compose.document.backend.semantic	Experimental semantic export contracts for non-fixed outputs.	Keep exporters separate from PDF fixed-layout rendering.
com.demcha.compose.document.debug	Snapshot/debug adapters for canonical layout graph inspection.	Debug output should be deterministic and safe for tests.

Shared Engine Foundation

Package	Responsibility	Extension rule
com.demcha.compose.engine.components.*	Low-level ECS components, content payloads, style values, geometry, layout, and render markers.	Use only for engine primitives; public document authoring should go through DocumentDsl and semantic nodes.
com.demcha.compose.engine.core	Entity manager, canvas, traversal context, and base ECS system contracts.	Keep core thin; put stage-specific logic in layout, pagination, measurement, or render packages.
com.demcha.compose.engine.layout	Low-level entity layout systems.	Preserve deterministic traversal and container sizing semantics.
com.demcha.compose.engine.layout.container	Container alignment, expansion, and module width helpers.	Helpers should operate on existing ECS state and avoid renderer dependencies.
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	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.

Template Layer

Package	Responsibility	Extension rule
com.demcha.compose.document.templates.api	Public template interfaces and registries.	Interfaces compose into DocumentSession; do not add legacy composer overloads.
com.demcha.compose.document.templates.builtins	Thin built-in template facades.	Facades choose the composer/theme and emit lifecycle logs; composition logic belongs in support packages.
com.demcha.compose.document.templates.data.*	Public template specs and domain data models.	Specs should read like domain data, not layout scripts.
com.demcha.compose.document.templates.support.common	Shared template composition primitives, module specs, link helpers, layout policy, and lifecycle logging.	Keep reusable and backend-neutral.
com.demcha.compose.document.templates.support.cv	CV-specific scene composers.	CV layout rules belong here, not in generic business helpers.
com.demcha.compose.document.templates.support.business	Invoice, proposal, and cover-letter scene composers and policies.	Use shared module/render paths and template layout policy.
com.demcha.compose.document.templates.support.schedule	Schedule-specific scene composer.	Keep schedule-specific table/rhythm decisions isolated here.
com.demcha.compose.document.templates.theme	Older shared theme objects for built-ins (e.g. WeeklyScheduleTheme). Distinct from …templates.themes (plural) below.	Themes carry styling decisions, not document content. New v2 token work goes in themes, not here.
com.demcha.compose.document.templates.themes	Templates-v2 theme token records — Spacing, Typography (future Palette). Pure value types, no engine / session dependencies.	One source of truth per token group; keep it dependency-free.
com.demcha.compose.document.templates.components	Templates-v2 reusable composition components shared across families — Header, Module, MarkdownText.	Stateless after construction; produce DocumentNodes. Family-specific components go in <family>.v2.components.
com.demcha.compose.document.templates.blocks	Templates-v2 module-body block kinds — ParagraphBlock, BulletListBlock, NumberedListBlock, IndentedBlock, KeyValueBlock, MultiParagraphBlock, EducationBlock, WorkHistoryBlock.	A block declares what content appears; the renderer expands it per active theme / tokens.
com.demcha.compose.document.templates.decorations	Templates-v2 decoration library — Divider, AccentStrip, Spacer (Panel / Banner / Ornament reserved).	First-class artefacts any preset can attach; not baked into composer logic.
com.demcha.compose.document.templates.widgets	Shared visual widgets usable by every family — CardWidget, TableWidget, TimelineAxisWidget.	Keep generic (no CV-only assumptions) so invoice / proposal / cover-letter can reuse them.
com.demcha.compose.document.templates.tables	Reserved for Templates-v2 reusable table styles (zebra / minimal-grid / borderless / accent-header / financial). Currently package-info.java only — no classes yet (Phase F).	Land table styles here, independent of the data they render.

Preset families. Concrete document families live under …templates.<family> — cv, coverletter, invoice, proposal, schedule. CV and cover letter additionally ship a layered v2 surface (…cv.v2.* / …coverletter.v2.*: data / theme / components / widgets / presets). These per-family packages are documented by the template guides rather than enumerated here — see which-template-system.md for the status matrix and templates/v2-layered/ for the layered architecture.

theme vs themes. The near-identical names are a known rough edge. …templates.theme (singular) is the older shared-theme-object package (built-in WeeklyScheduleTheme); …templates.themes (plural) is the Templates-v2 token-record package (Spacing, Typography). Until the two are consolidated, treat themes (plural) as the home for new v2 token work. The consolidation itself is a planned 2.0 change (it moves public types, so it is binary-incompatible) — tracked in the deprecation inventory.

Policy

• Public authoring starts at GraphCompose.document(...), DocumentSession, and DocumentDsl.
• engine.* is internal foundation; it can be used by tests and low-level tooling, but it is not the recommended app authoring API.
• Fluent low-level entity builders are test-support harnesses only; production code should use semantic nodes and engine model/assembly types instead.
• Do not introduce compatibility aliases for removed package roots.
• Every production package must have package-info.java explaining responsibility, ownership, and extension rules.