houseplan-card/docs/specs/021-color-css-injection.md

ТЗ #21 — безопасные пользовательские цвета

• Issue: https://github.com/Matysh/houseplan-card/issues/21
• Приоритет: P2
• Статус: реализовано; целевой gate v1.61.0-beta.1 пройден, ожидается публикация
• Блокирует цветовые части #50 и #56; SVG sanitization из #51 остаётся отдельной задачей

Проблема

Новые записи проходят backend-валидацию, но старый, импортированный или вручную изменённый store может попасть во frontend без повторной проверки. Подтверждённый разрыв: marker.ripple_color доходил до CSS custom property как часть строки inline-style. Lit не позволяет выйти из HTML-атрибута, но строка вида red;position:fixed могла добавить соседние CSS declarations.

Единый контракт

Все сохраняемые цвета Houseplan имеют только вид #RRGGBB:

• ровно # и шесть шестнадцатеричных цифр;
• регистр букв любой;
• без пробелов, короткого #RGB, имени цвета, rgb(), var(), url() и других CSS-функций;
• неверное значение не исправляется и не записывается автоматически: при чтении используется безопасный штатный fallback.

Это соответствует уже существующим color picker и backend-схеме. Расширять форматы цвета в рамках #21 не требуется.

Реализация

Frontend

Один pure helper safeStoredColor(value, fallback) является общей границей для всех цветов из сохранённой конфигурации:

• цвет и фон пространства;
• глобальный фон и палитра заливок, включая стены и Glow;
• обводка и заливка декоративных объектов и текста;
• marker.ripple_color;
• компонент выбора цвета.

Проверка выполняется при проекции данных для рендера, поэтому защищает и старый store, записанный до этого правила. Невалидный пользовательский ripple не должен перекрывать безопасный динамический цвет лампы.

HA может отдавать rgb_color. Это не сохраняемый пользовательский цвет: приложение принимает три конечных числа, ограничивает каждый канал диапазоном 0–255, округляет и само создаёт каноническую строку rgb(R, G, B). На последней границе inline-style разрешены только строгий #RRGGBB и именно такой сгенерированный rgb().

Backend

Все поля цвета используют один _COLOR = ^#[0-9a-fA-F]{6}$. Поведение API не меняется: корректный hex принимается, остальные формы отклоняются.

Совместимость

• валидные планы визуально не меняются;
• невалидный старый цвет заменяется только в runtime на штатный fallback;
• исходный config не мутируется при чтении;
• при следующем обычном редактировании color picker показывает безопасный fallback, а сохранение записывает валидный цвет.

Обязательные проверки перед пре-релизом

1. Unit corpus: валидный mixed-case hex; short hex, whitespace, named/rgb, ;, braces, comment, backslash, newline, url(), overlong и non-string.
2. Проекция устройства: hostile ripple_color заменяется динамическим цветом включённой RGB-лампы либо null, если такого цвета нет.
3. Последняя style-граница не выводит hostile ripple declaration.
4. Decor/space/fill resolvers используют fallback и не меняют входной объект.
5. Backend одинаково отклоняет hostile значение во всех цветовых полях.
6. Browser smoke на импортированном hostile config: нет overlay, внешнего запроса, новой style declaration и ошибки рендера.

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

• Ни одно значение цвета из store не попадает в CSS/SVG без общей проверки.
• Все новые записи принимают только #RRGGBB.
• Динамический цвет HA остаётся рабочим и не может содержать произвольный CSS.
• Визуальное поведение валидных существующих планов не изменено.
• Целевые frontend/backend тесты и браузерные regression smokes выполнены в gate v1.61.0-beta.1; issue закрывается после зелёного exact-SHA CI и проверки release assets.