GraphCompose: как я приволок ECS из геймдева и снапшот-тесты из фронта в PDF-генерацию на Java

• Низкоуровневые рисовалки — iText, PDFBox. Быстро, мощно, но ты буквально пишешь на бумаге пиксели координатами. Любой инвойс превращается в 200 строк contentStream.beginText() / setFont() / newLineAtOffset(...). А потом приходит дизайнер и говорит: «отступ должен быть 14, а не 12».
  
• Шаблонные движки — JasperReports, OpenPDF. Удобно для отчётов, но XML-шаблон — это отдельный язык, отдельный инструментарий, отдельная боль на ревью. Изменения логики растекаются между Java-кодом, JRXML и DTO.
  
• HTML→PDF — Flying Saucer, OpenHtmlToPdf. Внешне просто, но любой нетривиальный layout превращается в борьбу с CSS-движком, который про печатные документы знает мало.

try (DocumentSession document = GraphCompose.document(Path.of("output.pdf"))
        .pageSize(DocumentPageSize.A4)
        .margin(24, 24, 24, 24)
        .create()) {
    document.pageFlow(page -> page
            .module("Summary", module -> module.paragraph("Hello GraphCompose")));
    document.buildPdf();
}

• собирает семантические узлы (DocumentNode — модули, секции, параграфы, таблицы, строки, изображения, дивайдеры, page-break-ы, слои-стеки),
  
• компилирует их в layout-граф (DocumentSession.layoutGraph()),
  
• пагинирует по правилам, заданным в определении узла (NodeDefinition),
  
• отдаёт результат активному бэкенду (PDF через PDFBox, или DOCX через Apache POI).

src/main/java/com/demcha/compose/engine/
├── core/
│   ├── EntityManager.java        // менеджер сущностей
│   ├── SystemECS.java            // базовый класс системы
│   ├── SystemRegistry.java       // регистрация систем
│   ├── Canvas.java               // координатная система
│   └── LayoutTraversalContext.java
├── components/                   // компоненты (Placement, ContentSize, Padding…)
├── layout/                       // системы layout
├── pagination/                   // системы пагинации
└── render/                       // системы рендера

• Композиция вместо наследования. Параграф с границей — это не подкласс параграфа, это сущность с компонентами ParagraphContent + Border + Padding. Добавить новый кросс-режущий аспект — это новый компонент, а не новая ветка в иерархии классов.
  
• Дешёвые проверки. «Есть ли у этой сущности рендер-маркер?» — entity.hasRender(), O(1).
  
• Чистые системы. EntityRenderOrder сначала собирает лёгкие sort-entries для каждого слоя, потом сортирует — без обращения к компонентам в горячей точке компаратора. Это критично, потому что render-order пересчитывается при каждой пагинации.
  
• Расширяемость. Хотите добавить, скажем, эффект тени? Добавляете компонент Shadow и систему, которая его обрабатывает на render-этапе. Бэкенд рисует тень, если у сущности есть этот компонент. Никакой движок переделывать не надо.

document.add(new LayerStackBuilder()
        .name("Hero")
        .back(heroBackgroundShape)              // фон, top-left
        .center(heroContent)                    // контент по центру
        .layer(badge, LayerAlign.TOP_RIGHT)     // бэйдж в углу
        .build());

GraphCompose.document(...)
  → DocumentSession (мутабельная, не thread-safe, одна на запрос)
  → DocumentDsl / template compose
  → semantic nodes
  → layout graph              ← ПРОХОД 1
  → layout snapshot or render ← ПРОХОД 2
  → PDF stream/bytes/file

LayoutSnapshotAssertions.assertThat(document.layoutSnapshot())
        .matchesGoldenFile("invoice-overview-layout.json");

• ParentComponent даёт авторитетную parent-связь,
  
• Entity.children — канонический порядок сиблингов,
  
• PageBreaker гоняет приоритетный топологический обход: в очередь готовых попадают только узлы без необработанных детей,
  
• внутри ready-queue — сортировка по ComputedPosition.y, потом по глубине, потом по UUID.

1. Layout math unit tests           — проверяют отдельные расчёты
2. Layout snapshot tests            — проверяют детерминированную геометрию
                                      всего документа до рендера
3. PDF visual regression (PNG-diff) — проверяют, что рендер выглядит как раньше

PdfVisualRegression visual = PdfVisualRegression.standard()
        .perPixelTolerance(6)
        .mismatchedPixelBudget(0);
byte[] pdf = session.toPdfBytes();
visual.assertMatchesBaseline("invoice-overview", pdf);

mvn test -Dgraphcompose.visual.approve=true

Successful: 5000
Errors:     0
Time:       2499 ms

.rowCells(
    DocumentTableCell.text("Total").colSpan(3)
            .withStyle(DocumentTableStyle.builder()
                    .fillColor(DocumentColor.LIGHT_GRAY)
                    .build()),
    DocumentTableCell.text("$200.00"));

GraphCompose.document(Path.of("proposal.pdf"))
        .pageBackground(new Color(252, 248, 240))  // кремовая бумага
        .create();

section
    .band(navy)                    // полноширинный цветной баннер
    .softPanel(palePink)           // fill + 8pt corner radius + 12pt padding
    .accentLeft(navy, 4)           // акцентная полоса слева
    .accentBottom(navy, 2);        // линейка снизу под заголовком

section.addRich(t -> t
    .plain("Status: ")
    .bold("Pending")
    .plain(" — last review on ")
    .accent("Mar 14", brandBlue));

• [ ] table row spans (vertical merging)
  
• [ ] header repeat on page break + zebra rows + total row пресеты в TablePreset
  
• [ ] anchored overlay позиции (position(x, y) внутри слоя)
  
• [ ] Maven Central релиз (сейчас живёт через JitPack)
  
• [ ] настоящий PPTX export (v1.3 уже даёт manifest skeleton)

• Исходники: https://github.com/DemchaAV/GraphCompose
  
• Maven через JitPack:

  
      com.github.DemchaAV
      GraphCompose
      v1.4.1
  
  

• Документация в репо: docs/architecture.md, docs/lifecycle.md, docs/pagination-ordering.md, docs/benchmarks.md.
  
• Runnable примеры: в репозитории есть модуль examples/ — там CV, cover letter, инвойс, обычное предложение, cinematic предложение, недельное расписание, module-first документ. Один Java-файл на пример, никакого XML.

  ./mvnw -f examples/pom.xml clean package
  ./mvnw -f examples/pom.xml exec:java \
      -Dexec.mainClass=com.demcha.examples.GenerateAllExamples
  

  Каждый пример пишет PDF в examples/build/.

• Описывает документ через семантику, а не через рисование. Код приложения должен читаться как структура контента.
  
• Тестирует layout до рендера. Снапшоты, как в фронте. Регрессии ловятся в JSON-диффе, а не в визуальном код-ревью.
  
• Один документ — много бэкендов. PDF сегодня, DOCX вчера-сегодня (уже работает), PPTX/HTML завтра. Без переписывания пользовательского кода.
  
• Производит PDF, который не стыдно показать дизайнеру. Layer-стеки, фоны, темы, rich-text — first-class, не workaround-ы.
  
• Не тормозит. ~2 мс на инвойс, 11k+ doc/sec на 16 потоках, ноль падений в стресс-тесте.