DemchaAV · DemchaAV · Jul 6, 2026 · Jul 6, 2026
@@ -336,14 +336,12 @@ Choose the smallest tests that match the change:
 - For engine/backend boundary changes:
   [EnginePdfBoundaryTest.java](./src/test/java/com/demcha/compose/engine/architecture/EnginePdfBoundaryTest.java)
   [PdfRenderInterfaceGuardTest.java](render-pdf/src/test/java/com/demcha/compose/engine/render/pdf/PdfRenderInterfaceGuardTest.java)
-- For low-level test harness changes:
-  [ComponentBuilderTest.java](qa/src/test/java/com/demcha/compose/engine/components/ComponentBuilderTest.java)
 - For PDF fragment-handler dispatch changes:
   [PdfRenderInterfaceGuardTest.java](render-pdf/src/test/java/com/demcha/compose/engine/render/pdf/PdfRenderInterfaceGuardTest.java)
 - For layout/positioning behavior:
   [ComputedPositionTest.java](./src/test/java/com/demcha/compose/engine/components/layout/ComputedPositionTest.java)
 - For pagination and multi-page behavior:
-  [PageBreakerIntegrationTest.java](qa/src/test/java/com/demcha/compose/engine/integration/PageBreakerIntegrationTest.java)
+  [PaginationEdgeCaseTest.java](qa/src/test/java/com/demcha/compose/document/api/PaginationEdgeCaseTest.java)
 - For Templates v2 CV / cover-letter presets:
   [CvV2VisualParityTest.java (CV)](qa/src/test/java/com/demcha/compose/document/templates/cv/presets/CvV2VisualParityTest.java)
   [CoverLetterV2VisualParityTest.java (cover letter)](qa/src/test/java/com/demcha/compose/document/templates/coverletter/presets/CoverLetterV2VisualParityTest.java)

@@ -67,7 +67,7 @@ Concretely:
   states the stateless invariant explicitly.
 - [`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)
+- [`PdfBackendExtensibilityTest`](../../render-pdf/src/test/java/com/demcha/compose/document/backend/fixed/pdf/PdfBackendExtensibilityTest.java)
   pins three behaviours:
   - A custom handler whose `payloadType()` matches a built-in default
     replaces the default for that backend (verified via call counter

@@ -174,6 +174,6 @@ across mixed flat / nested entries.
   [`0003-api-stability-and-internal-marker.md`](0003-api-stability-and-internal-marker.md)
   (gate that allows new components on existing records).
 - Tests:
-  [`src/test/java/com/demcha/compose/document/dsl/ListBuilderNestedTest.java`](../../src/test/java/com/demcha/compose/document/dsl/ListBuilderNestedTest.java).
+  [`qa/src/test/java/com/demcha/compose/document/dsl/ListBuilderNestedTest.java`](../../qa/src/test/java/com/demcha/compose/document/dsl/ListBuilderNestedTest.java).
 - Snapshot baseline:
   `src/test/resources/layout-snapshots/document/nested_list_three_levels.json`.
@@ -198,6 +198,6 @@ etc.).
   that lands the same recursion-friendly shape on lists):
   [`0012-nested-list-evolution.md`](0012-nested-list-evolution.md).
 - Tests:
-  [`src/test/java/com/demcha/compose/document/table/TableCellComposedContentTest.java`](../../src/test/java/com/demcha/compose/document/table/TableCellComposedContentTest.java).
+  [`qa/src/test/java/com/demcha/compose/document/table/TableCellComposedContentTest.java`](../../qa/src/test/java/com/demcha/compose/document/table/TableCellComposedContentTest.java).
 - Snapshot baseline:
   `src/test/resources/layout-snapshots/document/table_cell_with_paragraph.json`.
@@ -215,8 +215,8 @@ diagram authors who want overflow can opt into
   feature):
   [`0013-composed-table-cell.md`](0013-composed-table-cell.md).
 - Tests:
-  [`src/test/java/com/demcha/compose/document/dsl/CanvasLayerBuilderTest.java`](../../src/test/java/com/demcha/compose/document/dsl/CanvasLayerBuilderTest.java).
+  [`qa/src/test/java/com/demcha/compose/document/dsl/CanvasLayerBuilderTest.java`](../../qa/src/test/java/com/demcha/compose/document/dsl/CanvasLayerBuilderTest.java).
 - Snapshot baseline:
   `src/test/resources/layout-snapshots/document/canvas_layer_basic.json`.
 - Showcase:
-  [`examples/src/main/java/com/demcha/examples/CanvasLayerExample.java`](../../examples/src/main/java/com/demcha/examples/CanvasLayerExample.java).
+  [`examples/src/main/java/com/demcha/examples/features/canvas/CanvasLayerExample.java`](../../examples/src/main/java/com/demcha/examples/features/canvas/CanvasLayerExample.java).
@@ -37,75 +37,6 @@ Rule of thumb:
 - if the logic needs `Placement`, `ContentSize`, `Margin`, or parent traversal semantics, it probably belongs in a helper or system utility
 - if the logic only needs identity, component access, or canonical child order, it may belong on `Entity`
 
-## Low-level test harness builders
-
-The old fluent entity builders are no longer production authoring API. They now
-live under `src/test/java/com/demcha/compose/testsupport/engine/assembly` and
-exist to keep low-level engine tests readable. Production features should start
-from `DocumentDsl`, canonical nodes, node definitions, or internal engine model
-types.
-
-### Use `EmptyBox<T>` in tests when
-
-Use [EmptyBox.java](../../render-pdf/src/test/java/com/demcha/compose/testsupport/engine/assembly/container/EmptyBox.java) when the new object is a leaf entity or a small custom object that does not manage children itself.
-
-Examples in the codebase:
-
-- [TextBuilder.java](../../render-pdf/src/test/java/com/demcha/compose/testsupport/engine/assembly/TextBuilder.java)
-- [ImageBuilder.java](../../render-pdf/src/test/java/com/demcha/compose/testsupport/engine/assembly/ImageBuilder.java)
-- [CircleBuilder.java](../../render-pdf/src/test/java/com/demcha/compose/testsupport/engine/assembly/CircleBuilder.java)
-- [LineBuilder.java](../../render-pdf/src/test/java/com/demcha/compose/testsupport/engine/assembly/LineBuilder.java)
-- [LinkBuilder.java](../../render-pdf/src/test/java/com/demcha/compose/testsupport/engine/assembly/LinkBuilder.java)
-- [ElementBuilder.java](../../render-pdf/src/test/java/com/demcha/compose/testsupport/engine/assembly/ElementBuilder.java)
-
-This is the right choice for the exact case you asked about: an object that does not expand into a child-owning container and just needs base entity functionality plus layout/render participation.
-
-What `EmptyBox<T>` gives you:
-
-- entity creation
-- auto-generated `EntityName`
-- fluent `addComponent(...)`
-- parent/child helpers
-- access to `EntityManager`
-- default `build()` behavior through the builder hierarchy
-
-This `EntityManager` access is for low-level engine tests and compatibility
-harnesses only. Canonical application behavior should be described through
-`GraphCompose.document(...)`, `DocumentSession`, and `DocumentDsl`; session
-features such as `guideLines(true)` are not routed through `EntityManager`.
-
-### Use `ShapeBuilderBase<T>` in tests when
-
-Use [ShapeBuilderBase.java](../../render-pdf/src/test/java/com/demcha/compose/testsupport/engine/assembly/container/ShapeBuilderBase.java) when the object is still a leaf, but you want common shape helpers such as:
-
-- fill color
-- stroke
-- corner radius
-
-Examples:
-
-- [RectangleBuilder.java](../../render-pdf/src/test/java/com/demcha/compose/testsupport/engine/assembly/RectangleBuilder.java)
-- [CircleBuilder.java](../../render-pdf/src/test/java/com/demcha/compose/testsupport/engine/assembly/CircleBuilder.java)
-
-### Use `ContainerBuilder<T>` in tests when
-
-Use [ContainerBuilder.java](../../render-pdf/src/test/java/com/demcha/compose/testsupport/engine/assembly/container/ContainerBuilder.java) when the new object owns child entities and participates in parent/child layout.
-
-Examples:
-
-- [HContainerBuilder.java](../../render-pdf/src/test/java/com/demcha/compose/testsupport/engine/assembly/HContainerBuilder.java)
-- [VContainerBuilder.java](../../render-pdf/src/test/java/com/demcha/compose/testsupport/engine/assembly/VContainerBuilder.java)
-- [ModuleBuilder.java](../../render-pdf/src/test/java/com/demcha/compose/testsupport/engine/assembly/ModuleBuilder.java)
-
-Use this path when the object should call `addChild(...)` and arrange nested entities.
-
-Special note for the low-level module test harness:
-
-- `ModuleBuilder` is a low-level test harness for full-width section behavior
-- it resolves to the full available width of its parent minus its own horizontal margin
-- it should usually live under a normal root `vContainer(...)` or a canonical semantic page flow such as `DocumentSession.dsl().pageFlow()`
-- nested horizontal/vertical composition should happen inside the module through regular containers
-
 ## Minimum components a new object usually needs
 
 ### Render marker
@@ -178,10 +109,6 @@ For simple fixed-size objects, set `ContentSize` directly in the builder.
 
 For measured objects, compute size in `build()` before the entity is registered.
 
-Example:
-
-- [TextBuilder.java](../../render-pdf/src/test/java/com/demcha/compose/testsupport/engine/assembly/TextBuilder.java) calls `TextComponent.autoMeasureText(...)` when auto-size is enabled.
-
 ### Layout components
 
 The layout engine expects the usual layout metadata to be present when needed:
@@ -237,7 +164,7 @@ Container rule of thumb:
 
 Some engine objects look like containers from the outside, but still need their own leaf rendering contract inside.
 
-The test-support table harness is the current low-level example:
+The engine's table layout uses exactly this contract:
 
 - the table root is a breakable vertical container
 - each row is a non-breakable leaf entity with explicit `ContentSize`
@@ -257,7 +184,6 @@ Why the table uses this contract:
 
 Relevant files:
 
-- [TableBuilder.java](../../render-pdf/src/test/java/com/demcha/compose/testsupport/engine/assembly/TableBuilder.java)
 - [TableRow.java](../../src/main/java/com/demcha/compose/engine/components/renderable/TableRow.java)
 - [TableResolvedCell.java](../../src/main/java/com/demcha/compose/engine/components/content/table/TableResolvedCell.java)
 
@@ -413,16 +339,6 @@ See [pagination-ordering.md](../architecture/pagination-ordering.md) for a focus
 
 If those components are missing or inconsistent, the renderer cannot save you later.
 
-## When to add a method to the test-support `ComponentBuilder`
-
-Add a method to [ComponentBuilder.java](../../render-pdf/src/test/java/com/demcha/compose/testsupport/engine/assembly/ComponentBuilder.java) when:
-
-- a low-level engine test needs direct entity assembly
-- the object is not ready or not appropriate for public canonical authoring
-- you want it tracked alongside other pending test harness builders before render/layout execution
-
-Do not add a method there if the new object is only an internal helper for templates.
-
 ## Practical checklist for a new object
 
 - choose the correct builder base class
@@ -438,14 +354,6 @@ Do not add a method there if the new object is only an internal helper for templ
 
 ## Good examples to copy
 
-- leaf text with measured size:
-  [TextBuilder.java](../../render-pdf/src/test/java/com/demcha/compose/testsupport/engine/assembly/TextBuilder.java)
-- shape-like object:
-  [RectangleBuilder.java](../../render-pdf/src/test/java/com/demcha/compose/testsupport/engine/assembly/RectangleBuilder.java)
-- fixed leaf line object:
-  [LineBuilder.java](../../render-pdf/src/test/java/com/demcha/compose/testsupport/engine/assembly/LineBuilder.java)
-- container:
-  [ModuleBuilder.java](../../render-pdf/src/test/java/com/demcha/compose/testsupport/engine/assembly/ModuleBuilder.java)
 - template-level composition helper:
   [SectionDispatcher.java](../../templates/src/main/java/com/demcha/compose/document/templates/cv/components/SectionDispatcher.java)
 

@@ -51,7 +51,7 @@ document.pageFlow()
         .build();
 ```
 
-See the [Inline shapes example](examples/src/main/java/com/demcha/examples/features/text/InlineShapesExample.java)
+See the [Inline shapes example](../examples/src/main/java/com/demcha/examples/features/text/InlineShapesExample.java)
 for the full set (`dot`, `arrow`, `chevron`, `diamond`, `star`, `checkmark`,
 `checkbox`).
 

@@ -255,9 +255,9 @@ about, at near-zero cost per run.
   full reference: pipeline position, snapshot contents,
   determinism guarantees, downstream-project adoption, CI policy,
   what NOT to snapshot.
-- [`LayoutSnapshotPublicApiDogfoodTest`](../../src/test/java/com/demcha/testing/layout/LayoutSnapshotPublicApiDogfoodTest.java)
+- [`LayoutSnapshotPublicApiDogfoodTest`](../../qa/src/test/java/com/demcha/testing/layout/LayoutSnapshotPublicApiDogfoodTest.java)
   — a working integration test that drives the snapshot API
   entirely through the published surface. Copyable starting point.
-- [`CvV2VisualParityTest`](../../src/test/java/com/demcha/compose/document/templates/cv/presets/CvV2VisualParityTest.java)
+- [`CvV2VisualParityTest`](../../qa/src/test/java/com/demcha/compose/document/templates/cv/presets/CvV2VisualParityTest.java)
   — example of the pixel-level pattern (currently test-only;
   becoming public via Track N).
@@ -89,7 +89,7 @@ On first run the assertion writes
 `src/test/resources/layout-snapshots/my-feature/scenario_a.json`. To
 accept a baseline change after a deliberate refactor, re-run with
 `-Dgraphcompose.updateSnapshots=true`. See
-[`LayoutSnapshotRegressionExample`](../../examples/src/main/java/com/demcha/examples/LayoutSnapshotRegressionExample.java)
+[`LayoutSnapshotRegressionExample`](../../examples/src/main/java/com/demcha/examples/features/snapshots/LayoutSnapshotRegressionExample.java)
 for a runnable end-to-end demonstration.
 
 ## See also

@@ -93,4 +93,4 @@ the machine check.
 Runnable walkthrough of the full workflow:
 [`LayoutSnapshotRegressionExample`](../../examples/src/main/java/com/demcha/examples/features/snapshots/LayoutSnapshotRegressionExample.java).
 A real in-tree test using the production pattern:
-[`ShapeContainerLayoutSnapshotTest`](../../src/test/java/com/demcha/compose/document/dsl/ShapeContainerLayoutSnapshotTest.java).
+[`ShapeContainerLayoutSnapshotTest`](../../qa/src/test/java/com/demcha/compose/document/dsl/ShapeContainerLayoutSnapshotTest.java).
@@ -152,7 +152,7 @@ they explicitly call the method.
 ## Put it all together
 
 The runnable example
-[`examples/.../TableAdvancedExample.java`](../../examples/src/main/java/com/demcha/examples/TableAdvancedExample.java)
+[`examples/.../TableAdvancedExample.java`](../../examples/src/main/java/com/demcha/examples/features/tables/TableAdvancedExample.java)
 combines every Phase D feature on one PDF: a 3-column invoice with a
 row-spanning side note, zebra body rows, a totals row, and a
 repeating "Item / Qty / Amount" header on every continuation page.
@@ -185,4 +185,4 @@ The Phase D feature set pins five test invariants:
 - [`TableBuilder`](../../src/main/java/com/demcha/compose/document/dsl/TableBuilder.java) — full builder API.
 - [`DocumentTableCell`](../../src/main/java/com/demcha/compose/document/table/DocumentTableCell.java) — cell payload with `colSpan` / `rowSpan` mutators.
 - [`DocumentTableStyle`](../../src/main/java/com/demcha/compose/document/table/DocumentTableStyle.java) — style overrides for fill, stroke, text style, padding.
-- Runnable example: `examples/src/main/java/com/demcha/examples/TableAdvancedExample.java`.
+- Runnable example: `examples/src/main/java/com/demcha/examples/features/tables/TableAdvancedExample.java`.
@@ -120,5 +120,5 @@ the section-level controls in the
 [keep-together recipe](keep-together.md).
 
 Runnable demo:
-[TimelineDemoTest](../../src/test/java/com/demcha/testing/visual/TimelineDemoTest.java)
+[TimelineDemoTest](../../qa/src/test/java/com/demcha/testing/visual/TimelineDemoTest.java)
 renders a marker/rail sheet to `target/visual-tests/timeline/timeline.pdf`.
@@ -87,4 +87,4 @@ section.addShape(120, 24, brand);                     // full strength
 ```
 
 Verified end-to-end (including the opaque byte-identity guarantee) by
-[`PdfShapeAlphaTest`](../../src/test/java/com/demcha/compose/document/backend/fixed/pdf/PdfShapeAlphaTest.java).
+[`PdfShapeAlphaTest`](../../render-pdf/src/test/java/com/demcha/compose/document/backend/fixed/pdf/PdfShapeAlphaTest.java).
@@ -69,9 +69,9 @@ to `IllegalArgumentException`.
 
 The recipe catalogue split into focused pages:
 
-- [`docs/recipes/shape-as-container.md`](recipes/shape-as-container.md)
-- [`docs/recipes/transforms.md`](recipes/transforms.md)
-- [`docs/recipes/tables.md`](recipes/tables.md) — covers row span,
+- [`docs/recipes/shape-as-container.md`](../recipes/shape-as-container.md)
+- [`docs/recipes/transforms.md`](../recipes/transforms.md)
+- [`docs/recipes/tables.md`](../recipes/tables.md) — covers row span,
   zebra, totals, repeated header
 
 ## Worth checking

@@ -16,7 +16,7 @@ preset classes under `templates/cv/presets/` and 14 paired letter
 presets under `templates/coverletter/presets/`. v1.x SemVer "API
 stability" covers the engine, not the templates layer — the
 templates carve-out is documented in
-[ADR 0011](adr/0011-templates-v2-architecture.md). The breaking
+[ADR 0011](../adr/0011-templates-v2-architecture.md). The breaking
 migration is in
 [Templates v2 — CV / cover-letter API rebuilt](#templates-v2--cv--cover-letter-api-rebuilt)
 below.
@@ -74,7 +74,7 @@ The `com.demcha.compose.document.layout` package — including
 `LayoutGraph`, `PlacedFragment`, `PlacedNode`, `BoxConstraints`,
 `MeasureResult`, `NodeDefinition`, `PreparedNode`, and ~15 other
 records — is now annotated
-[`@Internal`](../src/main/java/com/demcha/compose/document/api/Internal.java)
+[`@Internal`](../../src/main/java/com/demcha/compose/document/api/Internal.java)
 at the package level.
 
 The annotation is a documentation signal, not a visibility change. Code
@@ -88,7 +88,7 @@ Why: the v1.6 plan reorganises the layout package internally (split
 `BuiltInNodeDefinitions`, extract a `PlacementContext` interface, move
 payload records to a dedicated subpackage) and we want those refactors
 to ship without semver implications. See ADR
-[0003](adr/0003-api-stability-and-internal-marker.md).
+[0003](../adr/0003-api-stability-and-internal-marker.md).
 
 If you depend on a layout type today, please open an issue describing
 the use case so we can design a stable replacement.
@@ -157,7 +157,7 @@ custom handlers for the same payload type on one builder rejects the
 second with `IllegalArgumentException`.
 
 `PlacedFragment` and `PdfRenderEnvironment` remain `@Internal` — see
-ADR [0004](adr/0004-pdf-handler-spi-extension.md) for the trade-off.
+ADR [0004](../adr/0004-pdf-handler-spi-extension.md) for the trade-off.
 
 ## Templates v2 — CV / cover-letter API rebuilt
 
@@ -166,7 +166,7 @@ scratch in v1.6 under a four-layer architecture: **Theme tokens →
 Layout slots → Components + Blocks → Spec data**. v1.x SemVer "API
 stability" covers the engine, not the templates layer; the
 carve-out is documented in
-[ADR 0011](adr/0011-templates-v2-architecture.md).
+[ADR 0011](../adr/0011-templates-v2-architecture.md).
 
 The change deletes:
 
@@ -383,7 +383,7 @@ The refactor that turns each hand-coded preset back into a thin
 builder recipe is scheduled for v1.7 as Phase E.4. **Public API
 shape stays the same** — only the preset internals change, so
 callers do not need to migrate again. See
-[ADR 0011](adr/0011-templates-v2-architecture.md) for the full
+[ADR 0011](../adr/0011-templates-v2-architecture.md) for the full
 reasoning.
 
 ## Deprecations