feat(render-parity): add deterministic frame comparison tool

- Introduced `render-parity` crate for comparing rendered frames against reference images.
- Added command-line options for specifying manifest and output directory.
- Implemented image comparison metrics: mean absolute difference, maximum absolute difference, and changed pixel ratio.
- Created a configuration file `cases.toml` for defining test cases with global defaults and specific parameters.
- Added functionality to capture frames from `render-demo` and save diff images on discrepancies.
- Updated documentation to include usage instructions and CI model for automated testing.

1 files changed, 77 insertions, 0 deletions

diff --git a/docs/specs/render-parity.md b/docs/specs/render-parity.md
new file mode 100644
index 0000000..5c63c13
--- /dev/null
+++ b/docs/specs/render-parity.md
@@ -0,0 +1,77 @@
+# Рендер-паритет (кадровый diff)
+
+Документ описывает процесс проверки соответствия рендера:  
+`оригинальный движок -> эталонный кадр -> render-demo -> diff-метрики`.
+
+## Цель
+
+- Зафиксировать объективный критерий "паритет достигнут / не достигнут".
+- Убрать субъективную визуальную оценку "похоже/не похоже".
+- Дать CI-проверку, которая ловит регрессии сразу после коммита.
+
+## Единица проверки
+
+Один тест-кейс = один объект (одна модель) + фиксированная конфигурация:
+
+- архив ресурса;
+- имя модели;
+- `lod`;
+- `group`;
+- размер кадра (`width`, `height`);
+- угол камеры (`angle`);
+- PNG-эталон из оригинального рендера.
+
+## Инварианты детерминизма
+
+Для корректного сравнения кадры должны быть сняты в одинаковых условиях:
+
+- одинаковый FOV и расстояние камеры до объекта;
+- одинаковый clear-color/фон;
+- одинаковые `lod/group`;
+- фиксированный угол (`angle`), без анимации;
+- фиксированное разрешение.
+
+## Метрики сравнения
+
+Сравнение выполняется по RGB-каналам:
+
+- `mean_abs`: средняя абсолютная разница канала (0..255);
+- `max_abs`: максимальная разница канала;
+- `changed_ratio`: доля пикселей, где хотя бы один канал превышает `diff_threshold`.
+
+Кейс считается пройденным, если:
+
+- `mean_abs <= max_mean_abs`;
+- `changed_ratio <= max_changed_ratio`.
+
+## Конфигурация кейсов
+
+Файл: `parity/cases.toml`.
+
+- секция `[meta]`: глобальные дефолты;
+- `[[case]]`: параметры конкретной модели и путь к эталонному PNG.
+
+Эталонные кадры хранятся в `parity/reference/`.
+
+## Локальный запуск
+
+```bash
+cargo run -p render-parity -- \
+  --manifest parity/cases.toml \
+  --output-dir target/render-parity/current
+```
+
+При расхождении утилита пишет diff-изображение в:
+
+- `target/render-parity/current/diff/<case>.png`
+
+## CI-модель
+
+CI запускает `render-parity` на каждом push/PR:
+
+1. собирает `parkan-render-demo`;
+2. прогоняет кейсы из `cases.toml`;
+3. при падении публикует текущие кадры и diff как артефакт.
+
+Важно: оригинальный движок в CI обычно не запускается.  
+Эталонные PNG снимаются офлайн и версионируются в репозитории.