# AGENTS.md Конвертер docx → PDF на чистом Java (docx4j + Apache FOP, без LibreOffice/Aspose). Java 17, только Maven. Модули: `wordpdf-core` (библиотека), `wordpdf-cli` (fat-jar через maven-shade). ## Сборка - `mvn clean verify` — все модули + тесты; единственный гейт перед `git push` (lint/typecheck/CI в репозитории нет). - `mvn -pl wordpdf-cli package` — только fat-jar `wordpdf-cli/target/wordpdf-cli-1.0.0.jar`. - `dependency-reduced-pom.xml` — артефакт shade, уже в .gitignore, не коммитить. ## Тесты - JUnit 5, без внешних сервисов, headless (surefire уже задаёт `-Djava.awt.headless=true`). - Один тест: `mvn -pl wordpdf-core test -Dtest=WordPdfConverterTest#ruPlain_regularRunsUseRegularFont`. - Тесты `wordpdf-cli` зависят от test-jar `wordpdf-core` (classifier `tests`): сборка `-pl wordpdf-cli` без `-am` не пройдёт — либо строить из корня, либо `-am`. - Тестовые `.docx` коммитятся в `wordpdf-core/src/test/resources/samples/`; тесты их не генерируют. Пересоздать — одноразовой утилитой `SampleDocxGenerator` (команда в javadoc класса); POI — только test scope. - `BundledFontsTest` проверяет синхронность списка `ENTRIES` с реальными TTF в `resources/fonts/`: новый шрифт = файл + `Entry`, иначе тест красный. ## Эталон в references/ - 11-страничный документ (текст, таблицы, колонтитулы, 3 диаграммы + SmartArt, формулы) со своим эталонным PDF, экспортированным из Word 365: `word.docx` + `word.pdf` — Transitional OOXML (`schemas.openxmlformats.org/.../2006/...`). - `references/` — материалы для ручного сравнения с Word, не тестовые фикстуры: в тесты и в jar их не подключать (фикстуры — `wordpdf-core/src/test/resources/samples/`). ## Шрифты (важно при изменениях) - 30 TTF в `wordpdf-core/src/main/resources/fonts/` — бинарные фикстуры, часть jar; не удалять/переименовывать без обновления маппинга. - Алиасы MS→open-source: Calibri→Carlito, Cambria→Caladea, Arial→Arimo, Times New Roman→Tinos, Courier New→Cousine; fallback — DejaVu Sans. - Noto Naskh Arabic и Noto Sans Armenian (OFL, 278 КБ) добавлены ради глифов, которых нет больше ни в одном шрифте бандла (арабские дополнения U+07B1–U+08FF, армянские U+058D/U+058E). Регистрировать их в `BundledFontMapper` не требуется: `FontFallback.selectCovering` перебирает **весь** реестр `PhysicalFonts` и находит их сам — достаточно `BundledFonts.ENTRIES`. У них только regular-начертание (`BundledFonts.families()` это учитывает, `allFamiliesHaveAllVariants` их не проверяет). - `FopFallbackFonts.declare` декларирует в FOP-конфиге **все** бандл-семейства, а не один fallback: FOP умеет встраивать только задекларированные, а `font-family` в FO может запросить любой из них. - `slf4j-simple` обязателен: без него docx4j печатает предупреждение прямо в выходной PDF (регрессионный тест `noLoggingWarningInPdf`). - Символы U+2000–U+2EFF (em-dash, кавычки, многоточие): `RunFontSelector.symbolBlockFont` оставляет шрифт ранa, если в нём есть этот глиф, и только иначе подставляет виртуальный «Segoe UI Symbol» (маппится на fallback DejaVu Sans, см. `BundledFontMapper`). Так же делает Word: в `references/word.pdf` em-dash нарисован Calibri/Times, DejaVu там нет вообще. Регрессия — `ruPlain_emDashEmbeddedNotHelvetica` (проверяет, что глиф рисует **вшитый** шрифт, а не базовый Helvetica). ## Архитектура (неочевидное) - Пайплайн: байты docx → `DocxOnOffNormalizer` → `SymbolFontNormalizer` → `FieldNormalizer` → `GlyphCoverageNormalizer` → docx4j → XSL-FO (XSLT) → FOP → PDF. - Поля страниц: Word пишет `PAGE`/`NUMPAGES` сложным полем (`fldChar begin` → `instrText` → `separate` → кэш → `end`). Экспорт docx4j в FO `w:instrText` внутри такого поля игнорирует и печатает кэш docx — во всех колонтитулах одно число (в эталоне «2» вместо 1, 2, 3 …). `FieldNormalizer` разворачивает поле в `w:fldSimple` (его обрабатывает `FldSimpleWriter` из docx4j-export-fo: PAGE → `fo:page-number`, есть также NUMPAGES/SECTIONPAGES/PAGEREF), сохраняя внутри закэшированные ран — они дают шрифт/размер. Штатный `FieldsCombiner` docx4j делает то же, но не заходит внутрь `w:sdt`, а Word держит нумерацию именно в контентном контроле («Page Numbers (Top of Page)»). Трогаются только инструкции, для которых есть обработчик; вложенные поля пропускаются. Регрессия — `WordPdfConverterTest#pageNumbers_recomputedNotCached`, фикстура `samples/page-numbers.docx`. - Покрытие глифов: знак без глифа в шрифте ранa FOP рисует `.notdef` («#»). Docx4j 17.x сам ищет покрывающий шрифт (`FontFallback.selectCovering` по реестру `PhysicalFonts`), но с двумя дырами: `needsCoverage` возвращает false для «латинской» группы (поэтому U+2150–U+218F — римские цифры и дроби — остаются на Tinos навсегда), а `RunFontSelector.fallbackByScript` кэширует фолбэк **на всю группу Юникода** (обычные армянские «ՊՌՋտ» покрываются DejaVu Serif, и найденный DejaVu Serif подставляется следующим за ними U+058D/U+058E). `GlyphCoverageNormalizer` (шаг 2.4, тоже байты до JAXB) режет ран по покрытию и пишет семейство в `w:rFonts` (имя — `BundledFontMapper.documentFontName`, обратное к `bundledFamily`). Покрытие меряется `java.awt.Font.canDisplay` через `BundledFonts.awtFont` (не `GlyphCheck` — тот логирует INFO на каждый отсутствующий глиф). Трогаются только раны с одним `w:t` и с явным `w:rFonts`; если знака нет ни в одном бандл-шрифте, ран не меняется. Регрессия — `WordPdfConverterTest#exoticGlyphs_drawnNotHash`, unit — `GlyphCoverageNormalizerTest`, фикстура `samples/exotic-glyphs.docx`. - Известный остаток эталона: U+2188 (ↈ) и U+218A (↊) — есть только в GNU FreeSerif (GPL-3+ с Font Exception), которого в бандле нет намеренно (весь бандл — SIL OFL). В `references/word.pdf` на их месте у нас две решётки; ради них OFL не меняют. - Символьные шрифты: Word хранит маркеры списков и спецсимволы кодами из PUA (U+F0xx), глиф выбирается по имени шрифта (`Symbol`, `Wingdings`, `Webdings`). Экспорт docx4j в FO этих шрифтов не знает: код уходит в fallback, глифа нет, FOP рисует `.notdef` — в PDF решётка «#». `SymbolFontNormalizer` (шаг 1.6, тоже правит байты до JAXB) меняет код на Unicode, а имя шрифта — на `DejaVu Sans`. Таблица кодов — `SymbolMapper` из docx4j 17.x, отфильтрована по наличию глифа в DejaVu; константы сгенерированы, менять руками нельзя. Обрабатываются `w:lvl` (numbering.xml), `w:r` и `w:sym`; ран с `w:sym` разрезается, т.к. у символа собственный `w:font`. Регрессия — `WordPdfConverterTest#symbolFonts_bulletsAreNotHash`, фикстура `samples/symbol-bullets.docx`. - Порядок инициализации в `WordPdfConverter.convertToStream` важен: сначала `new BundledFontMapper()`, потом `BundledFonts.init()`, затем `BundledFonts.restrictToBundled()` (чистит реестр `PhysicalFonts` от системных шрифтов до `load()`; конструктор маппера каждый раз заново добавляет их). Не менять местами. - docx4j 17.x по-прежнему теряет атрибуты `w:val="off"/"on"` при JAXB-разборе — нормализация байтов до загрузки (`DocxOnOffNormalizer`) нужна и на 17.x (проверялось отключением: красный `ruPlain_regularRunsUseRegularFont`). - Ключ реестра `PhysicalFonts` — имя шрифта, и `addPhysicalFont(URI)` **не перезаписывает** занятый ключ. Системный `DejaVuSerif.ttf` занимает «dejavu serif», и наш `DejaVuSerif-Regular.ttf` (то же имя) не добавился бы — `BundledFonts.init()` перед регистрацией вызывает `dropNonBundled()`. - **`docx4j.convert.out.fo.gsubFeatures=false`** ставится в статическом блоке `WordPdfConverter` — критично. Иначе docx4j навешивает на `fo:inline` атрибут `fox:gsub-features`, не объявляя префикс `fox`; FO становится некорректным XML, `WordLayoutFixups` не может его разобрать, молча отказывается от всех фикс и оставляет хинты `docx4j-baseline`, которые FOP отвергает (`Invalid property encountered on "fo:block": docx4j-baseline`). Без фиксов нет ни колонок, ни колонок таблиц. - `WordLayoutFixups` (включён по умолчанию в 17.x) — постобработка DOM XSL-FO: `columnBreaks` (реально работают `w:cols/@w:num`, 2 колонки на стр. 9–11 эталона), `disregardBaselineShifts`, `lineBoxAttributes`, `stripHints` и др. Побочный эффект: авто-ширины колонок таблиц без `tblGrid`/`tcW` стали уже (слово может перенестись внутри ячейки) — в `tableImage_tableAndImage` сравнение нормализовано по пробелам. - Формулы OMML (`m:oMath`) рисует `jeuclid-fop`, который в 17.x пришёл вместе с `docx4j-export-fo` — отдельного кода не требуется (в 11.5.3 формула молча исчезала). - **`ServicesResourceTransformer` в maven-shade (`wordpdf-cli`) обязателен**: `META-INF/services/org.apache.fop.fo.ElementMapping` лежит и в `docx4j-fo-renderer-core`, и в `docx4j-export-fo`; без слияния второй перезаписывает первый, FOP не узнаёт namespace `fo:` и падает на `UnknownXMLObj cannot be cast to Root`. В fat-jar это не видно из тестов — тесты идут по classpath, проверять `java -jar`. - FOP в 17.x — форк `org.docx4j:docx4j-fo-renderer*` (пакеты `org.apache.fop.*`), он знает хинты `docx4j:baseline`/`docx4j:line-box` через `WordLayoutElementMapping`. `Fop.Renderers.getRenderer()` теперь возвращает **список** `w:renderer` (по mime) — `FopFallbackFonts.rendererFonts` ищет `application/pdf`. - Диаграммы: `docx2fo.xslt` умеет только `a:graphicData/pic:pic`, для `c:chart` и `dgm:relIds` там `notImplemented` (объект молча исчезает). Поэтому `DrawingPreRenderer.run(pkg)` (шаг 3.5 в `convertToStream`, после `setFontMapper` и до `FOSettings`) рендерит их своим Java2D-движком в PNG 300 dpi (`internal/chart/*`) и подменяет на `pic:pic`. Тест `chartsSmartArt_drawingsBecomeImages`, фикстура `samples/charts-smartart.docx`. - В `DrawingPreRenderer` нужны собственные rels части — `part.getRelationshipsPart()` (`Base`), а **не** `getOwningRelationshipPart()`: у `document.xml` последнее указывает на пакетный `.rels`. Обход `pkg.getParts()` — только по снимку списка: `createImagePart` докидывает части в тот же реестр. - SmartArt рисуется из `word/diagrams/drawing1.xml` (кэш разложенной Word-ом схемы: абсолютные позиции + `prstGeom`); текст-заполнители (`[Текст]`) лежат в `data1.xml` на `dgm:pt type="node"`, а формы ссылаются на `dgm:pt type="pres"` — связь через `dgm:cxn type="presOf"`. - `surface3D` (`Surface3dPainter`): перспективная проекция (`c:view3D/perspective`, по умолчанию 30°, и `depth`), грани — ровно ячейки сетки по 2 треугольника без передискретизации, цвет из `c:bandFmts` затемняется по нормали грани (Lambert). Грани рисуются в модельно-экранных координатах уже умноженными на `scale/off` — забыть масштаб значит нарисовать поверхность в субпиксельный ноль. - Знак `rotY` в DrawingML обратный правому правилу вокруг вертикали: в `Surface3dPainter.paint` он берётся как `-Math.toRadians(spec.rotY)`. Иначе передняя кромка категорий идёт вверх вправо, а ось рядов — вниз вправо (зеркально Word). - `c:view3D/perspective` — НЕ угол обзора камеры. Расстояние камеры в `Surface3dPainter` = `CAMERA_DISTANCE * (30/perspective)`, где `CAMERA_DISTANCE = 2.36` (эффективный `fov ≈ 49°`, подобран фитом по эталону Word). При наивном `fov = perspective` перспектива слишком слабая: ось рядов уходит вправо вместо почти вертикального ухода в глубину, лента выглядит плоской, а левый край схлопывается в точку. - Пропорции «коробки» surface3D (`DEPTH_RATIO = 0.705`, `HEIGHT_RATIO = 0.664`): глубина = 0.705 ширины (от неё `c:view3D/depth`), высота значений = `0.664 * availH/availW`, вписывание в область построения — равномерным масштабом. Раздельный масштаб x/y (или куб 1×1×1) даёт вертикальную гору вместо плоской ленты. - Поля вокруг коробки — доли области построения `GUTTER_LEFT = GUTTER_RIGHT = 0.1485`, `GUTTER_TOP = 0.116`, `GUTTER_BOTTOM = 0.146`; `offX`/`offY` обязаны включать левое и верхнее поле (без `topGutter` поверхность сидела на 22 pt выше эталона). Коробка занимает ~70% ширины: при полях «на глаз» поверхность растягивалась на 82% и лезла на подписи оси значений. - Калибровка камеры, коробки и полей зафиксирована тестами `Surface3dPainterTest.cameraMatchesWordReference` и `surfaceSilhouetteMatchesWordPlacement`. Эталон — стр. 3 `word-export.pdf` (экспорт Word), растеризованная `pdftoppm -r 300`; цели замеряются по **связному блоку граней** (серые грани в силуэт входят, по одной лишь насыщенности силуэт недомерен на 7%), пунктиру переднего ребра пола и подписям осей: уклон передней кромки 0,1282, аспект силуэта 0,207, шаг оси значений 0,0504, вертикальный шаг оси рядов 0,1176 (все — относительно ширины силуэта); сам силуэт 314,9×65,3 pt с центром в (227,3; 82,3). Замеры по скриншотам давали вдвое завышенную ось рядов и раздували глубину. - Нормаль грани считается в той же метрике, что и проекция: `v` умножается на `depthScale`, `w` уже умножен на `hScale`. Без масштаба в нормали поверхность кажется положе и все грани уходят в светлую часть Lambert. - Затенение граней surface3D — Lambert `0.92 + 0,88·dot` с клампом `[0,80; 1,25]` и боковым светом `LIGHT = (0,83, 0,48, 0,28)`. Дискретные множители эталона (гистограмма цветов граней, 300 dpi) — 0,40 / 0,75 / 0,85 / 1,04 / 1,06 / 1,10; группа 0,40 — узкая полоска underside под передним краем, и разгон Lambert до неё (отрицательные dot) по всем граням ухудшает совпадение с эталоном (17,2 → 17,6 средних расхождений на пиксель), поэтому нижний кламп 0,80. Направление света перебрано по 120 направлениям — текущее лучшее. Тест `shadingMatchesWordRange`. - Триангуляция ячейки — диагональ с **большей суммой значений** (`z[r][c] + z[r+1][c+1] >= z[r+1][c] + z[r][c+1]` → `w00–w11`, иначе `w01–w10`), то есть верхняя огибающая седла. Фиксированная диагональ невозможна: у седловой ячейки одна вершина попадает внутрь треугольника остальных трёх, и при «не той» диагонали второй треугольник становится невидимой щепкой, а видимая грань окрашивается не той полосой. Проверено по эталону (стр. 3 `word-export.pdf`, 300 dpi, сравнение полос по пикселям; ячейка Ряд 1→2 / Категория 2→3): верхняя огибающая 92,3 % совпадений полос, фиксированная `w00–w11` — 81,6 %, фиксированная `w01–w10` — 57,9 %, окраска целого квада без разрезки — 74,1 %, билинейная tessellation 3×3/6×6 — 67,8 %/66,0 %. Регрессия — `Surface3dPainterTest.saddleCellUsesHigherDiagonal` (нижняя кромка силуэта в окне 0,42…0,55 его ширины обязана быть полосы 3–4). Клиппинг полос — по треугольникам, не по кваду. - Пустой `c:title` при `c:autoTitleDeleted val="0"` даёт автозаголовок `Chart Title` (`ChartSpec.AUTO_TITLE`); для круговых (`pie`/`pie3D`/`doughnut`) вместо него — имя ряда. Тесты `ChartSpecTest`. - В кваде ячейки `w01` обязан быть `z[r+1][c]`, а `w10` — `z[r][c+1]` (u=категория, v=ряд). Перестановка закручивает квад в «бабочку»: дыры и самопересечения граней. - `ChartRenderer.axisBounds` для линейной оси значений без явного `c:min` всегда поднимает нижнюю границу до 0 (как Word); от этого зависит и легенда полос surface3D (`0-1 … 4-5`, а не `1-2 … 4-5`). Юнит-тесты — `Surface3dPainterTest`. - Не убирать shade-фильтры `META-INF/*.SF|*.DSA|*.RSA` — подписанные jar-файлы зависимостей ломают fat-jar. ## Точка входа - Библиотека: `WordPdfConverter.convert(Path)` / `convert(Path, Path)` — статический stateless-класс; ошибки — `ConversionException`. - CLI: `WordPdfCli` (fat-jar, Main-Class в манифесте). Коды возврата: 0 успех, 1 ошибка использования, 2 не конвертирован хотя бы один файл.