houseplan-card/docs/specs/424-capture-determinism.md

ТЗ #424 — Съёмка документации перестаёт зависеть от прогона

• Issue: https://github.com/Matysh/houseplan-card/issues/424
• Приоритет: P2, bug + infra; полный трек — одна поверхность (съёмка документации), но правка меняет содержимое всех закоммиченных кадров, а это требует объявленного решения, а не молчаливой пересъёмки. Класс файлов — B (demo/**, test/**) плюс C/D (docs/images/**)
• Ревизия: 1 (2026-09-02)

Сценарий

Приёмка скриншотов построена на одном правиле: каждый необъявленный кадр обязан совпасть с закоммиченным байт-в-байт. Пока съёмка недетерминирована, правило означает случайность — «изменились три кадра» может значить и правку продукта, и невезение на прогоне. Порог кадров-свидетелей (#408/#409) опирается на ту же посылку: свидетель — необъявленный кадр, совпавший байт-в-байт.

Проверить это стало возможно только после #422: кросс-прогонный гейт покраснел в первый же прогон на dev.

Что человек увидит до и после

Видимого поведения продукта задача не меняет.

До: два прогона съёмки на одном коммите дают разные кадры (в CI разошлись 01-view-desktop, 03-space-create, 06-device-editor; локально — те же хеши). Приёмка при этом молчит, потому что сравнивает с закоммиченным, а не прогоны между собой. После: восемь прогонов подряд дают один и тот же набор; «кадр изменился» снова означает «изменился продукт».

Проблема и контракт

Что именно расходится

Попиксельное сравнение двух вариантов 06-device-editor (1180×1100): 76 пикселей, максимум 2 уровня, четыре кластера по краям двух элементов шириной 466 и высотой 31 — скруглённые углы двух select.areasel, стоящих на полупиксельной границе (y = 433.5 и 496.5, border-radius: 6px).

Расходится один-два случайных кадра из десяти, каждый раз разных, а внутри процесса всё стабильно: capture.mjs --stability=3 зелёный. То есть страница приходит в один из нескольких устойчивых исходов ещё до снимка — это не «не успело устояться».

Чем это не оказалось (проверено исполнением)

• не CSS-переходы: гашение transition/animation инъекцией во все shadow root стабилизирует 06, но дрейф переезжает на 06-device-display-preview, затем на 01-view-desktop;
• не шрифты: ожидание document.fonts.ready после применения состояния и ожидание пустого getAnimations({subtree:true}) дрейф не убирают;
• не select: со скрытыми select 06 стабилен, но дрейф уходит на соседний кадр;
• не упаковщик: расхождение сохраняется при полностью отключённом oxipng;
• не кэш шрифтов: после rm -rf ~/.cache/fontconfig расходится не первый прогон, а произвольный;
• не обрезка: 08-room-card, ради которого вводили целочисленный клип (#410), стабилен во всех прогонах.

Причина

Композитор Chromium. Два его свойства делают кадр зависимым от истории прогона: частичная растеризация переиспользует ранее нарисованные куски тайла, а снимок берётся до завершения всех стадий композитора.

Контракт: съёмка документации фиксирует состояние композитора так, чтобы кадр зависел только от коммита. Достигается двумя флагами запуска в DETERMINISTIC_ARGS (demo/docs/capture.mjs):

'--run-all-compositor-stages-before-draw', '--disable-partial-raster'

Подбор проверен перебором, агрегированный хеш всех десяти кадров за восемь прогонов:

Конфигурация	Результат
как сейчас	3+ варианта
--num-raster-threads=1	не помогает
--disable-gpu	не помогает
только --run-all-compositor-stages-before-draw	2 варианта
run-all + --num-raster-threads=1	3 варианта
run-all + --disable-partial-raster	один хеш ×8

Оба флага обязательны: каждый по отдельности дрейф не убирает. Это и есть причина, по которой решение закрепляется тестом, а не комментарием.

Почему golden не затронут

demo/golden/run.mjs сравнивает с допуском (maxChannelDelta: 10, maxDiffRatio: 0.0005 для сцены), а наш дрейф — 2 уровня на 76 пикселях из 1,3 млн, то есть 0,006% при пороге 0,05%. Проверено: npm run golden:verify проходит целиком (153 сценария) в обоих прогонах. Менять golden эта задача не требует; если его когда-нибудь переведут на побайтовое сравнение, флаги понадобятся и там — это записано здесь, а не оставлено на догадку.

Скоуп / не-скоуп

В скоупе: флаги запуска (вынесенные в demo/docs/browser-args.mjs и используемые capture.mjs), контрактный тест на них, мутанты, разовая пересъёмка и приёмка десяти кадров, строка в docs/TESTING.md.

Не в скоупе: demo/golden/** (сравнение с допуском, дрейф ниже порога); кросс-прогонный гейт (#422 — мержится вместе с этой задачей); полупиксельная позиция select.areasel в продукте (симптом, а не причина: дрейф переезжает на другие кадры при её устранении).

UX, модель данных, i18n

Не применимо.

Критерии приёмки

• AC1. Восемь прогонов съёмки подряд на одном коммите дают один и тот же набор кадров. Доказательство: агрегированный хеш docs/images/*.png совпал восемь раз из восьми; отдельно — кросс-прогонный гейт #422 зелёный.
• AC2. Решение закреплено тестом, а не комментарием: контрактный тест требует обоих флагов в DETERMINISTIC_ARGS и объясняет, почему их два. Доказательство: тест в test/.
• AC3. Отрицательный прогон обязателен: снятие любого из двух флагов роняет контрактный тест. Доказательство: два мутанта в scripts/mutation-gate.mjs, прогнанные штатным раннером. Мутант проверяет именно тест, а не съёмку: дрейф стохастический (один-два кадра из десяти, не каждый прогон), и мутант, зависящий от везения, был бы флейковым — то есть худшим видом гейта.
• AC4. Кадры пересняты в каноническом окружении и приняты штатной процедурой; манифест содержит новый отпечаток скрипта. Доказательство: артефакт прогона «Скриншоты документации» и npm run docs:accept.
• AC5. Съёмка не стала медленнее более чем на 15%: --disable-partial-raster выключает оптимизацию перерисовки, и это могло бы стоить времени. Порог, а не «заметно»: критерий без числа не умеет провалиться. Доказательство: время полного прогона capture.mjs до и после, по два замера. Предварительно измерено на этапе ТЗ — 11 711 / 11 595 мс без флагов против 11 589 / 11 567 мс с флагами, то есть разница в пределах шума; если на канонической машине окажется иначе, порог и есть та граница, за которой решение пересматривается.
• AC6. golden:verify проходит без правок эталонов. Доказательство: полный прогон 153 сценариев.

План автотестов

Как тест доберётся до констант. capture.mjs — исполняемый скрипт: с строки 247 он безусловно поднимает Chromium, поэтому импортировать его в тест значит запустить съёмку внутри npm test (сегодня ни один тест браузер не поднимает, и нарушать это нельзя). Набор флагов выносится в чистый модуль demo/docs/browser-args.mjs, откуда capture.mjs его импортирует — тот же приём и по той же причине, что вынос clip.mjs в #422. Текстовый разбор файла через readFileSync (прецеденты — test/smoke-harness-contract.test.mjs, test/golden-matrix.test.mjs) тоже подошёл бы, но он проверяет строку, а не значение, и переживает опечатку в имени флага.

Юнит (test/capture-determinism-args.test.mjs):

1. DETERMINISTIC_ARGS из demo/docs/browser-args.mjs содержит оба флага (AC2, AC3).
2. Флаги перечислены вместе с уже принятыми (--force-color-profile=srgb, --font-render-hinting=none, --disable-lcd-text) — набор не разъезжается.
3. capture.mjs берёт набор из этого модуля, а не объявляет свой: иначе тест стерёг бы константу, которой никто не пользуется.

Мутанты (scripts/mutation-gate.mjs):

• capture-allows-partial-raster: убрать --disable-partial-raster → тест красный;
• capture-draws-before-compositor-settles: убрать --run-all-compositor-stages-before-draw → тест красный.

Проверка реальностью: кросс-прогонный гейт из #422 — он и есть измерение AC1; в конвейере оба изменения оказываются одновременно.

Риски

• Флаги — деталь реализации Chromium и могут исчезнуть в будущей версии. Смягчение: версия Chromium в проекте закреплена; исчезновение флага проявится как падение кросс-прогонного гейта, то есть громко, а не молча.
• --disable-partial-raster замедляет съёмку. Смягчение: AC5 требует замера; десять сценариев — не самая долгая часть конвейера.
• Разовая пересъёмка меняет все десять кадров сразу. Это тот самый случай, который вердикт конвейера называет «изменилось окружение съёмки»; смягчение: приёмка идёт штатной командой с явным решением человека, а порог свидетелей для неё обходится через --no-witnesses --reason, как и задумано.
• Дрейф может вернуться из другого источника. Смягчение: он теперь измеряется на каждом прогоне съёмки (#422), а не обнаруживается через месяц по странной приёмке.

Откат

Снятие двух флагов возвращает прежнее поведение; кадры при этом придётся переснять обратно. Продуктовый код не затрагивается.

Release-артефакты

• docs/CHANGELOG.md / docs/CHANGELOG.ru.md: не требуется (User-Visible: no).
• docs/TESTING.md: строка о том, почему съёмка запускается с этими флагами.
• docs/images/**: разовая пересъёмка всех десяти кадров.