houseplan-card/docs/specs/020-glow-open-door-spill.md

ТЗ #20 — Glow проходит через дверь по её фактическому состоянию

• Issue: https://github.com/Matysh/houseplan-card/issues/20
• Каноническая модель света: docs/LIGHT.md
• Связано: #19, #55, #71, #92, #306

Сценарий

Домочадец или гость смотрит House Plan в обычном View либо на киоск-панели в момент, когда в одной комнате горит свет, а дверь с привязанным контактным датчиком между комнатами открывается или закрывается.

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

Сейчас свет проходит через такую дверь независимо от её состояния; после изменения закрытая дверь остановит Glow, открытая пропустит его, а частично открытые ворота или cover оставят проход соответствующей ширины.

Проблема

Каноническая модель docs/LIGHT.md строит полигон видимости по реальной кладке: дверь, ворота или сохранённый passage вырезаются из стены и поэтому всегда прозрачны для Glow. _lightBarriers() классифицирует тип и наличие пола по обе стороны, но не учитывает состояние привязанного opening.contact. В результате визуальный символ может показывать закрытую дверь, а свет продолжает проходить через полный проём.

Старое описание задачи упоминало doorSector() и отдельные световые секторы. Такой модели после #71 нет: задача меняет только ширину выреза в той же кладке, которая уже является источником барьеров и fail-dark проверки источника.

Скоуп

• двери и ворота, привязанные к доступному binary_sensor или door-like cover;
• полный, нулевой и частичный коэффициент открытия;
• проёмы в контурных стенах и в независимых перегородках;
• единый коэффициент для символа проёма и апертуры Glow;
• инвалидация barrier/region cache только при изменении релевантного состояния;
• View и kiosk; та же геометрия участвует в существующих golden/smoke сценах.

Не-скоуп

• новая настройка, новый элемент интерфейса или сохранение runtime-состояния;
• изменение конфигурационной схемы и миграция;
• солнечные лучи, room fill, площадь, бумага, tunnel fill и геометрия символа кроме уже поддерживаемого коэффициента открытия;
• попытка угадать механику створки: частичная апертура всегда сужается симметрично относительно центра;
• свет за наружной дверью или воротами;
• изменение fallback переходных состояний cover без числовой позиции;
• автоматическое управление дверью или связанной сущностью.

Контракт поведения

1. Один коэффициент открытия

Канонический openingAmount() остаётся единственным источником числа 0..1, которое используют и видимый символ, и Glow. Resolver получает тип проёма, состояние, invert и при наличии — attributes.current_position связанного cover.

Проём / источник	Коэффициент amount
passage	всегда 1
дверь/ворота без contact	1 — действующая семантика постоянного проёма
доступный бинарный contact, закрыто/неактивно	0
доступный бинарный contact, открыто/активно	1
доступный cover с конечным current_position	clamp(position / 100, 0, 1)
известное значение при invert: true	1 - amount
contact missing/disabled либо unknown/unavailable	fallback непривязанной двери/ворот: 1; invert его не меняет
окно	его символ использует resolver как сейчас, но апертура Glow всегда 0

Для cover без конечного current_position сохраняется действующая интерпретация его строкового state. Задача не вводит last-known кеш и не меняет существующее поведение opening/closing без позиции. Значения NaN, бесконечность и нечисловые строки считаются отсутствующей позицией.

2. Реальная апертура в кладке

1. Сначала действует существующая allowlist door | gate | passage и проверка пола по обе стороны. Окно, неизвестный будущий тип и наружный проём остаются непрозрачными при любом состоянии.
2. Для прошедшего классификацию проёма вычисляется amount.
3. При amount <= 0 вырез не создаётся: исходная кладка остаётся целой и останавливает свет.
4. При amount >= 1 используется существующий полный вырез без изменения.
5. При 0 < amount < 1 длина выреза равна renderedLength * amount, а его центр, ось и глубина стены не меняются.
6. Правило одинаково для контурной стены и независимой перегородки. Для перегородки масштабируется именно PartitionOpeningCut, а не сохранённый OpeningCfg и не видимая геометрия стены.
7. Несколько проёмов обрабатываются действующей boolean-геометрией. Порядок записей в конфиге не меняет результат и не создаёт швов между пересекающимися вырезами.

Источник, поставленный внутрь закрывшегося проёма, попадает в непрозрачную кладку и полностью подавляется существующим fail-dark guard — так же, как источник внутри стены. Отдельного исключения для такого источника нет.

3. Обновление и кеши

Статическая геометрия и HA-состояние разделяются:

• geometryFingerprint по-прежнему считается только из пространства, cell_cm и grid pitch и используется для повторного recut общей стеновой геометрии;
• openingStateSignature содержит отсортированные по id записи только интерьерных дверей/ворот с привязкой: id:amount, где amount округлён до 0.001;
• barrierFingerprint включает geometryFingerprint и openingStateSignature; он ключует _lightBarrierPool и возвращается в region cache;
• кеш физических тел независимых стен учитывает фактические частичные cuts, а не только множество id прозрачных проёмов;
• посторонний HA tick с той же signature обязан попадать в кеш; глобальная очистка на каждый update запрещена.

Изменение contact должно попасть в обычный render tick без сохранения config. Пулы остаются ограниченными действующими LRU-лимитами.

UX

Новых контролов и сообщений нет. Пользователь продолжает привязывать contact в существующем диалоге проёма. Результат виден непосредственно на плане:

• закрытие убирает Glow за дверью;
• открытие возвращает его;
• позиционный cover меняет ширину светового прохода вместе с отображаемой степенью открытия.

Недоступность или деактивация contact не превращает архитектурный проём в стену и не порождает повторяющиеся toast/ошибки.

Модель данных и миграция

Модель и сохранённый JSON не меняются. Используются существующие поля opening.contact и opening.invert и live-state Home Assistant. Старые планы не мигрируются и при отсутствии доступной привязки отображаются как раньше.

i18n

Новых строк нет. Существующие названия состояния проёма и contact не меняются.

Критерии приёмки и доказательства

• AC1. Лампа в комнате A и закрытая привязанная дверь в B: B не получает Glow. Доказательство: unit геометрии + demo/smoke_glow.mjs.
• AC2. После перехода того же contact в открытое состояние Glow появляется в B не позднее следующего render tick, без config save. Доказательство: browser smoke с переключением fake hass.
• AC3. cover.current_position = 50 создаёт центрированный вырез ровно в половину полной длины, а символ получает тот же amount. Доказательство: unit единого resolver и geometry input + smoke-пиксели по обе стороны jamb.
• AC4. invert меняет известное бинарное/позиционное значение, но не меняет fallback missing/disabled/unknown/unavailable. Доказательство: unit-матрица.
• AC5. Ворота повторяют дверь; passage всегда прозрачен; окно, неизвестный тип и наружная дверь/ворота всегда непрозрачны для Glow. Доказательство: unit классификатора + расширенный glow smoke.
• AC6. Те же full/zero/partial правила работают для проёма с host.kind = partition; закрытая перегородка и её jamb остаются барьерами. Доказательство: geometry unit + smoke fixture с независимой перегородкой.
• AC7. Закрытие проёма, внутри которого стоит источник, полностью убирает его Glow. Доказательство: source-guard unit/smoke.
• AC8. Одинаковая signature переиспользует barrier cache при постороннем HA update; изменение amount создаёт новый barrier/region key; LRU остаётся bounded. Доказательство: cache contract unit.
• AC9. На large-house fixture переключение 20 door contacts не нарушает действующий stateUpdate/Glow performance budget. Доказательство: exact-SHA CI performance smoke перед бетой.
• AC10. Golden-сцена показывает closed/open/50% на толстой стене без тёмных швов и без света снаружи. Доказательство: reviewed Linux golden arteфакт.

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

1. Расширить test/logic.test.mjs: binary, cover position 0/1/50/100, clamp, invalid value, invert, outage fallback, passage/window.
2. Вынести чистую подготовку light apertures/signature либо покрыть существующий чистый geometry boundary так, чтобы unit проверял длину, центрирование, порядок и partition cut без Lit/DOM.
3. Расширить demo/smoke_glow.mjs динамической сменой contact и измерением пикселей в A, в апертуре, в B, за jamb и снаружи. Тот же smoke проверяет контурную стену и перегородку.
4. Добавить/обновить одну детерминированную golden-сцену closed/open/50%; baseline принимается только из полного Linux CI arteфакта по процессу.
5. Перед S7-code-review: npm run typecheck, npm test, npm run build, npm run bundle:sync, npm run bundle:budget, node demo/smoke_glow.mjs, node demo/docs/capture.mjs, затем проверка синхронности bundle tree.
6. Перед бетой: exact-SHA Validate с golden, полным browser matrix и performance smoke.

Риски и меры

Риск	Мера
stale Glow после изменения contact	state signature входит и в barriers, и в region fingerprint
частичный проём режется в контуре, но не в перегородке	отдельный AC6 и общий чистый aperture input
HA update пересчитывает дорогую boolean-геометрию без нужды	signature содержит только релевантные id/amount, LRU остаётся bounded
источник внутри закрытой двери протекает на одну сторону	AC7 фиксирует общий fail-dark body
визуал и свет используют разные проценты	один openingAmount() и unit single-source contract
partial cut создаёт микрошов или вылезает за jamb	clamp, центрирование, существующая boolean-геометрия и golden

Откат

Изменение не пишет данные. Безопасный откат — вернуть полную апертуру для всех интерьерных door/gate/passage и удалить state signature из barrier cache. Планы, привязки и сохранённые trails при этом не меняются.

Release-артефакты

• записи RU/EN changelog со ссылкой на #20;
• актуализация docs/LIGHT.md и при необходимости архитектурного описания кеша;
• синхронные production/demo bundle trees;
• reviewed golden baseline, если пиксели закономерно изменились;
• в release body — отдельный пункт только если владелец сочтёт эффект значимым, иначе общий Small fixes and improvements.

Принято предположительно, поменять свободно на ревью

• форма чистого aperture helper и место его файла;
• точная сериализация signature при сохранении семантики и округления 0.001;
• способ построения частичного PartitionOpeningCut без мутации config;
• разбиение smoke/golden сценариев по файлам.