SSAUGenerator/pptx/AGENTS.md

# AGENTS.md — генератор lab-gen-pptx

`lab-gen-pptx` собирает презентацию **PPTX** из обычных **Markdown**-файлов по
шаблону Самарского университета. Поведение задаётся файлом `config.yaml`.

## 1. Требования

- Node.js 18+.
- Зависимости: `pptxgenjs`, `js-yaml`.
- Для директив `::: image` с файлами `.puml` — Java 11+ (берётся из
  `JAVA_HOME`, иначе `java` из PATH) и файл `plantuml.jar` (см. `config.plantuml`).

## 2. Состав

```
config.yaml              # настройки (тема, тексты, таблицы, список слайдов)
content/
  slides/*.md            # по одному Markdown-файлу на слайд
  assets/                # задники (title-bg.jpeg, content-bg.jpg, final-bg.jpeg),
                         # готовые PNG/JPEG и исходники PlantUML (*.puml)
presentation.pptx        # результат сборки (ключ presentation.output)
.plantuml-cache/         # кэш отрендеренных PlantUML (ключ plantuml.cacheDir)
src/                     # cli.js, config.js, parse.js, render.js, plantuml.js, build.js
```

Все относительные пути считаются **от каталога `config.yaml`**.

Общий `plantuml.jar` монорепозитория лежит в корне, в `tools/plantuml.jar`
(`plantuml.jar: ../tools/plantuml.jar`). Для автономного дистрибутива положите
`tools/plantuml.jar` рядом с `config.yaml` и задайте путь `tools/plantuml.jar`.

## 3. Командная строка

```
lab-gen-pptx [config.yaml] [опции]

  -c, --config <file>   путь к config.yaml (по умолчанию config.yaml)
  -o, --output <file>   переопределить имя выходного файла
      --check           только проверить конфиг и ссылки
  -v, --verbose         подробный вывод
  -h, --help            справка
      --version         версия
```

```powershell
npm run check
npm run generate
```

## 4. Схема `config.yaml`

| Раздел | Назначение |
|---|---|
| `presentation` | `output`, `author`, `track` |
| `theme` | `width`/`height` (дюймы), `font`, `colors`, `backgrounds`, `slideNumber` |
| `text` | макеты текста для типов слайдов `titleSlide`, `section`, `content`, `final` |
| `table` | размер шрифта, цвета шапки/ячеек/границ |
| `callout` | плашка-вывод: заливка, рамка, цвета и размеры шрифтов |
| `metrics` | карточки-метрики: заливка, цвета, размеры значения и подписи |
| `flow` | нативная схема-цепочка: заливка, рамка, стрелки, размер |
| `chart` | палитра, размер шрифта, легенда, высота диаграммы |
| `plantuml` | рендеринг `*.puml` (см. п. 5) |
| `content.dir` | каталог контента |
| `slides` | список слайдов: `{ type, file }` |

Типы слайдов: `title`, `section`, `content`, `final`. Каждому типу соответствует
макет (`slideMaster`) с собственным фоном:

| type | Фон | Оформление |
|---|---|---|
| `title` | `title-bg.jpeg` | синий, белый текст в правой половине |
| `section` | `title-bg.jpeg` | разделитель, крупный белый текст справа |
| `content` | `content-bg.jpg` | белый лист, заголовок в верхней синей плашке |
| `final` | `final-bg.jpeg` | синий, белый текст справа |

Номер слайда выводится в правом нижнем углу для `content` и `section`.

## 5. Формат слайда (Markdown)

```md
# Заголовок слайда          -> заголовок
## Подзаголовок             -> подзаголовок (для title/final)

- пункт списка              -> маркер
  - вложенный пункт         -> вложенный маркер

Обычный абзац. **Жирный** текст, *курсив*, ==выделение== и `код`
поддерживаются в абзацах, пунктах и ячейках таблиц.

::: table
| Столбец A | Столбец B |
|---|---|
| 1 | 2 |
:::

::: image assets/pic.png
подпись под рисунком
:::

::: notes
Заметки докладчика (используются как сценарий выступления).
:::
```

### Богатое форматирование текста

В абзацах, пунктах списка и ячейках таблиц работает inline-разметка:

| Разметка | Результат |
|---|---|
| `**текст**` | полужирный |
| `*текст*` | курсив |
| `==текст==` | акцентный (брендовый) полужирный |
| `` `текст` `` | моноширинный (Consolas) |

Пункты списка рисуются с висячим отступом, поэтому многострочные пункты с
форматированием сохраняют маркер и выравнивание.

### Директива `::: callout "Заголовок"`

Плашка-вывод с заливкой и рамкой. Внутри — абзацы и/или пункты списка:

```md
::: callout "Итог"
Рынок проверяется ==дешёвым инкрементом==, а не дорогим запуском.
:::
```

Параметр `side=left|right` ставит плашку в левую или правую колонку слайда.
Если у слайда есть блоки с `side`, они верстаются в две колонки (левая/правая),
а остальные блоки — как обычно. Типовое сочетание: `::: image ... side=left`
и `::: callout ... side=right`.

### Директива `::: metrics`

Карточки-метрики (до четырёх). Каждая строка — `Значение | Подпись`
(допускается разделитель `—`):

```md
::: metrics
70% | новых товаров уходят с рынка
10 | сфер применения метода
:::
```

### Директива `::: flow`

Нативная схема-цепочка из скруглённых блоков со стрелками. Шаги разделяются
`->` (или `→`), можно писать по одному на строку:

```md
::: flow
Sprint Planning -> Спринт -> Sprint Review -> Ретроспектива
:::
```

Если ширина блока становится малой, схема автоматически разворачивается
вертикально.

### Директива `::: chart <тип> "Заголовок"`

Диаграмма на основе GFM-таблицы: первая колонка — категории, остальные —
числовые ряды (заголовки колонок = имена рядов). Поддерживаемые типы:
`bar`, `bar3d`, `line`, `pie`, `doughnut`, `area`, `radar`, `scatter`.

```md
::: chart doughnut "Новинки, которые не выживают"
| Итог | Доля, % |
|---|---|
| Успешные новинки | 30 |
| Уходят с рынка | 70 |
:::
```

### Директива `::: image` и PlantUML

`file` — относительно `content.dir` (`content/`). Если файл оканчивается на
`.puml` (`.plantuml`, `.pu`, `.iuml`), он рендерится в PNG через `plantuml.jar`
(см. `config.plantuml`) и вставляется как обычный рисунок:

```md
::: image assets/scrum-cycle.puml height=3.2
Цикл Scrum: от Product Backlog до масштабирования товара
:::
```

Подпись (строка под директивой) выводится под рисунком курсивом. Растровые
PNG/JPEG вставляются как есть. Необязательный параметр `height=<дюймы>`
(`h=`) ограничивает высоту рисунка, чтобы уместить под ним другие блоки;
пропорции сохраняются, рисунок центрируется. Параметр `side=left|right`
ставит рисунок в колонку (см. `::: callout`).

## 6. Задники

Изображения-задники извлечены из `presentation_16.pptx` в
`content/assets/` (`title-bg.jpeg`, `content-bg.jpg`, `final-bg.jpeg`). При замене
шаблона положите новые файлы и обновите пути в `theme.backgrounds`.

## 7. Шрифт

В шаблоне используется фирменный `Elektra Text Pro`, который обычно не установлен
в системе (иначе Word подставляет случайный шрифт). Поэтому по умолчанию задан
`Segoe UI` — близкий современный sans. Альтернативы: `Calibri`, `Candara`,
`Corbel`, `Noto Sans`, `Arial`. Смените `theme.font` при необходимости.

## 8. Проверка результата

Презентацию можно отрендерить для визуальной проверки через LibreOffice:

```powershell
soffice --headless --convert-to pdf --outdir . presentation.pptx
```